MAINT: Use pyproject and setuptools_scm

[larsoner]

To facilitate releases:

1. Move to pyproject.toml and make setup.py a thin wrapper
2. Use setuptools_scm to automate versioning
3. Upload to TestPyPI on master pushes (mostly for testing purposes of the GH action)
4. Automatically upload to PyPi when a release is published

After this PR, creating a new release should be as simple as doing a GH release of some master commit with a correctly tagged version number (e.g., v2.2.2 would be next), and it should automatically upload to PyPi.

Locally doing pip install -ve . I get:

$ codespell --version
2.2.2.dev64+g3f9d9a40

which seems totally reasonable since our previous release was 2.2.1.

Inspired by #2522 (comment) -- after this hopefully @peternewman you can release easily

[larsoner]

@peternewman feel free to merge if you're happy, but don't cut a release yet. I want to see the TestPyPI push work on main first. Assuming that succeeds, if you then make+publish a release on GH with a proper tag like v2.2.2, it should appear on PyPI shortly thereafter...

[peternewman]

@luzpaz will be able to do them too!

We'll just need to have a think about what sort of release cadence we want to aim for...

[peternewman]

Release documentation? In the readme or something maybe?

Just a few minor queries/suggestions.

[peternewman]

Don't we want releases here too, so TestPyPI is always equal to, or ahead of, the live one?

[larsoner]

The TestPyPI is really only meant to be there so that when this is merged we can see if it works at all and then iterate until it does so that eventually the Release step actually works. Once it works, I'd rather just delete this altogether, codespell is a small project and installing the "latest and greatest" is already nearly trivial with pip. I think it's actually easier/more common for people to know the command for "install the latest from GitHub source" than it is "add and use this separate TestPyPI repository index" 🤷

[peternewman]

This could definitely do with a note telling you to just release on GitHub or something....

[larsoner]

I don't think it would make sense to add a note here, as I don't think the Makefile is a common place to look for "how to make a release" information. We could add it to the readme, but not many people actually need to know. So I created this: https://github.com/codespell-project/codespell/wiki/How-to-make-a-release

[cclauss]

My sense is that everything will work as expected if this file is deleted.

[larsoner]

I kept it for legacy purposes / compat with existing calls like python setup.py check and python setup.py develop by following the Important 🔥 note at the top here

https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html

[cclauss]

The setup.py below no longer contains a check command. #2517 (comment)

[larsoner]

Seems to work fine, I get the same running check that I get on master:

$ python setup.py check
/Users/larsoner/opt/miniconda3/envs/mne/lib/python3.10/site-packages/setuptools/config/pyprojecttoml.py:108: _BetaConfiguration: Support for `[tool.setuptools]` in `pyproject.toml` is still *beta*.
  warnings.warn(msg, _BetaConfiguration)
running check

[larsoner]

After a little bit of iteration in master and cutting https://github.com/codespell-project/codespell/releases/tag/v2.2.2, we have https://pypi.org/project/codespell/2.2.2/#files

[DimitriPapadopoulos]

The new build system doesn't work properly on Ubuntu, see #2529, #2532 and #2547:

• pip install: The pip bundled with Ubuntu somehow is unable to find the package name codespell and replaces it with UNKNOWN. So far, it looks like he pip package bundled with Debian/Ubuntu is patched and breaks the build.
• python setup.py install: The setuptools bundled with Debian/Ubuntu complains that No module named 'pkg_resources' can be found, and is unable to pick the version and replaces it with 0.0.0.
• ...

Ideally, this should be worked around in codespell, we cannot expect end-users to overwrite the system pip and setuptools just to install codespell.

[cclauss]

pip install --upgrade --user pip setuptools

Besides, pipx is a better way to install cli tools like codespell.

---

python setup.py install is an attack vector so it is now strongly discouraged.

[DimitriPapadopoulos]

I now know it can be solved by pip install --upgrade --user pip setuptools, but how are end-users supposed to find it? This is not a viable solution for those who just want to install coedspell: neither overwriting the system pip and setuptools, nor using pipx (again a new command not installed by default on Ubuntu 22.04??) instead of pip. These are workarounds, but the overall feeling is that the Python module build/install process is currently a mess.

[larsoner]

Ideally, this should be worked around in codespell, we cannot expect end-users to overwrite the system pip and setuptools just to install codespell.

I expect end users to do pip install codespell to pick up the PyPI version, is that how/where you're experiencing these problems? If so I agree we need to fix our code.

