nsj-rest-lib2 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

nsj_rest_lib2/compiler/edl_model/ai_entity_edl.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, Union
+from pydantic import BaseModel, Field, RootModel, constr, conint, confloat
+
+
+PropertyType = Literal[
+    "string", "number", "integer", "boolean", "date", "datetime", "object"
+]
+
+# ---------------------------
+# Tipos básicos e utilitários
+# ---------------------------
+
+PrimitiveType = Literal[
+    "string", "number", "integer", "boolean", "date", "datetime", "object"
+]
+
+
+# Em EDL, type também pode apontar para outra entidade "scope.object" ou "array"
+# e propriedades podem ter metadados comuns.
+class Property(BaseModel):
+    # Tipo pode ser primitivo, "array", um caminho de entidade "escopo.entidade"
+    # ou um formato especializado (ex.: "uuid", "currency", "cpf", "cnpj"...)
+    type: str = Field(
+        ..., description="Tipo EDL (primitivo, array, ou escopo.entidade)."
+    )
+    cardinality: Optional[Literal["1_1", "0_1", "1_N", "0_N", "N_N"]] = None
+
+    # Metadados comuns
+    label: Optional[str] = None
+    description: Optional[str] = None
+    length: Optional[int] = None
+    pattern: Optional[str] = None
+    default: Optional[Any] = None
+    immutable: Optional[bool] = None
+    minimum: Optional[confloat()] = None
+    maximum: Optional[confloat()] = None
+    enum: Optional[List[Union[str, int]]] = None
+
+    # Chaves
+    pk: Optional[bool] = None
+    key_alternative: Optional[bool] = None  # alias semântico (chave natural)
+    pk_substitute: Optional[bool] = None  # usado em alguns exemplos
+    value: Optional[Any] = None  # valor fixo/derivado
+    format: Optional[str] = None  # ex.: "uuid", "currency", "quantity"
+
+    # Itens (para arrays embutidos)
+    items: Optional[Union["RelationDef", Property, Dict[str, Any]]] = None
+
+
+class ComposedMap(RootModel[Dict[str, Any]]):
+    """
+    Representa composed_properties: aceita mapeamentos arbitrários
+    (strings de caminho e/ou mapas aninhados).
+    """
+
+    pass
+
+
+# ---------------------------
+# Relations (objetos inline)
+# ---------------------------
+
+
+class RelationDef(BaseModel):
+    # Em EDL, relations podem ser "object" (estrutura inline) ou "array" de "object"
+    type: Optional[str] = Field(None, description='Tipicamente "object" ou "array".')
+    # Identificador opcional da relação/objeto
+    id_: Optional[str] = Field(None, alias="$id")
+    required: Optional[List[str]] = None
+    properties: Optional[Dict[str, Property]] = None
+    composed_properties: Optional[Dict[str, ComposedMap]] = None
+    items: Optional[Union[Property, Dict[str, Any]]] = None
+
+
+# ---------------------------
+# Regras (motor de regras)
+# ---------------------------
+
+RuleType = Literal["required", "custom", "format"]
+
+
+class Rule(BaseModel):
+    field: str
+    type: RuleType
+    when: Optional[str] = None
+    message: Optional[str] = None
+    messageParams: Optional[List[str]] = None
+    # Para tipo "format"
+    pattern: Optional[str] = None
+    # Para tipo "custom"
+    fn: Optional[str] = None
+
+
+# ---------------------------
+# Repository (mapeamento físico)
+# ---------------------------
+
+
+class LinkToBase(BaseModel):
+    base: str
+    baseProperty: str
+    column: str
+    onDelete: Optional[Literal["cascade", "restrict", "set_null"]] = None
+    nullable: Optional[bool] = None
+
+
+class IndexDef(BaseModel):
+    name: str
+    fields: List[str]
+    unique: Optional[bool] = None
+
+
+class ColumnsMap(RootModel[Dict[str, Any]]):
+    """
+    Suporta tanto mapeamentos simples {"prop": {"column": "col"}}
+    quanto caminhos aninhados ("totais.valorNf": {"column": "vnf"}).
+    """
+
+    pass
+
+
+class RepositoryBlock(BaseModel):
+    map: Optional[str] = None  # schema.tabela
+    shared_table: Optional[bool] = None
+    table_owner: Optional[bool] = None
+    linkToBase: Optional[LinkToBase] = None  # obrigatório para parciais
+    columns: Optional[ColumnsMap] = None
+    indexes: Optional[List[IndexDef]] = None
+
+
+# Em muitos exemplos, "repository" é um dicionário de blocos lógicos:
+# { "Documento": {...}, "documento.linhas": {...} }
+Repository = Dict[str, RepositoryBlock]
+
+
+# ---------------------------
+# API e Handlers
+# ---------------------------
+
+Verb = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+ComposePolicy = Literal["transparent", "readonly", "none"]
+
+
+class HttpResultSpec(BaseModel):
+    statusOnSuccess: Optional[int] = None
+    location: Optional[str] = None
+
+
+class HandlerResult(BaseModel):
+    expect: Optional[Literal["entity_row", "rows", "void"]] = None
+    entity: Optional[str] = None
+    http: Optional[HttpResultSpec] = None
+
+
+class ComposeMappingAttr(BaseModel):
+    attr: str
+    from_: Optional[str] = Field(None, alias="from")
+    # Para arrays: indicar o tipo composto do banco
+    as_: Optional[str] = Field(None, alias="as")
+    # Mapeamento de itens (quando from aponta para array)
+    mapping: Optional[List["ComposeMappingAttr"]] = None
+
+
+class CallCompose(BaseModel):
+    typeName: str
+    mapping: List[ComposeMappingAttr]
+    onMissing: Optional[Literal["error", "ignore", "null"]] = None
+
+
+class ArgBinding(BaseModel):
+    to: str
+    source: Literal["body", "context"]
+    from_: Optional[str] = Field(None, alias="from")
+    dbType: Optional[str] = None
+    compose: Optional[CallCompose] = None
+
+
+class CallSpec(BaseModel):
+    style: Optional[Literal["named"]] = None
+    argBinding: Optional[List[ArgBinding]] = None
+
+
+class HandlerError(BaseModel):
+    sqlstate: Optional[str] = None
+    httpStatus: Optional[int] = None
+    message: Optional[str] = None
+
+
+class HandlerConfig(BaseModel):
+    impl: Optional[str] = None  # ex.: "pg_function"
+    functionRef: Optional[str] = None
+    signature: Optional[List[str]] = None
+    call: Optional[CallSpec] = None
+    result: Optional[HandlerResult] = None
+    errors: Optional[List[HandlerError]] = None
+    transaction: Optional[Literal["wrap", "none"]] = None
+    validate: Optional[Literal["warn", "strict", "none"]] = None
+
+
+class APIBlock(BaseModel):
+    resource: Optional[str] = None
+    expose: Optional[bool] = None
+    verbs: Optional[List[Verb]] = None
+    filters: Optional[List[str]] = None
+    default_sort: Optional[List[str]] = None
+    includeExtensionsByDefault: Optional[bool] = None
+    subset: Optional[str] = None
+
+    # Parciais / composição
+    composeWithBase: Optional[bool] = None
+    composePolicy: Optional[ComposePolicy] = None
+
+    # Handlers por verbo
+    handlers: Optional[Dict[Verb, HandlerConfig]] = None
+
+
+# ---------------------------
+# Bloco principal: model
+# ---------------------------
+
+
+class ModelBlock(BaseModel):
+    mixins: Optional[List[str]] = None
+    required: Optional[List[str]] = None
+    main_properties: Optional[List[str]] = None
+
+    properties: Dict[str, Property] = Field(default_factory=dict)
+    composed_properties: Optional[Dict[str, ComposedMap]] = None
+    relations: Optional[Dict[str, RelationDef]] = None
+    rules: Optional[List[Rule]] = None
+
+    # Repository pode conter múltiplos blocos lógicos
+    repository: Optional[Repository] = None
+
+    api: Optional[APIBlock] = None
+
+
+# ---------------------------
+# Arquivo EDL (raiz)
+# ---------------------------
+
+
+class EDLFile(BaseModel):
+    edl_version: Literal["1.0"]
+    escopo: str
+
+    # Presentes conforme o tipo (entidade normal, trait, subclasse, parcial)
+    id: Optional[str] = None
+    trait_from: Optional[str] = None
+    trait: Optional[str] = None
+    extends: Optional[str] = None
+    partial_of: Optional[str] = None
+    partial: Optional[str] = None
+
+    # Outros observados nos exemplos
+    version: conint(ge=1)
+    abstract: Optional[bool] = None
+    native: Optional[bool] = None
+
+    model: ModelBlock

