From b5c5930c1cffd6843f88d451f692901577e9b79f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFs=20Postula?= Date: Wed, 25 Mar 2026 22:43:09 +0100 Subject: [PATCH] docs: add PyPI resource and pyproject autodiscovery documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for two new plugins: - pypi resource: PyPI registry interaction (source, condition) - pyproject autodiscovery: Python dependency updates via pyproject.toml + uv Signed-off-by: Loïs Postula --- .../resources/pypi/updatecli.d/default.yaml | 25 ++++++ .../docs/plugins/autodiscovery/pyproject.adoc | 78 +++++++++++++++++++ content/en/docs/plugins/resource/pypi.adoc | 49 ++++++++++++ 3 files changed, 152 insertions(+) create mode 100644 assets/code_example/docs/plugins/resources/pypi/updatecli.d/default.yaml create mode 100644 content/en/docs/plugins/autodiscovery/pyproject.adoc create mode 100644 content/en/docs/plugins/resource/pypi.adoc diff --git a/assets/code_example/docs/plugins/resources/pypi/updatecli.d/default.yaml b/assets/code_example/docs/plugins/resources/pypi/updatecli.d/default.yaml new file mode 100644 index 00000000..2c723113 --- /dev/null +++ b/assets/code_example/docs/plugins/resources/pypi/updatecli.d/default.yaml @@ -0,0 +1,25 @@ +name: PyPI resource example +sources: + requests: + name: Get latest requests version from PyPI + kind: pypi + spec: + name: requests + flask: + name: Get latest flask version matching >=3.0 + kind: pypi + spec: + name: flask + versionfilter: + kind: semver + pattern: ">=3.0.0" +conditions: + requests: + name: Test that requests version 2.31.0 exists on PyPI + kind: pypi + disablesourceinput: true + spec: + name: requests + version: 2.31.0 +targets: + # Targets are not supported diff --git a/content/en/docs/plugins/autodiscovery/pyproject.adoc b/content/en/docs/plugins/autodiscovery/pyproject.adoc new file mode 100644 index 00000000..5c46ba5c --- /dev/null +++ b/content/en/docs/plugins/autodiscovery/pyproject.adoc @@ -0,0 +1,78 @@ +--- +title: "Pyproject" +description: "Discover Python dependency updates from pyproject.toml" +lead: "kind: pyproject" +draft: false +images: [] +menu: + docs: + parent: "plugin-autodiscovery" +weight: 131 +toc: true +plugins: + - autodiscovery +--- + +== Description + +The pyproject crawler looks recursively for all Python dependencies from `pyproject.toml` files. +It detects the package manager in use via lock files (currently `uv.lock` is supported) and generates manifests to update dependencies using the appropriate tool. + +Dependencies are discovered from both `[project.dependencies]` and `[project.optional-dependencies]` sections. PEP 508 dependency strings are parsed to extract package names and version constraints. Environment markers are stripped. + +Generated manifests use the `pypi` resource as a source and `uv add` as a shell target, which atomically updates both `pyproject.toml` and `uv.lock`. + +== Manifest +=== Parameters + +{{< autodiscoveryparameters "pyproject" >}} + +==== Example + +===== Basic Example + +[source,yaml] +---- +# updatecli.d/pyproject.yaml +autodiscovery: + crawlers: + pyproject: + rootdir: "." + versionfilter: + kind: semver + pattern: minor +---- + +===== Filter to Specific Packages + +[source,yaml] +---- +# updatecli.d/pyproject-only.yaml +autodiscovery: + crawlers: + pyproject: + only: + - packages: + "requests": "" + "flask": "" +---- + +===== Private PyPI Registry + +[source,yaml] +---- +# updatecli.d/pyproject-private.yaml +autodiscovery: + crawlers: + pyproject: + rootdir: "." + # Custom PyPI index URL propagated to all generated pypi source specs + indexurl: "https://pypi.example.com/" + versionfilter: + kind: semver + pattern: ">=1.0.0" +---- + +NOTE: The `indexurl` parameter is propagated to all generated pypi resource specs, allowing consistent registry configuration across all discovered dependencies. For private registry authentication, the `pypi` resource supports a `token` field for Bearer token auth. + +NOTE: The alias `python/uv` can also be used instead of `pyproject`. diff --git a/content/en/docs/plugins/resource/pypi.adoc b/content/en/docs/plugins/resource/pypi.adoc new file mode 100644 index 00000000..e864c16b --- /dev/null +++ b/content/en/docs/plugins/resource/pypi.adoc @@ -0,0 +1,49 @@ +--- +title: "PyPI" +description: "Interact with the PyPI registry" +lead: "kind: pypi" +date: 2026-03-25T00:00:00+00:00 +draft: false +images: [] +menu: + docs: + parent: "plugin-resource" +toc: true +plugins: + - source + - condition +--- +// +:toc: +// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key +:toclevels: 4 + +[cols="1^,1^,1^",options=header] +|=== +| source | condition | target +| ✔ | ✔ | ✗ +|=== + +**source** + +The PyPI "source" retrieves the latest version of a Python package from a PyPI-compatible registry matching a specific version filter. PEP 440 pre-release versions (alpha, beta, rc) are automatically normalized to semver for filtering. + +**condition** + +The PyPI "condition" tests that a specific version exists on a PyPI-compatible registry. + +**target** + +The PyPI "target" is not supported. + +== Parameter + +{{< resourceparameters "sources" "pypi" >}} + +== Example + +[source,yaml] +---- +# updatecli.yaml +{{}} +----