macss-modular-api 0.4.4__tar.gz → 0.4.6__tar.gz

{macss_modular_api-0.4.4/src/macss_modular_api.egg-info → macss_modular_api-0.4.6}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: macss-modular-api
-Version: 0.4.4
+Version: 0.4.6
 Summary: Use-case-centric toolkit for building modular APIs with Starlette. Define UseCase classes (input → validate → execute → output), connect them to HTTP routes, and expose OpenAPI documentation automatically.
 Author: ccisne.dev
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/macss-dev/modular_api
-Project-URL: Repository, https://github.com/macss-dev/modular_api/tree/main/py
+Project-URL: Repository, https://github.com/macss-dev/modular_api/tree/main/code/py
 Project-URL: Issues, https://github.com/macss-dev/modular_api/issues
-Project-URL: Documentation, https://github.com/macss-dev/modular_api/tree/main/py#readme
+Project-URL: Documentation, https://github.com/macss-dev/modular_api/tree/main/code/py#readme
 Keywords: api,usecase,openapi,starlette,modular,macss
 Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: AsyncIO
@@ -114,7 +114,7 @@ pip install modular-api[serve]
 ## Error handling
 
 ```python
-async def execute(self) -> None:
+async def execute(self) -> FoundUserOutput:
     user = await repository.find_by_id(self.input.user_id)
     if not user:
         raise UseCaseException(
@@ -122,7 +122,7 @@ async def execute(self) -> None:
             message="User not found",
             error_code="USER_NOT_FOUND",
         )
-    self._output = FoundUserOutput(name=user.name)
+    return FoundUserOutput(name=user.name)
 ```
 
 ---
@@ -130,13 +130,13 @@ async def execute(self) -> None:
 ## Testing
 
 ```python
-def test_hello_world():
+async def test_hello_world():
     usecase = HelloWorld(HelloInput(name="World"))
     error = usecase.validate()
     assert error is None
 
-    await usecase.execute()
-    assert usecase.output.message == "Hello, World!"
+    output = await usecase.execute()
+    assert output.message == "Hello, World!"
 ```
 
 See [doc/testing_guide.md](doc/testing_guide.md) for the full testing guide.

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/README.md

@@ -79,7 +79,7 @@ pip install modular-api[serve]
 ## Error handling
 
 ```python
-async def execute(self) -> None:
+async def execute(self) -> FoundUserOutput:
     user = await repository.find_by_id(self.input.user_id)
     if not user:
         raise UseCaseException(
@@ -87,7 +87,7 @@ async def execute(self) -> None:
             message="User not found",
             error_code="USER_NOT_FOUND",
         )
-    self._output = FoundUserOutput(name=user.name)
+    return FoundUserOutput(name=user.name)
 ```
 
 ---
@@ -95,13 +95,13 @@ async def execute(self) -> None:
 ## Testing
 
 ```python
-def test_hello_world():
+async def test_hello_world():
     usecase = HelloWorld(HelloInput(name="World"))
     error = usecase.validate()
     assert error is None
 
-    await usecase.execute()
-    assert usecase.output.message == "Hello, World!"
+    output = await usecase.execute()
+    assert output.message == "Hello, World!"
 ```
 
 See [doc/testing_guide.md](doc/testing_guide.md) for the full testing guide.

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macss-modular-api"
-version = "0.4.4"
+version = "0.4.6"
 description = "Use-case-centric toolkit for building modular APIs with Starlette. Define UseCase classes (input → validate → execute → output), connect them to HTTP routes, and expose OpenAPI documentation automatically."
 readme = "README.md"
 license = "MIT"