Or are you instead trying to install the latest development version from source? For people trying to get the development version (or do development), I think it's okay if it's more complicated. I think we should:

1. Document that, to install from source, pip, setuptools, setuptools_scm, and tomli need to be installed and new enough.
2. Look into we can adding a requires line in setup.py somehow so that an error is raised if setup.py is run/used and these are not up to date.
3. Or maybe we should get rid of the legacy setup.py altogether. It might be causing more problems than it solves.

I know this causes more work for people, but to me if we can help people move toward newer/better installation methods then it's not necessarily entirely a waste of time for them.

[DimitriPapadopoulos]

While pip install codespell works, I was indeed thinking of installing from source. The latter doesn't work on vanilla Ubuntu, and while I agree it is OK to require a different version of pip, my remarks were more about the lack of proper documentation or error messages and suggestions when pip or setuptools fail.

About your proposals:

1. Yes, a Build from source paragraph would ba a great addition. I suggest current paragraph Development Setup in the README is renamed to Build from source and moved just below Installation.
2. I have come to the (temporary) conclusion that Debian/Ubuntu patches might be responsible for these issues, not the version of pip (or setuptools). I need to double-check that, but if true, requires cannot help here.
3. Yes, I vote for removing setup.py. What is the point of keeping it, if it is broken?

Don't get me wrong, I am all for the transition from a setup.py executable to a descriptive pyproject.toml in the Python ecosystem. It's just that the transition has not been well planned and is far from smooth:

• Error messages don't make any sense.
• Constant changes. For example, I have just learned there's a pipx in addition to pip! The pace of breaking changes requires too much involvement from users who just want to build a module from source. Not every user is a hardcore Python developer, spending the whole day on Python packaging.
• No clear and simple documentation on how to install a Python module from sources. It's just a bunch of specific cases for now. I agree the situation should be much better after the transition is over than before it started, but we're not there yet.

[DimitriPapadopoulos]

Current status:

• Installing from source with pip install on Ubuntu 22.04 works after pip install --upgrade pip.
• Installing from source with the legacy python setup.py install on Ubuntu 22.04 works after pip install --upgrade pip setuptools setuptools_scm.

These requirements are partially covered by the Requirements for Installing Packages in the Python Packaging User Guide:

Ensure pip, setuptools, and wheel are up to date

While pip alone is sufficient to install from pre-built binary archives, up to date copies of the setuptools and wheel projects are useful to ensure you can also install from source archives:

python3 -m pip install --upgrade pip setuptools wheel

Still:

• The error messages when these requirements are not met are unhelpful. Unfortunately, they most probably cannot be fixed in codespell, and I get it's impossible to fix old versions of setuptools out there in the wild. We will likely have to live with these unhelpful error messages.
• For python setup.py install, I also had to upgrade setuptools_scm. This needs to be documented and if possible enforced. Not sure which version is required, it might be that the version bundled with Debian/Ubuntu is patched and that the patch is related to the error. Will have to double-check that at some point.
• In any case, we should link to the Requirements for Installing Packages and suggest running pip install --upgrade pip setuptools setuptools_scm before installing. That can be done under Development Setup, after renaming it to Build from source and moving it to the top just below Installation.

[larsoner]

Thanks for investigating @DimitriPapadopoulos . FYI the motivation behind setup.py is just the recommended (but experimental) Important note at the top here

https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html

