The difference between directory / distribution / package names in python packaging

March 6, 2024

• directory name is relevant for the project / root directory of the project
  • no convention with PEP8
• distribution name is relevant for how users would specify / install your code
  • used by PyPI / package repositories, source distribution, eggs, wheels
  • no convention with PEP8
  • requires the use of hyphens
  • https://peps.python.org/pep-0508/#names
  • https://peps.python.org/pep-0345/#name
• package name is relevant for how users would import your code
  • PEP8 - all-lowercase, underscores discouraged
• module name (importable module)
  • PEP8 - all-lowercase, underscores fine
• references
  • Poetry will try and find a package name based on distribution name (with dashes converted to underscores)
  • https://github.com/slackapi/python-slack-sdk/issues/962
  • https://github.com/google-github-actions/release-please-action/issues/396
  • https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives
  • You can specify a distribution name with underscores (still allowing you to build / upload / install), but it looks like this gets conflicted when you include underscores in pyproject.toml (which converts it back to hyphens). So best to standardize on distribution names with hyphens to keep things in sync and avoid confusion.

For example:

• in project A:

# project A
 
# project structure
poetry-demo                  <--- directory name
├── pyproject.toml
├── README.rst
├── poetry_demo              <--- package name
│   └── __init__.py
 
# pyproject.toml
[tool.poetry]
name = "poetry-demo"         <--- distribution name (this needs to use hyphens)
version = "0.1.0"

• in project B:

# project B
 
# pyproject.toml
[tool.poetry.dependencies]
poetry-demo = "0.1.0"        <--- distribution name
 
# installation
pip install poetry-demo      <--- distribution name
 
# usage
import poetry_demo           <--- package name