docs: clarify multiple dependency constraints

[Mohamedajab]

Pull Request Check List

Resolves: #6625

Clarifies that each multiple-constraint item is an alternative selected by non-overlapping environment markers. It also explains the different goals for application and library constraints, adds a broad library-compatible example, and recommends minimizing equivalent alternatives to reduce solver work.

• Added tests for changed code. (Documentation-only; the TOML example was parsed with Python tomllib.)
• Updated documentation for changed code.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/dependency-specification.md" line_range="731-732" />
<code_context>
 {{% /note %}}

+Each item is an alternative requirement for the same dependency. Its `python` or
+`markers` expression selects the environments where that alternative applies, while
+`version` selects the dependency versions allowed in those environments. The
+environment expressions must not overlap: if two alternatives could both apply,
+Poetry cannot determine which requirement to use.
+
+Choose version constraints according to what your project supports. Applications often
</code_context>
<issue_to_address>
**issue:** The documentation incorrectly states that multiple-constraint alternatives must never have overlapping environment markers and that Poetry cannot resolve such cases. Poetry supports overlapping duplicate dependencies and raises an error specifically when overlapping version constraints are incompatible, so this guidance rejects valid compatible configurations.

**Triggers:** When a project uses multiple alternatives whose markers overlap but whose version constraints are compatible.

**Suggested fix:** Qualify the rule to explain that overlapping alternatives are allowed when Poetry can merge compatible constraints, while incompatible overlapping constraints fail resolution.

```suggestion
environment expressions may overlap when Poetry can merge compatible version constraints. If
multiple overlapping alternatives have incompatible version constraints, dependency resolution fails.
```
</issue_to_address>

Sourcery assessment

Approval pending. 1 finding to address first.

Blocking findings: docs/dependency-specification.md:732

---

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

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

Sourcery assessment

Approved.