nsj_rest_lib2/compiler/edl_model/api_model.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Literal
+
+APIVerbs = Literal["GET", "POST", "PUT", "DELETE", "PATCH"]
+
+
+class APIModel(BaseModel):
+    resource: str = Field(
+        ...,
+        description="Nome do recurso REST (rota base dos endpoints; exemplo: 'clientes').",
+    )
+    expose: Optional[bool] = Field(
+        default=True,
+        description="Indica se a API deve ser exposta (padrão: True).",
+    )
+    verbs: Optional[List[APIVerbs]] = Field(
+        default=["GET", "POST", "PUT", "DELETE", "PATCH"],
+        description="Lista de verbos HTTP suportados pela API (padrão: todos).",
+    )
+    default_sort: Optional[List[str]] = Field(
+        None,
+        description="Lista de campos usados na ordenação padrão (padrão: se nada for fornecido, será usada, ao menos, a PK).",
+    )

nsj_rest_lib2/compiler/edl_model/column_meta_model.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Literal
+
+
+class ColumnMetaModel(BaseModel):
+    column: str = Field(..., description="Nome da coluna no banco de dados.")

nsj_rest_lib2/compiler/edl_model/entity_model.py

@@ -0,0 +1,66 @@
+from pydantic import BaseModel, Field
+from typing import Dict, List, Optional
+
+from nsj_rest_lib2.compiler.edl_model.property_meta_model import PropertyMetaModel
+from nsj_rest_lib2.compiler.edl_model.repository_model import RepositoryModel
+from nsj_rest_lib2.compiler.edl_model.api_model import APIModel
+from nsj_rest_lib2.compiler.edl_model.trait_property_meta_model import (
+    TraitPropertyMetaModel,
+)
+
+
+class EntityModel(BaseModel):
+    edl_version: Optional[str] = Field(default="1.0", description="Versão do EDL")
+    escopo: str = Field(..., description="Escopo do EDL (define a aplicação).")
+    description: str = Field(..., description="Descrição da entidade.")
+    id: str = Field(
+        ...,
+        description="Identificador único da entidade, dentro de um determinado escopo (podendo ser sobreescrito para um tenant ou grupo _empresarial).",
+    )
+    trait_from: Optional[str] = Field(
+        None, description="Identificador da entidade que a trait estende."
+    )
+    version: Optional[str] = Field(
+        default="1.0", description="Versão da entidade (padrão: 1.0)."
+    )
+    abstract: Optional[bool] = Field(
+        default=False,
+        description="Indica se a entidade é abstrata (padrão: False). Caso positivo, não gera código, mas pode ser usada na geração de código de outras entidades.",
+    )
+    mixins: Optional[List[str]] = Field(
+        None,
+        description="Lista de mixins (blocos reutilizáveis) aplicados ao modelo.",
+    )
+    required: Optional[List[str]] = Field(
+        None, description="Lista de campos obrigatórios no modelo."
+    )
+    partition_data: Optional[List[str]] = Field(
+        None,
+        description="Lista de propriedades da entidade, que serã usadas para particionamento dos dados no banco (sendo obrigatórias em todas as chamadas, inclusive como um tipo de filtro obrigatório).",
+    )
+    main_properties: Optional[List[str]] = Field(
+        None,
+        description="Lista de propriedades resumo do modelo (retornadas em qualquer chamada GET, mesmo que não pedidas por meio do parâmetro 'fields').",
+    )
+    search_properties: Optional[List[str]] = Field(
+        None,
+        description="Lista de propriedades do modelo que serão utilizadas nas chamadas de query do usuário (suportando também campos das entidades relacionadas). Sugere-se que a biblioteca crie automaticamente os índices para fulltext search.",
+    )
+    metric_label: Optional[List[str]] = Field(
+        None,
+        description="Lista de campos incluídos no agrupamento das métricas enviadas ao OpenTelemetry.",
+    )
+    trait_properties: Optional[Dict[str, TraitPropertyMetaModel]] = Field(
+        None,
+        description="Dicionário de propriedades condicionais da trait (isso é, especifica propriedades, e seus valores fixos, que serão usados como um tipo de filtro fixo usado como condição para que a propridade principal assum o papel daquele tipo de trait).",
+    )
+    properties: Dict[str, PropertyMetaModel] = Field(
+        ..., description="Dicionário de propriedades do modelo."
+    )
+    repository: RepositoryModel = Field(
+        ..., description="Configurações de mapeamento para o banco de dados."
+    )
+    api: Optional[APIModel] = Field(
+        None,
+        description="Definição da API REST associada ao modelo, com todos os seus endpoints.",
+    )

