domaintools-api-test-upload 2.6.3__tar.gz → 2.7.1__tar.gz

{domaintools_api_test_upload-2.6.3/domaintools_api_test_upload.egg-info → domaintools_api_test_upload-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domaintools_api_test_upload
-Version: 2.6.3
+Version: 2.7.1
 Summary: DomainTools Official Python API
 Author-email: DomainTools <integrations@domaintools.com>
 License: The MIT License (MIT)

domaintools_api_test_upload-2.7.1/VERSION

@@ -0,0 +1 @@
+2.7.1

{domaintools_api_test_upload-2.6.3 → domaintools_api_test_upload-2.7.1}/domaintools/_version.py

@@ -20,4 +20,4 @@ OTHER DEALINGS IN THE SOFTWARE.
 
 """
 
-current = "2.6.3"
+current = "2.7.1"

domaintools_api_test_upload-2.7.1/domaintools/decorators.py

@@ -0,0 +1,105 @@
+import functools
+import inspect
+
+from typing import List, Union
+
+from domaintools.docstring_patcher import DocstringPatcher
+from domaintools.request_validator import RequestValidator
+
+
+def api_endpoint(spec_name: str, path: str, methods: Union[str, List[str]]):
+    """
+    Decorator to tag a method as an API endpoint AND validate inputs.
+
+    Args:
+        spec_name: The key for the spec in api_instance.specs
+        path: The API path (e.g., "/users")
+        methods: A single method ("get") or list of methods (["get", "post"])
+    """
+
+    def decorator(func):
+        func._api_spec_name = spec_name
+        func._api_path = path
+
+        # Normalize methods to a list
+        normalized_methods = [methods] if isinstance(methods, str) else methods
+        func._api_methods = normalized_methods
+
+        # Get the signature of the original function ONCE
+        sig = inspect.signature(func)
+
+        @functools.wraps(func)
+        def wrapper(self, *args, **kwargs):
+
+            try:
+                bound_args = sig.bind(*args, **kwargs)
+            except TypeError:
+                # If arguments don't match signature, let the actual func raise the error
+                return func(*args, **kwargs)
+
+            arguments = bound_args.arguments
+
+            # Robustly find 'self' (it's usually the first argument in bound_args)
+            # We look for the first value in arguments, or try to get 'self' explicitly.
+            instance = arguments.pop("self", None)
+            if not instance and args:
+                instance = args[0]
+
+            # Retrieve the Spec from the instance
+            # We assume 'self' has a .specs attribute (like DocstringPatcher expects)
+            spec = getattr(self, "specs", {}).get(spec_name)
+
+            if "domains" in arguments.keys():
+                domains = arguments.pop("domains")
+                arguments["domain"] = (
+                    ",".join(domains) if isinstance(domains, (list, tuple)) else domains
+                )
+
+            if spec:
+                # Determine which HTTP method is currently being executed.
+                # If the function allows dynamic methods (e.g. method="POST"), use that.
+                # Otherwise, default to the first method defined in the decorator.
+                current_method = kwargs.get("method", normalized_methods[0])
+
+                # Run Validation
+                # This will raise a ValueError and stop execution if validation fails.
+                try:
+                    RequestValidator.validate(
+                        spec=spec,
+                        path=path,
+                        method=current_method,
+                        parameters=arguments,
+                    )
+                except ValueError as e:
+                    print(f"[Validation Error] {e}")
+                    raise e
+
+            # Proceed with the original function call
+            return func(*args, **kwargs)
+
+        # Copy tags to wrapper for the DocstringPatcher to find
+        wrapper._api_spec_name = func._api_spec_name
+        wrapper._api_path = func._api_path
+        wrapper._api_methods = func._api_methods
+
+        return wrapper
+
+    return decorator
+
+
+def auto_patch_docstrings(cls):
+    original_init = cls.__init__
+
+    @functools.wraps(original_init)
+    def new_init(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        try:
+            # We instantiate our patcher and run it
+            patcher = DocstringPatcher()
+            patcher.patch(self)
+        except Exception as e:
+            print(f"Auto-patching failed: {e}")
+
+    cls.__init__ = new_init
+
+    return cls

{domaintools_api_test_upload-2.6.3 → domaintools_api_test_upload-2.7.1}/domaintools/docstring_patcher.py

@@ -7,13 +7,6 @@ import logging
 class DocstringPatcher:
     """
     Patches docstrings for methods decorated with @api_endpoint.
-    - Uses the 'methods' list provided by the decorator.
-    - Finds non-standard parameters inside the 'requestBody' object.
-    - Displays Query Params, Request Body, and Result Body (Responses)
-      for all operations.
-    - Unpacks and displays properties of request body schemas.
-    - Searches components.parameters for request body properties
-      that match by name.
     """
 
     def patch(self, api_instance):
@@ -44,6 +37,7 @@ class DocstringPatcher:
                 path_item = spec_to_use.get("paths", {}).get(path, {})
                 for http_method in http_methods_to_check:
                     if http_method.lower() in path_item:
+                        # Helper is called via self, but it's an instance method calling a static method internally
                         api_doc = self._generate_api_doc_string(spec_to_use, path, http_method)
                         all_doc_sections.append(api_doc)
 
@@ -66,77 +60,18 @@ class DocstringPatcher:
                 method_wrapper.__get__(api_instance, api_instance.__class__),
             )
 
-    def _generate_api_doc_string(self, spec: dict, path: str, method: str) -> str:
-        """Creates the formatted API docstring section for ONE operation."""
-
-        details = self._get_operation_details(spec, path, method)
-        lines = [f"--- Operation: {method.upper()} {path} ---"]
-
-        lines.append(f"\n  Summary: {details.get('summary', 'N/A')}")
-        lines.append(f"  Description: {details.get('description', 'N/A')}")
-        lines.append(f"  External Doc: {details.get('external_doc', 'N/A')}")
-
-        # 1. Always display Query Parameters
-        lines.append("\n  Query Parameters:")
-        if not details["query_params"]:
-            lines.append("    (No query parameters)")
-        else:
-            for param in details["query_params"]:
-                lines.append(f"\n    **{param['name']}** ({param['type']})")
-                lines.append(f"      Required:    {param['required']}")
-                lines.append(f"      Description: {param['description']}")
-
-        # 2. Always display Request Body
-        lines.append("\n  Request Body:")
-        if not details["request_body"]:
-            lines.append("    (No request body)")
-        else:
-            body = details["request_body"]
-            lines.append(f"\n    **{body['type']}**")
-            lines.append(f"      Required:    {body['required']}")
-            lines.append(f"      Description: {body['description']}")
-
-            if body.get("properties"):
-                lines.append(f"      Properties:")
-                for prop in body["properties"]:
-                    lines.append(f"\n        **{prop['name']}** ({prop['type']})")
-                    lines.append(f"          Description: {prop['description']}")
-
-            if body.get("parameters"):
-                lines.append(f"      Parameters (associated with this body):")
-                for param in body["parameters"]:
-                    param_in = param.get("in", "N/A")
-                    lines.append(
-                        f"\n        **{param['name']}** ({param['type']}) [in: {param_in}]"
-                    )
-                    lines.append(f"          Required:    {param['required']}")
-                    lines.append(f"          Description: {param['description']}")
-
-        # 3. Always display Result Body (Responses)
-        lines.append("\n  Result Body (Responses):")
-        if not details["responses"]:
-            lines.append("    (No responses defined in spec)")
-        else:
-            for resp in details["responses"]:
-                lines.append(f"\n    **{resp['status_code']}**: ({resp['type']})")
-                lines.append(f"      Description: {resp['description']}")
-
-        return "\n".join(lines)
-
-    def _get_operation_details(self, spec: dict, path: str, method: str) -> dict:
+    @staticmethod
+    def get_operation_details(spec: dict, path: str, method: str) -> dict:
         """
-        Gets all details. Includes:
-        - Logic to find non-standard 'parameters' in 'requestBody'
-        - Logic to parse requestBody schema properties
-        - Logic to parse responses
-        - **NEW**: Logic to match requestBody properties to components/parameters
+        Gets all details for a specific operation.
+        Static method: Can be used without instantiating the class.
+        Usage: DocstringPatcher.get_operation_details(spec, '/users', 'post')
         """
         details = {"query_params": [], "request_body": None, "responses": []}
         if not spec:
             return details
 
         try:
-            # --- Get component parameters for lookup ---
             components = spec.get("components", {})
             all_component_params = components.get("parameters", {})
 
@@ -154,23 +89,22 @@ class DocstringPatcher:
             resolved_body_def = {}
             if body_def:
                 if "$ref" in body_def:
-                    resolved_body_def = self._resolve_ref(spec, body_def["$ref"])
+                    resolved_body_def = DocstringPatcher._resolve_ref(spec, body_def["$ref"])
                 else:
                     resolved_body_def = body_def
                 body_level_params = resolved_body_def.get("parameters", [])
 
             all_param_defs = path_level_params + operation_level_params
-            # --- End Parameter Logic ---
 
             details["summary"] = operation.get("summary")
             details["description"] = operation.get("description")
             details["external_doc"] = operation.get("externalDocs", {}).get("url", "N/A")
 
-            # --- Query Param Processing (from path/operation only) ---
+            # --- Query Params ---
             resolved_params = []
             for param_def in all_param_defs:
                 if "$ref" in param_def:
-                    resolved_params.append(self._resolve_ref(spec, param_def["$ref"]))
+                    resolved_params.append(DocstringPatcher._resolve_ref(spec, param_def["$ref"]))
                 else:
                     resolved_params.append(param_def)
 
@@ -180,12 +114,11 @@ class DocstringPatcher:
                         "name": p.get("name"),
                         "required": p.get("required", False),
                         "description": p.get("description", "N/A"),
-                        "type": self._get_param_type(spec, p.get("schema")),
+                        "type": DocstringPatcher._get_param_type(spec, p.get("schema")),
                     }
                 )
-            # --- End Query Param Processing ---
 
-            # --- Request Body Processing ---
+            # --- Request Body ---
             if body_def:
                 content = resolved_body_def.get("content", {})
                 media_type = next(iter(content.values()), None)
@@ -194,7 +127,7 @@ class DocstringPatcher:
 
                 if media_type and "schema" in media_type:
                     schema = media_type["schema"]
-                    schema_type = self._get_param_type(spec, schema)
+                    schema_type = DocstringPatcher._get_param_type(spec, schema)
 
                 details["request_body"] = {
                     "required": resolved_body_def.get("required", False),
@@ -204,23 +137,27 @@ class DocstringPatcher:
                     "properties": [],
                 }
 
-                # --- Process schema properties with new lookup logic ---
+                # --- Schema Properties ---
                 resolved_schema = {}
-                if "$ref" in schema:
-                    resolved_schema = self._resolve_ref(spec, schema["$ref"])
-                elif schema.get("type") == "object":
-                    resolved_schema = schema
+                current_schema_for_props = schema
+                while "$ref" in current_schema_for_props or "$ref:" in current_schema_for_props:
+                    ref = current_schema_for_props.get("$ref") or current_schema_for_props.get(
+                        "$ref:"
+                    )
+                    if not ref:
+                        break
+                    current_schema_for_props = DocstringPatcher._resolve_ref(spec, ref)
 
-                if resolved_schema.get("type") == "object" and "properties" in resolved_schema:
-                    for prop_name, prop_def in resolved_schema["properties"].items():
+                if (
+                    current_schema_for_props.get("type") == "object"
+                    and "properties" in current_schema_for_props
+                ):
+                    for prop_name, prop_def in current_schema_for_props["properties"].items():
 
                         found_param_match = False
-                        # --- Try to find a match in components/parameters ---
-                        # (Iterate over values, e.g., the LimitParam object)
                         for component_param_def in all_component_params.values():
                             if component_param_def.get("name") == prop_name:
-                                # Found a match! Use its details.
-                                prop_type = self._get_param_type(
+                                prop_type = DocstringPatcher._get_param_type(
                                     spec, component_param_def.get("schema")
                                 )
                                 prop_desc = component_param_def.get("description", "N/A")
@@ -231,18 +168,19 @@ class DocstringPatcher:
                                 break
 
                         if not found_param_match:
-                            # No match, process as a normal schema property
-                            prop_type = self._get_param_type(spec, prop_def)
+                            prop_type = DocstringPatcher._get_param_type(spec, prop_def)
                             prop_desc = prop_def.get("description", "N/A")
                             details["request_body"]["properties"].append(
                                 {"name": prop_name, "type": prop_type, "description": prop_desc}
                             )
 
-                # --- Body Parameter Processing (for non-standard spec) ---
+                # --- Body Parameters ---
                 resolved_body_params = []
                 for param_def in body_level_params:
                     if "$ref" in param_def:
-                        resolved_body_params.append(self._resolve_ref(spec, param_def["$ref"]))
+                        resolved_body_params.append(
+                            DocstringPatcher._resolve_ref(spec, param_def["$ref"])
+                        )
                     else:
                         resolved_body_params.append(param_def)
 
@@ -253,17 +191,16 @@ class DocstringPatcher:
                             "in": p.get("in"),
                             "required": p.get("required", False),
                             "description": p.get("description", "N/A"),
-                            "type": self._get_param_type(spec, p.get("schema")),
+                            "type": DocstringPatcher._get_param_type(spec, p.get("schema")),
                         }
                     )
-            # --- End Request Body Processing ---
 
-            # --- Response Processing Logic ---
+            # --- Responses ---
             responses_def = operation.get("responses", {})
             for status_code, resp_def in responses_def.items():
                 resolved_resp = {}
                 if "$ref" in resp_def:
-                    resolved_resp = self._resolve_ref(spec, resp_def["$ref"])
+                    resolved_resp = DocstringPatcher._resolve_ref(spec, resp_def["$ref"])
                 else:
                     resolved_resp = resp_def
 
@@ -274,7 +211,7 @@ class DocstringPatcher:
 
                 if media_type and "schema" in media_type:
                     schema = media_type["schema"]
-                    resp_type = self._get_param_type(spec, schema)
+                    resp_type = DocstringPatcher._get_param_type(spec, schema)
 
                 details["responses"].append(
                     {
@@ -283,14 +220,14 @@ class DocstringPatcher:
                         "type": resp_type,
                     }
                 )
-            # --- END: Response Processing Logic ---
 
             return details
         except Exception as e:
             logging.warning(f"Error parsing spec for {method.upper()} {path}: {e}", exc_info=True)
             return details
 
-    def _resolve_ref(self, spec: dict, ref: str):
+    @staticmethod
+    def _resolve_ref(spec: dict, ref: str):
         """Resolves a JSON schema $ref string."""
         if not spec or not ref.startswith("#/"):
             return {}
@@ -310,25 +247,99 @@ class DocstringPatcher:
                 return {}
         return current_obj
 
-    def _get_param_type(self, spec: dict, schema: dict) -> str:
-        """Gets a display-friendly type name from a schema object."""
+    @staticmethod
+    def _get_param_type(spec: dict, schema: dict) -> str:
+        """
+        Gets the type name. Handles recursion and arrays.
+        """
         if not schema:
             return "N/A"
 
-        # Check for malformed refs (like in your example spec)
-        schema_ref = schema.get("$ref")
-        if not schema_ref:
-            # Handle user's typo: "$ref:"
-            schema_ref = schema.get("$ref:")
+        current_schema = schema
+        ref_name = None
+
+        while True:
+            ref_string = current_schema.get("$ref") or current_schema.get("$ref:")
+
+            if not ref_string:
+                break
+
+            ref_name = ref_string.split("/")[-1]
 
-        if schema_ref:
-            return schema_ref.split("/")[-1]
+            resolved = DocstringPatcher._resolve_ref(spec, ref_string)
 
-        schema_type = schema.get("type", "N/A")
+            if not resolved:
+                return ref_name or "N/A"
+
+            if "schema" in resolved:
+                current_schema = resolved["schema"]
+            else:
+                current_schema = resolved
+
+        schema_type = current_schema.get("type", "N/A")
 
         if schema_type == "array":
-            items_schema = schema.get("items", {})
-            items_type = self._get_param_type(spec, items_schema)
+            items_schema = current_schema.get("items", {})
+            items_type = DocstringPatcher._get_param_type(spec, items_schema)
             return f"array[{items_type}]"
 
+        if schema_type == "object" and ref_name:
+            return ref_name
+
         return schema_type
+
+    def _generate_api_doc_string(self, spec: dict, path: str, method: str) -> str:
+        """Creates the formatted API docstring section for ONE operation."""
+
+        # Call static method
+        details = self.get_operation_details(spec, path, method)
+
+        lines = [f"--- Operation: {method.upper()} {path} ---"]
+
+        lines.append(f"\n  Summary: {details.get('summary', 'N/A')}")
+        lines.append(f"  Description: {details.get('description', 'N/A')}")
+        lines.append(f"  External Doc: {details.get('external_doc', 'N/A')}")
+
+        lines.append("\n  Query Parameters:")
+        if not details["query_params"]:
+            lines.append("    (No query parameters)")
+        else:
+            for param in details["query_params"]:
+                lines.append(f"\n    **{param['name']}** ({param['type']})")
+                lines.append(f"      Required:    {param['required']}")
+                lines.append(f"      Description: {param['description']}")
+
+        lines.append("\n  Request Body:")
+        if not details["request_body"]:
+            lines.append("    (No request body)")
+        else:
+            body = details["request_body"]
+            lines.append(f"\n    **{body['type']}**")
+            lines.append(f"      Required:    {body['required']}")
+            lines.append(f"      Description: {body['description']}")
+
+            if body.get("properties"):
+                lines.append(f"      Properties:")
+                for prop in body["properties"]:
+                    lines.append(f"\n        **{prop['name']}** ({prop['type']})")
+                    lines.append(f"          Description: {prop['description']}")
+
+            if body.get("parameters"):
+                lines.append(f"      Parameters (associated with this body):")
+                for param in body["parameters"]:
+                    param_in = param.get("in", "N/A")
+                    lines.append(
+                        f"\n        **{param['name']}** ({param['type']}) [in: {param_in}]"
+                    )
+                    lines.append(f"          Required:    {param['required']}")
+                    lines.append(f"          Description: {param['description']}")
+
+        lines.append("\n  Result Body (Responses):")
+        if not details["responses"]:
+            lines.append("    (No responses defined in spec)")
+        else:
+            for resp in details["responses"]:
+                lines.append(f"\n    **{resp['status_code']}**: ({resp['type']})")
+                lines.append(f"      Description: {resp['description']}")
+
+        return "\n".join(lines)

domaintools_api_test_upload-2.7.1/domaintools/request_validator.py

@@ -0,0 +1,118 @@
+from domaintools.docstring_patcher import DocstringPatcher
+
+
+class RequestValidator:
+    """
+    Validates user input against the OpenAPI spec using DocstringPatcher.
+    Separates validation logic based on HTTP verbs.
+    """
+
+    TYPE_MAP = {
+        "string": str,
+        "integer": int,
+        "number": (int, float),
+        "boolean": bool,
+        "array": list,
+        "object": dict,
+    }
+
+    @staticmethod
+    def validate(
+        spec: dict,
+        path: str,
+        method: str,
+        parameters: dict = None,
+    ):
+        """
+        Orchestrator: Decides which validation to run based on the HTTP method.
+        """
+        method = method.upper()
+
+        # GET requests: Validate Query Parameters only
+        if method == "GET":
+            RequestValidator.validate_query_params(spec, path, method, parameters)
+
+        # POST/PUT/PATCH: Validate Request Body
+        elif method in ["POST", "PUT", "PATCH"]:
+            RequestValidator.validate_body(spec, path, method, parameters)
+
+        return True
+
+    @staticmethod
+    def validate_query_params(spec: dict, path: str, method: str, q_params: dict):
+        """
+        Validates ONLY the query parameters.
+        """
+        q_params = q_params or {}
+        details = DocstringPatcher.get_operation_details(spec, path, method)
+        errors = []
+
+        for param in details["query_params"]:
+            param_name = param["name"]
+            is_required = param["required"]
+            param_type = param["type"]
+
+            # Check existence
+            if is_required and param_name not in q_params:
+                errors.append(f"Missing required query parameter: '{param_name}'")
+                continue
+
+            # Check Type (only if present)
+            if param_name in q_params:
+                val = q_params[param_name]
+                RequestValidator._check_type(val, param_type, f"query.{param_name}", errors)
+
+        if errors:
+            raise ValueError("Query Parameter Validation Failed:\n  - " + "\n  - ".join(errors))
+
+    @staticmethod
+    def validate_body(spec: dict, path: str, method: str, body_data: dict):
+        """
+        Validates ONLY the request body.
+        """
+        details = DocstringPatcher.get_operation_details(spec, path, method)
+        errors = []
+
+        if not details["request_body"]:
+            # If spec has no body defined, but user sent one, you might want to warn
+            # or simply ignore. We will ignore here.
+            return
+
+        body_rules = details["request_body"]
+
+        # Check Body Existence
+        if not body_data:
+            raise ValueError("Validation Failed: Missing required request body.")
+
+        # Check Body Properties
+        # Only proceed if we have data and the spec defines properties
+        if body_data and body_rules.get("properties"):
+            for prop in body_rules["properties"]:
+                p_name = prop["name"]
+                p_type = prop["type"]
+
+                # Check Type if the property exists in the user input
+                if p_name in body_data:
+                    RequestValidator._check_type(
+                        body_data[p_name], p_type, f"body.{p_name}", errors
+                    )
+
+        if errors:
+            raise ValueError("Body Validation Failed:\n  - " + "\n  - ".join(errors))
+
+    @staticmethod
+    def _check_type(value, openapi_type, field_name, errors):
+        """Helper to check python types against OpenAPI string types."""
+        simple_type = openapi_type
+
+        if "array" in openapi_type:
+            simple_type = "array"
+        elif openapi_type not in RequestValidator.TYPE_MAP:
+            return
+
+        expected_type = RequestValidator.TYPE_MAP.get(simple_type)
+
+        if expected_type and not isinstance(value, expected_type):
+            errors.append(
+                f"Invalid type for '{field_name}'. Expected {simple_type}, got {type(value).__name__}."
+            )