From 9940eaed2cee41996b85007b6155aaba1184f124 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Thu, 21 May 2026 22:01:52 -0700
Subject: [PATCH 01/15] Added packaging guide entry on dependency locking

---
 .../declare-dependencies.md                   | 156 ++++++++++++++++++
 1 file changed, 156 insertions(+)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 56519a44..45d3abfd 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -506,3 +506,159 @@ Why you specify dependencies
 How to specify dependencies
 When you use different specifiers
 :::
+
+## Dependency Locking
+
+In addition to declaring dependencies in `pyproject.toml`, it is common for
+packages to lock down exact versions of all their dependencies in a separate
+lock file. A lock file provides benefits of reproducibilty, security, and
+potentially faster installs, among other things.
+
+### `pyproject.toml` vs lock file
+* `pyproject.toml`: provides the range of requirements for others to
+use your package in their project.
+* **lock file**: records a fully resolved environment for working with or on
+your package directly
+
+:::{admonition} Official Lock File
+:class: note
+As of March 2025, [PEP 751](https://pep.python.org/pep-0751) defined a standard
+`pylock.toml` format to unify the various lock file formats in use by other
+package managers (e.g. `uv.lock`, `poetry.lock`, `pdm.lock`). Most package
+managers provide ways to generate a PEP 751 compatible file. See [PyPA
+specification](https://packaging.python.org/en/latest/specifications/pylock-toml/)
+for up-to-date formatting info on `pylock.toml`
+:::
+
+### How to work with lock files?
+
+Lock files are not maintained manually. Package managers and IDEs provide tools
+to create, update, and reformat lock files as needed. Below are common package
+manager CLI workflows for lock files:
+
+::::{tab-set}
+
+:::{tab-item} uv (recommended)
+```sh
+# Create a uv.lock file based on pyproject.toml
+> uv lock
+
+# Update uv.lock
+> uv lock --upgrade
+
+# Install packages into environment based on uv.lock
+> uv sync
+
+# PEP 751 pylock.toml support
+> uv export --format pylock.toml -o pylock.toml # export uv.lock -> pylock.toml
+> uv pip sync pylock.toml                       # install from pylock.toml
+```
+See [official docs](https://docs.astral.sh/uv/concepts/projects/sync/) for more details
+:::
+
+:::{tab-item} Poetry
+```sh
+# Create a poetry.lock file based on pyproject.toml
+> poetry lock
+
+# Update poetry.lock
+> poetry update
+
+# Install packages into environment based on poetry.lock
+> poetry sync
+
+```
+PEP 751 pylock.toml not yet supported (track progress on [GitHub](https://github.com/python-poetry/poetry/issues/10356))
+
+See [official docs](https://python-poetry.org/docs/basic-usage/#installing-dependencies) for more details
+:::
+
+:::{tab-item} PDM
+```sh
+# Create a pdm.lock file based on pyproject.toml
+> pdm lock
+
+# Update pdm.lock
+> pdm update
+
+# Install packages into environment based on pdm.lock
+> pdm sync
+
+# PEP 751 pylock.toml support
+> pdm export -f pylock -o pylock.toml  # export pdm.lock -> pylock.toml
+> pdm lock --lockfile pylock.toml      # install from pylock.toml
+```
+See [official docs](https://pdm-project.org/latest/usage/lockfile/) for more details
+:::
+
+::::
+
+### Should I use a lock file?
+
+Most package managers will maintain a lock file automatically for you (e.g. uv,
+Poetry, PDM). The real question is when you version control the lock file as
+part of your package.
+
+:::{admonition} Rule of Thumb
+:class: tip
+If your project is an application others use directly, include a lock file as
+the recommended environment.
+
+If your project is a library to be used in other projects and it is mature
+enough to have CI, include a lock file for CI and contributors.
+
+:::
+
+There is some maintenance cost from lock files. Maintainers should aim to update
+the lock file neither too rarely nor too often.
+* Too rarely means you risk missing updates with bugfixes, security patches,
+performance improvements, etc.
+* Too often means you may introduce bugs or even security vulnerablilites before
+maintainers of your dependencies catch them. Package managers are starting to
+support [dependency cooldowns](
+https://blog.pypi.org/posts/2026-04-02-incident-report-litellm-telnyx-supply-chain-attack/#dependency-cooldowns
+) to mitigate this.
+
+When you decide to update a lock file, consider what changed before committing
+it to the project. Good changes to focus on are
+1) major version updates (e.g.  `pandas 2.X.X` -> `pandas 3.X.X`)
+2) new transitive dependencies (i.e. not part of your `pyproject.toml`)
+
+:::{tip}
+A lock file captures one tested environment, not the full compatibility range
+declared in `pyproject.toml`. Projects that use lock files should still have CI
+test other environments such as
+
+1) the latest packages consistent with your `pyproject.toml`, subject to
+dependency cooldowns. This lets you know if a dependency update breaks your
+package.
+2) older supported versions of Python to let you know if a recent change to your
+package no longer works with an older Python release.
+:::
+
+
+::::{dropdown} What about `requirements.txt`
+:icon: info
+:color: primary
+
+Older approaches to locking used `pip freeze` to generate a `requirements.txt`
+that got used as a lock file. These are minimal lock files that pin a specific
+version for the system on which the command was run. They might look like
+```
+# requirements.txt
+numpy==2.4.6
+plotly==6.7.0
+pyzmq==27.1.0
+```
+
+However, this minimal level of specificity has several downsides making lock
+files the preferred format:
+* The versions satisfying `pyproject.toml` may differ between your MacOS and the
+Linux server your CI runs on. Lock files contain platform-specific resolutions
+* Packages can get updated without a version update for both legitimate and
+malicious reasons. Lock files specify exact hashes to catch this.
+* Other metadata determined during resolution of `pyproject.toml` (e.g. which
+dependencies are transitive, where the packages were downloaded from, etc.) that
+can help speed up future installs is lost.
+
+::::

From 51df0f9c83689287b3d9913e584a662b889c018c Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 10:27:01 -0700
Subject: [PATCH 02/15] Clarify pyproject.toml vs lock file

---
 package-structure-code/declare-dependencies.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 45d3abfd..23a24afa 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -515,10 +515,9 @@ lock file. A lock file provides benefits of reproducibilty, security, and
 potentially faster installs, among other things.
 
 ### `pyproject.toml` vs lock file
-* `pyproject.toml`: provides the range of requirements for others to
-use your package in their project.
-* **lock file**: records a fully resolved environment for working with or on
-your package directly
+* `pyproject.toml`: defines all supported environments for users importing
+your package into their project.
+* **lock file**: defines a specific environment used for development
 
 :::{admonition} Official Lock File
 :class: note

From 185b382fab8d4f3dbe7b3c750f1cda551815761c Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 10:31:38 -0700
Subject: [PATCH 03/15] maintained to written

---
 package-structure-code/declare-dependencies.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 23a24afa..87b7b028 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -531,7 +531,7 @@ for up-to-date formatting info on `pylock.toml`
 
 ### How to work with lock files?
 
-Lock files are not maintained manually. Package managers and IDEs provide tools
+Lock files are not written by hand. Package managers and IDEs provide tools
 to create, update, and reformat lock files as needed. Below are common package
 manager CLI workflows for lock files:
 

From cd2c12f1a56a602d1e5b7d1478c28b90b1e0948a Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 11:09:16 -0700
Subject: [PATCH 04/15] Prose description of lock file operations

---
 package-structure-code/declare-dependencies.md | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 87b7b028..27550bc1 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -532,8 +532,19 @@ for up-to-date formatting info on `pylock.toml`
 ### How to work with lock files?
 
 Lock files are not written by hand. Package managers and IDEs provide tools
-to create, update, and reformat lock files as needed. Below are common package
-manager CLI workflows for lock files:
+to create, update, and reformat lock files as needed.
+
+1) **Create** - Package managers often do this automatically though it can be
+done manually. For example, calling `uv add numpy` will automatically create a
+`uv.lock` file, setup the environment, and install numpy.
+2) **Update** - This is not done automatically by package managers.
+Maintainers can choose to do this manually or setup their own automated
+workflow. Updates can be for specific packages or all dependencies.
+3) **Reformat** - Package managers currently use native formats (e.g.
+uv uses `uv.lock`) and provide tools for converting into `pylock.toml` and other
+formats (e.g. `requirements.txt`) when needed
+
+Below are common package manager CLI workflows for lock files:
 
 ::::{tab-set}
 