One thing I was going to check is that if a install_requires in the legacy setup.py with suitable setuptools, pip, and setuptools_scm versions would be enough to at least emit errors for people if they try with tools that are too old. This is way better than UNKONWN-0.0.0 being installed, and still probably better than not having any python setup.py install support (though I'm not 100% convinced at this point...)

[DimitriPapadopoulos]

If these issues are caused by patches applied by Debian/Ubuntu, install_requires won't help. I really need to investigate whether these issues are related to older versions of pip and setuptools, or to patches applied by Debian/Ubuntu. The risk is that they keep applying the patch to future versions, hence breaking install_requires is they start shipping the requested versions of pip and setuptools, but patched.

[DimitriPapadopoulos]

Starting from scratch, after erasing ~/.local/lib/python3.10/ and /usr/local/lib/python3.10 on my machine.

The python3-setuptools DEB package on my Ubuntu 22.04 machine appeared to lack module pkg_resources, which is required by the legacy installation from source process. Yet, the python3-pkg-resources DEB package was installed!

$ dpkg -l | grep setuptools
ii  python3-setuptools                         59.6.0-1.2                              all          Python3 Distutils Enhancements
$ dpkg -l | grep python3-pkg-resources
ii  python3-pkg-resources                      59.6.0-1.2                              all          Package Discovery and Resource Access using pkg_resources
$ 
$ python3 setup.py install --user
Traceback (most recent call last):
  File "/my/path/codespell/setup.py", line 3, in <module>
    from setuptools import setup
  File "/usr/lib/python3/dist-packages/setuptools/__init__.py", line 16, in <module>
    import setuptools.version
  File "/usr/lib/python3/dist-packages/setuptools/version.py", line 1, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'
$ 

After re-installing the DEB package python3-pkg-resources, the legacy and new installation from source processes fail in similar ways, unable to retrieve the package name (UNKNOWN) or the version (0.0.0):

$ sudo apt reinstall python3-pkg-resources
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
0 upgraded, 0 newly installed, 1 reinstalled, 0 to remove and 0 not upgraded.
Need to get 132 kB of archives.
After this operation, 0 B of additional disk space will be used.
Get:1 http://fr.archive.ubuntu.com/ubuntu jammy/main amd64 python3-pkg-resources all 59.6.0-1.2 [132 kB]
Fetched 132 kB in 0s (1 820 kB/s)               
(Reading database ... 241320 files and directories currently installed.)
Preparing to unpack .../python3-pkg-resources_59.6.0-1.2_all.deb ...
Unpacking python3-pkg-resources (59.6.0-1.2) over (59.6.0-1.2) ...
Setting up python3-pkg-resources (59.6.0-1.2) ...
$ 
$ python3 setup.py install --user
running install
[...]
Installed /home/user/.local/lib/python3.10/site-packages/UNKNOWN-0.0.0-py3.10.egg
Processing dependencies for UNKNOWN==0.0.0
Finished processing dependencies for UNKNOWN==0.0.0
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 
$ pip install . --user
Processing /my/path/codespell
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: UNKNOWN
  Building wheel for UNKNOWN (pyproject.toml) ... done
  Created wheel for UNKNOWN: filename=UNKNOWN-2.2.3.dev39+g8609de50-py3-none-any.whl size=8165 sha256=5011e4941f77ff90bdeeb3074557e3d0596cd61c192612a241065c121894c170
  Stored in directory: /tmp/pip-ephem-wheel-cache-mk4yarg5/wheels/e9/c8/df/25c3c4bfff9990df43d5bef57491ee5bbb2c8e5ee19f6074df
Successfully built UNKNOWN
Installing collected packages: UNKNOWN
Successfully installed UNKNOWN-2.2.3.dev39+g8609de50
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 

Therefore, the pkg_resources issue was specific to my machine. With that out of that way, I can investigate the UNKNOWN and 0.0.0 issues.

[larsoner]

After re-installing the DEB package python3-pkg-resources, the legacy and new installation from source processes fail in similar ways, unable to retrieve the package name (UNKNOWN) or the version (0.0.0):

Okay great, this is one scenario I think where raising an error would be good. Can you see if just adding setup_requires to setup.py like:

setup(
    setup_requires=('setuptools>=61', 'setuptools_scm[toml]>=6.2'),
)

is enough to get an error at your end? If so, then if you do:

pip install --user setuptools==61 setuptools_scm==6.2

does the install then succeed?

We should probably also update

codespell/pyproject.toml

Line 49 in df00783

requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2", "wheel"]

to set the min to setuptools 61 since that's when pyproject.toml support was added.

[DimitriPapadopoulos]

I will try your suggestion, but first let me document all the issues I have encountered on Ubuntu 22.04

The next issue is that DEB package python3-setuptools-scm is not installed by default on Ubuntu 22.04, and the Python module is not pulled by pip install – hence your suggestion to add a requires makes absolute sense.

However, while installing DEB package python3-setuptools-scm does help with the version number in the legacy case, it does NOT help with the UNKNOWN package name, in either case:

$ sudo apt install python3-setuptools-scm
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  python3-setuptools-scm
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 31,7 kB of archives.
After this operation, 132 kB of additional disk space will be used.
Get:1 http://fr.archive.ubuntu.com/ubuntu jammy/universe amd64 python3-setuptools-scm all 6.4.2-1 [31,7 kB]
Fetched 31,7 kB in 0s (563 kB/s)                  
Selecting previously unselected package python3-setuptools-scm.
(Reading database ... 241320 files and directories currently installed.)
Preparing to unpack .../python3-setuptools-scm_6.4.2-1_all.deb ...
Unpacking python3-setuptools-scm (6.4.2-1) ...
Setting up python3-setuptools-scm (6.4.2-1) ...
$ 
$ python3 setup.py install --user
running install
[...]
Installed /home/user/.local/lib/python3.10/site-packages/UNKNOWN-2.2.3.dev39+g8609de50-py3.10.egg
Processing dependencies for UNKNOWN==2.2.3.dev39+g8609de50
Finished processing dependencies for UNKNOWN==2.2.3.dev39+g8609de50
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 
$ 
$ pip install . --user
Processing /my/path/codespell
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: UNKNOWN
  Building wheel for UNKNOWN (pyproject.toml) ... done
  Created wheel for UNKNOWN: filename=UNKNOWN-2.2.3.dev39+g8609de50-py3-none-any.whl size=8165 sha256=89ac5bfc7db1dfdd85e0db90b793b9f84550623e4c3fc3a3a420f2faff91b330
  Stored in directory: /tmp/pip-ephem-wheel-cache-ty10cw0x/wheels/e9/c8/df/25c3c4bfff9990df43d5bef57491ee5bbb2c8e5ee19f6074df
Successfully built UNKNOWN
Installing collected packages: UNKNOWN
Successfully installed UNKNOWN-2.2.3.dev39+g8609de50
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 

And this, despite the DEB package versions appear to be recent enough:

$ dpkg -l | grep python3-setuptools
ii  python3-setuptools                         59.6.0-1.2                              all          Python3 Distutils Enhancements
ii  python3-setuptools-scm                     6.4.2-1                                 all          blessed package to manage your versions by scm tags for Python 3
$ 
$ pip list | grep setuptools
setuptools              59.6.0
setuptools-scm          6.4.2
$ 

Next let me replace the Python modules provided by these DEB packages with the same version installed by pip:

$ pip install --user --ignore-installed setuptools==59.6.0
Collecting setuptools==59.6.0
  Using cached setuptools-59.6.0-py3-none-any.whl (952 kB)
Installing collected packages: setuptools
Successfully installed setuptools-59.6.0
$ 
$ python3 setup.py install --user
running install
[...]
Installed /home/user/.local/lib/python3.10/site-packages/UNKNOWN-2.2.3.dev39+g8609de50-py3.10.egg
Processing dependencies for UNKNOWN==2.2.3.dev39+g8609de50
Finished processing dependencies for UNKNOWN==2.2.3.dev39+g8609de50
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 

Clearly setuptools==59.6.0 does not work here, it's not a Debian/Ubuntu patch problem after all. We can bisect to find the minimal setuptools version:

$ pip install --user --ignore-installed setuptools==60.0.0
Collecting setuptools==60.0.0
  Using cached setuptools-60.0.0-py3-none-any.whl (952 kB)
Installing collected packages: setuptools
Successfully installed setuptools-60.0.0
$ 
$ python3 setup.py install --user
running install
[...]
Installed /home/user/.local/lib/python3.10/site-packages/UNKNOWN-2.2.3.dev39+g8609de50-py3.10.egg
Processing dependencies for UNKNOWN==2.2.3.dev39+g8609de50
Finished processing dependencies for UNKNOWN==2.2.3.dev39+g8609de50
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 
$ pip install --user --ignore-installed setuptools==61.0.0
Collecting setuptools==61.0.0
  Using cached setuptools-61.0.0-py3-none-any.whl (1.1 MB)
Installing collected packages: setuptools
Successfully installed setuptools-61.0.0
$ 
$ python3 setup.py install --user
/home/user/.local/lib/python3.10/site-packages/setuptools/config/pyprojecttoml.py:100: _ExperimentalProjectMetadata: Support for project metadata in `pyproject.toml` is still experimental and may be removed (or change) in future releases.
  warnings.warn(msg, _ExperimentalProjectMetadata)
Install ``trove-classifiers`` to ensure proper validation. Meanwhile a list of classifiers will be downloaded from PyPI.
/home/user/.local/lib/python3.10/site-packages/setuptools/config/pyprojecttoml.py:100: _ExperimentalProjectMetadata: Support for project metadata in `pyproject.toml` is still experimental and may be removed (or change) in future releases.
  warnings.warn(msg, _ExperimentalProjectMetadata)
running install
|...]
running install_egg_info
Copying codespell.egg-info to /home/user/.local/lib/python3.10/site-packages/codespell-2.2.3.dev39+g8609de50-py3.10.egg-info
running install_scripts
Installing codespell script to /home/user/.local/bin
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 