@@ -39,9 +39,9 @@ dev = [
 
 [project.urls]
 Homepage = "https://github.com/macss-dev/modular_api"
-Repository = "https://github.com/macss-dev/modular_api/tree/main/py"
+Repository = "https://github.com/macss-dev/modular_api/tree/main/code/py"
 Issues = "https://github.com/macss-dev/modular_api/issues"
-Documentation = "https://github.com/macss-dev/modular_api/tree/main/py#readme"
+Documentation = "https://github.com/macss-dev/modular_api/tree/main/code/py#readme"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6/src/macss_modular_api.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: macss-modular-api
-Version: 0.4.4
+Version: 0.4.6
 Summary: Use-case-centric toolkit for building modular APIs with Starlette. Define UseCase classes (input → validate → execute → output), connect them to HTTP routes, and expose OpenAPI documentation automatically.
 Author: ccisne.dev
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/macss-dev/modular_api
-Project-URL: Repository, https://github.com/macss-dev/modular_api/tree/main/py
+Project-URL: Repository, https://github.com/macss-dev/modular_api/tree/main/code/py
 Project-URL: Issues, https://github.com/macss-dev/modular_api/issues
-Project-URL: Documentation, https://github.com/macss-dev/modular_api/tree/main/py#readme
+Project-URL: Documentation, https://github.com/macss-dev/modular_api/tree/main/code/py#readme
 Keywords: api,usecase,openapi,starlette,modular,macss
 Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: AsyncIO
@@ -114,7 +114,7 @@ pip install modular-api[serve]
 ## Error handling
 
 ```python
-async def execute(self) -> None:
+async def execute(self) -> FoundUserOutput:
     user = await repository.find_by_id(self.input.user_id)
     if not user:
         raise UseCaseException(
@@ -122,7 +122,7 @@ async def execute(self) -> None:
             message="User not found",
             error_code="USER_NOT_FOUND",
         )
-    self._output = FoundUserOutput(name=user.name)
+    return FoundUserOutput(name=user.name)
 ```
 
 ---
@@ -130,13 +130,13 @@ async def execute(self) -> None:
 ## Testing
 
 ```python
-def test_hello_world():
+async def test_hello_world():
     usecase = HelloWorld(HelloInput(name="World"))
     error = usecase.validate()
     assert error is None
 
-    await usecase.execute()
-    assert usecase.output.message == "Hello, World!"
+    output = await usecase.execute()
+    assert output.message == "Hello, World!"
 ```
 
 See [doc/testing_guide.md](doc/testing_guide.md) for the full testing guide.

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/src/modular_api/core/modular_api.py

@@ -59,6 +59,7 @@ class ModularApi:
         title: str = "Modular API",
         version: str = "0.0.0",
         release_id: str | None = None,
+        servers: list[dict[str, str]] | None = None,
         metrics_enabled: bool = False,
         metrics_path: str = "/metrics",
         log_level: LogLevel = LogLevel.info,
@@ -67,6 +68,7 @@ class ModularApi:
         self._title = title
         self._version = version
         self._release_id = release_id or f"{version}-debug"
+        self._servers = servers
         self._metrics_enabled = metrics_enabled
         self._metrics_path = metrics_path
         self._log_level = log_level
@@ -188,6 +190,8 @@ class ModularApi:
 
         # OpenAPI endpoints
         spec_kwargs: dict[str, Any] = {"title": self._title, "port": port, "version": self._version}
+        if self._servers is not None:
+            spec_kwargs["servers"] = self._servers
         routes.append(Route("/openapi.json", endpoint=openapi_json_handler(**spec_kwargs)))
         routes.append(Route("/openapi.yaml", endpoint=openapi_yaml_handler(**spec_kwargs)))
 

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/src/modular_api/core/usecase.py

@@ -49,13 +49,15 @@ def _normalize_schema(raw: dict[str, Any]) -> dict[str, object]:
                 # Convert examples → example (nullable fields)
                 if "examples" in prop and prop["examples"]:
                     collapsed["example"] = prop["examples"][0]
+                collapsed.pop("additionalProperties", None)
                 normalized_props[name] = _reorder_type_first(collapsed)
                 if name in required:
                     required.remove(name)
                 continue
 
-        # Strip Pydantic's auto-generated ``title`` and ``default`` from properties
-        cleaned = {k: v for k, v in prop.items() if k not in ("title", "default")}
+        # Strip Pydantic's auto-generated ``title``, ``default``, and
+        # ``additionalProperties`` (emitted for dict[str, Any] fields) from properties.
+        cleaned = {k: v for k, v in prop.items() if k not in ("title", "default", "additionalProperties")}
 
         # Convert Pydantic ``examples`` (list, Draft 2020-12) → OpenAPI ``example`` (singular)
         if "examples" in cleaned and cleaned["examples"]:

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/src/modular_api/core/usecase_handler.py

@@ -8,7 +8,6 @@ the full use-case lifecycle: parse → validate → execute → respond.
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any, Callable
 
 from pydantic import ValidationError
@@ -114,7 +113,9 @@ def usecase_handler(factory: UseCaseFactory) -> Any:
             )
 
         except UseCaseException as exc:
-            print(f"UseCaseException: {exc}", file=sys.stderr)
+            logger = getattr(request.state, LOGGER_STATE_KEY, None)
+            if logger is not None:
+                logger.error("UseCaseException", fields={"error": str(exc), "status": exc.status_code})
             return Response(
                 content=json.dumps(exc.to_json()),
                 status_code=exc.status_code,
@@ -131,7 +132,9 @@ def usecase_handler(factory: UseCaseFactory) -> Any:
                 media_type=_JSON_CONTENT_TYPE,
             )
         except Exception as exc:
