Folder naming convention for python projects

There are three conventions, which you might find confusing.

1. The standard

PEP8 defines a standard for how to name packages and modules:

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.

2. Actually, nobody cares about the recommendation about not using underscores

Even though it's in PEP8, many packages use underscores and the community doesn't consider it poor practice. So you see many names like sqlalchemy_searchable, etc.

Although you can create a folder with a name which does not match your package name, it's generally a bad idea to do so because it makes things more confusing.

So you'll usually use all-lowercase names with underscores for your folders.

3. Package naming on pypi

The name of a package when it's installed doesn't need to match the name it's published to on pypi (the source for pip installs). Packages on pypi tend to be named with hyphens, not underscores.e.g. flask-cors, which installs the package flask_cors.

However, you'll note that if you follow-up on this example that flask-cors's GitHub repo defines the package code in a flask_cors/ directory. This is the norm.

It gets a bit messy though, because pip package installation is case-insensitive and treats underscores and hyphens equivalently. So Flask-Cors, fLASK_cOrs, etc are all "equivalent".Personally, I don't like playing games with this -- I recommend just naming packages on pypi in all-lowercase with hyphens, which is what most people do.

Disclaimer: I don't own or maintain sqlalchemy-searchable or flask-cors, but at time of writing they're good examples of packages with underscores in their names.

Here is an example of how we might organize a repository called altimeter-valport-lcm which contains the package altimeter_valeport_lcm. The package contains the module altimeter_valeport_lcm.parser:

altimeter-valeport-lcm/├── altimeter_valeport_lcm│   ├── parser.py│   ├── __init__.py│   └── __main__.py├── README.rst└── setup.py

[NOTE]:

• All lowercase for choosing the package name.
• The repository should use the same name as the package, except that they repository substitute dashes (-) for underscores (_).

Read More.

Python packages should also have short, all-lowercase names, although the use of underscores is discouraged. Pep 8 Style Guide

This is the recommendation for packages, which is the main folder containing modules, for testing, setup, and script files, *.py and __init__.py. Therefore, I am assuming the folder is the package and as such, should be all lower case with no underscore (see the link Some Package Github ).