Edit This Page

This tutorial takes a small Python package from python -m build to a release in your Repsy Open Source PyPI repository, and explains the rules Repsy applies to an upload and what each refusal looks like. It complements Publishing a PyPI Package, which shows the same setup in short.

Prerequisites

• A PyPI repository on your Repsy Open Source instance, see Creating a Private PyPI Registry. The examples use the upload address https://<your-repsy-host>/<repo-name>. There is no username in the address, and https://<your-repsy-host> stands for the address of the package protocol port of your instance, for example http://localhost:9090 for a local start.
• Python 3 with pip.
• A credential: your username and password, or a deploy token. A deploy token goes into the password field and needs the Read/Write access type to publish; the username can be any non-empty value.

Install the tools that build and upload a package:

python -m pip install --upgrade build twine

mkdir example-project && cd example-project
mkdir example_package
touch example_package/__init__.py

def print_hello_world():
    print("Hello World!")

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "example-package"
version = "1.0.0"
description = "An example package."
requires-python = ">=3.9"

python -m build

dist/example_package-1.0.0-py3-none-any.whl
dist/example_package-1.0.0.tar.gz

[distutils]
index-servers =
    repsy

[repsy]
repository = https://<your-repsy-host>/<repo-name>
username = <username>
password = <password-or-token>

export TWINE_REPOSITORY_URL=https://<your-repsy-host>/<repo-name>
export TWINE_USERNAME=<username>
export TWINE_PASSWORD=<password-or-token>
python -m twine upload --non-interactive dist/*

python -m twine upload -r repsy dist/*

python -m twine upload --repository-url https://<your-repsy-host>/<repo-name> dist/*

curl -u <username>:<password-or-token> https://<your-repsy-host>/<repo-name>/simple/example-package/

What Repsy Checks on Upload

A refused upload changes nothing in the repository: nothing is stored and no version appears. An upload has to pass all of these checks:

1. Credentials. A user account can upload to every repository of the instance. A deploy token can upload to its own repository when its access type is Read/Write. A Read Only token, an expired or revoked token, a token of another repository and missing credentials are all refused with 401, and Repsy asks for HTTP Basic credentials. Nobody can upload anonymously, not even to a public repository.

2. Sizes. The package name, the version and Requires-Python are limited to 255 characters each, and so is the file name. Longer values are refused with 400. Descriptive values that are too long, such as a home page, an author, an author email, a license or a description content type of more than 255 characters, are not stored, and the upload still succeeds.

3. The file name. The file has to be named <name>-<version>[-<tag>...].<extension>, where the extension is whl, tar.gz or zip, and the version is written in the canonical form of PEP 440, as python -m build writes it:

   Accepted in a file name	Refused in a file name
   1.0.0	v1.0.0
   1.0.0rc1, 1.0.0a1, 1.0.0b2	1.0.0alpha1 (spelled out)
   1.0.0.post1	1.0.0+build5 (a local version)
   1.0.0.dev1	01.0.0 (leading zeros)

   Other kinds of files, such as eggs or Windows installers, are refused too.

4. The digest. Every upload has to state the SHA-256 digest of its file, and Repsy compares it with the file it received. twine does this for you. A hand-written client that leaves it out or sends a wrong one is refused with 400.

5. Package Override. See Uploading a Version Again.

6. The version. The version in the metadata of the upload has to be a valid Python version. Repsy normalizes the spelling it accepts here, for example 1.0-rc1 to 1.0rc1.

7. The size limit. An upload of more than 500 MB is refused with 413. An administrator can change the limit of Repsy with the MULTIPART_MAX_FILE_SIZE and MULTIPART_MAX_REQUEST_SIZE environment variables.

The name of a package is normalized before it is stored: runs of -, _ and . become one -, and upper case becomes lower case. Example_Package, example.package and example-package are the same package, and pip asks for it by the normalized name.

Repsy accepts pre-releases, dev releases and post releases like final releases: 1.0.0rc1, 1.0.0.dev1 and 1.0.0.post1 are published like 1.0.0. The repository has no setting that switches one of these kinds off.

Uploading a Version Again

Whether you can upload a file that already exists is decided by the Package Override setting of the repository. An administrator changes it in the repository settings.

The rule is applied to the file name, not to the version. When you upload the wheel of a version and later its source distribution, or a wheel with another platform tag, these are different files and are not overrides. Running python -m twine upload dist/* again for a version that is already published is refused for the first file that exists, and twine stops there.

Publish a new version instead of replacing an old one whenever you can: a client that has already installed or cached a file does not know that it changed.

Troubleshooting

twine prints the HTTP status of a refused upload. Repsy also sends the identifier of the error and a message in a JSON body, which twine shows when you add --verbose.

The next step is to install the package with pip.

Installing a PyPI Package Installing Python Packages with pip

Was this page helpful?

Yes No