-            print(f"usecase_handler unexpected error: {exc}", file=sys.stderr)
+            logger = getattr(request.state, LOGGER_STATE_KEY, None)
+            if logger is not None:
+                logger.error("Unexpected error in use case handler", fields={"error": str(exc)})
             return Response(
                 content=json.dumps({"error": "Internal server error"}),
                 status_code=500,

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/src/modular_api/openapi/swagger_docs.py

@@ -5,7 +5,7 @@ system-aware dark mode.  The local ``/openapi.json`` endpoint provides
 the spec.  Styling, dark mode, and Swagger UI loading are handled
 entirely by docs-ui — no inline CSS or JS in this template.
 
-See: https://github.com/macss-dev/modular_api/tree/main/docs-ui
+See: https://github.com/macss-dev/modular_api/tree/main/code/docs-ui
 """
 
 from __future__ import annotations

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/tests/test_fromjson_validation.py

@@ -9,6 +9,7 @@ Error message contract (identical across all 3 SDKs for parity):
 """
 
 import json
+from typing import Any
 
 import pytest
 from pydantic import Field, ValidationError
@@ -120,3 +121,28 @@ class TestFromJsonHandlerErrors:
         assert resp.status_code == 200
         body = resp.json()
         assert body["greeting"] == "Hi Alice, age 25"
+
+
+# ── Unit: dict[str, Any] object type validation ──────────────────────────
+
+
+class ObjectInput(Input):
+    id: str = Field(description="ID")
+    details: dict[str, Any] = Field(description="Nested object")
+
+
+class TestFromJsonObjectType:
+    """Pydantic strict mode validates dict[str, Any] as object type."""
+
+    def test_accepts_dict_for_object_field(self) -> None:
+        result = ObjectInput.from_json({"id": "abc", "details": {"amount": 100}})
+        assert result.id == "abc"
+        assert result.details == {"amount": 100}
+
+    def test_rejects_string_for_object_field(self) -> None:
+        with pytest.raises(ValidationError):
+            ObjectInput.from_json({"id": "abc", "details": "not-a-dict"})
+
+    def test_rejects_list_for_object_field(self) -> None:
+        with pytest.raises(ValidationError):
+            ObjectInput.from_json({"id": "abc", "details": [1, 2]})

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/tests/test_modular_api.py

@@ -209,6 +209,53 @@ class TestAutoMountedEndpoints:
         assert "Test API" in response.text
 
 
+# ── Custom servers in OpenAPI spec ────────────────────────────
+
+
+class TestCustomServers:
+    """ModularApi propagates servers to the OpenAPI spec."""
+
+    def _build_client(self, **api_options: object) -> TestClient:
+        api = _make_api(**api_options)
+        api.module("test", lambda m: m.usecase("ping", _PingUseCase.from_json))
+        app = api.build()
+        return TestClient(app)
+
+    def test_uses_localhost_default_when_servers_not_provided(self) -> None:
+        client = self._build_client()
+        spec = client.get("/openapi.json").json()
+        assert len(spec["servers"]) == 1
+        assert "localhost" in spec["servers"][0]["url"]
+
+    def test_propagates_custom_servers_to_openapi_spec(self) -> None:
+        client = self._build_client(
+            servers=[{"url": "https://miapi.example.com", "description": "Production"}],
+        )
+        spec = client.get("/openapi.json").json()
+        assert len(spec["servers"]) == 1
+        assert spec["servers"][0]["url"] == "https://miapi.example.com"
+        assert spec["servers"][0]["description"] == "Production"
+
+    def test_supports_multiple_servers(self) -> None:
+        client = self._build_client(
+            servers=[
+                {"url": "https://prod.example.com", "description": "Production"},
+                {"url": "http://192.168.5.82:8080", "description": "LAN"},
+            ],
+        )
+        spec = client.get("/openapi.json").json()
+        assert len(spec["servers"]) == 2
+        assert spec["servers"][0]["url"] == "https://prod.example.com"
+        assert spec["servers"][1]["url"] == "http://192.168.5.82:8080"
+
+    def test_preserves_server_descriptions(self) -> None:
+        client = self._build_client(
+            servers=[{"url": "https://api.example.com", "description": "Main API"}],
+        )
+        spec = client.get("/openapi.json").json()
+        assert spec["servers"][0]["description"] == "Main API"
+
+
 # ── Step 2.9.3: Middleware pipeline order ─────────────────────
 
 

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/tests/test_schema_conformance.py

@@ -4,14 +4,19 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from typing import Any
 
 import sys
 
+from pydantic import Field
+
 _EXAMPLE_DIR = Path(__file__).resolve().parent.parent / "example"
 sys.path.insert(0, str(_EXAMPLE_DIR))
 
 from modules.greetings.usecases.hello_world import HelloWorldInput, HelloWorldOutput  # type: ignore[import-untyped]
 
+from modular_api.core.usecase import Input
+
 _FIXTURES = Path(__file__).resolve().parent.parent.parent / "tests" / "fixtures"
 
 
@@ -48,3 +53,16 @@ class TestSchemaConformance:
     def test_hello_output_to_json(self) -> None:
         instance = HelloWorldOutput(message="Hello!")
         assert instance.to_json() == {"message": "Hello!"}
+
+
+class WebhookInput(Input):
+    instruction_id: str = Field(description="Payment instruction ID", examples=["20260323ABC"])
+    transfer_details: dict[str, Any] = Field(description="Nested transfer info", examples=[{"amount": 2300, "currency": "PEN"}])
+
+
+class TestSchemaConformanceObjectType:
+    """Verify dict[str, Any] produces a schema identical to the shared fixture."""
+
+    def test_webhook_input_schema_matches_fixture(self) -> None:
+        fixture = _load_fixture("webhook_input_schema.json")
+        assert WebhookInput.to_schema() == fixture

{macss_modular_api-0.4.4 → macss_modular_api-0.4.6}/tests/test_usecase_handler.py

@@ -205,3 +205,80 @@ class TestUseCaseLifecycle:
         client = TestClient(app)
         client.post("/spy", json={})
         assert captured_loggers == ["fake-logger"]
+
+
+# ── Scoped-logger error integration (issue #7) ───────────────────────────
+
+
+class TestScopedLoggerInErrorPaths:
+    """Catch blocks must log through the request-scoped logger (with trace_id)
+    instead of printing to stderr."""
+
+    @staticmethod
+    def _build_app_with_logger(
+        factory,
+        log_lines: list[str],
+    ) -> Starlette:
+        """App with logging middleware capturing output into log_lines."""
+        from starlette.middleware import Middleware
+
+        from modular_api.core.logger.logging_middleware import logging_middleware
+        from modular_api.core.logger.logger import LogLevel
+
+        mw_cls = logging_middleware(
+            log_level=LogLevel.debug,
+            service_name="test-svc",
+            write_fn=lambda line: log_lines.append(line),
+        )
+        return Starlette(
+            routes=[Route("/test", usecase_handler(factory), methods=["POST"])],
+            middleware=[Middleware(mw_cls)],
+        )
+
+    def test_logs_use_case_exception_through_scoped_logger(self) -> None:
+        log_lines: list[str] = []
+        app = self._build_app_with_logger(FailingUseCase, log_lines)
+        client = TestClient(app, raise_server_exceptions=False)
+        resp = client.post(
+            "/test",
+            json={"name": "x"},
+            headers={"X-Request-ID": "trace-py-uce-001"},
+        )
+        assert resp.status_code == 409
+
+        error_logs = [
+            json.loads(l)
+            for l in log_lines
+            if '"level": "error"' in l and "UseCaseException" in l
+        ]
+        assert len(error_logs) > 0, "expected error log from scoped logger"
+        assert error_logs[0]["trace_id"] == "trace-py-uce-001"
+
+    def test_logs_unexpected_error_through_scoped_logger(self) -> None:
+        log_lines: list[str] = []
+        app = self._build_app_with_logger(CrashingUseCase, log_lines)
+        client = TestClient(app, raise_server_exceptions=False)
+        resp = client.post(
+            "/test",
+            json={"name": "x"},
+            headers={"X-Request-ID": "trace-py-crash-002"},
+        )
+        assert resp.status_code == 500
+
+        error_logs = [
+            json.loads(l)
+            for l in log_lines
+            if '"level": "error"' in l and "Unexpected error" in l
+        ]
+        assert len(error_logs) > 0, "expected error log from scoped logger"
+        assert error_logs[0]["trace_id"] == "trace-py-crash-002"
+
+    def test_does_not_throw_when_logger_unavailable(self) -> None:
+        """When no logging middleware is present, catch blocks must not crash."""
+        app = Starlette(
+            routes=[Route("/test", usecase_handler(FailingUseCase), methods=["POST"])],
+        )
+        client = TestClient(app, raise_server_exceptions=False)
+        resp = client.post("/test", json={"name": "x"})
+        assert resp.status_code == 409
+        assert resp.json()["message"] == "Already exists"