Python: Multiple packages in one repository or one package per repository?

One aspect is covered herehttps://pip.readthedocs.io/en/stable/reference/pip_install/#vcs-support

In particular, if setup.py is not in the root directory you have to specify the subdirectory where to find setup.py in the pip install command.

So if your repository layout is:

• pkg_dir/
  • setup.py # setup.py for package pkg
  • some_module.py
• other_dir/
  • some_file
  • some_other_file

You’ll need to use pip install -e vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir.

I am researching the same issue myself. PyPa documentation recommends the layout described in 'native' subdirectory of: https://github.com/pypa/sample-namespace-packages

I find the single package structure described below, very useful, see the discussion around testing the 'installed' version. https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structureI think this can be extended to multiple packages. Will post as I learn more.

"Best" approach? That's a matter of opinion, which is not the domain of SO. But here are a couple of justifications for creating separate packages:

1. Package is functionally independent of the other packages in your project.
   That is, doesn't import from them and performs a function that could be useful to other developers. Extra points if the function this package performs is similar to packages already in PyPI.Extra points if the package has a stable API and clear documentation. Penalty points if package is a thin grab bag of unrelated functions that you factored out of multiple packages for ease of maintenance, but the functions don't have an unifying principle.
2. The package is optional with respect to your main project, so there'd be cases where users could reasonably choose to skip installing it.
   Perhaps one package is a "client" and the other is the "server". Or perhaps the package provides OS-specific capabilities.Note that a package like this is not functionally independent of the main project and so does not qualify under the previous bullet point, but this would still be a good reason to separate it.

I agree with @boriska's point that the "single package" project structure is a maintenance convenience well worth striving for. But not (and this is just my opinion, I'm going to get downvoted for expressing it) at the expense of cluttering up the public package index with a large number of small packages that are never installed separately.