pypa / pypa/packaging.python.org

Canonical guide to specifying dependencies?

Open
#685 9 comments 11 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

component: guides help wanted type: enhancement
Dominant language
Python
Stars
1.7k
Forks
1.7k
Avg merge
3d 12h
Merged PRs (30d)
4

Description

We should probably have a canonical guide to installing dependencies on packaging.python.org, especially since PEP 508 has changed things like how to link to a git repository. I get a lot of questions like, "Why are my dependency links not working now?" and since I don't really use those I can just tell people, "Oh something about that changed, here's an inscrutable PEP that maybe would help"?

This could be done incrementally (and can be broken into smaller parts, providing there is "clearing house" page that links to the other pages), but it would be nice to clearly cover:

  1. The syntax for declaring dependencies
  2. The syntax for environment markers
  3. How to declare dependencies to a URL (i.e. not PyPI)
  4. The differences between what goes in a requirements.txt file and what can be declared in install_requires
  5. The use of constraints.txt files (which I think really reduces the need for requirements.txt.
  6. How to use extras.
  7. What is and is not allowed as a dependency in packages uploaded to PyPI.

Some of this is defined in various PEPs, but my understanding is that the canonical and current documentation should live on packaging.python.org.

There should also probably be a "hat note" (Wikipedia terminology) pointing to any such page from managing application dependencies to this page.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing managing application dependencies tutorial and PEP 508, then audit the current packaging.python.org documentation for dependency guidance. A complete result would provide a canonical guide covering the seven listed dependency topics and link to it from the tutorial.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.