Pylibjuju feedback to up and coming changes


#1

A recent request to expose existing Juju functionality already existing in the go CLI came up, although greatly appreciated it unfortunately changed generated code. The python Juju library (pylibjuju) uses generated code to create a backend wrapper that talks and negotiates with the Juju API servers. Any time a API server facade is changed (including parameter changes), a schema is created inside of the juju source code by the developer changing the API server. This code can then be used as the source of the pylibjuju generated code. With this in mind any new changes to the API server would remove the previous change request.

The problem was that this change, in theory should already be picked up as the definitions (parameter and response structs in Juju) inside pylibjuju because new schema files should have already been generated from Juju. I verified this and unfortunately although the facades inside pylibjuju are versioned, the definitions are not and are in fact global to all facade versions. Digging deeper the definitions are not from a specific API facade version, but the first occurrence of that API facade.

Changes

Changing pylibjuju requires some fundamental changes and it would be great to get feedback so that’s possible for the following to happen:

  1. Make it much easier for you as consumers of pylibjuju to know which version of the facades are in play.
  2. This in turn will make it easier to expose new features that Juju exposes via the API facades.
  3. Ease of maintainability going forward

To address these, the following PR aims to fulfil those by:

  1. Using the latest facade for every API request is now it’s pinned in a similar way to how the go CLI does it. This allows a common set of facades to speak to each other in the shim layer around the pylibjuju backend. New version of pylibjuju schema can be generated, but it becomes the responsibility of the developer to bump the facade versions inside the connections.py file so that correct negotiation of facades happen. This should help with knowing which API version of the facade is used.
  2. With the previous points change, the new parameters can then be updated by bumping the facade version and then coding adding any coding changes to the shim layer. The shim layer can then handle any incompatible facades versioning correctly; either by supporting old versions using version checking or by dropping support (either decision needs to be thoroughly thought through).
  3. Lastly; ease of maintainability is fulfilled by ensuring that pylibjuju is less likely to break because we pin to a known existing version. Giving pylibjuju a much more stable platform in the future.

Potential issues

Going forward with the suggest PR means that we now expose values that where never exposed before, so updating to this library may cause breakages. A concrete example might be the following:

Prior to these changes:

async def AddRelation(self, endpoints):

After the changes:

async def AddRelation(self, endpoints=None, via_cidrs=None):

If this is something that we can’t or don’t want to do, then please let the Juju team know (or me personally) as soon as possible, so that we can prevent any unwanted side effects.

Beta testers

If anyone wants to test this, then please do go and checkout the branch and have a play, I’d like feedback as early as possible so we prevent any harm to code bases.


#2

I just want to put in my support as I think this leads to something that won’t accidentally break talking to a different Juju version. We intentionally version our API and put in effort to trying to maintain backwards compatibility (eg a 2.5 client can talk to a 2.6 server).

I also think it is good to point out that we would like to move the Shim layer towards expecting named arguments, as it makes it easier to preserve compatibility over positional arguments. Is that still part of the plan?


#3

Yes, the on caveat to Juju developers is that if they change the name of a field in a struct without rev’ing the api facade it will cause breakages later on. This was always the case, it’s just more evident now.