updatecli · olblak · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/pkg/plugins/autodiscovery/pyproject/main.go b/pkg/plugins/autodiscovery/pyproject/main.go
@@ -1,3 +1,23 @@
+// Package pyproject implements the autodiscovery crawler for Python projects.
+//
+// It walks a root directory looking for pyproject.toml files and generates one manifest per
+// dependency declared in [project.dependencies] and [project.optional-dependencies]. Other
+// tables, such as [dependency-groups], [tool.poetry], and [build-system], are not read.
+//
+// The package manager is detected from the lock file sitting next to each pyproject.toml.
+// Only uv is supported today, through uv.lock:
+//
+//   - uv.lock present and the uv command available: a pypi source and a shell target running
+//     `uv lock --upgrade-package` are generated. Only uv.lock is rewritten; the constraints
+//     declared in pyproject.toml are left untouched.
+//   - uv.lock present but the uv command missing: the whole pyproject.toml is skipped, since
+//     Updatecli cannot re-lock what it would bump.
+//   - no lock file: only the pypi source is generated, so the latest version is reported but
+//     nothing is modified.
+//
+// Dependency strings are parsed as PEP 508 specifiers. Environment markers are stripped rather
+// than evaluated, extras are dropped from the tracked package name, and direct references such
+// as `mypkg @ https://...` are skipped.
 package pyproject
 
 import (
@@ -20,6 +40,14 @@ type Spec struct {
 	Only MatchingRules `yaml:",omitempty"`
 	//  `versionfilter` provides parameters to specify the version pattern used when generating manifest.
 	//
+	//  If unspecified, Updatecli falls back to kind `pep440` and reuses each dependency's own
+	//  constraint as the pattern, such as `>=2.28` for `requests>=2.28`, or `*` when the
+	//  dependency is declared without a constraint.
+	//
+	//  kind - pep440 (default)
+	//    versionfilter of kind `pep440` uses PEP 440 version specifiers natively
+	//    pattern accepts a PEP 440 version specifier such as `>=2.28`, `>=1.0,<3.0`, or `*` (any)
+	//
 	//  kind - semver
 	//    versionfilter of kind `semver` uses semantic versioning as version filtering
 	//    pattern accepts one of:
@@ -30,6 +58,8 @@ type Spec struct {
 	//      `major` - Updatecli handles patch, minor, AND major version update
 	//      `majoronly` - Updatecli only handles major version update
 	//      `a version constraint` such as `>= 1.0.0`
+	//    relative patterns such as `minor` are resolved against the version currently declared
+	//    by each dependency, so `minor` generates the pattern `2.x` for `requests>=2.28`
 	//
 	//  kind - regex
 	//    versionfilter of kind `regex` uses regular expression as version filtering
@@ -38,15 +68,15 @@ type Spec struct {
 	//  example:
 	//  ```
 	//    versionfilter:
-	//      kind: semver
-	//      pattern: minor
+	//      kind: pep440
+	//      pattern: ">=2.28"
 	//  ```
 	//
-	//  and its type like regex, semver, or just latest.
-	//
 	//  More examples can be found at https://www.updatecli.io/docs/core/versionfilter/
 	VersionFilter version.Filter `yaml:",omitempty"`
 	// IndexURL specifies a custom PyPI index URL propagated to all generated source specs.
+	// It carries no credentials: authenticating against a private registry requires setting the
+	// pypi resource `token` field on the generated manifests.
 	IndexURL string `yaml:",omitempty"`
 }