unique_toolkit 0.7.9__py3-none-any.whl → 1.33.3__py3-none-any.whl

unique_toolkit/_common/docx_generator/schemas.py

@@ -0,0 +1,80 @@
+from docx.document import Document as DocumentObject
+from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
+from docxtpl import DocxTemplate
+from pydantic import BaseModel
+
+
+class HeadingField(BaseModel):
+    text: str
+    level: int = 4
+    alignment: WD_PARAGRAPH_ALIGNMENT = WD_PARAGRAPH_ALIGNMENT.LEFT
+
+    def add(self, doc: DocumentObject):
+        p = doc.add_heading(self.text, level=self.level)
+        p.alignment = self.alignment
+        return p
+
+    def __str__(self):
+        return f"HeadingField(text={self.text}, level={self.level}, alignment={self.alignment})"
+
+
+class ParagraphField(BaseModel):
+    text: str
+    style: str | None = None
+    alignment: WD_PARAGRAPH_ALIGNMENT = WD_PARAGRAPH_ALIGNMENT.LEFT
+
+    def add(self, doc: DocumentObject):
+        p = doc.add_paragraph(self.text, style=self.style)
+        p.alignment = self.alignment
+        return p
+
+    def __str__(self):
+        return f"ParagraphField(text={self.text}, style={self.style}, alignment={self.alignment})"
+
+
+class RunField(BaseModel):
+    text: str
+    italic: bool | None = False
+    bold: bool | None = False
+    alignment: WD_PARAGRAPH_ALIGNMENT = WD_PARAGRAPH_ALIGNMENT.LEFT
+
+    def __str__(self):
+        return f"RunField(text={self.text}, italic={self.italic}, alignment={self.alignment})"
+
+
+class RunsField(BaseModel):
+    runs: list[RunField]
+    style: str | None = None
+    alignment: WD_PARAGRAPH_ALIGNMENT = WD_PARAGRAPH_ALIGNMENT.LEFT
+
+    def add(self, doc: DocumentObject):
+        if not self.runs:
+            return None
+        p = doc.add_paragraph(style=self.style)
+        for run in self.runs:
+            r = p.add_run(run.text)
+            if run.italic:
+                r.italic = True
+            if run.bold:
+                r.bold = True
+        return p
+
+    def __str__(self):
+        return f"RunsField(runs={self.runs}, style={self.style}, alignment={self.alignment})"
+
+
+class ContentField(BaseModel):
+    contents: list[HeadingField | ParagraphField | RunsField]
+
+    def add(self, doc: DocxTemplate):
+        sd = doc.new_subdoc()
+        for content in self.contents:
+            # if isinstance(content, ImageField):
+            #     content.download_image(self.download_path)
+            #     content.add(sd) # type: ignore
+            # else:
+            content.add(sd)  # type: ignore
+        return sd
+
+    def __str__(self):
+        return f"ContentField(contents={self.contents})"

unique_toolkit/_common/docx_generator/service.py

