docverse 1.0.0b2__tar.gz

docverse-1.0.0b2/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Change log
+
+<!-- scriv-insert-here -->

docverse-1.0.0b2/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: docverse
+Version: 1.0.0b2
+Summary: Python client for the Docverse documentation hosting platform.
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8
+Requires-Dist: httpx>=0.26
+Requires-Dist: pydantic>=2.5
+
+# Docverse
+
+Docverse is a hosting platform for versioned documentation websites, built by [Rubin Observatory](https://www.lsst.io).
+This package is the Python client and `docverse` command-line tool for uploading documentation builds to a Docverse service.
+
+**Docverse is a pre-release.** The API and this client are still changing, and no public Docverse service is available yet.
+
+The design is documented in [SQR-112: Docverse documentation hosting platform design](https://sqr-112.lsst.io).
+Development happens in [lsst-sqre/docverse](https://github.com/lsst-sqre/docverse).

docverse-1.0.0b2/README.md

@@ -0,0 +1,9 @@
+# Docverse
+
+Docverse is a hosting platform for versioned documentation websites, built by [Rubin Observatory](https://www.lsst.io).
+This package is the Python client and `docverse` command-line tool for uploading documentation builds to a Docverse service.
+
+**Docverse is a pre-release.** The API and this client are still changing, and no public Docverse service is available yet.
+
+The design is documented in [SQR-112: Docverse documentation hosting platform design](https://sqr-112.lsst.io).
+Development happens in [lsst-sqre/docverse](https://github.com/lsst-sqre/docverse).

docverse-1.0.0b2/changelog.d/20260512_120000_DM_54688.md

@@ -0,0 +1,3 @@
+### New features
+
+- New `LifecycleRule` discriminated union (`DraftInactivityRule`, `BuildHistoryOrphanRule`, `RefDeletedRule`) and `LifecycleRuleSet` root model exported from `docverse.models`. The `lifecycle_rules` field on `Organization`, `OrganizationCreate`, `OrganizationUpdate`, `Project`, `ProjectCreate`, and `ProjectUpdate` now uses this typed shape so script-side configuration gets IDE autocomplete and pydantic validation, and the duplicate-rule-type guard runs locally before any request goes out. `ProjectCreate` gains the field so a project can be provisioned with lifecycle rules in a single request instead of requiring a follow-up PATCH.

docverse-1.0.0b2/changelog.d/20260512_180000_DM_54688.md

@@ -0,0 +1,3 @@
+### New features
+
+- New `LifecycleEvalRunStatus` enum (`pending`, `in_progress`, `succeeded`, `partial_failure`, `failed`) describes the lifecycle of a `lifecycle_eval_runs` aggregate row. Shared shape with `KeeperSyncRunStatus` so the dispatcher / per-org / reaper pattern transfers between the two subsystems.

docverse-1.0.0b2/changelog.d/20260605_120000_DM_55159.md

@@ -0,0 +1,3 @@
+### New features
+
+- Typed the `build_processing` queue-job `progress` payload. A new `BuildProcessingProgress` model — with nested `EditionUpdateRef` (the `editions_updated`/`editions_skipped` entries) and `PublishJobRef` (the `publish_jobs` entries) — is exported from `docverse.models`, and `QueueJob.progress` is now `BuildProcessingProgress | None` instead of an untyped dict, so generated clients and `api-types` get real fields. All fields are optional and the models use `extra="allow"`, so other job kinds' progress payloads round-trip unchanged.

docverse-1.0.0b2/changelog.d/20260605_130000_DM_55159_hateoas.md

@@ -0,0 +1,3 @@
+### New features
+
+- Added optional `edition_url` to `EditionUpdateRef` and `queue_job_url` to `PublishJobRef` in `docverse.models`. These surface the HATEOAS links now embedded in a `build_processing` job's `progress` payload, so consumers can follow `edition_url` / `queue_job_url` instead of reconstructing `…/editions/{slug}` and `/queue/jobs/{id}` paths.

docverse-1.0.0b2/changelog.d/20260605_140000_DM_55159_subject_url.md

@@ -0,0 +1,3 @@
+### New features
+
+- Added optional `subject_url`, `build_url`, and `edition_url` fields to the `QueueJob` model in `docverse.models`. These carry the HATEOAS back-reference links from a queue job to the API resource it processes (the build for `build_processing` jobs, the edition for publish jobs), so consumers follow a link instead of reconstructing the build/edition path.

docverse-1.0.0b2/changelog.d/20260729_120000_DM_55551_openapi_polish.md

@@ -0,0 +1,8 @@
+### Backwards-incompatible changes
+
+- `KeeperSyncTombstone` no longer carries a `docverse_id` field. It exposed an internal Docverse database row id; the entry's Base32 `id` and `display_path` already identify the resource.
+
+### Other changes
+
+- Model fields now declare realistic OpenAPI example values: HATEOAS `*_url` fields show full example URLs and public-ID fields show genuine Crockford Base32 identifiers, drawn from shared constants in `docverse.models._examples`.
+- Public enums (`KeeperSyncTombstoneReason`, `KeeperSyncRunKind`, `EditionKind`, `TrackingMode`, `JobKind`, `JobStatus`, `PublishStatus`, `OrgRole`, and others) document each value in their class docstrings, which pydantic surfaces as the enum schema description in generated OpenAPI documents.

docverse-1.0.0b2/changelog.d/20260729_140000_DM_55658.md

@@ -0,0 +1,3 @@
+### Backwards-incompatible changes
+
+- The client distribution is renamed from `docverse-client` to `docverse` and now owns the plain `docverse` import root as a regular package. Import the client as `from docverse import DocverseClient` and models as `from docverse.models import Project`; the `docverse.client` module path is gone. The `docverse` CLI script name is unchanged. Release tags use the `client/` prefix (e.g. `client/0.1.0`).

docverse-1.0.0b2/changelog.d/20260807_120000_DM_54684_tarball_hash.md

@@ -0,0 +1,3 @@
+### Bug fixes
+
+- `create_tarball` no longer folds the current time into the digest it reports, so archiving byte-identical content twice now yields the same `content_hash`. The digest covers the compressed bytes, and `tarfile`'s `w:gz` mode stamps `time.time()` into the gzip header's MTIME field, so the hash changed as soon as two calls straddled an integer second. The gzip stream is now built explicitly with `mtime=0`, and with no embedded original filename. Note that the digest is still derived from the tarball rather than from file contents alone, so the same documentation built twice — in separate CI runs, or from a fresh checkout — will still hash differently because each tar member carries its own mtime.

docverse-1.0.0b2/changelog.d/20260810_200000_DM_55772_edition_autocreation.md

@@ -0,0 +1,3 @@
+### New features
+
+- Added `EditionAutocreationConfig` (exported from `docverse.models`), the shape of the new `edition_autocreation` field on the `Organization`, `OrganizationUpdate`, `Project`, and `ProjectUpdate` models. It carries a single knob for now, `semver_aggregates` (default `true`), controlling whether a stable semver release also auto-creates its major (`N`) and minor (`N.M`) aggregate editions. The model forbids unknown keys, so a typo in a `PATCH` payload fails validation client-side rather than silently doing nothing. Instances are frozen — the server resolves an unconfigured project to a single shared default config, so assignment is rejected; use `model_copy(update=...)` to derive a variant.

docverse-1.0.0b2/changelog.d/20260813_020000_DM_55772_kind_source.md

@@ -0,0 +1,4 @@
+### New features
+
+- Added `EditionKindSource` (exported from `docverse.models`), the `derived` | `declared` enum behind the new `kind_source` field on `Edition` and `EditionUpdate`. `derived` means Docverse owns the edition's `kind` and recomputes it from the edition's ref and the project's slug-rewrite rules on every sync and tracked build; `declared` means an operator set it and no automated path rewrites it. The field is read-only on `Edition` — a kind becomes `declared` by PATCHing `kind` to a *different* value — and settable on `EditionUpdate` so a declared kind can be handed back to Docverse with `EditionUpdate(kind_source=EditionKindSource.derived)`.
+- `EditionUpdate.kind` no longer pins an edition when it merely echoes the kind the edition already has, so a read-modify-write client that round-trips a full `Edition` no longer opts editions out of automatic kind derivation as a side effect.

docverse-1.0.0b2/changelog.d/20260901_120000_DM_55762_content_hash_optional.md

@@ -0,0 +1,3 @@
+### New features
+
+- `BuildCreate.content_hash` is now optional and deprecated, and `DocverseClient.create_build`'s `content_hash` argument defaults to `None` — when unset the key is left out of the request body rather than sent as `null`. Docverse now computes a build's content identity itself while processing the upload and overwrites whatever the client supplied, so the field is documented as a transport-integrity and provenance digest of the uploaded tarball that makes no claim about content identity, and it will be removed in a future release. Nothing breaks today: the `sha256:<64 hex>` pattern is still enforced on any value that is supplied, and `docverse upload` still computes the tarball digest with `create_tarball` and sends it. There is no runtime deprecation warning — the notice is carried by the field descriptions and by a `deprecated: true` flag on the field's JSON Schema, both of which surface in the server's OpenAPI schema so client codegen can act on it.

docverse-1.0.0b2/changelog.d/20260902_120000_DM_56012_terminal_build_statuses.md

@@ -0,0 +1,3 @@
+### New features
+
+- `BuildStatus` gains two terminal values that a build can now be reported in: `superseded`, for a build that a newer live build for the same `(project, git_ref)` took over before it was processed, and `cancelled`, for a build deleted before processing finished. Neither means anything went wrong — that is still `failed` — but neither build will ever be published. Both are accepted by the `status` filter on `GET /orgs/{org}/projects/{project}/builds`, so `docverse` callers can list them directly. The client dist is unreleased, so there is no compatibility shim: code that exhaustively matches on `BuildStatus` needs arms for the new values.

docverse-1.0.0b2/changelog.d/20260902_170000_DM_56012_deleted_skipped_progress.md

@@ -0,0 +1,3 @@
+### New features
+
+- `BuildProcessingProgress` gains a `deleted_skipped` field. It is `true` on a `build_processing` job that completed without publishing anything because the build was deleted — whether the delete landed before the worker picked the job up or while the worker was still uploading — so the build is `cancelled` rather than published. The key already round-tripped through `extra="allow"`; declaring it puts the flag in the generated OpenAPI schema so callers can tell this outcome apart from a real publish.

docverse-1.0.0b2/changelog.d/20260903_120000_DM_56012_httpx_floor.md

@@ -0,0 +1,3 @@
+### Other changes
+
+- The minimum supported `httpx` version is raised from 0.25 to 0.26. httpx 0.25 pins `httpcore<0.19`, and `httpcore` 0.18's anyio backend evaluates `anyio.abc.ByteStream` eagerly at class-definition time. anyio 4.15.0 made `anyio.abc` a lazily imported submodule, so importing `httpcore` before anything else imports `anyio.abc` raises `AttributeError: module 'anyio' has no attribute 'abc'`. httpx 0.26 requires `httpcore` 1.x, whose anyio backend uses postponed annotations and is unaffected.

docverse-1.0.0b2/changelog.d/20260904_120000_DM_56012_retired_status_progress.md

@@ -0,0 +1,3 @@
+### New features
+
+- `BuildProcessingProgress` gains a `retired_status` field, typed by a new `RetiredBuildStatus` enum exported from `docverse.models`. It names the state a build was found in when its worker stood down — `cancelled` for a delete or lifecycle reap, `failed` for the stranded-build sweep, `superseded` for a newer build taking over, and `missing` when the row was gone by the time the worker looked. The key already round-tripped through `extra="allow"`, but only for statuses that exist: the vanished-row case wrote `null`, which the model's drop-`None` serializer stripped, leaving that outcome unrepresentable. Declaring the field puts the value in the generated OpenAPI schema as an enum callers can switch on, and the vanished-row close-out now serialises `retired_status: "missing"`. `RetiredBuildStatus` is `BuildStatus` plus `missing`, because a soft-deleted build keeps whatever status it had — `missing` is not a `BuildStatus` since there is no row to persist it on.

docverse-1.0.0b2/changelog.d/20260908_120000_DM_54691_build_date_purged.md

@@ -0,0 +1,3 @@
+### New features
+
+- `Build` gains `date_purged: datetime | None`, which reports when the build's object-store content was permanently reclaimed. It is the field to check before assuming a soft-deleted build can be restored: null means the content is still there, a timestamp means the row is a tombstone and the files are gone. The field defaults to `None`, so a response from a server that does not yet send it still parses.

docverse-1.0.0b2/changelog.d/20260908_220000_DM_54691_restore_build.md

@@ -0,0 +1,3 @@
+### New features
+
+- `DocverseClient.restore_build(org, project, build)` restores a soft-deleted build and returns it. The build's status is not changed — one deleted before it finished comes back `cancelled` — since a restore recovers the row and its content rather than re-running the build. A build whose content has already been reclaimed raises `DocverseClientError` with `status_code` 409; check `Build.date_purged` before assuming a deleted build can be brought back.

docverse-1.0.0b2/changelog.d/20260914_120000_DM_56083_public_ids.md

@@ -0,0 +1,3 @@
+### Backwards-incompatible changes
+
+- `Project`, `Organization`, and `OrganizationSummary` gain a required `id` field carrying the resource's Crockford Base32 public identifier. Parsing a response from a Docverse server older than this release will fail validation; upgrade the server alongside the client.

docverse-1.0.0b2/changelog.d/20260914_180000_DM_56083_date_deleted.md

@@ -0,0 +1,3 @@
+### New features
+
+- `Project` gains an optional `date_deleted` field carrying the project's soft-deletion timestamp, `None` for a live project. A project is only returned deleted when the request asked for it with `include_deleted=true`, but the field parses either way, so a consumer can tell a deletion from a project that simply stopped appearing in the listing.

docverse-1.0.0b2/changelog.d/20260914_200000_DM_56083_list_projects.md

@@ -0,0 +1,3 @@
+### New features
+
+- New `DocverseClient.list_projects(org, ...)` returns an organization's whole project listing as a `ProjectList`, walking the `Link rel="next"` chain so paging is the client's problem rather than the caller's. It forwards `updated_since` (as an ISO 8601 timestamp with its offset), `include_deleted`, and `order`, and takes an `if_none_match` validator that it sends on the first request alone — a precondition describes the page the caller already holds, not the cursor URLs that follow. The result carries the first page's `etag` back verbatim for the next poll; a 304 there yields `not_modified=True` with an empty `projects` list and no further requests.

docverse-1.0.0b2/changelog.d/20260914_220000_DM_56083_updated_since_overlap.md

@@ -0,0 +1,3 @@
+### Other changes
+
+- `DocverseClient.list_projects` now backdates `updated_since` by an overlap window before sending it, 60 seconds by default (`DEFAULT_UPDATED_SINCE_OVERLAP`, overridable per call with the new `updated_since_overlap` keyword; `timedelta(0)` restores the old behaviour). A project's `date_updated` is stamped with PostgreSQL's transaction *start* clock and commit order is not start order, so a slow write can become visible after a poll that has already passed its timestamp; asking from slightly earlier is what keeps that row from being skipped forever. The consequence is that a filtered pass re-sends rows, so treat the listing as a set of upserts keyed on each project's `id` rather than as a stream of distinct changes.

docverse-1.0.0b2/changelog.d/20260915_020000_DM_56083_validator_guidance.md

@@ -0,0 +1,3 @@
+### Other changes
+
+- `ProjectList.etag` now says plainly that it is the validator to poll with, and the only one Docverse offers: the server sends no `Last-Modified` and ignores an `If-Modified-Since`. The tag is derived from the listing watermark at full precision, so it notices a change however soon after the previous one it landed and whichever order the two writes committed in.

docverse-1.0.0b2/changelog.d/20260916_230000_DM_56083_listing_default_edition.md

@@ -0,0 +1,3 @@
+### Other changes
+
+- `Project.default_edition` is now populated on every row that `DocverseClient.list_projects` returns, not only on single-project responses; the field's description no longer says it is omitted from list responses. It stays `None` only for a soft-deleted project.

docverse-1.0.0b2/changelog.d/_template.md

@@ -0,0 +1,7 @@
+### Backwards-incompatible changes
+
+### New features
+
+### Bug fixes
+
+### Other changes

docverse-1.0.0b2/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "docverse"
+description = "Python client for the Docverse documentation hosting platform."
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.12"
+dynamic = ["version"]
+dependencies = [
+    "click>=8",
+    "httpx>=0.26",
+    "pydantic>=2.5",
+]
+
+[project.scripts]
+docverse = "docverse._cli:main"
+
+[build-system]
+requires = [
+    "setuptools>=75",
+    "setuptools_scm[toml]>=8",
+]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "coverage[toml]",
+    "pytest",
+    "pytest-asyncio",
+    "respx",
+]
+
+[tool.setuptools_scm]
+root = ".."
+# Match client release tags (e.g. "client/0.1.0"). The explicit tag_regex is
+# required because setuptools_scm's default cannot parse slash-prefixed tags.
+tag_regex = '^client/(?P<version>[0-9].*)$'
+git_describe_command = [
+    "git",
+    "describe",
+    "--dirty",
+    "--tags",
+    "--long",
+    "--match",
+    "client/[0-9]*",
+]
+fallback_version = "0.0.0"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+extend = "../ruff-shared.toml"
+
+[tool.ruff.lint.extend-per-file-ignores]
+"src/docverse/_cli.py" = [
+    "PLR0917", # Too many positional arguments (Click builds the CLI from
+               # the decorated command signature; nothing calls it directly).
+]
+
+[tool.coverage.run]
+parallel = true
+branch = true
+source = ["docverse"]
+
+[tool.coverage.paths]
+source = ["src"]
+
+[tool.coverage.report]
+show_missing = true

docverse-1.0.0b2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

docverse-1.0.0b2/src/docverse/__init__.py

@@ -0,0 +1,22 @@
+"""Docverse client library."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._client import DEFAULT_UPDATED_SINCE_OVERLAP, DocverseClient, ProjectList
+from ._exceptions import BuildProcessingError, DocverseClientError
+from ._tar import create_tarball
+
+__all__ = [
+    "DEFAULT_UPDATED_SINCE_OVERLAP",
+    "BuildProcessingError",
+    "DocverseClient",
+    "DocverseClientError",
+    "ProjectList",
+    "__version__",
+    "create_tarball",
+]
+
+try:
+    __version__ = version("docverse")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

docverse-1.0.0b2/src/docverse/_annotations.py

@@ -0,0 +1,63 @@
+"""Auto-detection of build provenance annotations from CI environments."""
+
+from __future__ import annotations
+
+import os
+
+from .models.builds import BuildAnnotations
+
+__all__ = [
+    "detect_github_actions_annotations",
+    "merge_annotations",
+]
+
+
+def detect_github_actions_annotations() -> BuildAnnotations | None:
+    """Detect build provenance from GitHub Actions environment variables.
+
+    Returns a populated ``BuildAnnotations`` if running inside GitHub
+    Actions (``GITHUB_ACTIONS == "true"``), otherwise ``None``.
+    """
+    if os.environ.get("GITHUB_ACTIONS") != "true":
+        return None
+
+    server_url = os.environ.get("GITHUB_SERVER_URL", "https://github.com")
+    repository = os.environ.get("GITHUB_REPOSITORY")
+    run_id = os.environ.get("GITHUB_RUN_ID")
+
+    run_url: str | None = None
+    if repository and run_id:
+        run_url = f"{server_url}/{repository}/actions/runs/{run_id}"
+
+    return BuildAnnotations(
+        commit_sha=os.environ.get("GITHUB_SHA"),
+        github_repository=repository,
+        github_run_id=run_id,
+        github_run_url=run_url,
+        github_run_attempt=os.environ.get("GITHUB_RUN_ATTEMPT"),
+        github_workflow=os.environ.get("GITHUB_WORKFLOW"),
+        github_actor=os.environ.get("GITHUB_ACTOR"),
+        github_event_name=os.environ.get("GITHUB_EVENT_NAME"),
+        ci_platform="github-actions",
+    )
+
+
+def merge_annotations(
+    auto: BuildAnnotations | None,
+    manual: dict[str, str] | None,
+) -> BuildAnnotations | None:
+    """Merge auto-detected and manual annotations.
+
+    Manual entries take precedence over auto-detected values.  Returns
+    ``None`` if both inputs are empty/None.
+    """
+    result: dict[str, str] = {}
+    if auto is not None:
+        result.update(
+            {k: v for k, v in auto.model_dump().items() if v is not None}
+        )
+    if manual:
+        result.update(manual)
+    if not result:
+        return None
+    return BuildAnnotations.model_validate(result)