writing python libraries: structure, naming and import best practices

Question

Let's say I have to write several small to medium libraries for my company.

Does it make sense, in a pythonic way, to use the Java approach and prefix all of them with a common high-level package (ahem, module) such as achieving the following structure:

mycompany.mylibrary1.moduleA
mycompany.mylibrary1.moduleB.moduleD
mycompany.mylibrary2.moduleC

or is it better to simply go for:

mylibrary1.moduleA
mylibrary1.moduleB.moduleD
mylibrary2.moduleC

I see that most of the time the 2nd approach is used, but I was looking for a confirmation (or not) that's the way to go.

I could not find anything in this respect in PEP 008, beside:

The naming conventions of Python's library are a bit of a mess, so we'll never get this completely consistent [...]

and then we get only modules and class naming indications, as well as the fact that relative imports are discouraged.

The fact that absolute imports are the way to go make the decision of how you organize your libraries really important (and I'm not here to discuss whether avoiding relative imports is good or bad).

I do like the Java approach that namespaces all of your libraries, but I have the impression it's not pythonic... what's the suggested way to go?

PS. While in general 'best practice' questions are considered as subjective on SO, in Python the existance of the PEP makes them in my opinion very objective! Though the answer might be... there's not best practice for organizing your libraries..

Answer 1

There is a cognitive issue with python imports and names. Since there are so many different kinds of first-order objects (primitives, modules, classes, functions, classes pretending to be modules, modules pretending to be objects, et cetera) people tend to use dot-notation to indicate that an entity has "arrived" from an external source. Thus

import foo.bar
e = foo.bar.make_entity()

is felt to be clearer than

from foo.bar import make_entity
e = make_entity()

However, this means that you will frequently have to type the full path of whatever you need to access. "com.example.some.lib.module.frobnicate() gets tiresome quickly. Thus, a polite library supplies a reasonably short name for its access.