Skip to content

Docs: add guide for mirroring from another Simple API mirror #2144

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vani2009 wants to merge 1 commit into from
Closed

Docs: add guide for mirroring from another Simple API mirror #2144

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/mirror_from_mirror_simple_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
Mirror from a mirror (Simple API)
=================================
Comment on lines +1 to +2
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new doc page isn’t linked from the main docs toctree (e.g. docs/index.rst), so it may not be discoverable or included in the built documentation. Please add it to an appropriate toctree so it appears in navigation/output.

Copilot uses AI. Check for mistakes.

Bandersnatch can mirror packages from another Python package index that
implements the Simple Repository API (PEP 503). This allows you to create
Copy link
Contributor

@cooperlees cooperlees Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
implements the Simple Repository API (PEP 503). This allows you to create
implements the Simple Repository API (PEP 503 + 691). This allows you to create

Please mention PEP691 as this is what defines the JSON we rely on :)

a secondary mirror from an existing mirror instead of directly from PyPI.

Configuration
-------------

Set the ``master`` option in your bandersnatch configuration to the base
URL of the upstream mirror.

Example::

[mirror]
master = https://example-mirror.org/simple/

Notes
-----

- The upstream mirror must implement the Simple Repository API (PEP 503).
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page says the upstream mirror only needs to implement the PEP 503 Simple Repository API, but Bandersnatch also requires PyPI’s JSON API (/pypi/<project>/json) for project metadata (as documented under master in docs/mirror_configuration.md). Please update the “Requirements/Notes” to state the upstream must provide the JSON API as well, and clarify that the “simple” API method uses PEP 691 JSON (via Accept: application/vnd.pypi.simple.v1+json), not just HTML PEP 503.

Suggested change
- The upstream mirror must implement the Simple Repository API (PEP 503).
- The upstream mirror must implement the Simple Repository API, supporting both:
- PEP 691 JSON responses for the Simple API via ``Accept: application/vnd.pypi.simple.v1+json``.
- PyPI's JSON project metadata API at ``/pypi/<project>/json``.

Copilot uses AI. Check for mistakes.
- Ensure the URL ends with ``/simple/``.
Comment on lines +12 to +23
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The master setting here is documented as pointing at the upstream /simple/ endpoint, but Bandersnatch’s Master.simple_url appends /simple to the configured base URL. Setting master = https://example-mirror.org/simple/ will result in requests to .../simple//simple and break mirroring; document master as the upstream base (e.g. https://example-mirror.org) and remove the “URL ends with /simple/” guidance.

Suggested change
URL of the upstream mirror.
Example::
[mirror]
master = https://example-mirror.org/simple/
Notes
-----
- The upstream mirror must implement the Simple Repository API (PEP 503).
- Ensure the URL ends with ``/simple/``.
URL of the upstream mirror (for example, ``https://example-mirror.org``).
Example::
[mirror]
master = https://example-mirror.org
Notes
-----
- The upstream mirror must implement the Simple Repository API (PEP 503).
- Bandersnatch will append ``/simple`` to the configured ``master`` URL.

Copilot uses AI. Check for mistakes.
- Some mirrors may have partial content or different filtering rules.
- Synchronization speed depends on the upstream mirror performance.

Comment on lines +19 to +26
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description mentions “Notes about JSON Simple API vs HTML”, but the content here doesn’t explain the PEP 691 JSON vs PEP 503 HTML distinction or what happens if the upstream only serves HTML. Consider adding a short note under “Notes” describing the required content-negotiation/JSON support and any fallback options (e.g., using api-method = xmlrpc where applicable).

Copilot uses AI. Check for mistakes.
Use cases
---------

- Creating an internal mirror from an organizational mirror
- Reducing load on PyPI by chaining mirrors
- Regional or offline mirror setups
Loading