@@ -544,6 +555,7 @@ manager CLI workflows for lock files:
 
 # Update uv.lock
 > uv lock --upgrade
+> uv lock --upgrade-package pandas
 
 # Install packages into environment based on uv.lock
 > uv sync
@@ -562,6 +574,7 @@ See [official docs](https://docs.astral.sh/uv/concepts/projects/sync/) for more
 
 # Update poetry.lock
 > poetry update
+> poetry update pandas numpy
 
 # Install packages into environment based on poetry.lock
 > poetry sync

From a1664bcd83d4ae5ac3852a403901939be38eeaae Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 11:25:49 -0700
Subject: [PATCH 05/15] Clarify checking diff of lock file is not necessary

---
 package-structure-code/declare-dependencies.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 27550bc1..302b213e 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -631,8 +631,13 @@ support [dependency cooldowns](
 https://blog.pypi.org/posts/2026-04-02-incident-report-litellm-telnyx-supply-chain-attack/#dependency-cooldowns
 ) to mitigate this.
 
-When you decide to update a lock file, consider what changed before committing
-it to the project. Good changes to focus on are
+When you decide to update a lock file, make sure to test that the resulting
+environment works before committing. If it fails because of some dependency
+update, then it may be necessary to update `pyproject.toml` to cap the supported
+versions of that dependency unless/until the code can be updated to support it.
+
+It can also be good, though not necessary, to double check what changed when
+updating a lock file. The diff can be noisy so the main changes to focus on are
 1) major version updates (e.g.  `pandas 2.X.X` -> `pandas 3.X.X`)
 2) new transitive dependencies (i.e. not part of your `pyproject.toml`)
 
