Reviewer's Guide by Sourcery

This PR updates the dependency specification documentation to include explicit directory and file paths for local dependencies. The changes ensure that users have clear, practical examples when referencing dependencies via paths, which improves clarity and reduces potential confusion around relative vs. absolute paths.

No diagrams generated as the changes look simple and do not need a visual representation.

File-Level Changes

this is not a path dependency at all, it is a url dependency

Nop @dimbleby, it's path dependency for sure. I'm using one of my own packages as a Git submodule and imported it directly as a path dependency in Poetry.

Main Project (pyproject.toml):

[project]
name = "poetry-issue"
version = "0.1.0"
description = ""
authors = [
    { name = "Abdullah Alqahtani", email = "[email protected]" }
]
requires-python = ">=3.11,<4.0"
dependencies = [
    "xapi_guard_middleware @ file:///xapi_guard_middleware"
]
package-mode = false

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

Submodule Package (xapi_guard_middleware/pyproject.toml):

[tool.poetry]
name = "xapi-guard-middleware"
version = "1.0.6"
description = "XAPI Guard is a FastAPI middleware that protects your API endpoints by validating the X-API-Key header."
authors = [
    "Abdullah Alqahtani <[email protected]>"
]
packages = [
    { include = "xapi_guard_middleware" }
]
readme = "README.md"
license = "MIT"

[tool.poetry.dependencies]
python = ">=3.11,<4.0"
fastapi = ">=0.109.0,<0.115.8"

[tool.poetry.group.dev.dependencies]
pytest = "^8.3.4"
httpx = "^0.28.1"
pytest-asyncio = "^0.23.5"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

You can see in the image, that I imported the package as a path dependency.

It's 100% path dependency.

It is a url dependency using the file:// protocol

Hi @dimbleby,

Kindly check this

URL: https://python-poetry.org/docs/dependency-specification#path-dependencies

And you have 2 ways to import the package from the path:

1. from the tar.gz file

[project]
# ...
dependencies = [
    "my-package @ file:///absolute/path/to/my-package/dist/my-package-0.1.0.tar.gz"
]

2. from the entire folder (without building the package again)

[project]
# ...
dependencies = [
    "my-package @ file:///absolute/path/to/my-package"
]

Hi @dimbleby,

Kindly check this,

URL: https://python-poetry.org/docs/dependency-specification#url-dependencies

[project]
# ...
dependencies = [
    "my-package @ https://example.com/my-package-0.1.0.tar.gz"
]

This is an example of URL dependency,

When it's using HTTP, HTTPS and importing it from github, gitlab, bitbucket, etc...

@dimbleby bro it's very clear.

You are mistaken.

A "path dependency" is a poetry invention, there is no such thing in the standard python packaging world.

This is a file url.

You are mistaken.

A "path dependency" is a poetry invention, there is no such thing in the standard python packaging world.

This is a file url.

I know that, then it's file url dependency, is that ok?

It's really clear like soon 😶‍🌫️

Tell me @dimbleby what need to be added or changed in my PR?

In my opinion this section of the docs is mis-organised.

The split into "path" dependencies and "url" dependencies made sense when the primary syntax was poetry's own, and this distinction was real.

But now that PEP621 and standard dependencies are primary it makes more sense to treat them all as url dependencies - because that's what they are.

Maybe rearranging this is more than you want to take on, maybe maintainers will feel that the smaller change that you have here is an improvement anyway - even if there is more that could be done.

Deploy preview for website ready!

✅ Preview
https://website-aa82q467e-python-poetry.vercel.app

Built with commit 2f177b5.
This pull request is being automatically deployed with vercel-action

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.