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 importan…

Accepted Answer

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.

writing python libraries: structure, naming and import best practices

Solution

Problem