pulp · mdellweg · Jul 28, 2026 · Jul 27, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/.ci/run_container.sh b/.ci/run_container.sh
@@ -69,8 +69,8 @@ else
 fi
 export PULP_CONTENT_ORIGIN
 
-PULP_DJANGO_SECRET="$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")"
-export PULP_DJANGO_SECRET
+PULP_SECRET_KEY="$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")"
+export PULP_SECRET_KEY
 
 "${CONTAINER_RUNTIME}" \
   run ${RM:+--rm} \
@@ -82,7 +82,7 @@ export PULP_DJANGO_SECRET
   ${PULP_DOMAIN_ENABLED:+--env PULP_DOMAIN_ENABLED} \
   ${PULP_ENABLED_PLUGINS:+--env PULP_ENABLED_PLUGINS} \
   --env PULP_CONTENT_ORIGIN \
-  --env PULP_DJANGO_SECRET \
+  --env PULP_SECRET_KEY \
   --detach \
   --name "pulp-ephemeral" \
   --volume "${PULP_CLI_TEST_TMPDIR}/settings:/etc/pulp${SELINUX:+:Z}" \

diff --git a/.ci/scripts/check_click_for_mypy.py b/.ci/scripts/check_click_for_mypy.py
@@ -5,7 +5,7 @@
 #     "packaging>=25.0,<25.1",
 # ]
 # ///
-
+import sys
 from importlib import metadata
 
 from packaging.version import Version
@@ -15,4 +15,4 @@
     if click_version < Version("8.1.1"):
         print("🚧 Linting with mypy is currently only supported with click>=8.1.1. 🚧")
         print("🔧 Please run `pip install click>=8.1.1` first. 🔨")
-        exit(1)
+        sys.exit(1)
diff --git a/.ci/scripts/collect_changes.py b/.ci/scripts/collect_changes.py
@@ -9,10 +9,12 @@
 
 import itertools
 import re
+import typing as t
 from pathlib import Path
 
 import tomllib
 from git import GitCommandError, Repo
+from packaging.version import Version
 from packaging.version import parse as parse_version
 
 # Read Towncrier settings
@@ -51,29 +53,29 @@
 )
 
 
-def get_changelog(repo, branch):
+def get_changelog(repo: Repo, branch: str) -> str:
     branch_tc_settings = tomllib.loads(repo.git.show(f"{branch}:pyproject.toml"))["tool"][
         "towncrier"
     ]
     branch_changelog_file = branch_tc_settings.get("filename", "NEWS.rst")
     return repo.git.show(f"{branch}:{branch_changelog_file}") + "\n"
 
 
-def _tokenize_changes(splits):
+def _tokenize_changes(splits: list[str]) -> t.Iterator[list[Version | str]]:
     assert len(splits) % 3 == 0
     for i in range(len(splits) // 3):
         title = splits[3 * i]
         version = parse_version(splits[3 * i + 1])
         yield [version, title + splits[3 * i + 2]]
 
 
-def split_changelog(changelog):
+def split_changelog(changelog: str) -> tuple[str, list[list[Version | str]]]:
     preamble, rest = changelog.split(START_STRING, maxsplit=1)
     split_rest = re.split(TITLE_REGEX, rest)
     return preamble + START_STRING + split_rest[0], list(_tokenize_changes(split_rest[1:]))
 
 
-def main():
+def main() -> None:
     repo = Repo(Path.cwd())
     remote = repo.remotes[0]
     branches = [ref for ref in remote.refs if re.match(r"^([0-9]+)\.([0-9]+)$", ref.remote_head)]
@@ -91,7 +93,7 @@ def main():
         except GitCommandError:
             print("No changelog found on this branch.")
             continue
-        dummy, changes = split_changelog(changelog)
+        _dummy, changes = split_changelog(changelog)
         new_changes = sorted(main_changes + changes, key=lambda x: x[0], reverse=True)
         # Now remove duplicates (retain the first one)
         main_changes = [new_changes[0]]

diff --git a/Makefile b/Makefile
@@ -93,11 +93,11 @@ unittest_glue:
 
 .PHONY: docs
 docs:
-	pulp-docs build
+	uv run --only-group docs pulp-docs build --draft --no-blog
 
 .PHONY: servedocs
 servedocs:
-	pulp-docs serve -w CHANGES.md -w pulp-glue/pulp_glue -w pulp_cli/generic.py
+	uv run --only-group docs pulp-docs serve --draft --no-blog -w CHANGES.md -w src -w pulp-glue/src
 
 pulp-glue/pulp_glue/%/locale/messages.pot: pulp-glue/pulp_glue/%/*.py
 	xgettext -d $* -o $@ pulp-glue/pulp_glue/$*/*.py

diff --git a/cookiecutter/ci/{{ cookiecutter.__project_name }}/.ci/run_container.sh b/cookiecutter/ci/{{ cookiecutter.__project_name }}/.ci/run_container.sh
@@ -69,8 +69,8 @@ else
 fi
 export PULP_CONTENT_ORIGIN
 
-PULP_DJANGO_SECRET="$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")"
-export PULP_DJANGO_SECRET
+PULP_SECRET_KEY="$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")"
+export PULP_SECRET_KEY
 
 "${CONTAINER_RUNTIME}" \
   run ${RM:+--rm} \
