enh: update dependency page to support pep 735 and uv #584

lwasser · 2025-11-04T19:40:30Z

No description provided.

lwasser · 2025-11-04T19:42:30Z

package-structure-code/declare-dependencies.md

-To ensure this works as you want it to, activate your package's development
-environment prior to installing anything using `pip`.
+:::{todo}
+We shouldn't show UV pip install, so how do you add optional feature deps with UV??


@zanieb I wondered if you could help us here by reviewing this and helping me understand how astral expects users to use uv to install things like feature dependencies etc. Adding deps is super easy and clear to me but i'd love your input on this pr if you have bandwidth.

lwasser · 2025-11-04T19:43:35Z

package-structure-code/declare-dependencies.md

+**Install optional dependencies:**
+```bash
+# FIXME
+uv pip install -e ".[docs]"              # Single group


Will uv sync sync everything or do you have to tell it to sync specific groups? uv pip install could install into the wrong environment i think?

so i did figure out that you can uv sync --group so it won't install group items by default but you can ask it to and it will.

The different tho is if we use hatch - it's a different model entirely. where you tell Hatch what features or groups to install into individual, unique environments, whereas UV just plops things into a single project-based envt. 🤯

There's also the --active flag that will choose whatever environment that is currently active

@all-contributors please add @yeelauren for docs, review

lauren i've turned this into an issue to address in the pr for this same page (that i'll reopen next week) post workshop!!

lwasser · 2025-11-04T19:43:47Z

package-structure-code/declare-dependencies.md

-`python -m pip install ".[tests]"`
+You can use uv sync to sync dependency groups too
+```bash
+# TEST ME


This all works perfectly

lwasser · 2025-11-04T19:43:57Z

package-structure-code/declare-dependencies.md

