versioning

Author: njbrake

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openresponses-types"
-version = "0.1.0"
+version = "2.3.0"
 description = "Python SDK for OpenResponses specification"
 readme = "README.md"
 license = "Apache-2.0"

scripts/generate_types.py

@@ -10,11 +10,12 @@
 Options:
     --force     Regenerate even if spec hasn't changed
     --check     Check if spec has changed without regenerating (exit 1 if changed)
-    --version   Show current spec hash and exit
+    --version   Show current spec version and hash, then exit
 """
 
 import argparse
 import hashlib
+import json
 import re
 import subprocess
 import sys
@@ -28,8 +29,10 @@
 SPEC_CACHE_DIR = PROJECT_ROOT / "src" / "openresponses_types" / "_spec_cache"
 SPEC_CACHE_FILE = SPEC_CACHE_DIR / "openapi.json"
 SPEC_HASH_FILE = SPEC_CACHE_DIR / "openapi.sha256"
+SPEC_VERSION_FILE = SPEC_CACHE_DIR / "openapi.version"
 OUTPUT_FILE = PROJECT_ROOT / "src" / "openresponses_types" / "types.py"
 INIT_FILE = PROJECT_ROOT / "src" / "openresponses_types" / "__init__.py"
+PYPROJECT_FILE = PROJECT_ROOT / "pyproject.toml"
 
 GENERATION_HEADER = '''\
 """Auto-generated Pydantic models from OpenResponses OpenAPI specification.
@@ -38,6 +41,7 @@
 
 This file is generated by: scripts/generate_types.py
 Source: {spec_url}
+Spec Version: {spec_version}
 Spec Hash: {spec_hash}
 
 To regenerate:
@@ -54,6 +58,12 @@ def fetch_spec() -> bytes:
         return response.read()
 
 
+def extract_spec_version(content: bytes) -> str:
+    """Extract the version from the OpenAPI spec."""
+    spec = json.loads(content)
+    return spec.get("info", {}).get("version", "0.0.0")
+
+
 def compute_hash(content: bytes) -> str:
     """Compute SHA-256 hash of content."""
     return hashlib.sha256(content).hexdigest()
@@ -66,11 +76,19 @@ def get_cached_hash() -> str | None:
     return None
 
 
-def save_spec_cache(content: bytes, spec_hash: str) -> None:
-    """Save the spec and its hash to the cache directory."""
+def get_cached_version() -> str | None:
+    """Get the previously stored spec version, if any."""
+    if SPEC_VERSION_FILE.exists():
+        return SPEC_VERSION_FILE.read_text().strip()
+    return None
+
+
+def save_spec_cache(content: bytes, spec_hash: str, spec_version: str) -> None:
+    """Save the spec, its hash, and version to the cache directory."""
     SPEC_CACHE_DIR.mkdir(parents=True, exist_ok=True)
     SPEC_CACHE_FILE.write_bytes(content)
     SPEC_HASH_FILE.write_text(spec_hash)
+    SPEC_VERSION_FILE.write_text(spec_version)
 
 
 def fix_discriminator_issues() -> None:
@@ -113,7 +131,7 @@ def format_output() -> None:
         print(f"Warning: ruff formatting failed: {result.stderr}", file=sys.stderr)
 
 
-def generate_models(spec_hash: str) -> None:
+def generate_models(spec_hash: str, spec_version: str) -> None:
     """Run datamodel-codegen to generate Pydantic models."""
     print("Generating Pydantic models...")
 
@@ -141,17 +159,21 @@ def generate_models(spec_hash: str) -> None:
         print(f"Error generating models: {result.stderr}", file=sys.stderr)
         sys.exit(1)
 
-    prepend_header(spec_hash)
+    prepend_header(spec_hash, spec_version)
     fix_discriminator_issues()
     format_output()
-    update_init_spec_hash(spec_hash)
+    update_init_metadata(spec_hash, spec_version)
     print(f"Generated: {OUTPUT_FILE}")
 
 
-def prepend_header(spec_hash: str) -> None:
+def prepend_header(spec_hash: str, spec_version: str) -> None:
     """Prepend generation header to the output file."""
     content = OUTPUT_FILE.read_text()
-    header = GENERATION_HEADER.format(spec_url=OPENRESPONSES_SPEC_URL, spec_hash=spec_hash)
+    header = GENERATION_HEADER.format(
+        spec_url=OPENRESPONSES_SPEC_URL,
+        spec_hash=spec_hash,
+        spec_version=spec_version,
+    )
 
     lines = content.split("\n")
     filtered_lines = []
@@ -166,16 +188,31 @@ def prepend_header(spec_hash: str) -> None:
     OUTPUT_FILE.write_text(header + "\n".join(filtered_lines))
 
 
