Skip to content

Commit 3636d16

Browse files
Copilotbytemain
Copilot
and
bytemain
authored
Document API response metadata requirements
Agent-Logs-Url: https://github.com/version-fox/vfox-python/sessions/b5f59091-7d95-4295-adf3-c4cdda830c77 Co-authored-by: bytemain <13938334+bytemain@users.noreply.github.com>
1 parent 839a6e3 commit 3636d16

1 file changed

Lines changed: 219 additions & 0 deletions

File tree

‎docs/python-build-standalone-api-response.md‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# Python Build Standalone API Response Requirements
2+
3+
## Scope
4+
5+
This document defines only the API response requirements for Python Build Standalone release metadata.
6+
7+
The API data source is GitHub Releases and release assets. The API must only return fields that are available from GitHub Release data or can be reliably parsed from release asset names.
8+
9+
The response must not describe unavailable concepts or client-specific behavior.
10+
11+
## Data Source
12+
13+
The API reads release information from:
14+
15+
```text
16+
https://github.com/astral-sh/python-build-standalone/releases
17+
```
18+
19+
For each GitHub Release, the API may use:
20+
21+
- Release tag name
22+
- Release asset name
23+
- Release asset download URL
24+
- Release asset size
25+
- Release asset content type
26+
- Release asset created time
27+
- Release asset updated time
28+
- Release asset digest
29+
30+
GitHub Release assets currently include a `digest` field in the following format:
31+
32+
```text
33+
sha256:<hex-encoded-sha256>
34+
```
35+
36+
Example:
37+
38+
```text
39+
sha256:f76cc83c7db16cfc8794bf6e44d834152b57d8bab4e04e823cbc59ed23ec22f8
40+
```
41+
42+
## Response Shape
43+
44+
The API returns a JSON object with an `items` array.
45+
46+
```json
47+
{
48+
"items": [
49+
{
50+
"implementation": "cpython",
51+
"version": "3.10.20",
52+
"display_version": "3.10.20",
53+
"variant": "default",
54+
"release": "20260414",
55+
"filename": "cpython-3.10.20+20260414-aarch64-apple-darwin-install_only.tar.gz",
56+
"url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.10.20%2B20260414-aarch64-apple-darwin-install_only.tar.gz",
57+
"platform": {
58+
"os": "darwin",
59+
"arch": "aarch64",
60+
"libc": null
61+
},
62+
"asset": {
63+
"size": 19408836,
64+
"content_type": "application/octet-stream",
65+
"created_at": "2026-04-14T17:26:12Z",
66+
"updated_at": "2026-04-14T17:26:13Z",
67+
"digest": "sha256:f76cc83c7db16cfc8794bf6e44d834152b57d8bab4e04e823cbc59ed23ec22f8",
68+
"sha256": "f76cc83c7db16cfc8794bf6e44d834152b57d8bab4e04e823cbc59ed23ec22f8"
69+
}
70+
}
71+
]
72+
}
73+
```
74+
75+
## Top-Level Fields
76+
77+
| Field | Type | Required | Description |
78+
| --- | --- | --- | --- |
79+
| `items` | array | Yes | List of recognized Python Build Standalone release assets. |
80+
81+
## Item Fields
82+
83+
Each item represents one recognized release asset.
84+
85+
| Field | Type | Required | Description |
86+
| --- | --- | --- | --- |
87+
| `implementation` | string | Yes | Python implementation parsed from the asset name, such as `cpython`. |
88+
| `version` | string | Yes | Python version parsed from the asset name, such as `3.10.20`. |
89+
| `display_version` | string | Yes | Version string for display. Free-threaded builds use the `t` suffix. |
90+
| `variant` | string | Yes | Build variant, such as `default` or `freethreaded`. |
91+
| `release` | string | Yes | GitHub Release tag name, such as `20260414`. |
92+
| `filename` | string | Yes | GitHub Release asset name. |
93+
| `url` | string | Yes | GitHub Release asset download URL. |
94+
| `platform` | object | Yes | Platform information parsed from the asset name. |
95+
| `asset` | object | No | GitHub Release asset metadata and derived checksum fields. |
96+
97+
## Platform Fields
98+
99+
| Field | Type | Required | Description |
100+
| --- | --- | --- | --- |
101+
| `os` | string | Yes | Operating system parsed from the asset name, such as `linux`, `darwin`, or `windows`. |
102+
| `arch` | string | Yes | CPU architecture parsed from the asset name, such as `x86_64` or `aarch64`. |
103+
| `libc` | string or null | No | Linux libc parsed from the asset name, such as `gnu` or `musl`; otherwise `null`. |
104+
105+
## Asset Fields
106+
107+
The `asset` object contains metadata from the GitHub Release asset. If a field is not present in the GitHub Release asset data, the API must not invent it.
108+
109+
| Field | Type | Required | Description |
110+
| --- | --- | --- | --- |
111+
| `size` | number | No | Asset size in bytes from GitHub Release asset metadata. |
112+
| `content_type` | string | No | Asset MIME type from GitHub Release asset metadata. |
113+
| `created_at` | string | No | Asset creation time from GitHub Release asset metadata. |
114+
| `updated_at` | string | No | Asset update time from GitHub Release asset metadata. |
115+
| `digest` | string | No | Asset digest from GitHub Release asset metadata, such as `sha256:<hex>`. |
116+
| `sha256` | string | No | Hex-encoded SHA-256 checksum derived from `digest` when `digest` starts with `sha256:`. |
117+
118+
## Parsing Rules
119+
120+
### Version
121+
122+
The `version` field is parsed from the Python version segment of the asset name.
123+
124+
Example:
125+
126+
```text
127+
cpython-3.10.20+20260414-aarch64-apple-darwin-install_only.tar.gz
128+
```
129+
130+
Produces:
131+
132+
```json
133+
{
134+
"version": "3.10.20"
135+
}
136+
```
137+
138+
### Display Version
139+
140+
Default builds use the original version string:
141+
142+
```json
143+
{
144+
"version": "3.10.20",
145+
"display_version": "3.10.20",
146+
"variant": "default"
147+
}
148+
```
149+
150+
Free-threaded builds append `t`:
151+
152+
```json
153+
{
154+
"version": "3.13.3",
155+
"display_version": "3.13.3t",
156+
"variant": "freethreaded"
157+
}
158+
```
159+
160+
### Variant
161+
162+
The API currently recognizes:
163+
164+
| Variant | Rule |
165+
| --- | --- |
166+
| `default` | Asset name does not contain the free-threaded marker. |
167+
| `freethreaded` | Asset name contains the free-threaded marker. |
168+
169+
### SHA-256
170+
171+
When GitHub Release asset metadata contains:
172+
173+
```json
174+
{
175+
"digest": "sha256:f76cc83c7db16cfc8794bf6e44d834152b57d8bab4e04e823cbc59ed23ec22f8"
176+
}
177+
```
178+
179+
The API may return both the original `digest` and the normalized `sha256` value:
180+
181+
```json
182+
{
183+
"digest": "sha256:f76cc83c7db16cfc8794bf6e44d834152b57d8bab4e04e823cbc59ed23ec22f8",
184+
"sha256": "f76cc83c7db16cfc8794bf6e44d834152b57d8bab4e04e823cbc59ed23ec22f8"
185+
}
186+
```
187+
188+
If `digest` is missing or does not use the `sha256:` prefix, `sha256` must be omitted.
189+
190+
## Filtering Rules
191+
192+
The API should only return release assets that can be recognized and parsed.
193+
194+
The API should exclude assets when:
195+
196+
- The implementation cannot be parsed.
197+
- The Python version cannot be parsed.
198+
- The platform cannot be parsed.
199+
- The asset is not a target Python Build Standalone release asset.
200+
- The asset filename does not match the expected format.
201+
202+
## Sorting Rules
203+
204+
The API should return versions from newest to oldest.
205+
206+
For the same Python version, default builds should be ordered before free-threaded builds.
207+
208+
## Acceptance Criteria
209+
210+
- The response contains a top-level `items` array.
211+
- Each item represents one recognized GitHub Release asset.
212+
- Each item contains `implementation`, `version`, `display_version`, `variant`, `release`, `filename`, `url`, and `platform`.
213+
- `release` comes from the GitHub Release tag name.
214+
- `filename` comes from the GitHub Release asset name.
215+
- `url` comes from the GitHub Release asset download URL.
216+
- `asset.digest` is returned when GitHub Release asset metadata provides it.
217+
- `asset.sha256` is returned when it can be derived from a `sha256:<hex>` digest.
218+
- Fields that are not present in GitHub Release data and cannot be reliably parsed are not returned.
219+
- Unrecognized assets are excluded.

0 commit comments

Comments
 (0)