codecraftai-restclient-tailscale 1.2.0__py3-none-any.whl

ccai/restclient/tailscale/__init__.py

@@ -0,0 +1,21 @@
+"""
+    .. module:: tailscale
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Typed, aspect-driven REST client package for the Tailscale
+                   public API (``api.tailscale.com/api/v2/``).
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.restclient.tailscale.tailscaleclient import TailscaleClient
+from ccai.restclient.tailscale.aspectstailscale import (
+    AspectsTailscale, DEFAULT_TAILSCALE_ASPECTS
+)
+
+
+__all__ = ["TailscaleClient", "AspectsTailscale", "DEFAULT_TAILSCALE_ASPECTS"]

ccai/restclient/tailscale/_codegen/__init__.py

@@ -0,0 +1,11 @@
+"""
+    .. module:: _codegen
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Maintainer-facing OpenAPI import and model-emitter package.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []

ccai/restclient/tailscale/_codegen/emitter.py

@@ -0,0 +1,288 @@
+"""
+    .. module:: emitter
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that walks the ``components/schemas`` section of a
+                   Tailscale OpenAPI document and emits one
+                   :class:`SchemaObject` subclass file per schema.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import ast
+import os
+
+from typing import Any, Dict, List, Tuple
+
+from ccai.restclient.tailscale._codegen.typemap import python_type_for_schema
+
+
+GENERATED_HEADER = '''"""
+    .. module:: {module_name}
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Auto-generated Tailscale OpenAPI model class.
+
+    DO NOT EDIT BY HAND. This file is generated by the codegen importer.
+    Run ``python -m ccai.restclient.tailscale._codegen.import_openapi``
+    to regenerate after the upstream OpenAPI document changes.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+'''
+
+# The import statements a generated model module may need, in the order they are emitted.  Each entry is the
+# module name and the names that can be imported from it.  An empty entry marks the break between the standard
+# library group and the ccai group.
+MODEL_IMPORT_CANDIDATES = [
+    ("datetime", ["datetime"]),
+    ("typing", ["Any", "Dict", "List", "Optional"]),
+    None,
+    ("ccai.restclient.base.schemaobject", ["SchemaObject"]),
+    ("ccai.restclient.base.schemafield", ["Field"]),
+]
+
+
+def class_name_for_schema(*, schema_name: str) -> str:
+    """
+        Compute the emitted Python class name for an OpenAPI schema name.
+
+        :param schema_name: The schema key from ``components/schemas``.
+
+        :returns: A ``Tailscale``-prefixed PascalCase class name.
+    """
+    cleaned = schema_name.replace("_", " ").replace("-", " ")
+    parts = cleaned.split()
+    pascal_parts: List[str] = []
+    for part in parts:
+        if len(part) == 0:
+            continue
+        pascal_parts.append(part[0].upper() + part[1:])
+
+    joined = "".join(pascal_parts)
+    rtnval = "Tailscale{}".format(joined)
+    return rtnval
+
+
+def module_name_for_class(*, class_name: str) -> str:
+    """
+        Compute the lowercase-no-underscore module file stem for a class.
+
+        :param class_name: The emitted Python class name.
+
+        :returns: The module file stem (no ``.py`` suffix).
+    """
+    rtnval = class_name.lower()
+    return rtnval
+
+
+def _emit_field_line(*, field_name: str, field_schema: Dict[str, Any],
+                     required: bool) -> str:
+    """
+        Build a single ``Field`` assignment source line for a schema property.
+
+        :param field_name: The OpenAPI property name.
+        :param field_schema: The OpenAPI schema fragment for the property.
+        :param required: Whether the property is in the schema ``required``
+            list.
+
+        :returns: A single line of Python source.
+    """
+    py_type = python_type_for_schema(schema=field_schema)
+
+    description = field_schema.get("description")
+    desc_arg = ""
+    if description is not None:
+        flat = " ".join(description.split())
+        safe = flat.replace('"', "'")
+        desc_arg = ', description="{}"'.format(safe)
+
+    if required is True:
+        rtnval = '    {} = Field({}, required=True{})'.format(
+            field_name, py_type, desc_arg)
+        return rtnval
+
+    rtnval = '    {} = Field(Optional[{}], required=False, default=None{})'.format(
+        field_name, py_type, desc_arg)
+    return rtnval
+
+
+def _emit_import_lines(*, body_text: str) -> List[str]:
+    """
+        Emit the import statements for a generated model module, limited to the names the module body references.
+
+        :param body_text: The generated class source.
+
+        :returns: The import lines, with a blank line between the standard library and ccai groups.
+    """
+    referenced_names = set()
+    tree = ast.parse(body_text)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            referenced_names.add(node.id)
+
+    groups: List[List[str]] = [[]]
+    for candidate in MODEL_IMPORT_CANDIDATES:
+        if candidate is None:
+            groups.append([])
+            continue
+        module_name, names = candidate
+        used_names = []
+        for name in names:
+            if name in referenced_names:
+                used_names.append(name)
+        if len(used_names) > 0:
+            groups[-1].append("from {} import {}".format(module_name, ", ".join(used_names)))
+
+    lines: List[str] = []
+    for group in groups:
+        if len(group) == 0:
+            continue
+        if len(lines) > 0:
+            lines.append("")
+        lines.extend(group)
+
+    return lines
+
+
+def emit_schema_module(*, schema_name: str,
+                        schema: Dict[str, Any]) -> Tuple[str, str, str]:
+    """
+        Emit the Python source for one OpenAPI schema.
+
+        :param schema_name: The schema key from ``components/schemas``.
+        :param schema: The OpenAPI schema fragment dictionary.
+
+        :returns: A tuple of ``(class_name, module_name, source_text)``.
+    """
+    class_name = class_name_for_schema(schema_name=schema_name)
+    module_name = module_name_for_class(class_name=class_name)
+
+    # The class body is generated first so the imports can be limited to the names it references.
+    lines: List[str] = []
+    lines.append("class {}(SchemaObject):".format(class_name))
+
+    description = schema.get("description")
+    doc_summary = "Auto-generated from Tailscale OpenAPI schema '{}'.".format(
+        schema_name)
+    lines.append('    """')
+    lines.append("        {}".format(doc_summary))
+    if description is not None:
+        flat = " ".join(description.split())
+        lines.append("")
+        lines.append("        {}".format(flat))
+    lines.append('    """')
+
+    properties = schema.get("properties")
+    required_list = schema.get("required")
+    if required_list is None:
+        required_list = []
+
+    if properties is None or len(properties) == 0:
+        lines.append("")
+        lines.append("    pass")
+    else:
+        lines.append("")
+        # Stable, deterministic ordering: required first then alphabetical.
+        ordered_names = sorted(
+            properties.keys(),
+            key=lambda name: (0 if name in required_list else 1, name))
+        for prop_name in ordered_names:
+            prop_schema = properties[prop_name]
+            is_required = prop_name in required_list
+            field_line = _emit_field_line(field_name=prop_name,
+                                          field_schema=prop_schema,
+                                          required=is_required)
+            lines.append(field_line)
+
+    lines.append("")
+    body_text = os.linesep.join(lines)
+
+    header_lines: List[str] = []
+    header_lines.append(GENERATED_HEADER.format(module_name=module_name))
+    header_lines.extend(_emit_import_lines(body_text=body_text))
+    header_lines.append("")
+    header_lines.append("")
+    header_lines.append("")
+    header_lines.append("")
+
+    source_text = os.linesep.join(header_lines) + body_text
+    rtnval = (class_name, module_name, source_text)
+    return rtnval
+
+
+def emit_all_schemas(*, schemas: Dict[str, Any]) -> Dict[str, Tuple[str, str]]:
+    """
+        Emit Python source for every object schema in a schemas section.
+
+        :param schemas: The ``components/schemas`` dictionary.
+
+        :returns: A mapping of ``module_name`` to ``(class_name, source)``.
+    """
+    rtnval: Dict[str, Tuple[str, str]] = {}
+
+    for schema_name in sorted(schemas.keys()):
+        schema = schemas[schema_name]
+        if not isinstance(schema, dict):
+            continue
+
+        declared_type = schema.get("type")
+        has_props = "properties" in schema
+        has_allof = "allOf" in schema
+
+        # Only object-shaped schemas become model classes. Scalar/enum
+        # aliases (string, array) are not emitted as classes.
+        if declared_type != "object" and not has_props and not has_allof:
+            continue
+
+        class_name, module_name, source_text = emit_schema_module(
+            schema_name=schema_name, schema=schema)
+        rtnval[module_name] = (class_name, source_text)
+
+    return rtnval
+
+
+def emit_model_init(*, emitted: Dict[str, Tuple[str, str]]) -> str:
+    """
+        Emit the ``model/__init__.py`` re-export source.
+
+        :param emitted: The mapping produced by :func:`emit_all_schemas`.
+
+        :returns: The ``__init__.py`` source text.
+    """
+    lines: List[str] = []
+    lines.append('"""')
+    lines.append("    .. module:: model")
+    lines.append("        :synopsis: Re-exports for the generated Tailscale "
+                 "OpenAPI model classes.")
+    lines.append("")
+    lines.append("    DO NOT EDIT BY HAND. Regenerate via")
+    lines.append("    ``python -m ccai.restclient.tailscale._codegen."
+                 "import_openapi``.")
+    lines.append('"""')
+    lines.append("")
+
+    all_names: List[str] = []
+    for module_name in sorted(emitted.keys()):
+        class_name, _ = emitted[module_name]
+        all_names.append(class_name)
+        lines.append("from ccai.restclient.tailscale.model.{} import {}".format(
+            module_name, class_name))
+
+    lines.append("")
+    lines.append("__all__ = [")
+    for class_name in sorted(all_names):
+        lines.append('    "{}",'.format(class_name))
+    lines.append("]")
+    lines.append("")
+
+    rtnval = os.linesep.join(lines)
+    return rtnval

ccai/restclient/tailscale/_codegen/import_openapi.py

@@ -0,0 +1,174 @@
+"""
+    .. module:: import_openapi
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Maintainer-facing script that fetches the Tailscale
+                   OpenAPI document, validates it, and regenerates the
+                   typed model classes under ``model/``.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import hashlib
+import os
+
+from typing import Any, Dict
+
+import requests
+import yaml
+
+from ccai.errors.exceptions import ConfigurationError, SemanticError
+
+from ccai.restclient.tailscale._codegen.emitter import (
+    emit_all_schemas, emit_model_init
+)
+
+
+OPENAPI_URL = "https://api.tailscale.com/api/v2?outputOpenapiSchema=true"
+
+PACKAGE_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+SPEC_DIR = os.path.join(PACKAGE_ROOT, "_spec")
+MODEL_DIR = os.path.join(PACKAGE_ROOT, "model")
+SPEC_FILE = os.path.join(SPEC_DIR, "openapi.json")
+SHA_FILE = os.path.join(SPEC_DIR, "openapi.sha256")
+
+
+def fetch_openapi_document(*, url: str = OPENAPI_URL) -> str:
+    """
+        Fetch the upstream Tailscale OpenAPI document text.
+
+        :param url: The upstream document URL.
+
+        :returns: The raw document text.
+
+        :raises: :class:`ConfigurationError` when the upstream URL returns a
+            non-200 status.
+    """
+    response = requests.get(url, timeout=30)
+    if response.status_code != 200:
+        err_msg_lines = ["Failed to fetch the Tailscale OpenAPI document."]
+        err_msg_lines.append("URL: {}".format(url))
+        err_msg_lines.append("STATUS: {}".format(response.status_code))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise ConfigurationError(err_msg)
+
+    rtnval = response.text
+    return rtnval
+
+
+def validate_openapi_document(*, document_text: str) -> Dict[str, Any]:
+    """
+        Parse and validate an OpenAPI document text against OpenAPI 3.x.
+
+        :param document_text: The raw document text (YAML or JSON).
+
+        :returns: The parsed document dictionary.
+
+        :raises: :class:`SemanticError` when the document is not a valid
+            OpenAPI 3.x document.
+    """
+    try:
+        parsed = yaml.safe_load(document_text)
+    except yaml.YAMLError as yamlerr:
+        err_msg_lines = ["Tailscale OpenAPI document failed to parse."]
+        err_msg_lines.append("DETAIL: {}".format(yamlerr))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise SemanticError(err_msg) from None
+
+    if not isinstance(parsed, dict):
+        raise SemanticError("Tailscale OpenAPI document is not a mapping.")
+
+    version = parsed.get("openapi")
+    if version is None or not str(version).startswith("3."):
+        err_msg_lines = ["Document is not an OpenAPI 3.x document."]
+        err_msg_lines.append("FOUND VERSION: {}".format(version))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise SemanticError(err_msg)
+
+    try:
+        from openapi_spec_validator import validate as _validate_spec
+        _validate_spec(parsed)
+    except ImportError:
+        # The validator is an optional maintainer-side dependency. The
+        # version check above is the minimum gate when it is absent.
+        pass
+    except Exception as valerr:
+        err_msg_lines = ["Tailscale OpenAPI document failed schema validation."]
+        err_msg_lines.append("DETAIL: {}".format(valerr))
+        err_msg = os.linesep.join(err_msg_lines)
+        raise SemanticError(err_msg) from None
+
+    rtnval = parsed
+    return rtnval
+
+
+def regenerate_models(*, document: Dict[str, Any]) -> int:
+    """
+        Regenerate every model file from a validated OpenAPI document.
+
+        :param document: The parsed and validated OpenAPI document.
+
+        :returns: The count of model files written.
+    """
+    components = document.get("components")
+    if components is None:
+        raise SemanticError("OpenAPI document has no 'components' section.")
+
+    schemas = components.get("schemas")
+    if schemas is None:
+        raise SemanticError("OpenAPI document has no 'components/schemas'.")
+
+    emitted = emit_all_schemas(schemas=schemas)
+
+    if not os.path.exists(MODEL_DIR):
+        os.makedirs(MODEL_DIR)
+
+    written = 0
+    for module_name in sorted(emitted.keys()):
+        _, source_text = emitted[module_name]
+        target_path = os.path.join(MODEL_DIR, "{}.py".format(module_name))
+        with open(target_path, "w", encoding="utf-8") as model_file:
+            model_file.write(source_text)
+        written = written + 1
+
+    init_source = emit_model_init(emitted=emitted)
+    init_path = os.path.join(MODEL_DIR, "__init__.py")
+    with open(init_path, "w", encoding="utf-8") as init_file:
+        init_file.write(init_source)
+
+    rtnval = written
+    return rtnval
+
+
+def main() -> None:
+    """
+        Run the full fetch/validate/regenerate import flow.
+
+        :returns: ``None``.
+    """
+    document_text = fetch_openapi_document()
+    document = validate_openapi_document(document_text=document_text)
+
+    if not os.path.exists(SPEC_DIR):
+        os.makedirs(SPEC_DIR)
+
+    with open(SPEC_FILE, "w", encoding="utf-8") as spec_file:
+        spec_file.write(document_text)
+
+    digest = hashlib.sha256(document_text.encode("utf-8")).hexdigest()
+    with open(SHA_FILE, "w", encoding="utf-8") as sha_file:
+        sha_file.write(digest)
+        sha_file.write(os.linesep)
+
+    count = regenerate_models(document=document)
+
+    print("Regenerated {} Tailscale model files.".format(count))
+    return
+
+
+if __name__ == "__main__":
+    main()

ccai/restclient/tailscale/_codegen/typemap.py

@@ -0,0 +1,97 @@
+"""
+    .. module:: typemap
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that maps OpenAPI ``type``/``format`` declarations
+                   onto Python type expressions used by the model emitter.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import os
+
+from typing import Any, Dict
+
+from ccai.errors.exceptions import SemanticError
+
+
+SCALAR_TYPE_MAP: Dict[str, str] = {
+    "string": "str",
+    "integer": "int",
+    "number": "float",
+    "boolean": "bool",
+}
+
+
+def python_type_for_schema(*, schema: Dict[str, Any]) -> str:
+    """
+        Resolve a single OpenAPI schema fragment to a Python type expression
+        usable as a ``Field`` ``field_type`` argument.
+
+        :param schema: An OpenAPI schema fragment dictionary.
+
+        :returns: A Python type-expression string (for example ``"str"`` or
+            ``"List[str]"``).
+
+        :raises: :class:`SemanticError` when the fragment declares a type
+            that the emitter has no mapping for.
+    """
+    if schema is None:
+        rtnval = "Any"
+        return rtnval
+
+    ref_value = schema.get("$ref")
+    if ref_value is not None:
+        # Cross-schema references are emitted as quoted forward-ref strings.
+        # The ``Field`` descriptor accepts ``Any`` for ``field_type`` so a
+        # string class name is a valid, import-order-independent type tag.
+        ref_name = ref_value.rsplit("/", 1)[-1]
+        rtnval = "'Tailscale{}'".format(ref_name)
+        return rtnval
+
+    declared_type = schema.get("type")
+
+    if declared_type is None:
+        # allOf / oneOf / untyped fragments degrade to Any so the emitter
+        # never produces an unimportable file.
+        rtnval = "Any"
+        return rtnval
+
+    if isinstance(declared_type, list):
+        # OpenAPI 3.1 allows a list of types (commonly ["string", "null"]).
+        non_null = [entry for entry in declared_type if entry != "null"]
+        if len(non_null) == 1:
+            inner_schema = dict(schema)
+            inner_schema["type"] = non_null[0]
+            rtnval = python_type_for_schema(schema=inner_schema)
+            return rtnval
+        rtnval = "Any"
+        return rtnval
+
+    if declared_type == "array":
+        item_schema = schema.get("items")
+        item_type = python_type_for_schema(schema=item_schema)
+        rtnval = "List[{}]".format(item_type)
+        return rtnval
+
+    if declared_type == "object":
+        rtnval = "Dict[str, Any]"
+        return rtnval
+
+    if declared_type in SCALAR_TYPE_MAP:
+        if declared_type == "string":
+            declared_format = schema.get("format")
+            if declared_format == "date-time":
+                rtnval = "datetime"
+                return rtnval
+        rtnval = SCALAR_TYPE_MAP[declared_type]
+        return rtnval
+
+    err_msg_lines = ["Unmapped OpenAPI type encountered by the emitter."]
+    err_msg_lines.append("TYPE: {}".format(declared_type))
+    err_msg = os.linesep.join(err_msg_lines)
+    raise SemanticError(err_msg)