nexus-framework 0.2.1__tar.gz → 0.2.2__tar.gz

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexus-framework
-Version: 0.2.1
+Version: 0.2.2
 Summary: Ultimate Simplicity, Uncompromising Power. Next-Gen Python Framework for Web, Data, and AI.
 Project-URL: Homepage, https://github.com/nexus-framework/nexus
 Project-URL: Documentation, https://github.com/nexus-framework/nexus#readme

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/nexus/__init__.py

@@ -110,7 +110,7 @@ from nexus.web.template.engine import NXEngine
 from nexus.web.upload import UploadFile
 from nexus.web.websocket import WebSocket, WebSocketDisconnect, WebSocketGroup
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 __all__ = [
     "LLM",

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/nexus/cli.py

@@ -234,7 +234,7 @@ def _handle_db(
 NEXUS_BANNER_HELP = """
 ==============================================================================
                           NEXUS FRAMEWORK CLI
-         Ultimate Simplicity, Uncompromising Power (v0.2.1)
+         Ultimate Simplicity, Uncompromising Power (v0.2.2)
 ==============================================================================
 
 Usage:

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/nexus/core/entities/__init__.py

@@ -337,6 +337,11 @@ class Route:
     permissions: str | list[str] | tuple[str, ...] | None = None
     roles: str | list[str] | tuple[str, ...] | None = None
     cache: int | None = None
+    status_code: int | None = None
+    tags: list[str] | None = None
+    is_system: bool = False
+    override: bool = False
+    extra: dict[str, Any] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
         if self.roles is not None and self.auth is None:

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/nexus/web/app.py

@@ -22,7 +22,7 @@ if TYPE_CHECKING:
 
 
 from nexus.config.settings import NexusSettings, get_settings
-from nexus.core.entities import NexusRequest, NexusResponse
+from nexus.core.entities import HTTPMethod, NexusRequest, NexusResponse
 from nexus.core.exceptions import HTTPException, InternalServerError, NotFoundError
 from nexus.logging.logger import get_logger, setup_logging
 from nexus.web.asgi import (
@@ -189,7 +189,7 @@ class NexusApp:
     def _register_observability_routes(self) -> None:
         """Register built-in /metrics, /health, and /ready endpoints."""
 
-        @self.get("/metrics")
+        @self.get("/metrics", is_system=True)
         def prometheus_metrics() -> NexusResponse:
             """Expose Prometheus-formatted metrics."""
             text = self.metrics.render_prometheus_text()
@@ -199,7 +199,7 @@ class NexusApp:
                 content_type="text/plain; version=0.0.4; charset=utf-8",
             )
 
-        @self.get("/health")
+        @self.get("/health", is_system=True)
         async def liveness_probe() -> NexusResponse:
             """Component liveness probe for Kubernetes and load balancers."""
             healthy, details = await self.health_manager.check_liveness()
@@ -213,7 +213,7 @@ class NexusApp:
                 content_type="application/json",
             )
 
-        @self.get("/ready")
+        @self.get("/ready", is_system=True)
         async def readiness_probe() -> NexusResponse:
             """Readiness probe checking backing services (DB, Redis, etc.)."""
             ready, details = await self.health_manager.check_readiness()
@@ -232,12 +232,12 @@ class NexusApp:
         from nexus.core.entities import HTMLResponse, JSONResponse
         from nexus.web.openapi import get_redoc_html, get_swagger_ui_html
 
-        @self.get("/openapi.json")
+        @self.get("/openapi.json", is_system=True)
         def openapi_schema() -> NexusResponse:
             schema = self.openapi_generator.generate_schema(self.router)
             return JSONResponse(schema)
 
-        @self.get("/docs")
+        @self.get("/docs", is_system=True)
         def swagger_ui() -> NexusResponse:
             html = get_swagger_ui_html(
                 title=f"{self.title} - Swagger UI",
@@ -245,7 +245,7 @@ class NexusApp:
             )
             return HTMLResponse(html)
 
-        @self.get("/redoc")
+        @self.get("/redoc", is_system=True)
         def redoc_ui() -> NexusResponse:
             html = get_redoc_html(
                 title=f"{self.title} - ReDoc",
@@ -396,6 +396,35 @@ class NexusApp:
     # Level 1 (Magical): Route Registration Decorators
     # =========================================================================
 
+    def route(
+        self,
+        path: str,
+        methods: tuple[HTTPMethod, ...] = (HTTPMethod.GET,),
+        name: str | None = None,
+        summary: str | None = None,
+        auth: bool | str | list[str] | tuple[str, ...] | None = None,
+        permissions: str | list[str] | tuple[str, ...] | None = None,
+        roles: str | list[str] | tuple[str, ...] | None = None,
+        cache: int | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
+    ) -> Callable[[Any], Any]:
+        """Register a generic HTTP route handler."""
+        return self.router.route(
+            path,
+            methods=methods,
+            name=name,
+            summary=summary,
+            auth=auth,
+            permissions=permissions,
+            roles=roles,
+            cache=cache,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
+        )
+
     def get(
         self,
         path: str,
@@ -404,10 +433,21 @@ class NexusApp:
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
         cache: int | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Register a GET route handler with optional response caching."""
         return self.router.get(
-            path, name=name, auth=auth, permissions=permissions, roles=roles, cache=cache
+            path,
+            name=name,
+            auth=auth,
+            permissions=permissions,
+            roles=roles,
+            cache=cache,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def post(
@@ -417,9 +457,21 @@ class NexusApp:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Register a POST route handler."""
-        return self.router.post(path, name=name, auth=auth, permissions=permissions, roles=roles)
+        return self.router.post(
+            path,
+            name=name,
+            auth=auth,
+            permissions=permissions,
+            roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
+        )
 
     def put(
         self,
@@ -428,9 +480,21 @@ class NexusApp:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Register a PUT route handler."""
-        return self.router.put(path, name=name, auth=auth, permissions=permissions, roles=roles)
+        return self.router.put(
+            path,
+            name=name,
+            auth=auth,
+            permissions=permissions,
+            roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
+        )
 
     def patch(
         self,
@@ -439,9 +503,21 @@ class NexusApp:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Register a PATCH route handler."""
-        return self.router.patch(path, name=name, auth=auth, permissions=permissions, roles=roles)
+        return self.router.patch(
+            path,
+            name=name,
+            auth=auth,
+            permissions=permissions,
+            roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
+        )
 
     def delete(
         self,
@@ -450,9 +526,21 @@ class NexusApp:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Register a DELETE route handler."""
-        return self.router.delete(path, name=name, auth=auth, permissions=permissions, roles=roles)
+        return self.router.delete(
+            path,
+            name=name,
+            auth=auth,
+            permissions=permissions,
+            roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
+        )
 
     def include_blueprint(self, blueprint: Any, prefix: str = "") -> None:
         """Mount a Blueprint / RouteGroup into the application router."""
@@ -473,6 +561,9 @@ class NexusApp:
                     permissions=route.permissions,
                     roles=route.roles,
                     cache=route.cache,
+                    status_code=route.status_code,
+                    tags=route.tags,
+                    extra=route.extra,
                 )
                 self.router.add_route(routed)
             else:
@@ -640,7 +731,7 @@ class NexusApp:
         if inspect.isawaitable(result):
             result = await result
 
-        response = self._normalize_response(result)
+        response = self._normalize_response(result, default_status_code=route.status_code or 200)
 
         # Apply response caching & ETag computation
         if (
@@ -667,13 +758,13 @@ class NexusApp:
 
         return response
 
-    def _normalize_response(self, result: Any) -> NexusResponse:
+    def _normalize_response(self, result: Any, default_status_code: int = 200) -> NexusResponse:
         """Normalize handler return values into a NexusResponse."""
         if isinstance(result, NexusResponse):
             return result
 
         # Handle (data, status_code) tuple return
-        status_code = 200
+        status_code = default_status_code
         data = result
         if isinstance(result, tuple) and len(result) == 2 and isinstance(result[1], int):
             data, status_code = result

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/nexus/web/router.py

@@ -112,10 +112,14 @@ class Router:
                     current.children[part] = RadixNode(part)
                 current = current.children[part]
 
-        for r in self._all_routes[:-1]:
+        for r in list(self._all_routes[:-1]):
             if r.path == route.path:
                 for method in route.methods:
                     if method in r.methods:
+                        if getattr(r, "is_system", False) or getattr(route, "override", False):
+                            if r in self._all_routes:
+                                self._all_routes.remove(r)
+                            continue
                         msg = f"Duplicate route: [{method.value}] {route.path} already registered."
                         raise ValueError(msg)
 
@@ -132,10 +136,15 @@ class Router:
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
         cache: int | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Decorator to register a handler directly on this router."""
 
         def decorator(handler: Any) -> Any:
+            is_sys = bool(kwargs.pop("is_system", False))
+            is_ovr = bool(kwargs.pop("override", False))
             new_route = Route(
                 path=path,
                 methods=methods,
@@ -146,6 +155,11 @@ class Router:
                 permissions=permissions,
                 roles=roles,
                 cache=cache,
+                status_code=status_code,
+                tags=tags,
+                is_system=is_sys,
+                override=is_ovr,
+                extra=kwargs,
             )
             self.add_route(new_route)
             return handler
@@ -160,6 +174,9 @@ class Router:
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
         cache: int | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Decorator for GET routes."""
         return self.route(
@@ -170,6 +187,9 @@ class Router:
             permissions=permissions,
             roles=roles,
             cache=cache,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def post(
@@ -179,6 +199,9 @@ class Router:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Decorator for POST routes."""
         return self.route(
@@ -188,6 +211,9 @@ class Router:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def put(
@@ -197,6 +223,9 @@ class Router:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Decorator for PUT routes."""
         return self.route(
@@ -206,6 +235,9 @@ class Router:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def patch(
@@ -215,6 +247,9 @@ class Router:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Decorator for PATCH routes."""
         return self.route(
@@ -224,6 +259,9 @@ class Router:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def delete(
@@ -233,6 +271,9 @@ class Router:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         """Decorator for DELETE routes."""
         return self.route(
@@ -242,6 +283,9 @@ class Router:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def match(self, path: str, method: str) -> tuple[Route, dict[str, Any]] | None:
@@ -334,9 +378,29 @@ class Router:
 class Blueprint:
     """Modular Route Group with prefix and isolated/inherited routing rules."""
 
-    def __init__(self, prefix: str = "", name: str | None = None) -> None:
-        self.prefix = "/" + prefix.strip("/") if prefix else ""
-        self.name = name
+    def __init__(
+        self,
+        name_or_prefix: str = "",
+        prefix: str | None = None,
+        name: str | None = None,
+        auth: bool | str | list[str] | tuple[str, ...] | None = None,
+        permissions: str | list[str] | tuple[str, ...] | None = None,
+        roles: str | list[str] | tuple[str, ...] | None = None,
+    ) -> None:
+        if prefix is not None:
+            raw_prefix = prefix
+            self.name = name or (name_or_prefix if name_or_prefix != prefix else None)
+        elif name_or_prefix.startswith("/"):
+            raw_prefix = name_or_prefix
+            self.name = name
+        else:
+            raw_prefix = ""
+            self.name = name or (name_or_prefix if name_or_prefix else None)
+
+        self.prefix = "/" + raw_prefix.strip("/") if raw_prefix else ""
+        self.auth = auth
+        self.permissions = permissions
+        self.roles = roles
         self.routes: list[Route] = []
 
     def add_route(self, route: Route) -> None:
@@ -353,6 +417,9 @@ class Blueprint:
             permissions=route.permissions,
             roles=route.roles,
             cache=route.cache,
+            status_code=route.status_code,
+            tags=route.tags,
+            extra=route.extra,
         )
         self.routes.append(scoped_route)
 
@@ -366,8 +433,13 @@ class Blueprint:
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
         cache: int | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         def decorator(handler: Any) -> Any:
+            is_sys = bool(kwargs.pop("is_system", False))
+            is_ovr = bool(kwargs.pop("override", False))
             new_route = Route(
                 path=path,
                 methods=methods,
@@ -378,6 +450,11 @@ class Blueprint:
                 permissions=permissions,
                 roles=roles,
                 cache=cache,
+                status_code=status_code,
+                tags=tags,
+                is_system=is_sys,
+                override=is_ovr,
+                extra=kwargs,
             )
             self.add_route(new_route)
             return handler
@@ -392,6 +469,9 @@ class Blueprint:
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
         cache: int | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         return self.route(
             path,
@@ -401,6 +481,9 @@ class Blueprint:
             permissions=permissions,
             roles=roles,
             cache=cache,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def post(
@@ -410,6 +493,9 @@ class Blueprint:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         return self.route(
             path,
@@ -418,6 +504,9 @@ class Blueprint:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def put(
@@ -427,6 +516,9 @@ class Blueprint:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         return self.route(
             path,
@@ -435,6 +527,9 @@ class Blueprint:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def patch(
@@ -444,6 +539,9 @@ class Blueprint:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         return self.route(
             path,
@@ -452,6 +550,9 @@ class Blueprint:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )
 
     def delete(
@@ -461,6 +562,9 @@ class Blueprint:
         auth: bool | str | list[str] | tuple[str, ...] | None = None,
         permissions: str | list[str] | tuple[str, ...] | None = None,
         roles: str | list[str] | tuple[str, ...] | None = None,
+        status_code: int | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
     ) -> Callable[[Any], Any]:
         return self.route(
             path,
@@ -469,4 +573,7 @@ class Blueprint:
             auth=auth,
             permissions=permissions,
             roles=roles,
+            status_code=status_code,
+            tags=tags,
+            **kwargs,
         )

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/nexus/web/template/engine.py

@@ -25,12 +25,15 @@ class NXEngine:
 
     def __init__(
         self,
-        templates_dir: str | Path = "./templates",
+        templates_dir: str | Path | None = None,
         *,
+        template_dir: str | Path | None = None,
         auto_reload: bool = True,
         cache_size: int = 500,
     ) -> None:
-        self.templates_dir = Path(templates_dir).resolve()
+        target = templates_dir if templates_dir is not None else (template_dir or "./templates")
+        self.templates_dir = Path(target).resolve()
+        self.template_dir = self.templates_dir
         self.auto_reload = auto_reload
         self.cache_size = cache_size
 

{nexus_framework-0.2.1 → nexus_framework-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nexus-framework"
-version = "0.2.1"
+version = "0.2.2"
 description = "Ultimate Simplicity, Uncompromising Power. Next-Gen Python Framework for Web, Data, and AI."
 readme = "README.md"
 requires-python = ">=3.11"