@@ -82,7 +82,7 @@ export PULP_DJANGO_SECRET
   ${PULP_DOMAIN_ENABLED:+--env PULP_DOMAIN_ENABLED} \
   ${PULP_ENABLED_PLUGINS:+--env PULP_ENABLED_PLUGINS} \
   --env PULP_CONTENT_ORIGIN \
-  --env PULP_DJANGO_SECRET \
+  --env PULP_SECRET_KEY \
   --detach \
   --name "pulp-ephemeral" \
   --volume "${PULP_CLI_TEST_TMPDIR}/settings:/etc/pulp${SELINUX:+:Z}" \

diff --git a/cookiecutter/ci/{{ cookiecutter.__project_name }}/.ci/scripts/check_click_for_mypy.py b/cookiecutter/ci/{{ cookiecutter.__project_name }}/.ci/scripts/check_click_for_mypy.py
@@ -5,7 +5,7 @@
 #     "packaging>=25.0,<25.1",
 # ]
 # ///
-
+import sys
 from importlib import metadata
 
 from packaging.version import Version
@@ -15,4 +15,4 @@
     if click_version < Version("8.1.1"):
         print("🚧 Linting with mypy is currently only supported with click>=8.1.1. 🚧")
         print("🔧 Please run `pip install click>=8.1.1` first. 🔨")
-        exit(1)
+        sys.exit(1)
diff --git a/cookiecutter/ci/{{ cookiecutter.__project_name }}/.ci/scripts/collect_changes.py b/cookiecutter/ci/{{ cookiecutter.__project_name }}/.ci/scripts/collect_changes.py
@@ -9,10 +9,12 @@
 
 import itertools
 import re
+import typing as t
 from pathlib import Path
 
 import tomllib
 from git import GitCommandError, Repo
+from packaging.version import Version
 from packaging.version import parse as parse_version
 
 # Read Towncrier settings
@@ -51,29 +53,29 @@
 )
 
 
-def get_changelog(repo, branch):
+def get_changelog(repo: Repo, branch: str) -> str:
     branch_tc_settings = tomllib.loads(repo.git.show(f"{branch}:pyproject.toml"))["tool"][
         "towncrier"
     ]
     branch_changelog_file = branch_tc_settings.get("filename", "NEWS.rst")
     return repo.git.show(f"{branch}:{branch_changelog_file}") + "\n"
 
 
