Koschey
=======

Internal immortal PyPI index — Koschey, the package keeper.

``Koschey`` is a corporate PyPI index and package quarantine system.
It is designed to provide reliability, transparency, and control
over internal Python packages.

Why “Koschey”
-------------

The name comes from Koschey the Deathless — a figure from Russian folklore
who hid his soul inside an egg. ``Koschey`` likewise protects the soul of
each package — and keeps a close eye on Python eggs. 🥚🐍


.. code-block:: bash

    pip install koschey

Features
--------

``Koschey`` can act both as a transparent proxy to public Python repositories
and as a secure host for proprietary packages. It provides a unified, standards-compliant
and reliable internal index for engineering teams.

* **Mirror and cache.** Acts as a proxy to external repositories while keeping
  local copies of downloaded packages for reliability and auditability.
  Implements ``last-serial`` support for incremental sync and minimal traffic.
* **Private package hosting.** Supports direct upload and storage of proprietary
  distributions inside your organization.
* **Quarantine layer.** Packages mirrored from external sources are first placed
  in quarantine: they are downloaded and stored locally, but remain hidden from
  the ``simple`` API for a configured number of days. This allows time for
  automated checks or manual review. Individual versions can be approved
  explicitly, or entire projects can be marked as *trusted* to skip quarantine.
* **Administrative panel.** Provides a web interface with multiple permission
  levels and flexible ACL integration. Custom authentication or access control
  can be added through a Python extension.
* **Configurable networking.** Outgoing traffic for mirrors can be routed
  through custom proxy logic, also extendable via Python.
* **Standards compliance.** Implements key packaging standards:
  PEP 658 (wheel metadata), PEP 691 (JSON Simple API),
  and PEP 710 (provenance records).
* **Simple API.** Provides both the classic ``simple`` (HTML/XML) interface
  and JSON endpoints, compatible with ``pip``, ``uv`` and other tooling.
* **High traversal efficiency.** Optimized to walk and synchronize large
  package sets with minimal latency and bandwidth usage.

Architecture
------------

Koschey is built with reliability and transparency in mind.
It uses **PostgreSQL** as the primary database for package metadata,
state tracking, and audit logs, and an **S3-compatible object storage**
for package files and signatures.
The system consists of several independent components — API, Worker,
and Admin Panel — communicating through shared storage and the database.

Requirements
------------

* Python >= 3.12
* POSIX-compatible system

License
-------

Apache License 2.0 — see the ``LICENSE`` file for details.

Project links
-------------

* PyPI: https://pypi.org/project/koschey/
* Source: https://github.com/alvassin/koschey
* Issues: https://github.com/alvassin/koschey/issues