nsj_rest_lib2/compiler/edl_model/index_model.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+
+class IndexModel(BaseModel):
+    name: str = Field(..., description="Nome do índice no banco de dados.")
+    columns: List[str] = Field(
+        ..., description="Lista de colunas que compõem o índice."
+    )
+    unique: Optional[bool] = Field(
+        default=False,
+        description="Indica se é um índice de unicidade (padrão: False). Se não for de unicidade, será um índice usado para otimização de queries.",
+    )

nsj_rest_lib2/compiler/edl_model/primitives.py

@@ -0,0 +1,43 @@
+import enum
+from typing import List
+
+
+class PrimitiveTypes(enum.Enum):
+    # TODO Validar esses tipos
+    STRING = "string"
+    NUMBER = "number"
+    INTEGER = "integer"
+    BOOLEAN = "boolean"
+    ARRAY = "array"
+    OBJECT = "object"
+    UUID = "uuid"
+    CURRENCY = "currency"
+    QUANTITY = "quantity"
+    CPF = "cpf"
+    CNPJ = "cnpj"
+    CPF_CNPJ = "cpf_cnpj"
+    EMAIL = "email"
+    DATE = "date"
+    DATETIME = "datetime"
+
+
+MAPPING_PRIMITIVE_TYPES_TO_PYTHON = {
+    PrimitiveTypes.STRING: "str",
+    PrimitiveTypes.NUMBER: "float",
+    PrimitiveTypes.INTEGER: "int",
+    PrimitiveTypes.BOOLEAN: "bool",
+    PrimitiveTypes.ARRAY: "List",
+    PrimitiveTypes.OBJECT: "dict",
+    PrimitiveTypes.UUID: "uuid.UUID",
+    PrimitiveTypes.CURRENCY: "float",
+    PrimitiveTypes.QUANTITY: "float",
+    PrimitiveTypes.CPF: "str",
+    PrimitiveTypes.CNPJ: "str",
+    PrimitiveTypes.CPF_CNPJ: "str",
+    PrimitiveTypes.EMAIL: "str",
+    PrimitiveTypes.DATE: "datetime.date",
+    PrimitiveTypes.DATETIME: "datetime.datetime",
+}
+
+BasicTypes = int | bool | float | str
+DefaultTypes = BasicTypes | List[BasicTypes]