-def update_init_spec_hash(spec_hash: str) -> None:
-    """Update the __spec_hash__ in __init__.py."""
+def update_init_metadata(spec_hash: str, spec_version: str) -> None:
+    """Update the __spec_hash__ and __spec_version__ in __init__.py."""
     if not INIT_FILE.exists():
         return
 
     content = INIT_FILE.read_text()
+
     # Update __spec_hash__ if it exists
     if "__spec_hash__" in content:
         content = re.sub(r'__spec_hash__\s*=\s*"[^"]*"', f'__spec_hash__ = "{spec_hash}"', content)
-        INIT_FILE.write_text(content)
+
+    # Update __spec_version__ if it exists
+    if "__spec_version__" in content:
+        content = re.sub(r'__spec_version__\s*=\s*"[^"]*"', f'__spec_version__ = "{spec_version}"', content)
+
+    INIT_FILE.write_text(content)
+
+
+def suggest_package_version(spec_version: str) -> str:
+    """Suggest a package version based on the spec version.
+
+    Package version matches the spec version directly.
+    For hotfixes, use PEP 440 post-releases (e.g., 2.3.0.post1).
+    """
+    return spec_version
 
 
 def main() -> None:
@@ -184,43 +221,51 @@ def main() -> None:
     parser.add_argument(
         "--check", action="store_true", help="Check if spec has changed without regenerating (exit 1 if changed)"
     )
-    parser.add_argument("--version", action="store_true", help="Show current spec hash and exit")
+    parser.add_argument("--version", action="store_true", help="Show current spec version and hash, then exit")
     args = parser.parse_args()
 
     if args.version:
+        cached_version = get_cached_version()
         cached_hash = get_cached_hash()
-        if cached_hash:
-            print(f"Current spec hash: {cached_hash}")
+        if cached_version and cached_hash:
+            print(f"Spec version: {cached_version}")
+            print(f"Spec hash: {cached_hash}")
+            print(f"Suggested package version: {suggest_package_version(cached_version)}")
         else:
-            print("No spec hash cached yet. Run without --version to generate.")
+            print("No spec cached yet. Run without --version to generate.")
         return
 
     spec_content = fetch_spec()
     current_hash = compute_hash(spec_content)
+    current_version = extract_spec_version(spec_content)
     cached_hash = get_cached_hash()
+    cached_version = get_cached_version()
 
     if cached_hash == current_hash and not args.force:
-        print(f"OpenResponses spec unchanged (hash: {current_hash[:12]}...)")
+        print(f"OpenResponses spec unchanged (v{current_version}, hash: {current_hash[:12]}...)")
         if args.check:
             sys.exit(0)
         print("Use --force to regenerate anyway.")
         return
 
     if cached_hash is None:
-        print("First time generating OpenResponses types.")
+        print(f"First time generating OpenResponses types (spec v{current_version}).")
     else:
         print("OpenResponses spec has CHANGED!")
-        print(f"  Previous: {cached_hash[:12]}...")
-        print(f"  Current:  {current_hash[:12]}...")
+        print(f"  Previous: v{cached_version} (hash: {cached_hash[:12]}...)")
+        print(f"  Current:  v{current_version} (hash: {current_hash[:12]}...)")
 
     if args.check:
         print("\nSpec change detected. Run without --check to regenerate.")
         sys.exit(1)
 
-    save_spec_cache(spec_content, current_hash)
-    generate_models(current_hash)
+    save_spec_cache(spec_content, current_hash, current_version)
+    generate_models(current_hash, current_version)
 
-    print("\nGeneration complete!")
+    print(f"\nGeneration complete!")
+    print(f"Spec version: {current_version}")
+    print(f"Suggested package version: {suggest_package_version(current_version)}")
+    print(f"\nTo release, update pyproject.toml version and tag: git tag v{suggest_package_version(current_version)}")
 
 
 if __name__ == "__main__":

src/openresponses_types/__init__.py

@@ -14,7 +14,8 @@
     event: ResponseStreamEvent = ...
 """
 
-__version__ = "0.1.0"
+__version__ = "2.3.0"
+__spec_version__ = "2.3.0"
 __spec_hash__ = "915047617fddd639c691fe1e00d5ba6917b7187d7abc62adf074fd7c823bad7f"
 
 # Re-export all types from generated module

src/openresponses_types/types.py

@@ -4,6 +4,7 @@
 
 This file is generated by: scripts/generate_types.py
 Source: https://raw.githubusercontent.com/openresponses/openresponses/main/public/openapi/openapi.json
+Spec Version: 2.3.0
 Spec Hash: 915047617fddd639c691fe1e00d5ba6917b7187d7abc62adf074fd7c823bad7f
 
 To regenerate: