docs: document python and platform dependency shorthands

[rumitvn]

Closes #9183

What

Adds a python and platform shorthands subsection to the Using environment markers part of the dependency-specification docs.

Why

The marker docs document the markers property but never document the python and platform shorthand keys available on long-form [tool.poetry.dependencies] entries, nor how they combine with an explicit markers value (the issue's three asks).

The new subsection covers:

• python → a version constraint on python_version (e.g. python = "^3.9" ⇒ python_version >= "3.9" and python_version < "4.0").
• platform → an exact match on sys_platform (e.g. platform = "darwin").
• That they are not deprecated, just shorthands, and that combining them with markers joins all conditions with and (with a worked example).
• That they are only available in the legacy [tool.poetry.dependencies] table; the PEP 621 [project] table uses inline PEP 508 markers instead.

Scoped to documenting current behavior. Docs-only change.

[sourcery-ai]

Hey - I've left some high level feedback:

• Since platform is described as an exact match on sys_platform, consider briefly clarifying what values Poetry expects there (e.g. darwin, win32, linux) or linking to where those canonical values are documented to avoid confusion with things like macOS.
• You describe [tool.poetry.dependencies] as the "legacy" table; it might help readers if you either link to or briefly reference the section explaining the preferred PEP 621 [project] usage so they can understand when to use each.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Since `platform` is described as an exact match on `sys_platform`, consider briefly clarifying what values Poetry expects there (e.g. `darwin`, `win32`, `linux`) or linking to where those canonical values are documented to avoid confusion with things like `macOS`.
- You describe `[tool.poetry.dependencies]` as the "legacy" table; it might help readers if you either link to or briefly reference the section explaining the preferred PEP 621 `[project]` usage so they can understand when to use each.

---

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