Add codegen

Author: julka

README.md

@@ -82,9 +82,9 @@ Run the script:
 python main.py
 ```
 
-### With typed parameters (optional)
+### With typed parameters (recommended)
 
-For IDE autocomplete and parameter validation, run the type generator after installing:
+For IDE autocomplete and parameter validation, run the type generator once after installing. Dict-based usage works without this step, but typed classes require it:
 
 ```bash
 python -m decodo.codegen.codegen

src/decodo/codegen/codegen.py

@@ -1,22 +1,63 @@
 from __future__ import annotations
 
+import argparse
 import os
 import shutil
+import sys
+from pathlib import Path
 
 from .web_scraping_api.generate_parameters import generate_parameters_file
 from .web_scraping_api.generate_targets import generate_targets_enum_file, generate_targets_file
-from .web_scraping_api.shared import local_ir_path, out_dir
+from .web_scraping_api.shared import local_ir_path, out_dir as _default_out_dir
+
+
+def _in_site_packages() -> bool:
+    return "site-packages" in str(Path(__file__).resolve())
 
 
 def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="python -m decodo.codegen.codegen",
+        description="Generate typed parameter classes from the Decodo IR schema.",
+    )
+    parser.add_argument(
+        "--out-dir",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Directory to write generated files into. "
+            "Defaults to the package's built-in generated/ directory "
+            "(editable installs only). Required for non-editable installs."
+        ),
+    )
+    args = parser.parse_args()
+
+    if args.out_dir is not None:
+        out_dir = str(Path(args.out_dir).resolve())
+    elif _in_site_packages():
+        print(
+            "error: running from a non-editable install.\n"
+            "Generated files would be written into site-packages and silently reverted\n"
+            "on the next `pip install --upgrade`.\n"
+            "Use --out-dir <path> to specify a project-local output directory.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    else:
+        out_dir = _default_out_dir
+
     os.makedirs(out_dir, exist_ok=True)
     init_path = os.path.join(out_dir, "__init__.py")
     if not os.path.exists(init_path):
         open(init_path, "w").close()
 
-    generate_parameters_file()
-    generate_targets_enum_file()
-    generate_targets_file()
+    generate_parameters_file(out_dir)
+    # The Target enum lives in decodo/targets.py (committed source). Only regenerate
+    # it when we have write access to the source tree (editable install). Non-editable
+    # installs already ship the enum baked into the package.
+    if not _in_site_packages():
+        generate_targets_enum_file()
+    generate_targets_file(out_dir)
 
     # Copy the downloaded IR JSON into generated/ so BundledSchema can load
     # schemas directly at runtime without a generated Python file.

src/decodo/codegen/web_scraping_api/generate_parameters.py

@@ -108,13 +108,14 @@ def get_parameters_file(api: WebScrapingApiIR) -> str:
     return "\n".join(lines)
 
 
-def generate_parameters_file() -> None:
+def generate_parameters_file(dest_dir: str | None = None) -> None:
     ir = fetch_intermediate_representation()
     api = ir["apis"]["webScrapingApi"]
     file_contents = get_parameters_file(api)
 
-    os.makedirs(out_dir, exist_ok=True)
-    out_path = os.path.join(out_dir, "parameters.py")
+    target = dest_dir if dest_dir is not None else out_dir
+    os.makedirs(target, exist_ok=True)
+    out_path = os.path.join(target, "parameters.py")
     with open(out_path, "w", encoding="utf-8") as f:
         f.write(file_contents)
 

src/decodo/codegen/web_scraping_api/generate_targets.py

@@ -207,13 +207,14 @@ def generate_targets_enum_file() -> None:
     print(f"  {targets_enum_path} ({target_count} targets)")
 
 
-def generate_targets_file() -> None:
+def generate_targets_file(dest_dir: str | None = None) -> None:
     ir = fetch_intermediate_representation()
     api = ir["apis"]["webScrapingApi"]
     file_contents = _get_targets_file_contents(api)
 
-    os.makedirs(out_dir, exist_ok=True)
-    out_path = os.path.join(out_dir, "targets.py")
+    target = dest_dir if dest_dir is not None else out_dir
+    os.makedirs(target, exist_ok=True)
+    out_path = os.path.join(target, "targets.py")
     with open(out_path, "w", encoding="utf-8") as f:
         f.write(file_contents)
 

src/decodo/schema/bundled_schema.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import warnings
 from pathlib import Path
 from typing import Any, ClassVar, cast
 
@@ -42,6 +43,12 @@ def __init__(self) -> None:
             }
             self._target_meta = _target_meta if _target_meta is not None else build_target_meta(api_targets)
         else:
+            warnings.warn(
+                "Decodo IR schema not found — payload validation is disabled. "
+                "Run: python -m decodo.codegen.codegen",
+                RuntimeWarning,
+                stacklevel=2,
+            )
             self._request_schemas = {}
             self._target_meta = _target_meta or {}