@@ -0,0 +1,225 @@
+import io
+import logging
+import re
+from pathlib import Path
+
+from docxtpl import DocxTemplate
+from markdown_it import MarkdownIt
+
+from unique_toolkit._common.docx_generator.config import DocxGeneratorConfig
+from unique_toolkit._common.docx_generator.schemas import (
+    ContentField,
+    HeadingField,
+    ParagraphField,
+    RunField,
+    RunsField,
+)
+
+generator_dir_path = Path(__file__).resolve().parent
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class DocxGeneratorService:
+    def __init__(self, config: DocxGeneratorConfig, *, template: bytes | None = None):
+        self._config = config
+        self._template = template
+
+    @staticmethod
+    def parse_markdown_to_list_content_fields(
+        markdown: str, offset_header_lvl: int = 0
+    ) -> list[HeadingField | ParagraphField | RunsField]:
+        # Initialize markdown-it parser
+        md = MarkdownIt()
+
+        # Preprocess markdown.
+        # - Replace all headings with the correct heading level
+        # - Remove "Relevant sources" heading
+        # - Replace "# Proposed answer" with "#### Proposed answer"
+        markdown = re.sub(r"(?m)^\s*## ", "#### ", markdown)
+        markdown = re.sub(r"(?m)^\s*### ", "##### ", markdown)
+        markdown = markdown.replace("# Relevant sources", "")
+        markdown = markdown.replace("# Proposed answer", "#### Proposed answer")
+
+        tokens = md.parse(markdown)
+
+        elements = []
+        current_section = {}
+        in_list = False
+        bullet_list_indent_level = 0
+        list_item_open = False
+
+        for token in tokens:
+            if token.type == "bullet_list_open":
+                in_list = True
+                bullet_list_indent_level = int(token.level / 2)
+
+            elif token.type == "bullet_list_close":
+                in_list = False
+                bullet_list_indent_level = 0
+
+            elif token.type == "list_item_open":
+                if list_item_open:
+                    elements.append(current_section)
+                list_item_open = True
+                list_level = token.level - bullet_list_indent_level
+                current_section = {
+                    "type": RunsField,
+                    "runs": [],
+                    "is_list_item": True,
+                    "level": list_level,
+                }
+
+            elif token.type == "list_item_close":
+                if current_section and current_section.get("runs"):
+                    elements.append(current_section)
+                current_section = {}
+                list_item_open = False
+
+            if token.type == "heading_open":
+                # Heading start, token.tag gives the level (e.g., 'h1', 'h2', etc.)
+                header_lvl = int(token.tag[1])  # Extract the level number from tag
+                current_section = {
+                    "type": HeadingField,
+                    "text": "",
+                    "level": header_lvl + offset_header_lvl,
+                }
+
+            elif token.type == "heading_close":
+                if current_section:
+                    elements.append(current_section)
+                current_section = {}
+
+            elif token.type == "paragraph_open":
+                if not in_list:  # Only create new paragraph if not in a list
+                    current_section = {"type": RunsField, "runs": []}
+
+            elif token.type == "paragraph_close":
+                if not in_list and current_section:  # Only append if not in a list
+                    elements.append(current_section)
+                    current_section = {}
+
+            elif token.type == "inline":
+                if current_section.get("type") == HeadingField:
+                    content = token.content
+                    if content.startswith("_page"):
+                        # replace "_pageXXXX_" with "PageXXXX", where XXXX can be any characters and numbers
+                        content = re.sub(
+                            r"^_page([a-zA-Z0-9\s-]+)_(.*?)",
+                            r"Page\1",
+                            content,
+                        )
+                        bold = True
+                    current_section["text"] += content
+                elif "runs" in current_section:
+                    bold = False
+                    italic = False
+                    runs = []
+                    if token.children:
+                        for child in token.children:
+                            content = child.content
+                            if child.type == "strong_open":
+                                bold = True
+                            elif child.type == "strong_close":
+                                bold = False
+                            elif child.type == "em_open":
+                                italic = True
+                            elif child.type == "em_close":
+                                italic = False
+                            if child.type == "softbreak":
+                                content += "\n"
+                            if content:  # Only add non-empty content
+                                runs.append(
+                                    RunField(
+                                        text=content,
+                                        bold=bold,
+                                        italic=italic,
+                                    )
+                                )
+                    else:
+                        runs.append(
+                            RunField(
+                                text=token.content,
+                                bold=bold,
+                                italic=italic,
+                            )
+                        )
+
+                    current_section["runs"].extend(runs)
+
+        # Process remaining elements
+        contents = []
+        for element in elements:
+            if not element:
+                continue
+            if element["type"] == HeadingField:
+                contents.append(
+                    HeadingField(
+                        text=element["text"],
+                        level=element["level"],
+                    )
+                )
+            elif element["type"] == RunsField:
+                if element.get("is_list_item", False):
+                    level: int = min(element.get("level", 1), 5)
+                    if level > 1:
+                        style = "List Bullet " + str(level)
+                    else:
+                        style = "List Bullet"
+                    contents.append(RunsField(style=style, runs=element["runs"]))
+                else:
+                    contents.append(RunsField(runs=element["runs"]))
+
+        return contents
+
+    def generate_from_template(
+        self,
+        subdoc_content: list[HeadingField | ParagraphField | RunsField],
+        fields: dict | None = None,
+    ):
+        """
+        Generate a docx file from a template with the given content.
+
+        Args:
+            subdoc_content (list[HeadingField | ParagraphField | RunsField]): The content to be added to the docx file.
+            fields (dict): Other fields to be added to the docx file. Defaults to None.
+        """
+        doc = DocxTemplate(io.BytesIO(self.template))
+
+        try:
+            content = {}
+            content["body"] = ContentField(contents=subdoc_content)
+
+            if fields:
+                content.update(fields)
+
+            for key, value in content.items():
+                if isinstance(value, ContentField):
+                    content[key] = value.add(doc)
+
+            doc.render(content)
+            docx_rendered_object = io.BytesIO()
+
+            doc.save(docx_rendered_object)
+            docx_rendered_object.seek(0)
+
+            return docx_rendered_object.getvalue()
+
+        except Exception as e:
+            _LOGGER.error(f"Error generating docx: {e}")
+            return None
+
+    def _get_default_template(self) -> bytes:
+        generator_dir_path = Path(__file__).resolve().parent
+        path = generator_dir_path / "template" / "Doc Template.docx"
+
+        file_content = path.read_bytes()
+
+        _LOGGER.info("Template downloaded from default template")
+
+        return file_content
+
+    @property
+    def template(self) -> bytes:
+        return self._template or self._get_default_template()