nsj_rest_lib2/compiler/edl_model/property_meta_model.py

@@ -0,0 +1,82 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+from nsj_rest_lib2.compiler.edl_model.primitives import BasicTypes, DefaultTypes
+from nsj_rest_lib2.compiler.edl_model.primitives import PrimitiveTypes
+
+
+class DomainConfigModel(BaseModel):
+    value: str = Field(..., description="Valor do enum.")
+    mapped_value: Optional[BasicTypes] = Field(
+        None, description="Valor mapeado do enum (gravado no BD)."
+    )
+
+
+class PropertyMetaModel(BaseModel):
+    type: PrimitiveTypes = Field(..., description="Tipo da propriedade.")
+    label: Optional[str] = Field(None, description="Rótulo da propriedade.")
+    description: Optional[str] = Field(None, description="Descrição da propriedade.")
+    default: Optional[DefaultTypes] = Field(
+        None,
+        description="Valor padrão da propriedade (caso não fornecido numa chamada de persistência). Pode indicar um valor, ou uma expressão (ex.: 'now()' para data/hora atual).",
+    )
+    pk: Optional[bool] = Field(
+        default=False, description="Indica se a propriedade é parte da chave primária."
+    )
+    key_alternative: Optional[bool] = Field(
+        default=False,
+        description="Indica se a propriedade é parte de uma chave alternativa (chave natural).",
+        alias="keyAlternative",
+    )
+    # Validação
+    max_length: Optional[int] = Field(
+        None, description="Comprimento máximo (para strings)."
+    )
+
+    ## TODO Sugestões de validação
+    min_length: Optional[int] = Field(
+        None, description="Comprimento mínimo (para strings).", alias="minLength"
+    )
+    pattern: Optional[str] = Field(
+        None,
+        description="Expressão regular que o valor da propriedade deve obedecer (para strings).",
+    )
+    minimum: Optional[float] = Field(
+        None, description="Valor mínimo permitido (para números)."
+    )
+    maximum: Optional[float] = Field(
+        None, description="Valor máximo permitido (para números)."
+    )
+    validator: Optional[str] = Field(
+        None,
+        description="Caminho completo para uma função de validação e alteração personalizada (ex.: 'module.validator'). Sendo que as funções dinâmicas sempre estarão no modulo XPTO.",
+    )  # TODO Definir padrão de carregamento do módulo de funções customizadas
+    domain_config: Optional[List[DomainConfigModel]] = Field(
+        None,
+        description="Lista de valores permitidos.",
+    )
+    immutable: Optional[bool] = Field(
+        default=False,
+        description="Indica se a propriedade é imutável (não pode ser alterada após a criação).",
+    )
+    trim: Optional[bool] = Field(
+        default=False,
+        description="Indica se espaços em branco devem ser removidos do início e fim (para strings).",
+    )
+    lowercase: Optional[bool] = Field(
+        default=False,
+        description="Indica se o valor deve ser convertido para minúsculas (para strings).",
+    )
+    uppercase: Optional[bool] = Field(
+        default=False,
+        description="Indica se o valor deve ser convertido para maiúsculas (para strings).",
+    )
+
+    on_save: Optional[str] = Field(
+        None,
+        description="Função de conversão para o tipo da entidade (ex.: converter string para uuid).",
+    )
+    on_retrieve: Optional[str] = Field(
+        None,
+        description="Função de conversão do tipo da entidade para o tipo da API (ex.: converter uuid para string).",
+    )