@@ -646,6 +651,7 @@ dependency cooldowns. This lets you know if a dependency update breaks your
 package.
 2) older supported versions of Python to let you know if a recent change to your
 package no longer works with an older Python release.
+
 :::
 
 

From 88d6b786c3ff320f3ab0b014ef2eda0084c6333f Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 12:02:09 -0700
Subject: [PATCH 06/15] Added more justification for lock files in intro
 paragraph

---
 package-structure-code/declare-dependencies.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 302b213e..cbde6810 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -512,7 +512,11 @@ When you use different specifiers
 In addition to declaring dependencies in `pyproject.toml`, it is common for
 packages to lock down exact versions of all their dependencies in a separate
 lock file. A lock file provides benefits of reproducibilty, security, and
-potentially faster installs, among other things.
+potentially faster installs, among other things. Pinning the exact dependency
+versions used in a project eliminates "works on my machine" bugs and gives CI a
+reproducible baseline. For applications meant to be run rather than imported,
+lock files also ensure anyone installing the project gets a known-good set of
+dependencies — not whatever happens to be latest.
 
 ### `pyproject.toml` vs lock file
 * `pyproject.toml`: defines all supported environments for users importing

From 71190c264685eacf992ec4aed4fba250992f984f Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 12:11:30 -0700
Subject: [PATCH 07/15] Elaborate on package hash

---
 package-structure-code/declare-dependencies.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index cbde6810..5b648c7c 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -678,7 +678,10 @@ files the preferred format:
 * The versions satisfying `pyproject.toml` may differ between your MacOS and the
 Linux server your CI runs on. Lock files contain platform-specific resolutions
 * Packages can get updated without a version update for both legitimate and
-malicious reasons. Lock files specify exact hashes to catch this.
+malicious reasons. Lock files include package hashes to catch this. A hash
+number is a unique signature computed from the code and any change to the code
+will cause the release to have a different hash even if is given the same
+releaes version number.
 * Other metadata determined during resolution of `pyproject.toml` (e.g. which
 dependencies are transitive, where the packages were downloaded from, etc.) that
 can help speed up future installs is lost.

From 88f7445d28b710df1c4eeee00821fc7eaef07cf6 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 12:23:45 -0700
Subject: [PATCH 08/15] Clarified lock files supporting multiple platforms and
 python versions compared to requirements.txt

---
 package-structure-code/declare-dependencies.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 5b648c7c..4eb65b6d 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -675,8 +675,12 @@ pyzmq==27.1.0
 
 However, this minimal level of specificity has several downsides making lock
 files the preferred format:
-* The versions satisfying `pyproject.toml` may differ between your MacOS and the
-Linux server your CI runs on. Lock files contain platform-specific resolutions
+* The versions satisfying `pyproject.toml` may differ between your Windows
+laptop and the Linux server your CI runs on. A single lock file contains the
+information needed to build platform specific and Python version specific
+environments. In contrast, a separate `requirements.txt` files is needed to
+store this information (e.g. `requirements.ci.txt`,
+`requirements.py313-macos.txt`)
 * Packages can get updated without a version update for both legitimate and
 malicious reasons. Lock files include package hashes to catch this. A hash
 number is a unique signature computed from the code and any change to the code

From 7ad8080fa353526c1188f25cb6f3b9ca52bc257b Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 12:27:08 -0700
Subject: [PATCH 09/15] maintain changed to generate

