Evaluate if we want to use google-style imports or not

[llucax]

At some point we decide we did want to use it, but it seems not trivial, so it's not just about saying yes, it is also about deciding a good packages/modules structure for this to make sense, so this is blocked until we decide on the structure:

• Revamp modules/package structure frequenz-sdk-python#575

---

We need a discussion to see if we want to go this route, and if it is viable.

This might not work that well for libraries/packages/modules that are not designed this way.

Also we have to have in mind how documentation is generate when using this, for example:

[Marenz]

Which aspect are you demonstrating with the screenshot of the documentation that you're worried about?

In general, to me it feels much nicer to import only the symbols I use directly. Except when they are very short or ambiguous then I use the long path.

[llucax]

Which aspect are you demonstrating with the screenshot of the documentation that you're worried about?

I'm showing that we use google style imports but in a style where the imported module is private (_base_classes), then it is not properly linked because the module is private and no documentation is generated for it and it looks weird because there is a private symbol leak that is completely irrelevant to the user, they only care about Receiver in this case, or it should be channels.Receiver maybe.

I have the impression that having private modules and exposing them through parent modules/packages is not suitable to use google-style imports, with google style imports I think it makes more sense to have even small modules public, or the other extreme, just have everything exposed through a short unique module name (for example fzchan instead of frequenz.channels.

[ktickner]

In theory anything you can import should be named in a self-explanatory way

I also found the distinction between modules and classes/functions to be unclear when reading the google style guide. This is probably due to my lack of experience in python, BUT i feel this would potentially lack clarity on when its okay to use the direct import

[llucax]

In theory anything you can import should be named in a self-explanatory way

Who's theory? 😆

I mean, with different styles there could be different approaches. Again, using the channels repo as example. Now we have from frequenz.channels import Broadcast. Broadcast doesn't sound completely self-explanatory in a wider context, IMHO it should be BroadcastChannel, but if we were to use google-style, then from frequenz.channels import broadcast; chan = broadcast.Channel(...); recv: broadcast.Receiver = chan.new_receiver() makes a lot of sense too IMHO.

I also found the distinction between modules and classes/functions to be unclear when reading the google style guide. This is probably due to my lack of experience in python, BUT i feel this would potentially lack clarity on when its okay to use the direct import

I think this is actually one thing that the google style is supposed to address. So, excluding some exceptions (like stuff in the typing module), all top-level (imported) symbols are modules, you are not allowed to import functions or classes separately.

[llucax]

At some point we decide we did want to use it, but it seems not trivial, so it's not just about saying yes, it is also about deciding a good packages/modules structure for this to make sense, so this is blocked until we decide on the structure:

• Revamp modules/package structure frequenz-sdk-python#575