As you can see, the package name is properly picked by setuptools==61.0.0, but not setuptools==60.0.0. It looks like we should require setuptools==61.0.0. However, according to @Saransh-cpp in #2532 (comment),
pyproject.toml is officially supported by setutptools>=64.0.0.

Therefore, I suggest we try directly in pyproject.toml and not in setup.py:

requires = ["setuptools>=64", "setuptools_scm[toml]>=6.2", "wheel"]

Let me check it works out of the box on Ubuntu 22.04.

[DimitriPapadopoulos]

Unfortunately, updating pyproject.toml does not automatically update setuptools, even in the case of the new installation process based on pip:

$ grep requires pyproject.toml
requires-python = ">=3.7"
requires = ["setuptools>=64", "setuptools_scm[toml]>=6.2", "wheel"]
$ 
$ pip install --user .
Processing /my/path/codespell
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: UNKNOWN
  Building wheel for UNKNOWN (pyproject.toml) ... done
  Created wheel for UNKNOWN: filename=UNKNOWN-2.2.3.dev39+g8609de50.d20221025-py3-none-any.whl size=8283 sha256=b198293157345b2d5315a834201aa8c7e176dd2389c1be96daf89ce395c7615b
  Stored in directory: /tmp/pip-ephem-wheel-cache-90vjngxt/wheels/e9/c8/df/25c3c4bfff9990df43d5bef57491ee5bbb2c8e5ee19f6074df