+You can use uv sync to sync dependency groups too
+```bash
+# TEST ME
+uv sync --group docs                     # Single group


need to test groups like this...

this also works well.

lwasser · 2025-11-04T19:45:00Z

We might want to add hatch environment examples with task runner features... in a small breakout ...

lwasser · 2025-11-04T19:45:47Z

we should also update this graphic when we are happy with this.

ucodery · 2025-11-04T21:21:46Z

images/python-package-dependency-types.png

I think this change makes the diagram a bit misleading now. Dependency Groups do not have to include your package, nor any subset of your package's required dependencies. They certainly can, by including your package just as any other dependency, but they can also be entirely disjointed.

You're right - I can take another stab at this tomorrow - maybe dependency groups are to the side in a small bubble?

so we have optional and your package which overlap as optional is for features. (and sometimes tests? if people include them)

And the dependency groups are development focused - not ever user facing.
Does this sound reasonable?

Yes, it's kind of awkward because there certainly will be some dependency groups that will be off in their own bubble (formatter environments) but others that will be supersets, like in the old graphic (test environments, generally)

package-structure-code/declare-dependencies.md

ucodery · 2025-11-04T21:29:39Z

package-structure-code/declare-dependencies.md

+
+```toml
+dependencies = [
+                "pandas",


This seems like a wild toml format 😶

Oh gosh - i'll look at this again tomorrow - i was jumping between the template - i have done a fairly big cleanup and this page. 😆

ucodery · 2025-11-04T21:31:32Z

package-structure-code/declare-dependencies.md


-Optional dependencies dependencies can be optionally installed by users
-depending upon their needs. There are two broad groups of optional dependencies:
+Optional (or feature) dependencies can be installed by users as needed. They add specific features to your package that not all users might need.  For example, if your package has an optional interactive plotting feature that uses Bokeh, you would list Bokeh as a feature dependency so users who don't need plotting don't have to install it.


This doc seems to now be missing a section, ### Group Dependencies

it's at the bottom - i am doing a big reorg now. I'm going to push what I have and will pick up again tomorrow so that this is all clearer. i hear you that it's not well organized.

ucodery · 2025-11-04T21:32:30Z

package-structure-code/declare-dependencies.md

-### Understanding optional vs. required dependencies
-You can think about dependencies as being either optional or required. If they are required, they will be listed in the `dependencies` key in the `project` table of your `pyproject.toml` file. If they are optional, they will be listed in the `[optional.dependencies]` table of your `pyproject.toml`.
+Specifying dependencies in your `pyproject.toml` file ensures that your package works correctly.
+Users automatically get the packages your code needs to run. For instance, if your package requires Pandas to run properly, Pandas will be installed into the users' environment when they install your package using uv, pip or conda, if you specify it as a dependency in your pyproject.toml file.


Not sure why you removed all the <code> embellishing in this paragraph.

ooh can you help me understand that comment Jeremiah? I added a paragraph (essentially, there was a todo from Jonny on adding a paragraph about the why). So this is a new paragraph that introduces why we need / care about dependencies and then we can talk more about the different kinds. as i'm writing this - i am realizing it's also confusing here because there are 3 kinds and only 1 is really necessary for a user to ensure the package works.

oh, nothing so significant. I just mean that the pyproject.toml and other TOML fields had their backticks removed.

ucodery · 2025-11-04T21:36:18Z

package-structure-code/declare-dependencies.md

+`python -m pip install plotMe`

-This means that in order for plotMe to work in a user's `environment` when installed, you also need to ensure that they have both of those required `dependencies` installed in their environment too.
+or if plotMe is in the pyproject.toml:


I think this needs expaned. "if plotMe is in the pyproject.toml's project.dependencies"? Or do you mean plotMe is the package, or something else?

oh no that's a blatant typo.

ucodery · 2025-11-04T21:38:07Z

package-structure-code/declare-dependencies.md


-1. Add a `[project.optional-dependencies]` table to your **pyproject.toml** file.
-2. Create named groups of dependencies using the syntax:
+You can also add feature dependencies to the


I don't see what this example specifically adds to the Dependency Group section.

I have removed this (I think). I wanted to touch on the fact that some people might include tests in the optional dependency group, as some people like to ship tests with their package (like the core scientific packages). I think it's just as confusing as I wrote it. For some reason, the packaging template really fries my brain when I work on it. it requires a lot of focus.

ucodery · 2025-11-04T21:39:34Z

package-structure-code/declare-dependencies.md

-Below we've created three sets of optional development dependencies named: tests, docs and lint. We've also added a set of feature dependencies.
+Will add this to your pyproject.toml
+```toml
+feature = [


This toml break-out needs to have the section header. This looks like a top-level field.

added throughout. i also reorganized to make this more clear.

package-structure-code/declare-dependencies.md

ucodery · 2025-11-04T22:05:25Z

package-structure-code/declare-dependencies.md

 :::{figure-md} python-package-dependencies

-<img src="../images/python-package-dependencies.png" alt="Diagram showing a Venn diagram with three sections representing the dependency groups listed above - docs feature and tests. In the center it says your-package and lists the core dependencies of that package seaborn and numpy. To the right are two arrows. The first shows the command python - m pip install your-package. It them shows how installing your package that way installs only the package and the two core dependencies into a users environment. Below is a second arrow with python -m pip install youPackage[tests]. This leads to an environment with both the package dependencies - your-package, seaborn and numpy and also the tests dependencies including pytest and pytest-cov ">
+<img src="../images/python-package-dependencies.png" alt="Diagram showing a Venn diagram with three sections representing dependency groups - docs, feature, and tests. In the center it shows your-package with core dependencies seaborn and numpy. Two arrows on the right demonstrate: first, python -m pip install your-package installs only the package and core dependencies. Second, python -m pip install your-package[tests] installs the package, core dependencies, and test dependencies including pytest and pytest-cov.">


I don't think the diagram does show any pip commands, unless I am missing something.

This is the image that i pasted into the pr body that this caption references- i haven't touched it yet because all of the UV stuff is new here. I'm trying to figure out ways to update our graphics and explain these 3 types of deps clearly.

My goal with this graphic was to show a user that the different types of dependencies may or may not install into their environments depending on how they call things when they use pip.

But the reason I haven't touched this graphic is that UV has a different model of doing things than pip does. And i also think i'm getting stuck on - thinking about how a user might install vs how a developer might install.

I think my brain was a bit fried from working on the packaging template, but I also welcome all of this feedback, and I'll make a point to work on this page FIRST in the morning tomorrow. But also, I'm not sure if we need a different structure here. The old structure isn't right!

This also relates to my question below - where uv pip install can be a bit dangerous (as we learned!!), and it might be better to avoid it. but there are users still using pip. and uv is newer.

i'm not sure how to manage messaging around this and am open to suggestions.

zanieb · 2025-11-04T23:08:58Z

Cool! I'll add this to my todo list (I'm at an onsite through the end of the week though so it'll be next week)

package-structure-code/declare-dependencies.md

lwasser · 2025-11-05T16:50:27Z

Cool! I'll add this to my todo list (I'm at an onsite through the end of the week, though so it'll be next week)

ok fantastic. I will create a shiny new pr with all of this content for review next week (I'm going to merge later today for a workshop tomorrow), but then we can do a proper review next week! Thank you so so much! My biggest question now relates to using uv pip install.

lwasser · 2025-11-05T16:56:41Z

Ok fantastic. i've made signfiicant improvements to this page. the plan:

merge it tonight before tomorrow's workshop
reopen a pr tonight or tomorrow with every line available for comment / edits, etc, so we can evaluate the entire page.
what's missing - links to using our copier template!

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

Co-authored-by: Jeremiah Paige <ucodery@gmail.com>

lwasser commented Nov 4, 2025

View reviewed changes

lwasser closed this Nov 4, 2025

lwasser reopened this Nov 4, 2025

lwasser force-pushed the dev branch from 0fcb7f5 to a929ba8 Compare November 4, 2025 19:47

ucodery reviewed Nov 4, 2025

View reviewed changes

willingc reviewed Nov 4, 2025

View reviewed changes

package-structure-code/declare-dependencies.md Outdated Show resolved Hide resolved

package-structure-code/declare-dependencies.md Outdated Show resolved Hide resolved

lwasser commented Nov 5, 2025

View reviewed changes

package-structure-code/declare-dependencies.md Outdated Show resolved Hide resolved

lwasser and others added 10 commits November 5, 2025 15:36

enh: update dependency page to support pep 735 and uv

503e046

enh: specifiers

bda0298

Apply suggestion from @willingc

c4daff9

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

Apply suggestion from @willingc

2b7e695

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

Apply suggestion from @ucodery

8f628da

Co-authored-by: Jeremiah Paige <ucodery@gmail.com>

Apply suggestion from @ucodery

7e85436

Co-authored-by: Jeremiah Paige <ucodery@gmail.com>

Apply suggestion from @lwasser

75f8d7c

enh: reorg

b367af1

enh: updates to deps page

c868504

enh: updates to deps page

d0a0100

lwasser force-pushed the dev branch from f3007b8 to d0a0100 Compare November 5, 2025 22:36

lwasser mentioned this pull request Nov 6, 2025

Add the --active flag that will choose whatever environment that is currently active #586

Open

lwasser merged commit d1f3d1f into pyOpenSci:main Nov 6, 2025
4 checks passed

lwasser deleted the dev branch November 6, 2025 15:22

matthewfeickert mentioned this pull request Nov 8, 2025

enh: Revise Pixi subsection in package dependency section #587

Open

enh: update dependency page to support pep 735 and uv #584

enh: update dependency page to support pep 735 and uv #584

Uh oh!

Conversation

lwasser commented Nov 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lwasser commented Nov 4, 2025

Uh oh!

lwasser commented Nov 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ucodery Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb commented Nov 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lwasser commented Nov 5, 2025

Uh oh!

lwasser commented Nov 5, 2025

Uh oh!

Uh oh!

ucodery Nov 4, 2025 •

edited

Loading