nsj_rest_lib2/compiler/edl_model/repository_model.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+from nsj_rest_lib2.compiler.edl_model.column_meta_model import ColumnMetaModel
+from nsj_rest_lib2.compiler.edl_model.index_model import IndexModel
+
+
+class RepositoryModel(BaseModel):
+    map: str = Field(
+        ..., description="Nome da tabela, no BD, para a qual a entidade é mapeada."
+    )
+    shared_table: Optional[bool] = Field(
+        default=False,
+        description="Indica se a tabela é compartilhada entre múltiplas entidades (padrão: False).",
+    )
+    table_owner: Optional[bool] = Field(
+        None, description="Indica que essa entidade é dona da tabela (schema)."
+    )  # TODO Validar explicação
+    properties: Optional[dict[str, ColumnMetaModel]] = Field(
+        None, description="Dicionário de colunas da entidade."
+    )
+    indexes: Optional[List[IndexModel]] = Field(
+        None, description="Lista de índices de banco de dados, associados à entidade."
+    )

nsj_rest_lib2/compiler/edl_model/trait_property_meta_model.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, Field
+
+from nsj_rest_lib2.compiler.edl_model.primitives import BasicTypes, PrimitiveTypes
+
+
+class TraitPropertyMetaModel(BaseModel):
+    type: PrimitiveTypes = Field(..., description="Tipo da propriedade.")
+    value: BasicTypes = Field(
+        ..., description="Valor fixo da propriedade de condicionamento do trait."
+    )