Successfully built UNKNOWN
Installing collected packages: UNKNOWN
Successfully installed UNKNOWN-2.2.3.dev39+g8609de50.d20221025
$ 
$ pip list | grep setuptools
setuptools              59.6.0
setuptools-scm          6.4.2
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 

As for modifying setup.py, it doesn't even work, not sure why right now:

$ grep requires setup.py 
        setup_requires=('setuptools>=64', 'setuptools_scm[toml]>=6.2'),
$ 
$ python3 setup.py install --user
/usr/lib/python3/dist-packages/setuptools/installer.py:27: SetuptoolsDeprecationWarning: setuptools.installer is deprecated. Requirements should be satisfied by a PEP 517 installer.
  warnings.warn(
/usr/lib/python3/dist-packages/pkg_resources/__init__.py:116: PkgResourcesDeprecationWarning: 1.16.0-unknown is an invalid version and will not be supported in a future release
  warnings.warn(
/usr/lib/python3/dist-packages/pkg_resources/__init__.py:116: PkgResourcesDeprecationWarning: 1.1build1 is an invalid version and will not be supported in a future release
  warnings.warn(
/usr/lib/python3/dist-packages/pkg_resources/__init__.py:116: PkgResourcesDeprecationWarning: 0.1.43ubuntu1 is an invalid version and will not be supported in a future release
  warnings.warn(
running install
/usr/lib/python3/dist-packages/setuptools/command/install.py:34: SetuptoolsDeprecationWarning: setup.py install is deprecated. Use build and pip and other standards-based tools.
  warnings.warn(
Traceback (most recent call last):
  File "/my/path/codespell/setup.py", line 6, in <module>
    setup(
  File "/usr/lib/python3/dist-packages/setuptools/__init__.py", line 153, in setup
    return distutils.core.setup(**attrs)
  File "/usr/lib/python3.10/distutils/core.py", line 148, in setup
    dist.run_commands()
  File "/usr/lib/python3.10/distutils/dist.py", line 966, in run_commands
    self.run_command(cmd)
  File "/usr/lib/python3.10/distutils/dist.py", line 984, in run_command
    cmd_obj.ensure_finalized()
  File "/usr/lib/python3.10/distutils/cmd.py", line 107, in ensure_finalized
    self.finalize_options()
  File "/usr/lib/python3/dist-packages/setuptools/command/install.py", line 45, in finalize_options
    orig.install.finalize_options(self)
  File "/usr/lib/python3.10/distutils/command/install.py", line 421, in finalize_options
    self.set_undefined_options('build',
  File "/usr/lib/python3.10/distutils/cmd.py", line 286, in set_undefined_options
    src_cmd_obj = self.distribution.get_command_obj(src_cmd)
  File "/usr/lib/python3.10/distutils/dist.py", line 857, in get_command_obj
    klass = self.get_command_class(command)
  File "/usr/lib/python3/dist-packages/setuptools/dist.py", line 893, in get_command_class
    self.cmdclass[command] = cmdclass = ep.load()
  File "/usr/lib/python3/dist-packages/pkg_resources/__init__.py", line 2465, in load
    return self.resolve()
  File "/usr/lib/python3/dist-packages/pkg_resources/__init__.py", line 2471, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
ModuleNotFoundError: No module named 'setuptools.command.build'
$ 
$ pip list | grep setuptools
setuptools              59.6.0
setuptools-scm          6.4.2
$ 
$ rm -r /home/user/.local/lib/python3.10
$ 

[DimitriPapadopoulos]

@larsoner In short, we have two issues:

1. Should we depend on setuptools>=61 (your suggestion and the result of the bisection) or setuptools>=64 (suggestion of @Saransh-cpp in Development Setup fails #2532 (comment))?
2. Then how to enforce these dependencies so that they are pulled automatically? Do you have a clue?

[Saransh-cpp]

@DimitriPapadopoulos, the "UNKNOWN" package name was a pip issue and not a setuptools issue. This has been solved in pip v22.3. See pypa/setuptools#3269 (comment).

I guess we could document it in codespell, but then we cannot possibly think about every error a developer would run into and document it? The classic works on my machine situation 😅

[Saransh-cpp]

And yes, I agree, having Debian or macOS packages installed locally breaks things quite often. I always prefer to use a virtual environment to avoid these breakages! (This can be documented too?)

[Saransh-cpp]

However, according to @Saransh-cpp in #2532 (comment), pyproject.toml is officially supported by setutptools>=64.0.0.

Not pyproject.toml, but editable builds with pyproject.toml 😉

[larsoner]

As for modifying setup.py, it doesn't even work, not sure why right now:

This at least raises an error rather than silently doing something bad. I would just go with this solution and 64 as the minimum, and do some documentation updates. I don't think we have to be perfect here, at least avoiding silent bad behavior is a good start

[DimitriPapadopoulos]

In my case, on Ubuntu 22.04, the UNKNOWN package issue name is fixed:

• either by upgrading to setuptools>=61.0.0, keeping pip==22.0.2 provided by Ubuntu,
• or by upgrading to pip>=22.3 (I haven't bisected but I trust you), keeping setuptools=59.6.0 provided by Ubuntu.

Therefore, I suspect this issue has been fixed or at least worked around in both setuptools and pip.

And, of course it works on your machine 😄 You are well aware of all these issues and I'm pretty sure you have fully up to date pip, setuptools and wheel on your machine, as suggested by the Requirements for Installing Packages. The thing is, not all users are aware of that or know where to look for guidance. I for one, would expect most packages to build on the fully up to date latest Long Term Support Ubuntu distribution, without too many updates or the need for virtualenvs. Too complex.

Any way, since we suggest editable installations using pip install -e ".[dev]", we must indeed go with setuptools>=64.

Since setuptools are unable to enforce or automate the installation of requirements, we will indeed have to document these requirements.

[Saransh-cpp]

Yes, python packaging can be a mess sometimes 😕

Updating the documentation sounds like a good idea!

[DimitriPapadopoulos]

This at least raises an error rather than silently doing something bad. I would just go with this solution and 64 as the minimum, and do some documentation updates. I don't think we have to be perfect here, at least avoiding silent bad behavior is a good start

Actually, it was the extra , breaking the build, whatever the version of pip or setuptools:

    setup(
        setup_requires=('setuptools>=64', 'setuptools_scm[toml]>=6.2'),
    )

Without the extra ,, the build works in the sense that it doesn't crash:

    setup(
        setup_requires=('setuptools>=64', 'setuptools_scm[toml]>=6.2')
    )

But it doesn't pull the requirements or at least warn that the requirements are not met, not any more than the requirements in pyproject.toml. Because setup.py is executable, I could add a few tests such as checking setuptools.__version__ and bail out if <64. However, this would warn and exit only from the legacy python3 setup install. But because pyproject.toml is declarative, if setuptools did not even warn of unmet requirements, there's not much we could do and that would be a serious bug. We must be missing something.

Could you point me to the relevant documentation so that I can double-check whether something's missing?

Also found this:
https://stackoverflow.com/questions/56008251/setup-requires-does-not-seem-to-install-dependencies#56009658

You import numpy (and Cython) before calling setup(). setup() doesn't have a chance to install anything.

In your case setup_requires cannot help. Install numpy and Cython before running setup.py. Or refactor setup.py to not import numpy and Cython.