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

ccai/gitlab/rest/generation/restclientgenerator.py

@@ -0,0 +1,581 @@
+"""
+    .. module:: restclientgenerator
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Generates REST client source from the GitHub OpenAPI description.
+    
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import argparse
+import ast
+import json
+import keyword
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+
+AUTO_GENERATED_BANNER = "# Auto-generated by RestClientGenerator. DO NOT EDIT.\n"
+
+SUPPORTED_HTTP_METHODS = {"get", "post", "put", "delete", "patch", "head", "options"}
+
+
+@dataclass
+class ParameterSpec:
+    """
+        Specification for a parameter from the OpenAPI description.
+    """
+    name: str
+    location: str
+    required: bool
+    schema: Dict[str, Any]
+    description: str
+
+
+@dataclass
+class OperationSpec:
+    """
+        Container holding details about an API operation.
+    """
+    path: str
+    http_method: str
+    group: str
+    operation_id: str
+    method_name: str
+    summary: str
+    description: str
+    parameters: List[ParameterSpec]
+    request_body: Optional[Dict[str, Any]]
+    responses: Dict[str, Any]
+    external_docs: Optional[Dict[str, Any]] = None
+
+
+class RestClientGenerator:
+    """
+        Shapes the patterns for the REST API generation.
+    """
+
+    def __init__(self, openapi_spec_file: str, clients_root: str, client_class_name: str = "GithubRestClient"):
+        self._spec_path = Path(openapi_spec_file).resolve()
+        self._clients_root = Path(clients_root).resolve()
+        self._client_class_name = client_class_name
+        self._spec = self._load_spec(self._spec_path)
+
+        self._components = self._spec.get("components", {})
+        self._tag_catalog: Dict[str, str] = {}
+        self._groups: Dict[str, List[OperationSpec]] = {}
+
+        self._process_spec()
+        return
+
+    def generate(self):
+        """
+            Generate all client, group, parameter, and response modules.
+        """
+        clients_root = self._clients_root
+        groups_dir = clients_root / "groups"
+        params_dir = clients_root / "parameters"
+        responses_dir = clients_root / "responses"
+
+        for directory in (groups_dir, params_dir, responses_dir):
+            directory.mkdir(parents=True, exist_ok=True)
+
+        sorted_groups = sorted(self._groups.keys())
+
+        for group in sorted_groups:
+            ops = sorted(self._groups[group], key=lambda o: o.method_name)
+            self._generate_parameter_module(group, ops, params_dir)
+            self._generate_response_module(group, ops, responses_dir)
+            self._generate_group_module(group, ops, groups_dir)
+
+        self._generate_client_module(sorted_groups, clients_root)
+        self._write_simple_init(groups_dir)
+        self._write_simple_init(params_dir)
+        self._write_simple_init(responses_dir)
+        self._write_simple_init(clients_root)
+        return
+
+    def _load_spec(self, spec_path: Path) -> Dict[str, Any]:
+        """
+            Load the OpenAPI specification from JSON or YAML.
+        """
+        suffix = spec_path.suffix.lower()
+        with spec_path.open("r", encoding="utf-8") as sf:
+            if suffix in (".yaml", ".yml"):
+                if yaml is None:
+                    errmsg = "PyYAML is required to load YAML specifications. Install with 'pip install pyyaml'."
+                    raise ImportError(errmsg)
+                return yaml.safe_load(sf)
+            return json.load(sf)
+
+    def _process_spec(self):
+        spec = self._spec
+
+        for item in spec.get("tags", []):
+            name = item["name"]
+            desc = item.get("description", "")
+            self._tag_catalog[self._safe_snake(name)] = desc
+
+        path_catalog: Dict[str, dict] = spec["paths"]
+        for path_leaf, method_catalog in path_catalog.items():
+            path_level_params = method_catalog.get("parameters", [])
+            for call_method, op_desc in method_catalog.items():
+                if call_method not in SUPPORTED_HTTP_METHODS:
+                    continue
+
+                operation_id = op_desc.get("operationId", "")
+                tags = op_desc.get("tags", [])
+                summary = op_desc.get("summary", "")
+                description = op_desc.get("description", "")
+                external_docs = op_desc.get("externalDocs")
+                responses = op_desc.get("responses", {})
+                request_body = op_desc.get("requestBody")
+
+                group_name, method_name = self._derive_group_and_method(operation_id, tags)
+
+                parameters = self._collect_parameters(
+                    path_level_params, op_desc.get("parameters", [])
+                )
+
+                op = OperationSpec(
+                    path=path_leaf,
+                    http_method=call_method.upper(),
+                    group=group_name,
+                    operation_id=operation_id,
+                    method_name=method_name,
+                    summary=summary,
+                    description=description,
+                    parameters=parameters,
+                    request_body=request_body,
+                    responses=responses,
+                    external_docs=external_docs,
+                )
+                self._groups.setdefault(group_name, []).append(op)
+        return
+
+    def _collect_parameters(self, path_level_params: List[dict], op_level_params: List[dict]) -> List[ParameterSpec]:
+        parameters: List[ParameterSpec] = []
+        for pentry in path_level_params + op_level_params:
+            param_def = self._dereference_parameter(pentry)
+            name = param_def.get("name", "unnamed")
+            location = param_def.get("in", "query")
+            required = bool(param_def.get("required", False))
+            schema = param_def.get("schema", {})
+            description = param_def.get("description", "")
+            parameters.append(
+                ParameterSpec(
+                    name=name,
+                    location=location,
+                    required=required,
+                    schema=schema,
+                    description=description,
+                )
+            )
+        return parameters
+
+    def _dereference_parameter(self, param_entry: dict) -> dict:
+        if "$ref" in param_entry:
+            ref_path = param_entry["$ref"]
+            resolved = self._resolve_ref(ref_path)
+            if not isinstance(resolved, dict):
+                errmsg = f"Reference '{ref_path}' did not resolve to a parameter dictionary."
+                raise ValueError(errmsg)
+            return resolved
+        return param_entry
+
+    def _resolve_ref(self, ref_path: str):
+        if not ref_path.startswith("#/"):
+            errmsg = f"Unsupported reference format '{ref_path}'."
+            raise ValueError(errmsg)
+
+        segments = ref_path.lstrip("#/").split("/")
+        obj: Any = self._spec
+        for segment in segments:
+            obj = obj[segment]
+        return obj
+
+    def _derive_group_and_method(self, operation_id: str, tags: List[str]) -> Tuple[str, str]:
+        group_name = tags[0] if tags else "default"
+        method_name = operation_id
+
+        if operation_id and "/" in operation_id:
+            parts = operation_id.split("/", 1)
+            group_name = parts[0]
+            method_name = parts[1]
+        elif not tags and operation_id:
+            group_name = operation_id
+            method_name = operation_id
+
+        group_name = self._safe_snake(group_name)
+        method_name = self._safe_snake(method_name)
+        return group_name, method_name
+
+    def _safe_snake(self, name: str) -> str:
+        snake = re.sub(r"[^0-9a-zA-Z]+", "_", name).strip("_").lower()
+        if snake == "" or snake[0].isdigit() or keyword.iskeyword(snake):
+            snake = f"op_{snake}"
+        return snake
+
+    def _safe_pascal(self, name: str) -> str:
+        parts = re.split(r"[^0-9a-zA-Z]+", name)
+        pascal = "".join([p.capitalize() for p in parts if p])
+        if pascal == "":
+            pascal = "Generated"
+        if pascal[0].isdigit():
+            pascal = f"Op{pascal}"
+        return pascal
+
+    def _file_slug(self, name: str) -> str:
+        """
+            Creates a filesystem-friendly slug without underscores.
+        """
+        slug = self._safe_snake(name).replace("_", "")
+        if slug == "":
+            slug = "generated"
+        if slug[0].isdigit():
+            slug = f"op{slug}"
+        return slug
+
+    def _field_default_literal(self, schema: Dict[str, Any], required: bool) -> str:
+        if required:
+            return ""
+
+        if "default" in schema:
+            dval = schema["default"]
+            if isinstance(dval, str):
+                return f'"{dval}"'
+            return str(dval)
+
+        return "None"
+
+    def _schema_to_type(self, schema: Dict[str, Any]) -> str:
+        if "$ref" in schema:
+            return "Any"
+
+        schema_type = schema.get("type", "any")
+        if schema_type == "integer":
+            return "int"
+        if schema_type == "number":
+            return "float"
+        if schema_type == "boolean":
+            return "bool"
+        if schema_type == "array":
+            item_schema = schema.get("items", {})
+            item_type = self._schema_to_type(item_schema)
+            return f"List[{item_type}]"
+        if schema_type == "object":
+            return "Dict[str, Any]"
+        return "str"
+
+    def _expected_status_codes(self, responses: Dict[str, Any]) -> List[int]:
+        expected: List[int] = []
+        
+        for code_val in sorted(responses.keys()):
+            code_int = None
+            if isinstance(code_val, str) and code_val.isdigit():
+                code_int = int(code_val)
+            if isinstance(code_val, int):
+                code_int = code_val
+            if code_int is not None:
+                if 200 <= code_int < 300:
+                    expected.append(code_int)
+        
+        if not expected:
+            expected.append(200)
+
+        return expected
+
+    def _generate_parameter_module(self, group: str, ops: List[OperationSpec], params_dir: Path):
+        slug = self._file_slug(group)
+
+        # Generate the dataclasses first so the typing import can be limited to the names they reference.
+        module_lines: List[str] = []
+
+        for op in ops:
+            class_name = f"{self._safe_pascal(group)}{self._safe_pascal(op.method_name)}Params"
+            module_lines.append(f"@dataclass")
+            module_lines.append(f"class {class_name}:")
+            if op.parameters:
+                module_lines.append(f"    \"\"\"")
+                module_lines.append(f"        Parameters for the '{op.operation_id}' operation.")
+                module_lines.append(f"    \"\"\"")
+            required_fields = [p for p in op.parameters if p.required]
+            optional_fields = [p for p in op.parameters if not p.required]
+
+            for param in required_fields + optional_fields:
+                attr_name = self._safe_snake(param.name)
+                ptype = self._schema_to_type(param.schema)
+                if not param.required:
+                    ptype = f"Optional[{ptype}]"
+                default_lit = self._field_default_literal(param.schema, param.required)
+                if default_lit:
+                    module_lines.append(f"    {attr_name}: {ptype} = {default_lit}")
+                else:
+                    module_lines.append(f"    {attr_name}: {ptype}")
+
+            if op.request_body is not None:
+                module_lines.append("    body: Optional[Any] = None")
+
+            if not op.parameters and op.request_body is None:
+                module_lines.append("    pass")
+            else:
+                module_lines.append("")
+                module_lines.append("    def path_params(self) -> Dict[str, Any]:")
+                module_lines.append("        params: Dict[str, Any] = {}")
+                for param in op.parameters:
+                    if param.location == "path":
+                        attr_name = self._safe_snake(param.name)
+                        module_lines.append(f"        if self.{attr_name} is not None:")
+                        module_lines.append(f"            params['{param.name}'] = self.{attr_name}")
+                module_lines.append("        return params")
+                module_lines.append("")
+                module_lines.append("    def query_params(self) -> Dict[str, Any]:")
+                module_lines.append("        params: Dict[str, Any] = {}")
+                for param in op.parameters:
+                    if param.location == "query":
+                        attr_name = self._safe_snake(param.name)
+                        module_lines.append(f"        if self.{attr_name} is not None:")
+                        module_lines.append(f"            params['{param.name}'] = self.{attr_name}")
+                module_lines.append("        return params")
+                module_lines.append("")
+                module_lines.append("    def header_params(self) -> Dict[str, Any]:")
+                module_lines.append("        params: Dict[str, Any] = {}")
+                for param in op.parameters:
+                    if param.location == "header":
+                        attr_name = self._safe_snake(param.name)
+                        module_lines.append(f"        if self.{attr_name} is not None:")
+                        module_lines.append(f"            params['{param.name}'] = self.{attr_name}")
+                module_lines.append("        return params")
+                module_lines.append("")
+                module_lines.append("    def body_params(self) -> Any:")
+                if op.request_body is not None:
+                    module_lines.append("        return self.body")
+                else:
+                    module_lines.append("        return None")
+            module_lines.append("")
+
+        body_text = "\n".join(module_lines)
+        header_lines: List[str] = [AUTO_GENERATED_BANNER]
+        header_lines.append("from dataclasses import dataclass")
+        typing_statement = self._typing_import_statement(["Any", "Dict", "List", "Optional"], body_text)
+        if typing_statement is not None:
+            header_lines.append(typing_statement)
+        header_lines.append("")
+        module_lines = header_lines + module_lines
+
+        content = "\n".join(module_lines).rstrip() + "\n"
+        out_path = params_dir / f"{slug}.py"
+        self._write_file(out_path, content)
+        return
+
+    def _generate_response_module(self, group: str, ops: List[OperationSpec], responses_dir: Path):
+        slug = self._file_slug(group)
+        module_lines: List[str] = [AUTO_GENERATED_BANNER]
+        module_lines.append("from typing import Any, Dict")
+        module_lines.append("")
+        module_lines.append("from requests import Response")
+        module_lines.append("")
+
+        for op in ops:
+            class_name = f"{self._safe_pascal(group)}{self._safe_pascal(op.method_name)}Response"
+            module_lines.append(f"class {class_name}:")
+            module_lines.append("    \"\"\"")
+            module_lines.append(f"        Response wrapper for the '{op.operation_id}' operation.")
+            module_lines.append("    \"\"\"")
+            module_lines.append("    def __init__(self, response: Response):")
+            module_lines.append("        self.response = response")
+            module_lines.append("        self.status_code = response.status_code")
+            module_lines.append("        self.headers: Dict[str, Any] = dict(response.headers)")
+            module_lines.append("        try:")
+            module_lines.append("            self.data = response.json()")
+            module_lines.append("        except Exception:")
+            module_lines.append("            self.data = response.content")
+            module_lines.append("        return")
+            module_lines.append("")
+            module_lines.append("    @property")
+            module_lines.append("    def ok(self) -> bool:")
+            module_lines.append("        rtnval = True if 200 <= self.status_code < 300 else False")
+            module_lines.append("        return rtnval")
+            module_lines.append("")
+
+        content = "\n".join(module_lines).rstrip() + "\n"
+        out_path = responses_dir / f"{slug}.py"
+        self._write_file(out_path, content)
+        return
+
+    def _generate_group_module(self, group: str, ops: List[OperationSpec], groups_dir: Path):
+        slug = self._file_slug(group)
+        class_name = f"{self._safe_pascal(group)}ApiGroup"
+        module_lines: List[str] = [AUTO_GENERATED_BANNER]
+        module_lines.append("from typing import Optional")
+        module_lines.append("")
+        module_lines.append("from ccai.gitlab.rest.aspectsrest import AspectsRest, DEFAULT_REST_ASPECTS")
+        module_lines.append("from ccai.gitlab.rest.restapigroup import RestApiGroup")
+        module_lines.append(f"from ccai.gitlab.rest.clients.parameters import {slug} as parameters")
+        module_lines.append(f"from ccai.gitlab.rest.clients.responses import {slug} as responses")
+        module_lines.append("")
+        module_lines.append("")
+        module_lines.append(f"class {class_name}(RestApiGroup):")
+        tag_desc = self._tag_catalog.get(group, "")
+        if tag_desc:
+            module_lines.append("    \"\"\"")
+            module_lines.append(f"        {tag_desc}")
+            module_lines.append("    \"\"\"")
+
+        for op in ops:
+            method_name = self._safe_snake(op.method_name)
+            params_class = f"{self._safe_pascal(group)}{self._safe_pascal(op.method_name)}Params"
+            resp_class = f"{self._safe_pascal(group)}{self._safe_pascal(op.method_name)}Response"
+            module_lines.append("")
+            module_lines.append(f"    def {method_name}(self, params: Optional[parameters.{params_class}] = None, *, aspects: Optional[AspectsRest] = DEFAULT_REST_ASPECTS) -> responses.{resp_class}:")
+            module_lines.append("        \"\"\"")
+            if op.summary:
+                module_lines.append(f"            {op.summary}")
+            else:
+                module_lines.append(f"            {op.description}")
+            module_lines.append("        \"\"\"")
+            module_lines.append(f"        if params is None:")
+            module_lines.append(f"            params = parameters.{params_class}()")
+            module_lines.append(f"        call_leaf = \"{op.path}\"")
+            module_lines.append("        path_params = params.path_params()")
+            module_lines.append("        if path_params:")
+            module_lines.append("            call_leaf = self.client.format_path(call_leaf, path_params)")
+            module_lines.append("        query_params = params.query_params()")
+            module_lines.append("        header_params = params.header_params()")
+            module_lines.append("        body_params = params.body_params()")
+            exp_status = self._expected_status_codes(op.responses)
+            module_lines.append(f"        exp_status = {exp_status}")
+            module_lines.append("        resp = self.client.perform_call(")
+            module_lines.append("            leaf=call_leaf,")
+            module_lines.append(f"            method=\"{op.http_method}\",")
+            module_lines.append("            params=query_params if query_params else None,")
+            module_lines.append("            body=body_params,")
+            module_lines.append("            exp_status=exp_status,")
+            module_lines.append("            headers=header_params if header_params else None,")
+            module_lines.append("            context_msg=None,")
+            module_lines.append("            aspects=aspects,")
+            module_lines.append("        )")
+            module_lines.append(f"        result = responses.{resp_class}(resp)")
+            module_lines.append("        return result")
+
+        content = "\n".join(module_lines).rstrip() + "\n"
+        out_path = groups_dir / f"{slug}.py"
+        self._write_file(out_path, content)
+        return
+
+    def _generate_client_module(self, sorted_groups: List[str], clients_root: Path):
+        client_filename = f"{self._client_class_name.lower()}.py"
+        client_file = clients_root / client_filename
+        imports: List[str] = [AUTO_GENERATED_BANNER]
+        imports.append("from typing import Optional")
+        imports.append("")
+        imports.append("from ccai.gitlab.rest.aspectsrest import AspectsRest, DEFAULT_REST_ASPECTS")
+        imports.append("from ccai.gitlab.rest.restclientbase import RestClientBase")
+        imports.append("from ccai.credentials.basecredential import BaseCredential")
+
+        for group in sorted_groups:
+            gclass = f"{self._safe_pascal(group)}ApiGroup"
+            gmodule = f"ccai.gitlab.rest.clients.groups.{self._file_slug(group)}"
+            imports.append(f"from {gmodule} import {gclass}")
+
+        imports.append("")
+
+        lines = imports
+        lines.append("")
+        lines.append(f"class {self._client_class_name}(RestClientBase):")
+        lines.append('    """')
+        lines.append("        GitHub public REST API client generated from the OpenAPI specification.")
+        lines.append("    \"\"\"")
+        lines.append("    def __init__(self, host: str, credential: BaseCredential, port: Optional[int] = None, scheme: Optional[str] = \"https\", aspects: AspectsRest = DEFAULT_REST_ASPECTS):")
+        lines.append("        super().__init__(host, credential, port, scheme=scheme, aspects=aspects)")
+
+        for group in sorted_groups:
+            gclass = f"{self._safe_pascal(group)}ApiGroup"
+            attr_name = f"_grp_{self._safe_snake(group)}"
+            lines.append(f"        self.{attr_name} = {gclass}(self)")
+        lines.append("        return")
+        lines.append("")
+
+        for group in sorted_groups:
+            gclass = f"{self._safe_pascal(group)}ApiGroup"
+            attr_name = f"_grp_{self._safe_snake(group)}"
+            prop_name = self._safe_snake(group)
+            lines.append("    @property")
+            lines.append(f"    def {prop_name}(self) -> {gclass}:")
+            lines.append(f"        return self.{attr_name}")
+            lines.append("")
+
+        content = "\n".join(lines).rstrip() + "\n"
+        self._write_file(client_file, content)
+        return
+
+    def _write_simple_init(self, target_dir: Path):
+        init_file = target_dir / "__init__.py"
+        if init_file.exists():
+            return
+        init_file.write_text("", encoding="utf-8")
+        return
+
+    def _typing_import_statement(self, candidate_names: List[str], body_text: str) -> Optional[str]:
+        """
+            Creates a 'from typing import ...' statement containing only the candidate names that the generated
+            module body references.
+
+            :param candidate_names: The typing names the body might use.
+            :param body_text: The generated module body.
+
+            :returns: The import statement, or None when the body references none of the candidate names.
+        """
+        referenced_names = set()
+        tree = ast.parse(body_text)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Name):
+                referenced_names.add(node.id)
+
+        used_names = []
+        for name in candidate_names:
+            if name in referenced_names:
+                used_names.append(name)
+
+        statement = None
+        if len(used_names) > 0:
+            statement = "from typing import {}".format(", ".join(used_names))
+
+        return statement
+
+    def _write_file(self, path: Path, content: str):
+        path.write_text(content, encoding="utf-8")
+        return
+
+
+def rest_client_generator_main():
+    """
+        Entry point used to generate REST client code from the OpenAPI specification.
+    """
+    parser = argparse.ArgumentParser(description="Generate GitHub REST client code from an OpenAPI specification.")
+    parser.add_argument("--client-root", required=True, help="Root directory where the generated client package (public) resides.")
+    parser.add_argument("--client-classname", default="GithubRestClient", help="Class name to use for the generated root client.")
+    parser.add_argument("--specfile", required=True, help="Path to the OpenAPI specification JSON or YAML file.")
+
+    args = parser.parse_args()
+
+    generator = RestClientGenerator(
+        openapi_spec_file=args.specfile,
+        clients_root=args.client_root,
+        client_class_name=args.client_classname
+    )
+    generator.generate()
+    return
+
+
+if __name__ == "__main__":
+    rest_client_generator_main()