Docs: adding a note about being able to specify a package's source repository

[glencairn]

Pull Request Check List

Resolves: #3476

• Added tests for changed code. (N/A)
• Updated documentation for changed code.

---

Adding a little note to the documentation about the ability to specify the source repository for a dependency.

As mentioned in the linked issue, poetry's dependency resolution was failing because the first private repository poetry looked in for a specified dependency returned a 404. Whether or not that's the right behavior is a different discussion, but the problem can immediately be solved using the source property.

[sinoroc]

I link https://github.com/python-poetry/poetry/issues/3269 as somewhat related.

[glencairn]

@sinoroc, thanks for the link. I also updated the list of options in the documentation for the poetry add command since it was definitely missing several of the available options.

[lcbm]

Sorry in advance, if this isn't the right place to ask... also, if there's documentation on what I'm about to say, please LMK! I wasn't able to find anything on source usage and it's intended behavior 😭

It is clear to me, from the documentation in this MR, that one purpose of source is to specify, from a bunch of external sources I may have, which one I want to use for each specific package.

Before elaborating what is not clear to me, please consider the pyproject.toml below 👇

[tool.poetry.dependencies]
private-dependency = {version = "^1.0.0", source = "private-source"}

# and 'private-dependency' depends on a 'public-library' which is not in "private-source" (my private registry)

[[tool.poetry.source]]
name = "private-source"
url = "https://foo.bar/simple/"
default = true

It is not clear to me if:

1. source will enforce that private-dependency and all of its requirements are installed from private-source (as pip does with --index-url) OR if source will enforce that only private-dependency is installed from private-source and its requirements will be installed according to poetry's default behavior (precedence to source but will still look for the private-dependency's dependencies in pypi);

2. let's say I have multiple sources in my pyproject.toml as well as multiple dependencies and each dependency is referencing their own source. If I want to ensure that each of my dependencies are looked up exclusively in their respective sources, can I set all my sources with default = true under [[tool.poetry.source]]?

Lastly, I looked for an example pyproject.toml with multiple repositories here and couldn't find one... I'll drop a suggestion here to add a piece in this MR for that as well, considering that it's in that context that source should be used 😄

[ggabriel96]

There's another PR doing this, #3400. It's just missing the CLI docs.

[neersighted]

Rebased onto current master. Just waiting on the CI to be unbroken to merge this (see #4753).

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.