-def _tokenize_changes(splits):
+def _tokenize_changes(splits: list[str]) -> t.Iterator[list[Version | str]]:
     assert len(splits) % 3 == 0
     for i in range(len(splits) // 3):
         title = splits[3 * i]
         version = parse_version(splits[3 * i + 1])
         yield [version, title + splits[3 * i + 2]]
 
 
-def split_changelog(changelog):
+def split_changelog(changelog: str) -> tuple[str, list[list[Version | str]]]:
     preamble, rest = changelog.split(START_STRING, maxsplit=1)
     split_rest = re.split(TITLE_REGEX, rest)
     return preamble + START_STRING + split_rest[0], list(_tokenize_changes(split_rest[1:]))
 
 
-def main():
+def main() -> None:
     repo = Repo(Path.cwd())
     remote = repo.remotes[0]
     branches = [ref for ref in remote.refs if re.match(r"^([0-9]+)\.([0-9]+)$", ref.remote_head)]
@@ -91,7 +93,7 @@ def main():
         except GitCommandError:
             print("No changelog found on this branch.")
             continue
-        dummy, changes = split_changelog(changelog)
+        _dummy, changes = split_changelog(changelog)
         new_changes = sorted(main_changes + changes, key=lambda x: x[0], reverse=True)
         # Now remove duplicates (retain the first one)
         main_changes = [new_changes[0]]

diff --git a/cookiecutter/ci/{{ cookiecutter.__project_name }}/Makefile b/cookiecutter/ci/{{ cookiecutter.__project_name }}/Makefile
@@ -107,11 +107,11 @@ unittest_glue:
 
 .PHONY: docs
 docs:
-	pulp-docs build
+	uv run --only-group docs pulp-docs build --draft --no-blog
 
 .PHONY: servedocs
 servedocs:
-	pulp-docs serve -w CHANGES.md -w pulp-glue/pulp_glue -w pulp_cli/generic.py
+	uv run --only-group docs pulp-docs serve --draft --no-blog -w CHANGES.md -w src -w pulp-glue/src
 {%- endif %}
 {%- if cookiecutter.translations %}
 {%- if cookiecutter.glue %}

diff --git a/...er.__project_name }}/pulp-glue{{ cookiecutter.__app_label_suffix }}/pyproject.toml.update b/...er.__project_name }}/pulp-glue{{ cookiecutter.__app_label_suffix }}/pyproject.toml.update
@@ -19,7 +19,11 @@ line-length = 100
 [tool.ruff.lint]
 # This section is managed by the cookiecutter templates.
 select = ["E4", "E7", "E9", "F"]
-extend-select = ["I", "INT", "PTH"]
+extend-select = ["FURB", "I", "INT", "PTH", "SIM1", "TID", "T10", "UP"]
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+# This section is managed by the cookiecutter templates.
+"distutils".msg = "The 'distutils' module has been deprecated since Python 3.9."
 
 [tool.mypy]
 # This section is managed by the cookiecutter templates.

