Use up-to-date namespace package setup for plugins

[snejus]

Description

Refactor beetsplug to use native namespace packages by removing __init__.py. Update documentation and setup.cfg to support namespace packages.

Changes

• Deleted beetsplug/__init__.py.
• Updated docs/dev/plugins.rst to reflect namespace package structure.
• Updated mypy configuration in setup.cfg

Motivation

Adopt PEP 420 native namespace packages to simplify plugin management and eliminate the need for __init__.py.

See https://realpython.com/python-namespace-package.

This setup is backwards-compatible, so plugins using the old pkgutil-based setup will continue working fine.

The advantage with this setup is that external plugins will now be able to import modules from 'beetsplug' package for typing purposes. Previously, mypy could not resolve these modules due to presence of __init__.py.

[JOJ0]

Built the docs and read them. I like the "attention" box. Some suggestions within.

What I miss in general in our docs is for plugin developers if there is anything specific they need to do in there pyproject.toml or setup.py files.

I'm not sure but is it enough to do this in a setup.py?

packages=find_packages(),

or is it better to do this:

packages=['beetsplug.myawesomeplugin'],

Here is some information about it: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#finding-simple-packages

Also the realpython article states a namespaces=True directive for a pyproject.toml. Is this required?

[tool.setuptools.packages.find]
where = ["."]
include = ["snake_corp"]
namespaces = true

Should we add the most important parts that need to be in the package config. Maybe only focusing on pyproject.toml and setup.py verisions (I suppose they are the most common) and maybe also link to the above? What do you think? Too much information? Less is more?

[JOJ0]

If the general info about (current) namespace packages is already explained in the realpython article, maybe here you can point out this chapter of the python docs just to make sure we document everything potentially interesting for plugin developers (and also those who adopt old/orphaned plugins;-)): https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#legacy-namespace-packages

[snejus]

Removed most of this section and added links to poetry and setuptools

[snejus]

Built the docs and read them. I like the "attention" box. Some suggestions within.

What I miss in general in our docs is for plugin developers if there is anything specific they need to do in there pyproject.toml or setup.py files.

I'm not sure but is it enough to do this in a setup.py?

packages=find_packages(),

or is it better to do this:

packages=['beetsplug.myawesomeplugin'],

Here is some information about it: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#finding-simple-packages

I prefer explicit (latter) over implicit. For example in beetcamp the following works fine:

packages = [{ include = "beetsplug" }]

I'm not sure we should include these instructions in the docs since we've got a variety of build tools and each has its own instructions. We haven't got anything special going on here so as long as they somehow include the beetsplug directory in their package things will work fine. Addings links to setuptools and poetry docs is a good idea though!