How to create a namespace package/project on pypi?

Project names on pypi and Python package names are a rather terrible mess: in many cases, a useful package name is already taken by some abandoned project with version 0.0.1.

So in order to publish a package with a rather common name, let’s for argument’s sake say “maths” (which has a version 0.0.0 project on PyPi already), the safest approach seems to be to instead use a personal/organizational namespace, e.g. xyz.maths.
A bit later on, maybe we want to publish yet another package xyz.graphs ( of course there is already a package graphs 0.1.3 on PyPi).

If I understand correctly there is already a recommendation for using namespace packages to indicate ownership in PEP 0423

My question is: how to do this properly on PyPi? All the information I found so far is confusing and partly contradictory (e.g. PEP0423 seems to say that a PyPi project name should include the dot while Packaging namespace packages — Python Packaging User Guide seems to recommend using names whith underscores?

So is there a best practice for:

  • choosing a pypi project name for
    • the namespace packe xyz (is this even necessary?)
    • all the subpackages like xyz.maths, xyz.graphs
  • creating the proper source code structures and setup.py for those projects
  • creating corresponding projects on RTD (readthedocs)
  • maybe also naming/organizing the corresponding source code on GitHub/GitLab?
3 Likes