Packaging tutorial: publishing to TestPyPI

[amercader]

OS version

Ubuntu

Python version

3.12

Pip version

24.3.1

Guide link

https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#

Problem description

Following the guide to set up GitHub Actions to automatically publish to PyPI, it also helps you set up pushing to TestPyPI:

And it’ll publish any push to TestPyPI which is useful for providing test builds to your alpha users as well as making sure that your release pipeline remains healthy!

Following these steps results on errors when pushing to test.pypi.org after the fist push, because on each subsequent push the version number and the package name are the same:

Uploading distributions to https://test.pypi.org/legacy/
Uploading ckan-2.12.0a0-py3-none-any.whl
WARNING  Error during upload. Retry with the --verbose option for more details. 
ERROR    HTTPError: 400 Bad Request from https://test.pypi.org/legacy/          
         File already exists ('ckan-2.12.0a0-py3-none-any.whl', with blake2_256 
         hash                                                                   
         '4a1a7a284be43e71a1492bc9aa756f19256adba83e76d05f6d7d45f3142b9341').   
         See https://test.pypi.org/help/#file-name-reuse for more information.  

If the action is meant to run on each push is reasonable to expect that the package version won't be changed every time and so it should have something like the commit ref or a timestamp appended.

Should this be addressed in the guide or is expected that users handle it at the application or GitHub actions level?

Error message

No response

[merwok]

The action is meant to run on tags or other mecanism you use for releases, not each commit

[amercader]

Correct, but that's not what the various mentions of Test PyPI in the guide and the resulting workflow file imply, as it is explicitly mentioned that every push will be published to Test PyPI:

And it’ll publish any push to TestPyPI which is useful for providing test builds to your alpha users as well as making sure that your release pipeline remains healthy!

So I think the guide should be updated to either remove the pushing to Test PyPI or to add an extra step to the Test PyPI job to append a timestamp to the version number. This would increase the guide's complexity though, as you would need to tweak the build job to something like the following, but only if pushing to Test PyPI

    - name: Add timestamp to version number
      if:  # TODO: only if pushing to test.pypi.org
      run: |
        TIMESTAMP=$(date +"%Y%m%d%H%M")
        sed -E -i 's/(.*)$/\1.pos"'$TIMESTAMP"/' VERSION.txt

Perhaps is better to just mention the option but leave to users the actual implementation, assuming the option to push to test.pypi.org is considered valuable enough to be left in the guide.

[matthewfeickert]

as it is explicitly mentioned that every push will be published to Test PyPI:

And it’ll publish any push to TestPyPI

"any" != "every". TestPyPI was not created as a CI service, so it should be understood that pushes to TestPyPI are intentional to test a release candidate.

So I think the guide should be updated to either remove the pushing to Test PyPI or to add an extra step to the Test PyPI job to append a timestamp to the version number

If additional clarification on the role of TestPyPI is needed in the guide that's fine, but deleting it or uploading packages that are not compliant with PEP 440 names should not happen.

[aaron-skydio]

Yeah, I think the guide should be clarified here. I understand from this thread and elsewhere that TestPyPI isn't intended to host things like nightlies or per-commit wheels. The guide currently does say this:

Requiring manual approvals in the testpypi GitHub Environment is typically unnecessary as it’s designed to run on each commit to the main branch and is often used to indicate a healthy release publishing pipeline.

which implies the intent is to publish to TestPyPI on every commit to main. This is also what the example workflow shown in the guide actually does.

It sounds like this both isn't an intended use case for TestPyPI, and doesn't actually work in practice for common versioning schemes - e.g. if you have some versioning that's constant across multiple commits like above (e.g. a version number checked into the repo), this doesn't work because you'd attempt to publish the same release multiple times. If you instead are using e.g. setuptools_scm to have a version per commit, TestPyPI rejects those version numbers because it doesn't allow publishing local version numbers.

[merwok]

IMO TestPyPI is useful when you’re trying to get package upload working, be it locally or in a repository branch with CI. You can increase versions, try permissions, create tokens, etc and at the end clean up everything, or ignore uploaded artifacts, and change testpypi to pypi in your config.

Doc like the snippet quoted in the previous message should apply to PyPI, i.e. the real, final workflow. We should not tell people to create a release for every commit, or to use TestPyPI regularly outside of specific packaging tasks!

[zahlman]

@merwok I don't think TestPyPI even really solves the problem in #10, though. The problem with uploading a package in order to test whether you can download and install it properly is: what if you can't, and you want to fix it? Now you're blocked from using the same version number on TestPyPI until you remove it manually (and TestPyPI uses the same UI and doc as main, so this is undiscoverable and discouraged). Which is especially problematic if, say, you're trying to debug a problem with setuptools_scm.