# poetry-plugin-pypi-mirror
## Description
*poetry-plugin-pypi-mirror* is a
[plugin](https://python-poetry.org/docs/master/plugins/) for
[poetry](https://python-poetry.org/), the Python packaging and dependency
manager. It enables poetry to substitute connections to pypi.org with
connections to a pypi.org mirror or pull-through cache **without requiring
project configuration changes**. This is ideal for situations where an
access-restricted or otherwise unsuitable-for-general-use pypi.org mirror must
be used by a subset of project contributors. For example:
* A private PyPI mirror internal to a business, required by company policy
* A limited-access PyPI mirror in a region where pypi.org is restricted
* A regional mirror that is more performant for a few users, and less performant
for everyone else
These mirrors can be used without this plugin by [adding them as project
repositories](https://python-poetry.org/docs/repositories/). However, this
requires the mirror to be included in the project's configuration, and this also
results in source entries for the mirror appearing in `poetry.lock`. Since only
a subset of project contributors can use these mirrors, that subset of users
would need to replace and remove references to the mirror repository each time
they want to contribute their changes back to the project. This is suboptimal.
## Usage
### Installation
Follow poetry's [plugin installation instructions](https://python-poetry.org/docs/master/plugins/#using-plugins), replacing `poetry-plugin` with `poetry-plugin-pypi-mirror`.
### Specifying a mirror
To specify a mirror, you can either define `plugins.pypi_mirror.url` in poetry's
[configuration](https://python-poetry.org/docs/configuration/), or set
environment variable `POETRY_PYPI_MIRROR_URL` to the full URL for a [PEP
503](https://peps.python.org/pep-0503/)-compatible mirror. When both are set the
environment variable will be used.
#### Poetry config example
```toml
[plugins]
[plugins.pypi_mirror]
url = "https://example.org/repository/pypi-proxy/simple/"
```
... in [either](https://python-poetry.org/docs/configuration/) a project's
`poetry.toml` (for per-project configuration), or the user's `config.toml`.
#### Environment variable example
```shell
POETRY_PYPI_MIRROR_URL=https://example.org/repository/pypi-proxy/simple/ poetry add pendulum
```
...or...
```shell
export POETRY_PYPI_MIRROR_URL=https://example.org/repository/pypi-proxy/simple/
poetry add cleo # uses mirror specified in first line
poetry lock # also uses mirror specified in first line
```
#### Authentication
If the mirror you're using requires authentication, you can add the credentials
like you would for any other repository.
Please note that repository names are case-sensitive, so it is important that
you configure the credentials for `PyPI`. `pypi` or other variations will not
work.
```shell
poetry config http-basic.PyPI <username> <password/token>
```
## Compatibility
*poetry-plugin-pypi-mirror* depends on poetry internals which can change between
poetry releases. It's important to ensure compatibility between the poetry
version in use and the plugin version in use.
| Poetry version(s) | Compatible plugin version(s) |
|-------------------|------------------------------|
| >= 1.3, < 1.9 | ^0.4.2 |
| ~1.2.1 | < 0.3.0 |
## Contributing
To contribute, open a [pull
request](https://github.com/arcesium/poetry-plugin-pypi-mirror/pulls).
### Sign your work
All commits must be signed to be accepted. Your signature certifies that you
have the right to submit your contribution(s) to the project, in accordance with
the principles described in the [Developer Certificate of
Origin](https://developercertificate.org/).
```
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```
To sign your commits, use the template below to generate a signature, and then
add that signature to your commit message(s):
```
Signed-off-by: Your Name <Your.Name@example.com>
```
You must use your true name. Pseudonyms are not permitted.
If you have set `git`'s `user.name` and `user.email`, you can sign commits
easily at commit time using `git commit -s`.
## See also
* [python-poetry/poetry#1632](https://github.com/python-poetry/poetry/issues/1632) - poetry feature request to add support for global repository URL replacement
Raw data
{
"_id": null,
"home_page": "https://github.com/arcesium/poetry-plugin-pypi-mirror",
"name": "poetry-plugin-pypi-mirror",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0.0",
"maintainer_email": "",
"keywords": "packaging,poetry,pypi",
"author": "Jacob Henner",
"author_email": "code@ventricle.us",
"download_url": "https://files.pythonhosted.org/packages/5f/1d/d7062f0c3b6c83144a77d3fe23b68c4c2bb9ad4c066565bfefaa467431f6/poetry_plugin_pypi_mirror-0.4.2.tar.gz",
"platform": null,
"description": "# poetry-plugin-pypi-mirror\n\n## Description\n\n*poetry-plugin-pypi-mirror* is a\n[plugin](https://python-poetry.org/docs/master/plugins/) for\n[poetry](https://python-poetry.org/), the Python packaging and dependency\nmanager. It enables poetry to substitute connections to pypi.org with\nconnections to a pypi.org mirror or pull-through cache **without requiring\nproject configuration changes**. This is ideal for situations where an\naccess-restricted or otherwise unsuitable-for-general-use pypi.org mirror must\nbe used by a subset of project contributors. For example:\n\n* A private PyPI mirror internal to a business, required by company policy\n* A limited-access PyPI mirror in a region where pypi.org is restricted\n* A regional mirror that is more performant for a few users, and less performant\n for everyone else\n\nThese mirrors can be used without this plugin by [adding them as project\nrepositories](https://python-poetry.org/docs/repositories/). However, this\nrequires the mirror to be included in the project's configuration, and this also\nresults in source entries for the mirror appearing in `poetry.lock`. Since only\na subset of project contributors can use these mirrors, that subset of users\nwould need to replace and remove references to the mirror repository each time\nthey want to contribute their changes back to the project. This is suboptimal.\n\n## Usage\n\n### Installation\n\nFollow poetry's [plugin installation instructions](https://python-poetry.org/docs/master/plugins/#using-plugins), replacing `poetry-plugin` with `poetry-plugin-pypi-mirror`.\n\n### Specifying a mirror\n\nTo specify a mirror, you can either define `plugins.pypi_mirror.url` in poetry's\n[configuration](https://python-poetry.org/docs/configuration/), or set\nenvironment variable `POETRY_PYPI_MIRROR_URL` to the full URL for a [PEP\n503](https://peps.python.org/pep-0503/)-compatible mirror. When both are set the\nenvironment variable will be used.\n\n#### Poetry config example\n\n```toml\n[plugins]\n[plugins.pypi_mirror]\nurl = \"https://example.org/repository/pypi-proxy/simple/\"\n```\n\n... in [either](https://python-poetry.org/docs/configuration/) a project's\n`poetry.toml` (for per-project configuration), or the user's `config.toml`.\n\n#### Environment variable example\n\n```shell\nPOETRY_PYPI_MIRROR_URL=https://example.org/repository/pypi-proxy/simple/ poetry add pendulum\n```\n\n...or...\n\n```shell\nexport POETRY_PYPI_MIRROR_URL=https://example.org/repository/pypi-proxy/simple/\npoetry add cleo # uses mirror specified in first line\npoetry lock # also uses mirror specified in first line\n```\n\n#### Authentication\n\nIf the mirror you're using requires authentication, you can add the credentials\nlike you would for any other repository.\n\nPlease note that repository names are case-sensitive, so it is important that\nyou configure the credentials for `PyPI`. `pypi` or other variations will not\nwork.\n\n```shell\npoetry config http-basic.PyPI <username> <password/token>\n```\n\n## Compatibility\n\n*poetry-plugin-pypi-mirror* depends on poetry internals which can change between\npoetry releases. It's important to ensure compatibility between the poetry\nversion in use and the plugin version in use.\n\n| Poetry version(s) | Compatible plugin version(s) |\n|-------------------|------------------------------|\n| >= 1.3, < 1.9 | ^0.4.2 |\n| ~1.2.1 | < 0.3.0 |\n\n## Contributing\n\nTo contribute, open a [pull\nrequest](https://github.com/arcesium/poetry-plugin-pypi-mirror/pulls).\n\n### Sign your work\n\nAll commits must be signed to be accepted. Your signature certifies that you\nhave the right to submit your contribution(s) to the project, in accordance with\nthe principles described in the [Developer Certificate of\nOrigin](https://developercertificate.org/).\n\n```\nDeveloper Certificate of Origin\nVersion 1.1\n\nCopyright (C) 2004, 2006 The Linux Foundation and its contributors.\n\nEveryone is permitted to copy and distribute verbatim copies of this\nlicense document, but changing it is not allowed.\n\n\nDeveloper's Certificate of Origin 1.1\n\nBy making a contribution to this project, I certify that:\n\n(a) The contribution was created in whole or in part by me and I\n have the right to submit it under the open source license\n indicated in the file; or\n\n(b) The contribution is based upon previous work that, to the best\n of my knowledge, is covered under an appropriate open source\n license and I have the right under that license to submit that\n work with modifications, whether created in whole or in part\n by me, under the same open source license (unless I am\n permitted to submit under a different license), as indicated\n in the file; or\n\n(c) The contribution was provided directly to me by some other\n person who certified (a), (b) or (c) and I have not modified\n it.\n\n(d) I understand and agree that this project and the contribution\n are public and that a record of the contribution (including all\n personal information I submit with it, including my sign-off) is\n maintained indefinitely and may be redistributed consistent with\n this project or the open source license(s) involved.\n```\n\nTo sign your commits, use the template below to generate a signature, and then\nadd that signature to your commit message(s):\n\n```\nSigned-off-by: Your Name <Your.Name@example.com>\n```\n\nYou must use your true name. Pseudonyms are not permitted.\n\nIf you have set `git`'s `user.name` and `user.email`, you can sign commits\neasily at commit time using `git commit -s`.\n\n## See also\n\n* [python-poetry/poetry#1632](https://github.com/python-poetry/poetry/issues/1632) - poetry feature request to add support for global repository URL replacement\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Poetry plugin that adds support for pypi.org mirrors and pull-through caches",
"version": "0.4.2",
"project_urls": {
"Homepage": "https://github.com/arcesium/poetry-plugin-pypi-mirror",
"Repository": "https://github.com/arcesium/poetry-plugin-pypi-mirror"
},
"split_keywords": [
"packaging",
"poetry",
"pypi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "248e80f3616ed9831e16614540601e68336e9866a334d1a3ffd1d80c03d27139",
"md5": "a282b5d046d0d183c9bd7a65d5256e59",
"sha256": "10e856491df18ef266138d5da7d857f609ac2abe8f4e4b8b6906fb98b46fff53"
},
"downloads": -1,
"filename": "poetry_plugin_pypi_mirror-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a282b5d046d0d183c9bd7a65d5256e59",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0.0",
"size": 7309,
"upload_time": "2024-03-03T08:34:24",
"upload_time_iso_8601": "2024-03-03T08:34:24.764911Z",
"url": "https://files.pythonhosted.org/packages/24/8e/80f3616ed9831e16614540601e68336e9866a334d1a3ffd1d80c03d27139/poetry_plugin_pypi_mirror-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5f1dd7062f0c3b6c83144a77d3fe23b68c4c2bb9ad4c066565bfefaa467431f6",
"md5": "142f1ffa586c08546def1e275c06a7f5",
"sha256": "ea1bddbece78c92d4c4f3a90cb9cc76fd62935309b16ca276f4743e102cc1ba6"
},
"downloads": -1,
"filename": "poetry_plugin_pypi_mirror-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "142f1ffa586c08546def1e275c06a7f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0.0",
"size": 6273,
"upload_time": "2024-03-03T08:34:28",
"upload_time_iso_8601": "2024-03-03T08:34:28.968149Z",
"url": "https://files.pythonhosted.org/packages/5f/1d/d7062f0c3b6c83144a77d3fe23b68c4c2bb9ad4c066565bfefaa467431f6/poetry_plugin_pypi_mirror-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-03 08:34:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "arcesium",
"github_project": "poetry-plugin-pypi-mirror",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "poetry-plugin-pypi-mirror"
}
JSON
