[docs] [issue25294] Absolute imports fail in some cases where relative imports would work

Nick Coghlan report at bugs.python.org
Wed Oct 7 06:08:36 CEST 2015

Nick Coghlan added the comment:

(Oops, it seems Brett already clarified the terminology. My apologies for the noise).

Modularity and module design is hard. It's one of the hardest problems in software engineering, which is why folks invent entire new vocabularies to attempt to describe the problem space effectively: http://connascence.io/

The simplest way to avoid these kinds of import related problems as a beginner in Python is to just put all your code in one module, and only factor it out into multiple modules when the single file becomes difficult to maintain.

Unfortunately, Java's "one public class per file" restriction, it's lack of standalone module level functions, and it's popularity as a university level teaching level has given a lot of people a lot of bad ideas as to what good multi-level modularity looks like, as Java throws out the notion of using modules to group closely related public classes and standalone functions into a single file, and instead makes you jump almost directly from classes to packages.

So perhaps that's the currently unwritten rule that would be worth documenting? That Python has 3 levels of namespacing (classes, modules, packages), and that flat namespaces are preferred in the standard library. If the namespace is broken up internally into multiple files for maintainability reasons, we prefer to still present a flat *public* API, as unittest, asyncio and concurrent.futures do.


Python tracker <report at bugs.python.org>

More information about the docs mailing list