diff --git a/cookiecutter/ci/{{ cookiecutter.__project_name }}/pyproject.toml.update b/cookiecutter/ci/{{ cookiecutter.__project_name }}/pyproject.toml.update
@@ -12,7 +12,7 @@ dev = [
 lint = [
   {include-group = "test"},
   "mypy~=1.20.0",
-  "ruff~=0.15.1",
+  "ruff~=0.16.0",
   "shellcheck-py~=0.11.0.1",
   "types-pygments",
   "types-pyyaml",
@@ -28,16 +28,34 @@ test = [
   "secretstorage>=3.5.0",
   "trustme>=1.1.0,<1.3",
 ]
-{%- if cookiecutter.glue %}
+{%- if cookiecutter.docs %}
+docs = [
+  "pulp-docs",
+]
+{%- endif %}
+{%- if cookiecutter.glue or cookiecutter.docs %}
 
 [tool.uv.sources]
 # This section is managed by the cookiecutter templates.
+{%- if cookiecutter.glue %}
 pulp-glue{{ cookiecutter.__app_label_suffix }} = { workspace = true }
+{%- endif %}
+{%- if cookiecutter.docs %}
+pulp-docs = { git = "https://github.com/pulp/pulp-docs" }
+{%- endif %}
+{%- endif %}
+{%- if cookiecutter.glue %}
 
 [tool.uv.workspace]
 # This section is managed by the cookiecutter templates.
 members = ["pulp-glue{{ cookiecutter.__app_label_suffix }}"]
 {%- endif %}
+{%- if cookiecutter.docs %}
+
+[tool.uv.dependency-groups]
+# This section is managed by the cookiecutter templates.
+docs = {requires-python = ">=3.11"}
+{%- endif %}
 
 [tool.uv.build-backend]
 # This section is managed by the cookiecutter templates.
@@ -210,13 +228,18 @@ extend-exclude = ["cookiecutter/bootstrap", "cookiecutter/ci", "cookiecutter/doc
 [tool.ruff.lint]
 # This section is managed by the cookiecutter templates.
 select = ["E4", "E7", "E9", "F"]
-extend-select = ["I", "INT", "PTH"]
+extend-select = ["FURB", "I", "INT", "PTH", "SIM1", "TID", "T10", "UP"]
 
 [tool.ruff.lint.isort]
 # This section is managed by the cookiecutter templates.
 sections = { second-party = ["pulp_glue"] }
 section-order = ["future", "standard-library", "third-party", "second-party", "first-party", "local-folder"]
 
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+# This section is managed by the cookiecutter templates.
+"distutils".msg = "The 'distutils' module has been deprecated since Python 3.9."
+"pulpcore.cli.common.generic".msg = "This module moved to 'pulp_cli.generic'."
+
 [tool.mypy]
 # This section is managed by the cookiecutter templates.
 strict = true

diff --git a/cookiecutter/update_pulp_cli.py b/cookiecutter/update_pulp_cli.py
@@ -41,7 +41,7 @@ def strategy_semver(requirement: Requirement, latest_version: Version) -> Requir
             rest.append(spec)
     assert upper_bound is not None
     if latest_version < Version(upper_bound.version):
-        _logger.warn(
+        _logger.warning(
             f"Dependency on {requirement} cannot be updated "
             "to include latest version {latest_version}."
         )
@@ -73,7 +73,7 @@ def latest_version(canonical_name: str, allow_prereleases: bool | None = None) -
         releases = json.loads(response.read())["releases"]
     available_versions = sorted(
         version
-        for version in (Version(key) for key in releases.keys())
+        for version in (Version(key) for key in releases)
         if allow_prereleases or not version.is_prerelease
     )
     return available_versions[-1]

diff --git a/docs/user/guides/installation.md b/docs/user/guides/installation.md
@@ -2,19 +2,19 @@
 
 ## TL;DR: Get Started Real Fast
 
-=== "pip"
+=== "uv"
 
     ```bash
-    pip install pulp-cli[pygments]
+    uv tool install pulp-cli[pygments]
     pulp config create -e
     # insert your server configuration here
     pulp status
     ```
 
-=== "uv"
+=== "pip"
 
     ```bash
-    uv tool install pulp-cli[pygments]
+    pip install pulp-cli[pygments]
     pulp config create -e
     # insert your server configuration here
     pulp status
@@ -97,14 +97,47 @@ pip install pulp-cli-deb
 ## From a source checkout
 
 If you intend to use unreleased features, or want to contribute to the CLI, you can install from source:
-```bash
-git clone git@github.com:pulp/pulp-cli.git
-pip install -e ./pulp-cli -e ./pulp-cli/pulp-glue
 
-# Optionally install plugins from source
-git clone git@github.com:pulp/pulp-cli-deb.git
-pip install -e ./pulp-cli-deb
+=== "uv"
 
-git clone git@github.com:pulp/pulp-cli-maven.git
-pip install -e ./pulp-cli-maven -e ./pulp-cli-maven/pulp-glue-maven
-```
+    ```bash
+    # Upon entering the source directory, uv handles the virtual environment on the fly.
+
+    git clone git@github.com:pulp/pulp-cli.git
+    cd pulp-cli
+    uv run pulp status
+
+    # Alternatively run in plugin development:
+    git clone git@github.com:pulp/pulp-cli-gem.git
+    cd pulp-cli-gem
+    uv run pulp status
+    ```
+
+=== "uv (install)"
+
+    ```bash
+    # The matching glue development version is automatically taken from the same workspace.
+
+    git clone git@github.com:pulp/pulp-cli.git
+    uv tool install --editable pulp-cli
+
+    # Alternatively install plugins from source:
+    git clone git@github.com:pulp/pulp-cli-gem.git
+    uv tool install pulp-cli --with-editable pulp-cli-gem
+    ```
+
+=== "pip"
+
+    ```bash
+    # The matching glue development version must be installed from the same source.
+
+    git clone git@github.com:pulp/pulp-cli.git
+    pip install -e ./pulp-cli -e ./pulp-cli/pulp-glue
+
+    # Alternatively install plugins from source:
+    git clone git@github.com:pulp/pulp-cli-deb.git
+    pip install -e ./pulp-cli-deb
+
+    git clone git@github.com:pulp/pulp-cli-maven.git
+    pip install -e ./pulp-cli-maven -e ./pulp-cli-maven/pulp-glue-maven
+    ```
diff --git a/pulp-glue/pyproject.toml b/pulp-glue/pyproject.toml
@@ -76,5 +76,9 @@ line-length = 100
 [tool.ruff.lint]
 # This section is managed by the cookiecutter templates.
 select = ["E4", "E7", "E9", "F"]
-extend-select = ["I", "INT", "PTH"]
+extend-select = ["FURB", "I", "INT", "PTH", "SIM1", "TID", "T10", "UP"]
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+# This section is managed by the cookiecutter templates.
+"distutils".msg = "The 'distutils' module has been deprecated since Python 3.9."