docs(dependency-specification): update dependency specification examp…

[anqorithm]

Description

This PR updates the dependency specification example in the documentation to include directory and file paths for better clarity. The update ensures that users can correctly reference dependencies in various directory structures, reducing confusion when specifying dependencies in pyproject.toml.

Changes Made

• Updated the dependency specification example to include explicit directory and file paths.
• Improved documentation to align with best practices.

Why This Change?

• Helps users correctly specify dependencies from local paths.
• Enhances clarity in documentation, especially for new users.
• Addresses potential confusion when using relative vs. absolute paths.

Checklist

• Added tests for changed code (if applicable).
• Updated documentation for changed code.

---

Summary by Sourcery

Clarify dependency specification examples by adding directory and file paths to guide users on referencing dependencies within different project structures.

Enhancements:

• Improve the clarity and precision of dependency specifications.

Documentation:

• Illustrate how to specify dependencies using both directory and file paths in pyproject.toml.

[sourcery-ai]

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

Change	Details	Files
Enhanced dependency specification example by incorporating explicit directory and file paths.	Added a directory path example to demonstrate how to reference local packages. Inserted a file path example to illustrate package referencing from a specific file in the distribution. Improved overall documentation clarity and adherence to best practices.	docs/dependency-specification.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!
• Generate a plan of action for an issue: Comment @sourcery-ai plan on
  an issue to generate a plan of action for it.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @anqorithm - I've reviewed your changes - here's some feedback:

Overall Comments:

• Consider adding examples for other dependency specification methods, such as using relative paths.

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[dimbleby]

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

[anqorithm]

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 = "anqorithm@protonmail.com" }
]
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 <anqorithm@protonmail.com>"
]
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.

[dimbleby]

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

[anqorithm]

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"
]

[anqorithm]

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...

[anqorithm]

@dimbleby bro it's very clear.

[dimbleby]

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.

[anqorithm]

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 😶‍🌫️

[anqorithm]

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

[dimbleby]

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.