Skip to content

Update repositories.md #5605

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

Merged
neersighted merged 6 commits into from
Sep 18, 2022
Merged

Update repositories.md #5605

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c530dac
Update repositories.md
jonapich May 13, 2022
e882e11
review comments, clarifications
jonapich May 18, 2022
9796418
Apply suggestions from code review
jonapich May 24, 2022
576b649
Update repositories.md
jonapich May 24, 2022
8cf774d
Update repositories.md
jonapich May 24, 2022
ec77eed
Apply suggestions from code review
jonapich Jun 6, 2022
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
49 changes: 35 additions & 14 deletions docs/repositories.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,11 @@ By default, Poetry discovers and installs packages from [PyPI](https://pypi.org)
install a dependency to your project for a [simple API repository](#simple-api-repository)? Let's
do it.

First, [configure](#project-configuration) the [package source](#package-source) repository to your
First, [configure](#project-configuration) the [package source](#package-source) as a secondary repository to your
project.

```bash
poetry source add foo https://pypi.example.org/simple/
poetry source add --secondary foo https://pypi.example.org/simple/
```

Then, assuming the repository requires authentication, configure credentials for it.
Expand Down Expand Up @@ -94,13 +94,20 @@ when publishing a package.

### Project Configuration

These package sources maybe managed using the [`source`]({{< relref "cli#source" >}}) command for
These package sources may be managed using the [`source`]({{< relref "cli#source" >}}) command for
your project.

```bash
poetry source add foo https://foo.bar/simple/
```

{{% note %}}

If your package source requires [credentials](#configuring-credentials) or
[certificates](#certificates), please refer to the relevant sections below.

{{% /note %}}

This will generate the following configuration snippet in your
[`pyproject.toml`]({{< relref "pyproject" >}}) file.

Expand All @@ -112,23 +119,26 @@ default = false
secondary = false
```

{{% warning %}}

If package sources are defined for a project, these will take precedence over
[PyPI](https://pypi.org). If you do not want this to be the case, you should declare **all** package
sources to be [secondary](#secondary-package-sources).

{{% /warning %}}
Any package source defined like this takes precedence over [PyPI](https://pypi.org).

See [Supported Package Sources](#supported-package-sources) for source type specific information.

{{% note %}}

If your package source requires [credentials](#configuring-credentials) or
[certificates](#certificates), please refer to the relevant sections below.
If you prefer to disable [PyPI](https://pypi.org) completely, you may choose to set one of your package sources to be the [default](#default-package-source).

To enable a package source only for a specific dependency, see [Secondary Package Sources](#secondary-package-sources).
Copy link
Member

@abn abn May 19, 2022

Choose a reason for hiding this comment

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

Suggested change
To enable a package source only for a specific dependency, see [Secondary Package Sources](#secondary-package-sources).
If the package source provides only specific dependencies, see [Secondary Package Sources](#secondary-package-sources).

Copy link
Contributor Author

@jonapich jonapich May 24, 2022

Choose a reason for hiding this comment

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

I think this suggestion makes it unclear what this is about. I rephrased to:

If you prefer to specify a package source for a specific dependency, see Secondary Package Sources.


{{% /note %}}


{{% warning %}}

If you do not want any of the custom sources to take precedence over [PyPI](https://pypi.org),
you must declare **all** package sources to be [secondary](#secondary-package-sources).

{{% /warning %}}


#### Default Package Source

By default, Poetry configures [PyPI](https://pypi.org) as the default package source for your
Expand Down Expand Up @@ -171,7 +181,18 @@ If you wish to avoid this, you may explicitly specify which source to search in
package.
Copy link
Member

@abn abn May 19, 2022

Choose a reason for hiding this comment

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

As per your comment, this maybe replaced like this.

- If you wish to avoid this, you may explicitly specify which source to search in for a particular package.
+ In order to limit the search for a specific package to a particular package source, you can explicitly specify what source to use.

Copy link
Contributor Author

@jonapich jonapich May 24, 2022

Choose a reason for hiding this comment

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

So, I applied this, but is limit still true here? It is stated that:

All package sources (including secondary sources) will be searched during the package lookup process. These network requests will occur for all sources, regardless of if the package is found at one or more sources.

and:

If package sources are configured as secondary, all it means is that these will be given a lower priority when selecting compatible package distribution that also exists in your default package source.

So it seems like --secondary and source = my-secondary-index only means the search is prioritized there, and not limited there. However, I cannot test this, because my internal pypi server redirects me to pypi.org if a package is missing.

Copy link
Member

@neersighted neersighted Jun 4, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

source = should restrict the dep to only that repository -- if we're doing otherwise, that's a bug.

Copy link
Contributor Author

@jonapich jonapich Jun 6, 2022

Choose a reason for hiding this comment

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

It's difficult for me to assert this, because my private pypi is set to redirect to pypi.org on missing packages.

Since this closely touches security, there really should be a unit test that asserts it.


```bash
poetry add --source pypi httpx
poetry add --source internal-pypi httpx
```

```toml
[tool.poetry.requirements]
httpx = { version = "*", source = "internal-pypi" }
urllib3 = "*"

[[tool.poetry.source]]
name = "internal-pypi"
url = "https://foo.bar/simple/"
secondary = true
```

{{% /note %}}
Expand Down