unique_toolkit/_common/endpoint_builder.py

@@ -0,0 +1,368 @@
+"""
+This module provides a minimal framework for building endpoint classes such that a client can use
+the endpoints without having to know the details of the endpoints.
+"""
+
+import warnings
+from enum import StrEnum
+from string import Template
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    ParamSpec,
+    Protocol,
+    TypeVar,
+    cast,
+)
+
+from pydantic import BaseModel, ValidationError
+
+# Paramspecs
+PayloadParamSpec = ParamSpec("PayloadParamSpec")
+PathParamsSpec = ParamSpec("PathParamsSpec")
+QueryParamsSpec = ParamSpec("QueryParamsSpec")
+
+# Type variables
+ResponseType = TypeVar("ResponseType", bound=BaseModel, covariant=True)
+PathParamsType = TypeVar("PathParamsType", bound=BaseModel)
+PayloadType = TypeVar("PayloadType", bound=BaseModel)
+QueryParamsType = TypeVar("QueryParamsType", bound=BaseModel)
+
+# Helper type to extract constructor parameters
+
+# Type for the constructor of a Pydantic model
+ModelConstructor = Callable[..., BaseModel]
+
+
+class HttpMethods(StrEnum):
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+
+
+# Backward compatibility TODO: Remove in 2.0.0.
+EndpointMethods = HttpMethods
+
+
+class ResponseValidationException(Exception):
+    """
+    This exception is raised when the response validation fails.
+    """
+
+    def __init__(
+        self, operation_name: str, response: dict[str, Any], pydantic_error: str
+    ):
+        super().__init__(
+            f"Response validation failed for operation {operation_name}\n"
+            f"Response: {response}\n"
+            f"Pydantic error: {pydantic_error}"
+        )
+        self._operation_name = operation_name
+        self._response = response
+        self._pydantic_error = pydantic_error
+
+    @property
+    def operation_name(self) -> str:
+        return self._operation_name
+
+    @property
+    def response(self) -> dict[str, Any]:
+        return self._response
+
+    @property
+    def pydantic_error(self) -> str:
+        return self._pydantic_error
+
+    def __str__(self):
+        return (
+            f"Response validation failed for {self._operation_name}\n"
+            + f"Response: {self._response}"
+        )
+
+
+class ApiOperationProtocol(
+    Protocol,
+    Generic[
+        PathParamsSpec,
+        PathParamsType,
+        PayloadParamSpec,
+        PayloadType,
+        QueryParamsSpec,
+        QueryParamsType,
+        ResponseType,
+    ],
+):
+    @staticmethod
+    def path_dump_options() -> dict[str, Any]: ...
+
+    @staticmethod
+    def path_params_model() -> type[PathParamsType]: ...
+
+    @staticmethod
+    def payload_dump_options() -> dict[str, Any]: ...
+
+    @staticmethod
+    def payload_model() -> type[PayloadType]: ...
+
+    @staticmethod
+    def response_validate_options() -> dict[str, Any]: ...
+
+    @staticmethod
+    def response_model() -> type[ResponseType]: ...
+
+    @staticmethod
+    def query_params_dump_options() -> dict[str, Any]: ...
+
+    @staticmethod
+    def query_params_model() -> type[QueryParamsType]: ...
+
+    @staticmethod
+    def create_path(
+        *args: PathParamsSpec.args, **kwargs: PathParamsSpec.kwargs
+    ) -> str: ...
+
+    @staticmethod
+    def create_path_from_model(
+        path_params: PathParamsType, *, model_dump_options: dict | None = None
+    ) -> str: ...
+
+    @staticmethod
+    def create_payload(
+        *args: PayloadParamSpec.args, **kwargs: PayloadParamSpec.kwargs
+    ) -> dict[str, Any]: ...
+
+    @staticmethod
+    def create_payload_from_model(
+        payload: PayloadType, *, model_dump_options: dict | None = None
+    ) -> dict[str, Any]: ...
+
+    @staticmethod
+    def create_query_params(
+        *args: QueryParamsSpec.args, **kwargs: QueryParamsSpec.kwargs
+    ) -> dict[str, Any]: ...
+
+    @staticmethod
+    def create_query_params_from_model(
+        query_params: QueryParamsType, *, model_dump_options: dict | None = None
+    ) -> dict[str, Any]: ...
+
+    @staticmethod
+    def handle_response(
+        response: dict[str, Any], *, model_validate_options: dict | None = None
+    ) -> ResponseType: ...
+
+    @staticmethod
+    def request_method() -> EndpointMethods: ...
+
+    @staticmethod
+    def models_from_combined(
+        combined: dict[str, Any],
+    ) -> tuple[PathParamsType, PayloadType, QueryParamsType]: ...
+
+
+class EmptyModel(BaseModel): ...
+
+
+# Model for any client to implement
+def build_api_operation(
+    *,
+    method: HttpMethods,
+    path_template: Template,
+    response_model_type: type[ResponseType],
+    path_params_constructor: Callable[PathParamsSpec, PathParamsType] = EmptyModel,
+    payload_dump_options: dict | None = None,
+    payload_constructor: Callable[PayloadParamSpec, PayloadType] = EmptyModel,
+    path_dump_options: dict | None = None,
+    query_params_constructor: Callable[QueryParamsSpec, QueryParamsType] = EmptyModel,
+    query_params_dump_options: dict | None = None,
+    response_validate_options: dict | None = None,
+    dump_options: dict | None = None,  # Deprecated
+) -> type[
+    ApiOperationProtocol[
+        PathParamsSpec,
+        PathParamsType,
+        PayloadParamSpec,
+        PayloadType,
+        QueryParamsSpec,
+        QueryParamsType,
+        ResponseType,
+    ]
+]:
+    """Generate a class with static methods for endpoint handling.
+
+    Uses separate models for path parameters and request body for clean API design.
+
+    Returns a class with static methods:
+    - create_url: Creates URL from path parameters
+    - create_payload: Creates request body payload
+    """
+
+    # Verify that the path_params_constructor and payload_constructor are valid pydantic models
+    if not dump_options:
+        dump_options = {
+            "exclude_unset": True,
+            "by_alias": True,
+            "exclude_defaults": True,
+        }
+    else:
+        warnings.warn(
+            "dump_options is deprecated. Use payload_dump_options instead.",
+            DeprecationWarning,
+        )
+
+    class Operation(ApiOperationProtocol):
+        @staticmethod
+        def path_dump_options() -> dict[str, Any]:
+            return path_dump_options or {}
+
+        @staticmethod
+        def path_params_model() -> type[PathParamsType]:
+            return cast(type[PathParamsType], path_params_constructor)
+
+        @staticmethod
+        def payload_dump_options() -> dict[str, Any]:
+            return payload_dump_options or {}
+
+        @staticmethod
+        def payload_model() -> type[PayloadType]:
+            return cast(type[PayloadType], payload_constructor)
+
+        @staticmethod
+        def query_params_dump_options() -> dict[str, Any]:
+            return query_params_dump_options or {}
+
+        @staticmethod
+        def query_params_model() -> type[QueryParamsType]:
+            return cast(type[QueryParamsType], query_params_constructor)
+
+        @staticmethod
+        def response_validate_options() -> dict[str, Any]:
+            return response_validate_options or {}
+
+        @staticmethod
+        def response_model() -> type[ResponseType]:
+            return response_model_type
+
+        @staticmethod
+        def path_template() -> Template:
+            return path_template
+
+        @staticmethod
+        def create_path_from_model(
+            path_params: PathParamsType, *, model_dump_options: dict | None = None
+        ) -> str:
+            if model_dump_options is None:
+                if path_dump_options is None:
+                    model_dump_options = dump_options
+                else:
+                    model_dump_options = path_dump_options
+
+            return path_template.substitute(
+                **path_params.model_dump(**model_dump_options)
+            )
+
+        @staticmethod
+        def create_path(
+            *args: PathParamsSpec.args, **kwargs: PathParamsSpec.kwargs
+        ) -> str:
+            model = Operation.path_params_model()(*args, **kwargs)
+            return Operation.create_path_from_model(model)
+
+        @staticmethod
+        def create_payload(
+            *args: PayloadParamSpec.args,
+            **kwargs: PayloadParamSpec.kwargs,
+        ) -> dict[str, Any]:
+            """Create request body payload."""
+            if payload_dump_options is None:
+                model_dump_options = dump_options
+            else:
+                model_dump_options = payload_dump_options
+
+            request_model = Operation.payload_model()(*args, **kwargs)
+            return request_model.model_dump(**model_dump_options)
+
+        @staticmethod
+        def create_payload_from_model(
+            payload: PayloadType, *, model_dump_options: dict | None = None
+        ) -> dict[str, Any]:
+            if model_dump_options is None:
+                if payload_dump_options is None:
+                    model_dump_options = dump_options
+                else:
+                    model_dump_options = payload_dump_options
+
+            return payload.model_dump(**model_dump_options)
+
+        @staticmethod
+        def create_query_params(
+            *args: QueryParamsSpec.args, **kwargs: QueryParamsSpec.kwargs
+        ) -> dict[str, Any]:
+            if query_params_dump_options is None:
+                model_dump_options = dump_options
+            else:
+                model_dump_options = query_params_dump_options
+
+            return query_params_constructor(*args, **kwargs).model_dump(
+                **model_dump_options
+            )
+
+        @staticmethod
+        def create_query_params_from_model(
+            query_params: QueryParamsType, *, model_dump_options: dict | None = None
+        ) -> dict[str, Any]:
+            if model_dump_options is None:
+                if query_params_dump_options is None:
+                    model_dump_options = dump_options
+                else:
+                    model_dump_options = query_params_dump_options
+
+            return query_params.model_dump(**model_dump_options)
+
+        @staticmethod
+        def handle_response(
+            response: dict[str, Any],
+            *,
+            model_validate_options: dict[str, Any] | None = None,
+        ) -> ResponseType:
+            if model_validate_options is None:
+                if response_validate_options is None:
+                    model_validate_options = {}
+                else:
+                    model_validate_options = response_validate_options
+            try:
+                return Operation.response_model().model_validate(
+                    response, **model_validate_options
+                )
+            except ValidationError as e:
+                raise ResponseValidationException(
+                    operation_name=Operation.__name__,
+                    response=response,
+                    pydantic_error=str(e),
+                ) from e
+
+        @staticmethod
+        def request_method() -> HttpMethods:
+            return method
+
+        @staticmethod
+        def models_from_combined(
+            combined: dict[str, Any],
+        ) -> tuple[PathParamsType, PayloadType, QueryParamsType]:
+            path_params = Operation.path_params_model().model_validate(
+                combined, by_alias=True, by_name=True
+            )
+            payload = Operation.payload_model().model_validate(
+                combined, by_alias=True, by_name=True
+            )
+            query_params = Operation.query_params_model().model_validate(
+                combined, by_alias=True, by_name=True
+            )
+            return path_params, payload, query_params
+
+    return Operation