---
 package-structure-code/declare-dependencies.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 4eb65b6d..ec5a60de 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -611,7 +611,7 @@ See [official docs](https://pdm-project.org/latest/usage/lockfile/) for more det
 
 ### Should I use a lock file?
 
-Most package managers will maintain a lock file automatically for you (e.g. uv,
+Most package managers will generate a lock file automatically for you (e.g. uv,
 Poetry, PDM). The real question is when you version control the lock file as
 part of your package.
 

From 35d8fbf0e4f24df9ca83baf27dc8b0c5c0b533c0 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sat, 23 May 2026 12:54:35 -0700
Subject: [PATCH 10/15] Typos and other wording fixes

---
 package-structure-code/declare-dependencies.md | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index ec5a60de..72e6052a 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -511,21 +511,21 @@ When you use different specifiers
 
 In addition to declaring dependencies in `pyproject.toml`, it is common for
 packages to lock down exact versions of all their dependencies in a separate
-lock file. A lock file provides benefits of reproducibilty, security, and
+lock file. A lock file provides benefits of reproducibility, security, and
 potentially faster installs, among other things. Pinning the exact dependency
 versions used in a project eliminates "works on my machine" bugs and gives CI a
 reproducible baseline. For applications meant to be run rather than imported,
 lock files also ensure anyone installing the project gets a known-good set of
-dependencies — not whatever happens to be latest.
+dependencies instead of whatever happens to be latest.
 
 ### `pyproject.toml` vs lock file
 * `pyproject.toml`: defines all supported environments for users importing
 your package into their project.
 * **lock file**: defines a specific environment used for development
 
-:::{admonition} Official Lock File
+:::{admonition} Standardized Lock File
 :class: note
-As of March 2025, [PEP 751](https://pep.python.org/pep-0751) defined a standard
+As of March 2025, [PEP 751](https://peps.python.org/pep-0751) defined a standard
 `pylock.toml` format to unify the various lock file formats in use by other
 package managers (e.g. `uv.lock`, `poetry.lock`, `pdm.lock`). Most package
 managers provide ways to generate a PEP 751 compatible file. See [PyPA
@@ -602,7 +602,6 @@ See [official docs](https://python-poetry.org/docs/basic-usage/#installing-depen
 
 # PEP 751 pylock.toml support
 > pdm export -f pylock -o pylock.toml  # export pdm.lock -> pylock.toml
-> pdm lock --lockfile pylock.toml      # install from pylock.toml
 ```
 See [official docs](https://pdm-project.org/latest/usage/lockfile/) for more details
 :::
@@ -685,7 +684,7 @@ store this information (e.g. `requirements.ci.txt`,
 malicious reasons. Lock files include package hashes to catch this. A hash
 number is a unique signature computed from the code and any change to the code
 will cause the release to have a different hash even if is given the same
-releaes version number.
+release version number.
 * Other metadata determined during resolution of `pyproject.toml` (e.g. which
 dependencies are transitive, where the packages were downloaded from, etc.) that
 can help speed up future installs is lost.

From bd49ceb832d0e9369544a1018b1ed7150590d040 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sun, 24 May 2026 09:16:47 -0700
Subject: [PATCH 11/15] Add pdm update package example

---
 package-structure-code/declare-dependencies.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index 72e6052a..da5e566a 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -596,6 +596,7 @@ See [official docs](https://python-poetry.org/docs/basic-usage/#installing-depen
 
 # Update pdm.lock
 > pdm update
+> pdm update pandas numpy
 
 # Install packages into environment based on pdm.lock
 > pdm sync

From b8e862cfe38b860464c157b54ded05eee50e0b95 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sun, 24 May 2026 09:56:59 -0700
Subject: [PATCH 12/15] Clarified carve out for not including lock file

---
 package-structure-code/declare-dependencies.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index da5e566a..d580f479 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -621,8 +621,9 @@ If your project is an application others use directly, include a lock file as
 the recommended environment.
 
 If your project is a library to be used in other projects and it is mature
-enough to have CI, include a lock file for CI and contributors.
-
+enough to have CI, include a lock file for CI and contributors. For a small
+library only you maintain that is shared amongst people you know, waiting to add
+a lock file is not an issue.
 :::
 
 There is some maintenance cost from lock files. Maintainers should aim to update

From 7fb2aa9942e38bd80b64cf03a61b61de09bb3297 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sun, 24 May 2026 10:20:22 -0700
Subject: [PATCH 13/15] Add recommendation for updating lock files

---
 package-structure-code/declare-dependencies.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index d580f479..fd2a603b 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -615,7 +615,7 @@ Most package managers will generate a lock file automatically for you (e.g. uv,
 Poetry, PDM). The real question is when you version control the lock file as
 part of your package.
 
-:::{admonition} Rule of Thumb
+:::{admonition} Recommendation: Versioning a lock file
 :class: tip
 If your project is an application others use directly, include a lock file as
 the recommended environment.
@@ -636,6 +636,14 @@ support [dependency cooldowns](
 https://blog.pypi.org/posts/2026-04-02-incident-report-litellm-telnyx-supply-chain-attack/#dependency-cooldowns
 ) to mitigate this.
 
+:::{admonition} Recommendation: Updating a lock file
+:class: tip
+Update lock files frequently (e.g. weekly) but configure a dependency cooldown
+of several days to avoid automatically installing the latest packages. Only
+override the cooldown if a new package has a needed bug fix or security
+patch.
+:::
+
 When you decide to update a lock file, make sure to test that the resulting
 environment works before committing. If it fails because of some dependency
 update, then it may be necessary to update `pyproject.toml` to cap the supported

From 69d49dde746c253bc8e7339cb16cada50db8cec5 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sun, 24 May 2026 11:19:12 -0700
Subject: [PATCH 14/15] Add more details on dependency cooldowns

---
 .../declare-dependencies.md                   | 40 +++++++++++++++++--
 1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index fd2a603b..ce97d576 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -632,9 +632,7 @@ the lock file neither too rarely nor too often.
 performance improvements, etc.
 * Too often means you may introduce bugs or even security vulnerablilites before
 maintainers of your dependencies catch them. Package managers are starting to
-support [dependency cooldowns](
-https://blog.pypi.org/posts/2026-04-02-incident-report-litellm-telnyx-supply-chain-attack/#dependency-cooldowns
-) to mitigate this.
+support dependency cooldowns to mitigate this.
 
 :::{admonition} Recommendation: Updating a lock file
 :class: tip
@@ -644,6 +642,42 @@ override the cooldown if a new package has a needed bug fix or security
 patch.
 :::
 
+::::{dropdown} Dependency cooldowns
+:icon: info
+:color: primary
+[Dependency cooldowns](
+https://blog.pypi.org/posts/2026-04-02-incident-report-litellm-telnyx-supply-chain-attack/#dependency-cooldowns
+) are strongly encouraged by security experts to avoid automatically downloading
+the latest package updates that may have been compromised with malware. Package
+manager tools are starting to support configurations for cooldowns
+```sh
+> uv lock --exclude-newer "3 days"`
+```
+or in `pyproject.toml`
+```toml
+[tool.uv]
+exclude-newer = "3 days"
+```
+
+Integrating cooldown constrained lock files into CI is important since this is
+where new packages are commonly tested first. Automated testing code that
+resolves `[project.dependencies]` every time
+```sh
+> python -m pip install .
+```
+can be replaced with
+```sh
+> uv lock --exclude-newer "3 days"`
+```
+or can be replaced with lock file based installations
+```sh
+> uv sync --frozen
+```
+Support for this varies across automated testing frameworks (e.g. hatch, nox) so
+consult their documentation for how to install dependencies from lock files with
+dependency cooldowns.
+::::
+
 When you decide to update a lock file, make sure to test that the resulting
 environment works before committing. If it fails because of some dependency
 update, then it may be necessary to update `pyproject.toml` to cap the supported

From 42d5c8a83bbc0a303c1bd351bcf405e26ca41188 Mon Sep 17 00:00:00 2001
From: Alex Armstrong <noemail>
Date: Sun, 24 May 2026 11:24:47 -0700
Subject: [PATCH 15/15] Add link for hash

---
 package-structure-code/declare-dependencies.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index ce97d576..75827f2b 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -725,8 +725,9 @@ environments. In contrast, a separate `requirements.txt` files is needed to
 store this information (e.g. `requirements.ci.txt`,
 `requirements.py313-macos.txt`)
 * Packages can get updated without a version update for both legitimate and
-malicious reasons. Lock files include package hashes to catch this. A hash
-number is a unique signature computed from the code and any change to the code
+malicious reasons. Lock files include package hashes to catch this. A
+[hash](https://en.wikipedia.org/wiki/Hash_function) is a unique signature
+computed from the code and any change to the code
 will cause the release to have a different hash even if is given the same
 release version number.
 * Other metadata determined during resolution of `pyproject.toml` (e.g. which