nsj_rest_lib2/compiler/entity_compiler.py

@@ -0,0 +1,118 @@
+import ast
+
+import black
+
+from nsj_rest_lib2.compiler.edl_model.entity_model import EntityModel
+from nsj_rest_lib2.compiler.edl_model.repository_model import RepositoryModel
+from nsj_rest_lib2.compiler.util.str_util import CompilerStrUtil
+
+
+class EntityCompiler:
+    def __init__(self):
+        pass
+
+    def compile(
+        self,
+        entity_model: EntityModel,
+        ast_entity_attributes: list[ast.stmt],
+        props_pk: list[str],
+    ) -> tuple[str, str]:
+        # Imports
+        imports = [
+            # import datetime
+            ast.Import(names=[ast.alias(name="datetime", asname=None)]),
+            # import uuid
+            ast.Import(names=[ast.alias(name="uuid", asname=None)]),
+            # from nsj_rest_lib.entity.entity_base import EntityBase
+            ast.ImportFrom(
+                module="nsj_rest_lib.entity.entity_base",
+                names=[ast.alias(name="EntityBase", asname=None)],
+                level=0,
+            ),
+            # from nsj_rest_lib.decorator.entity import Entity
+            ast.ImportFrom(
+                module="nsj_rest_lib.decorator.entity",
+                names=[ast.alias(name="Entity", asname=None)],
+                level=0,
+            ),
+        ]
+
+        # Entity
+        if len(props_pk) > 1:
+            raise Exception(
+                f"Entidade '{entity_model.id}' possui mais de uma chave primária (ainda não suportado): {props_pk}"
+            )
+        elif len(props_pk) <= 0:
+            raise Exception(
+                f"Entidade '{entity_model.id}' não possui nenhuma chave primária (ainda não suportado)."
+            )
+
+        default_order_props = []
+        if entity_model.api and entity_model.api.default_sort:
+            default_order_props = entity_model.api.default_sort
+
+        default_order_fields = []
+        for prop in default_order_props:
+            if (
+                entity_model.repository.properties
+                and prop in entity_model.repository.properties
+            ):
+                field = entity_model.repository.properties[prop].column
+            else:
+                field = prop
+
+            default_order_fields.append(CompilerStrUtil.to_snake_case(field))
+
+        if CompilerStrUtil.to_snake_case(props_pk[0]) not in default_order_fields:
+            default_order_fields.append(CompilerStrUtil.to_snake_case(props_pk[0]))
+
+        class_name = f"{CompilerStrUtil.to_pascal_case(entity_model.id)}Entity"
+        ast_class = ast.ClassDef(
+            name=class_name,
+            bases=[ast.Name(id="EntityBase", ctx=ast.Load())],
+            keywords=[],
+            decorator_list=[
+                ast.Call(
+                    func=ast.Name(id="Entity", ctx=ast.Load()),
+                    args=[],
+                    keywords=[
+                        ast.keyword(
+                            arg="table_name",
+                            value=ast.Constant(value=entity_model.repository.map),
+                        ),
+                        ast.keyword(
+                            arg="pk_field",
+                            value=ast.Constant(
+                                value=CompilerStrUtil.to_snake_case(props_pk[0])
+                            ),
+                        ),
+                        ast.keyword(
+                            arg="default_order_fields",
+                            value=ast.List(
+                                elts=[
+                                    ast.Constant(value=field)
+                                    for field in default_order_fields
+                                ],
+                                ctx=ast.Load(),
+                            ),
+                        ),
+                    ],
+                )
+            ],
+            body=ast_entity_attributes,
+        )
+
+        # Definindo o módulo
+        module = ast.Module(
+            body=imports + [ast_class],
+            type_ignores=[],
+        )
+        module = ast.fix_missing_locations(module)
+
+        # Compilando o AST do DTO para o código Python
+        code = ast.unparse(module)
+
+        # Chamando o black para formatar o código Python do DTO
+        code = black.format_str(code, mode=black.FileMode())
+
+        return (class_name, code)