67

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.

Shivkumar Birnale
  • 2,906
  • 1
  • 11
  • 17
CognitiveRobot
  • 1,337
  • 1
  • 9
  • 26
  • https://www.python.org/dev/peps/pep-0008/#package-and-module-names – hiro protagonist Oct 16 '18 at 04:26
  • 1
    1. Will work for project names, not for packages or modules 2. will work 3./4. not beautiful – Klaus D. Oct 16 '18 at 04:47
  • Thanks a lot. @Klaus, according to python standard, is there any difference between python project and package? – CognitiveRobot Oct 16 '18 at 05:16
  • 1
    Yes, a package or module needs to have a valid Python name. This excludes names with hyphens in it. You can still use them for the project folder if you have your package/module structure below it. This is because a project folder is usually in the `PYTHONPATH` folders and therefore not part of any `import` line. – Klaus D. Oct 16 '18 at 07:27
  • Thanks. That helps. Last question. I know we can write multiple modules in one package, but I was wondering whether it's a good practice to write multiple packages under one project. Appreciate your replies. – CognitiveRobot Oct 16 '18 at 08:45

3 Answers3

70

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.

  1. 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.

  1. 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.

sirosen
  • 1,716
  • 13
  • 17
  • 1
    Thanks a lot. Is there any difference between python project and package? – CognitiveRobot Oct 16 '18 at 05:38
  • 2
    "project" isn't a specific technical term in python, but "package" is. In my experience, people might say "project" to refer to the python code plus it's supporting cast of setup.py (or pyproject.toml or Pipfile), readme and documentation, changelog, license, etc etc. Any directory with `__init__.py` files is a valid package, and typically there will be 1 or 2 per project: the code under development, and tests. Tests can be a separate package from or subpackage of what they test -- both structures are valid and have different tradeoffs. – sirosen Oct 17 '18 at 12:50
  • Actually, “project” *is* [a defined term at PyPI](https://pypi.org/help/#packages): “A ‘project’ on PyPI is the name of a collection of releases and files, and information about them.” So “SQLAlchemy-Searchable” would be the project name; “SQLAlchemy-Searchable 1.4.1” is the “release” (“A ‘release’ on PyPI is a specific version of a project. For example, the requests project has many releases, like ‘requests 2.10’ and ‘requests 1.2.1’. A release consists of one or more ‘files’.”) And “SQLAlchemy-Searchable-1.4.1.tar.gz” is a “package.” (“something you can download and install”) – Jim Ratliff May 03 '22 at 17:17
  • 1
    Yes, that's definitely more accurate than my older comment. At runtime, in a python interpreter, there is no such thing as a "project", but there is such a thing as a "package". But "project" is an important/meaningful word if you want to interact with the PyPI API. – sirosen May 04 '22 at 18:21
9

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
│   ├── __init__.py
│   ├── __main__.py
│   ├── parser.py
│   └── snake_case.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 the repository substitutes dashes (-) for underscores (_).

Read More.

Benyamin Jafari
  • 27,880
  • 26
  • 135
  • 150
  • 1
    FWIW, the structure I see offered as a best practice is a little different, with a `src` directory intervening between the first and second `altimeter_valeport_lcm`: `altimeter_valeport_lcm/src/altimeter_valeport_lcm`. See the § [A simple project](https://packaging.python.org/en/latest/tutorials/packaging-projects/#a-simple-project) in PyPA’s tutorial “Packaging Python Projects.” [Ionel Mărieș offers several reasons](https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure) he believes that this structure is superior. – Jim Ratliff May 03 '22 at 15:14
  • 1
    @JimRatliff I don't think so this would be the best practice as you cannot find many repositories in Github with the proposed structure — a python repository name using underscore delimiter rather hyphen or containing `src` as a package or folder. To ensure that the structure I posted as an answer is proper, you can check this [example](https://github.com/python/miss-islington) which is one of the `python` repositories itself. – Benyamin Jafari May 03 '22 at 16:19
1

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 ).

tcratius
  • 525
  • 6
  • 15