You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fec5182
Browse filesBrowse the repository at this point in the historyBrowse files
SPEC_VERSION=$(uv run python -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["tool"]["apify"]["openapi-spec"]["version"])')
157
155
158
156
BODY=$(printf '%s\n' \
159
-
"- Syncs \`spec/openapi.json\` with the [published OpenAPI specification](https://docs.apify.com/api/openapi.json) and regenerates the Pydantic models, TypedDicts, and literal aliases from it." \
157
+
"- Regenerates the Pydantic models, TypedDicts, and literal aliases from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json), and records the version they were generated from in \`pyproject.toml\`." \
Copy file name to clipboardExpand all lines: .rules.md
+10-11Lines changed: 10 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,16 +12,15 @@ Uses [uv](https://docs.astral.sh/uv/) for project management and [Poe the Poet](
12
12
13
13
```bash
14
14
uv run poe install-dev # Install dev deps + git hooks
15
-
uv run poe check-code # Run all checks (lint, type-check, unit-tests, docstring + model checks)
15
+
uv run poe check-code # Run all checks (lint, type-check, unit-tests, docstring check)
16
16
uv run poe lint # Ruff format check + ruff check
17
17
uv run poe format # Auto-fix lint issues and format
18
18
uv run poe type-check # Run ty type checker
19
19
uv run poe unit-tests # Run unit tests
20
20
uv run poe check-docstrings # Verify async docstrings match sync
21
21
uv run poe fix-docstrings # Auto-fix async docstrings
22
-
uv run poe update-spec # Refresh spec/openapi.json from the published OpenAPI spec
23
-
uv run poe generate-models # Regenerate _models.py, _typeddicts.py, _literals.py from spec/openapi.json
24
-
uv run poe check-models # Verify the generated files match the committed spec
22
+
uv run poe generate-models # Regenerate _models.py, _typeddicts.py, _literals.py from the published spec
23
+
uv run poe generate-models-from-file <path># Regenerate from a local OpenAPI spec file
25
24
26
25
# Run a single test
27
26
uv run pytest tests/unit/test_file.py
@@ -78,14 +77,14 @@ Docstrings are written on sync clients and **automatically copied** to async cli
78
77
79
78
Each input-side TypedDict ships in two casings: snake_case (`RequestDict`) and camelCase (`RequestCamelDict`). The camel variants are synthesized in `scripts/postprocess_generated_models.py` from the Pydantic `Field(alias=...)` map; resource-client signatures union both with the Pydantic model so users can pass either casing without losing type-checker support.
80
79
81
-
`spec/openapi.json` is a **committed snapshot** of the published OpenAPI spec and the only input codegen reads. Generation is therefore a pure function of committed state — the same snapshot plus the same pinned tooling always produces the same output — which is what lets `check-models` verify the generated files offline.
82
-
83
-
- Generated by `datamodel-code-generator` from `spec/openapi.json` (config in `pyproject.toml` under `[tool.datamodel-codegen]`, aliases in `datamodel_codegen_aliases.json`)
80
+
- Generated by `datamodel-code-generator` from the OpenAPI spec at `https://docs.apify.com/api/openapi.json` (config in `pyproject.toml` under `[tool.datamodel-codegen]`, aliases in `datamodel_codegen_aliases.json`)
84
81
- After generation, `scripts/postprocess_generated_models.py` is run to apply additional fixes
85
-
- To regenerate locally: `uv run poe update-spec` to refresh the snapshot, then `uv run poe generate-models`. To try a candidate spec, overwrite `spec/openapi.json` and regenerate
86
-
-`uv run poe check-models` (part of `check-code`, and the `Models check` CI job) regenerates, compares, and restores the working tree — it never leaves the generated files modified, and it doesn't care whether they're committed. So a `datamodel-code-generator` or `ruff` upgrade that changes codegen output turns **its own** dependency-bump PR red — that PR carries the regenerated files, instead of the drift contaminating an unrelated spec change later
87
-
- In CI, the `Regenerate models` workflow (`on_schedule_regenerate_models.yaml`) runs nightly at 02:00 UTC: it refreshes the snapshot, regenerates, and opens a PR when the models change. It always generates on master and rebuilds its `ci/regenerate-models` branch from master instead of appending, so the PR diff is always "current spec vs current master". The PR opens with a mergeable `chore:` title — retitle it to `fix:`/`feat:` when the diff is user-facing, so it lands in the changelog and triggers a release
88
-
- The gate is the **generated models**, not the spec: `info.version` in the published spec carries a build timestamp that apify-docs bumps on every spec change, so the snapshot only moves together with the models it produces
82
+
- To regenerate locally:
83
+
- From the live published spec: `uv run poe generate-models`
84
+
- From a local spec file: `uv run poe generate-models-from-file path/to/openapi.json`
85
+
-`scripts/openapi_spec.py` downloads the spec once into git-ignored `tmp/openapi.json` (both codegen passes read that copy, so a spec redeployed mid-run can't leave the generated files describing two different inputs), and afterwards records the spec's `info.version` in `pyproject.toml` under `[tool.apify.openapi-spec]`. That version is **provenance only** — the spec is served latest-only, so it can't fetch that exact document back. It moves together with the generated files, so it stays behind the published spec whenever a spec change leaves the models unchanged
86
+
- In CI, the `Regenerate models` workflow (`on_schedule_regenerate_models.yaml`) runs nightly at 02:00 UTC: it regenerates from the published spec and opens a PR when the models change. It always generates on master and rebuilds its `ci/regenerate-models` branch from master instead of appending, so the PR diff is always "current spec vs current master". The PR opens with a mergeable `chore:` title — retitle it to `fix:`/`feat:` when the diff is user-facing, so it lands in the changelog and triggers a release
87
+
- The gate is the **generated models**, not the spec version: that version carries a build timestamp apify-docs bumps on every spec change, so a version bump on its own says nothing about whether the client is affected
89
88
- Manual regeneration is also possible from the GitHub Actions UI (`Regenerate models` workflow)
0 commit comments