Discourage use of subpackages

[stxlvt]

Discourage use of subpackages

[amontalenti]

Hmm. I think you misunderstand.

What I'm saying here is that you should not create a lib top-level package for your (private) repo, because that pollutes the global (sys.modules) namespace. I would infer from the rule that you should prefer mypackage/lib.py to ./lib.py in the project root, but most people recognize it can be bad form to put source modules in the project root, except in rare cases where the entire project is a single module.

I'll close this one because I don't think the suggestions add to the style guide.

[stxlvt]

I totally agree that you should not create a top-level package named lib, or anything else with so generic a name for that matter. There is, after all, only one package namespace in python and we need to take care to choose unique names for our packages and modules so as to avoid collisions with other packages and modules.

I assumed the gist of this line was about where you should place the package, and that the lib name was not meant to be the actual name of the package -- like if this was the line:

mypackage/lib/__init__.py preferred to mypackage-lib/__init__.py

It is this advice that I disagreed with. So I want to assume from now on that we give the lib package a name that is sufficiently unique, so that namespace collision is not an issue.

In this case it would be wrong to give the above advice, because in a majority of the cases it would be best to make mypackage-lib a separate pip distribution, or at least prepare for such a separation by making it another toplevel package of the mypackage pip distribution.

You know how it is. The next project by the same developer will also need some of the functionality in lib, but not anything from mypackage. What will he do? Depend on mypackage? Copy the lib subpackage and get a DRY nightmare? Hopefully he will see the error of his ways and make mypackage-lib separate.

Another likely problem arises when some other project wish to use the functionality in lib, but does not wish to depend on or use mypackage just to get at that subpackage. Maybe mypackage is big and bloated but the lib package is small, nifty and self-contained. What will they do? They have no good solutions except bugging the mypackage developer until he does the thing he should have done from the start, which is make mypackage-lib a separate distribution. But likely they will instead take the easy route and just plop lib into their own package. Now they ought to monitor what happens in the mypackage repository and apply all patches to the lib subpackage to their own copy as well. But are they going to do that? And they should also submit bugfixes back to the upstream project, but will that happen, now that they have their own copy?

All these problems would have been solved if the mypackage developer had been given good advice about how to structure his projects, or at the very least not been given bad advice about what to do.

I hope that I have at least managed to raise some doubts as to whether this advice is the right advice in most cases. And if I have, then I think it would be wrong to dole it out as a generic advice without any exceptions in this document. Please reconsider your decision to close this issue, and instead either delete, reformulate or add some exceptions or qualifiers to this line.