Folder naming convention for python projects

Question

What is the naming convention in python community to set names for project folders and subfolders?

my-great-python-project my_great_python_project  myGreatPythonProject  MyGreatPythonProject 

I find mixed up in the github. Appreciate your expert opinion.

Answer 1

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.