python-registry

📦 Python Registry (PEP 503 Static PyPI Index)

This repository acts as a private, static PyPI registry compliant with PEP 503 (Simple Repository API).

💡 Why This Repository Exists?

Unlike npm, Docker, or Maven, GitHub Packages does not natively support a PyPI registry.

To avoid relying on third-party SaaS platforms or hosting heavy, expensive infrastructure, this repository bridges that gap. It allows our organization to host custom Python packages (including packages located in subdirectories of monorepos) 100% within our GitHub ecosystem, securely and at zero cost.

---

🤖 How It Works & Automatic Updates

⚠️ DO NOT MANUALLY EDIT THIS REPOSITORY. Everything in this repository is 100% automated via CI/CD pipelines (e.g., CircleCI).

1. Trigger: A developer tags a release (vX.Y.Z) inside a source repository or a specific subdirectory of a monorepo.
2. Build: The CI pipeline enters the package folder, builds the .whl and .tar.gz artifacts using tools like Poetry or uv.
3. Fetch & Update: The pipeline automatically clones this python-registry repository, injects the new artifacts into the correct folder, and fully regenerates all HTML index files to ensure compatibility with Python installers.
4. Publish: The pipeline automatically commits and pushes the changes back to this repository.

---

📁 Repository Structure

The layout follows the strict PEP 503 layout required by Python package managers:

python-registry/
├── README.md
└── simple/
    ├── index.html                   # 📄 Main index (lists ALL available packages)
    │
    ├── my-package-a/                # 📁 Package A directory
    │   ├── index.html               # 📄 Package A index (lists all its available versions)
    │   ├── my_package_a-1.0.0-py3-none-any.whl
    │   └── my_package_a-1.0.0.tar.gz
    │
    └── my-package-b/                # 📁 Package B directory
        ├── index.html               # 📄 Package B index
        └── my_package_b-0.2.1-py3-none-any.whl

🚀 How to Use Clients / Package Managers

Since this registry is private, you must replace <YOUR-ORGANIZATION> with our actual GitHub organization name, and you will need a GitHub Personal Access Token (PAT) with read access to this repository.

1. Using Poetry

Add this registry as an explicit source in your pyproject.toml:

[[tool.poetry.source]]
name = "github-repository"
url = "https://github.com/iadvize/python-registry/main/simple/"
priority = "explicit"

Configure your credentials locally:

poetry config http-basic.github-repostory <your-github-username> <your-personal-access-token>

Install a package:

poetry add my-package-a --source github-repository

Using uv

Add this registry as an explicit source in your pyproject.toml:

[[tool.uv.index]]
name = "github-repository"
url = "https://github.com/iadvize/python-registry/main/simple/"

Install a package:

uv add my-package-a

Using pip

You can pass the extra index URL directly to pip. To handle private authentication seamlessly, include your token directly in the URL:

pip install my-package-a --extra-index-url https://<your-github-username>:<your-personal-access-token>@[raw.githubusercontent.com/](https://raw.githubusercontent.com/)<YOUR-ORGANIZATION>/python-registry/main/simple/

Or add it to your requirements.txt:

--extra-index-url https://<your-github-username>:<your-personal-access-token>https://iadvize/python-registry/main/simple/
my-package-a==1.0.0