Are there rules for naming single-module Python packages?

Question

Should the name I give to the lone module in a Python package match the name of the package?

For example if I have a package with a single module with the structure

super-duper/
    super/
        __init.py___
        mycode.py
        ...

I can create a package super-duper on PyPi which, when installed, will have two folders in site-packages with names that don't match:

 super/
 super_duper-1.2.3.dist-info/

which means that to import my project I use

import super

rather than the actual package name (super_duper)

This seems to be against common practice (judging from the folders for early every other package I see in site-packages) which follow the pattern

 same_name/
 same_name-1.2.3.dist-info/

for the PyPi package same-name.

Should I instead (always) structure my projects so as

super-duper/
    super_duper/
        __init.py___
        mycode.py
        ...

to ensure that the package name and module import name "match":

import super_duper

Is there a relevant best practice or rule I should be following?

Answer 1

The short answer to your question is: yes, it's generally a good practice to have the name of your module match the name of the package for single module packages (which should be most published packages.)

The slightly longer answer is that naming conventions are always political. The generally accepted method for defining language standards in Python is a process called "Python Enhancement Proposals" (PEPs). PEPs are governed by a body of PEP editors and are publicly indexed for review and commenting.

At present, there is only one "Active" (accepted and implemented) PEP I am aware of that covers module naming conventions, which is PEP 8:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

However, there is another proposal still in the drafting process called PEP 423 that recommends exactly what you state in your post:

Distribute only one package (or only one module) per project, and use package (or module) name as project name.

• It avoids possible confusion between project name and distributed package or module name.

• It makes the name consistent.

• It is explicit: when one sees project name, he guesses package/module name, and vice versa.

• It also limits implicit clashes between package/module names. By using a single name, when you register a project name to PyPI, you also perform a basic package/module name availability verification.

It's important to note that this PEP is still in a "Deferred" state, which means it has not been ratified by the PEP editors, and is blocked by another proposal (specifically the implementation of an update to the module metadata syntax in PEP 440). However, no competing standards have been drafted in the time since 423's original proposal, and much of the content seems to be fairly uncontroversial, so I would expect it to be accepted in the future without too many major changes.

Answer 2

There are no guidelines that I am aware of that require your project name to match the installed package or module. There is a deferred draft PEP-423 Naming conventions and recipes related to packaging, but this is effectively abandoned (a pending update was never applied).

You say you looked, but you probably missed some existing examples where the project name and package contained do not match:

• The BeautifulSoup project uses beautifulsoup4 for the project name on PyPI, which installs the package bs4.

• The dateutil Python package is available on PyPI as python-dateutil. Prefixing PyPI project names with python- is reasonably common, I counted 1512 such packages on PyPI today.

• The Viivakoodi project is a fork of pyBarcode. Their viivakoodi PyPI project installs a barcode package in site-packages. Another such fork project is Pillow, which is a fork of the Python Image Library. It is available on PyPI under that name but the package installs the PIL package.

That said, personally I prefer it for the PyPI project name and the package contained to match; it reduces confusion. The most notable exception is for project forks where the aim is to maintain the old package name to ease migration.

Answer 3

From PEP 8:

Overriding Principle

Names that are visible to the user as public parts of the API should follow conventions that reflect usage rather than implementation.

Package and Module Names

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

The only thing here that seems to address your question is that underscores in package names are discouraged.

There are currently other PEPs in the works to address some of the inconsistencies in Python packaging in general (426, 423), but until those are resolved I would go with what makes the most sense under PEP 20. If super is enough to convey what is being imported, then I'd be inclined to go with that (although if that's the case, why not use it for the PyPi package name as well?).

I don't think convention dictates they be the same, but in practice they are both trying to achieve the same goal, thus end up the same in most cases.

Answer 4

You have the right idea. the convention that I have seen used most often, and that has worked out well for me is:

/superduper
    /superduper
        __init__.py
        code.py
    /.git
    setup.py
    README.rst

you will find that most python devs prefer all lower-case with no special characters for the module names (setuptools, pexpect, matplotlib, etc.).
your top-level project folder should also match the git repo name, so that it doesn't change when you git clone.

my best advice, is take a look at the source from some good established projects, and mimic what they have done.