Distribution vs package naming

[labdmitriy]

Hi @cjolowicz,

Thank you for your great series of articles and this template, this is very useful and I am learning a lot!

I have a question about naming for distributions and packages.

I saw the following statement in the Chapter 1:

Use snake case for the package name hypermodern_python, as opposed to the kebab case used for the repository name hypermodern-python. In other words, name the package after your repository, replacing hyphens by underscores.

Surprisingly for me I can't explain to myself why hyphens are used for distributions, not underscores, and didn't find any best practices on it.
Therefore I decided to write an article with my thoughts about it, but still I don't understand why hyphens are so common for distribution names 😄

Could you please tell what is the reason for you to choose hyphens for distribution names?

Thank you.

[cjolowicz]

Thanks for asking an interesting question, and for writing the article! I particularly liked that you gathered data about existing naming practices from PyPI.

Personally, I prefer package names with hyphens because I find them easier to read. Hyphens have been a part of standard typography since Gutenberg.¹

By contrast, we've had the underscore character only since the advent of typewriters. According to this thesis, it was a fixture of the keyboard by 1881, and used for underlining by backing up the carriage and typing over the previous letter. It became a part of ASCII in 1963, and the C programming language made it a legal character in identifiers in the 1970s. I think you'd be hard-pressed to find a text with underscores that's not aimed at technical people. What's more, the original purpose of underscores was to provide underlining for devices that support inserting multiple characters in the same position. I still find it somewhat weird to read identifiers that underline the gaps between words, but not the words themselves.

This is obviously a personal choice, and there are well-known projects using underscores in their names. To name one prominent example, the import sorter previously used by this template was reorder_python_imports. Using underscores for both distribution and import names has the advantage of consistency, as hyphens are not legal characters in Python identifiers, while underscores are.

Worth noting that PEP 503 treats the three non-alphanumeric characters (., -, _) in package names as equivalent to -. So the above example appears as reorder-python-imports on PyPI.

Footnotes

1. Interestingly, before Gutenberg, the hyphen looked more like an underscore. Gutenberg was forced to move the hyphen to the middle of the line for mechanical reasons. ↩

[labdmitriy]

Wow thank you for such comprehensive answer!

Would you mind letting me include this information to the update of my blog post (referring to your answer)?

I definitely need to restructure and enhance the description in the post:

• I want to consider the case where the repository name differs more than by hyphen or underscore.
  The example of such package I saw recently is tzwhere)
• Do I understand correclty that even when we specify distribution name in setup.py/setup.cfg or pyproject.toml, this name will be normalized for the name on PyPI following the rules you mentioned? I didn't know about that.
  Package reorder_python_imports is an excellent example.
  But as I understand from the naming stats from PyPI, there are distributions with underscores only or even hyphens at the same time, probably these distributions were created before normalization was implemented?

Thank you.

[cjolowicz]

Would you mind letting me include this information to the update of my blog post (referring to your answer)?

Sure, you're welcome!

I want to consider the case where the repository name differs more than by hyphen or underscore.

This is quite common, especially the case with a python- or py prefix:

• python-dateutil
• pyyaml

Do I understand correctly that even when we specify distribution name in setup.py/setup.cfg or pyproject.toml, this name will be normalized for the name on PyPI following the rules you mentioned?

PyPI preserves the original name in the package metadata, as specified by the package author. The URL uses the normalized name (PEP 503), but name variants are accepted and redirected to the normalized name.

PEP 503 normalization also includes transforming to lowercase. For example, the metadata name for pyyaml is PyYAML, whose canonical form is pyyaml.

There is also the question of normalizing distribution filenames. For wheels, this is specified in PEP 427 and based on underscores and original case (for pyyaml, the wheel filename uses PyYAML). For sdists, this is unspecified (see this blog and this issue).

Tools like pip or Poetry will work with any name variant. For example, Poetry uses the original name from the package metadata (PyYAML) in pyproject.toml and poetry.lock, but you can poetry add pyyaml.

---

As an aside, name variants also exist for the console script (where applicable).

• cogapp (cog)
• rst-to-myst (rst2myst)

Sometimes, only the "marketing name" and/or the repository name are different:

• coverage (distribution, package, and script are named coverage, repository is named coveragepy, human-friendly name is Coverage.py)

[labdmitriy]

Thanks a lot for this detailed explanation!
This is more tricky than I expected 😅

Maybe this question is not related to Python directly, but your answer is an interesting historical note itself 😄

I will read your links and will update the post!

[labdmitriy]

PyPI preserves the original name in the package metadata, as specified by the package author. The URL uses the normalized name (PEP 503), but name variants are accepted and redirected to the normalized name.

I decided to make a small experiment - get the latest by update time package with both underscores and hyphens and now it is pyprocessors-mazars_table and it seems that URL is redirected from different URL variants to the original one, not normalized version of the name.

There are several examples of the redirections:

• https://pypi.org/project/pyprocessors-mazars_table/ -> https://pypi.org/project/pyprocessors-mazars_table/
• https://pypi.org/project/pyprocessors-mazars-table/ -> https://pypi.org/project/pyprocessors-mazars_table/
• https://pypi.org/project/pyprocessors-mazars.table/ -> https://pypi.org/project/pyprocessors-mazars_table/
• https://pypi.org/project/pyprocessors.mazars_table/ -> https://pypi.org/project/pyprocessors-mazars_table/
• https://pypi.org/project/pyprocessors_mazars_table/ -> https://pypi.org/project/pyprocessors-mazars_table/

[cjolowicz]

That's an interesting find! The topic of name normalization comes up regularly on the Python Discourse, in the Packaging category. This is a place where both the status quo and the future standards of the Python packaging ecosystem are discussed, and it's well worth following and engaging with.

[labdmitriy]

Thank you for the link!

[labdmitriy]

Hi Claudio,

I substantially restructured the article and also added the information that you provided.

Thanks a lot for your help!