fastapi-startkit 0.28.0__tar.gz → 0.30.0__tar.gz

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.28.0
+Version: 0.30.0
 Summary: Fastapi Starter kit components
 Author: Bedram Tamang
 Author-email: Bedram Tamang <tmgbedu@gmail.com>

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.28.0"
+version = "0.30.0"
 description = "Fastapi Starter kit components"
 authors = [
     {name = "Bedram Tamang", email = "tmgbedu@gmail.com"}
@@ -52,6 +52,7 @@ dev = [
     "dumpdie>=1.5.0",
     "pytest>=9.0.3",
     "pytest-asyncio>=1.3.0",
+    "pytest-cov>=6.0.0",
     "ruff>=0.9.0",
     "twine>=6.2.0",
     "itsdangerous>=2.2.0",
@@ -75,6 +76,30 @@ fixable = ["F401"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+norecursedirs = ["masoniteorm.backup", ".venv", "dist", "build", "__pycache__"]
+
+[tool.coverage.run]
+source = ["src/fastapi_startkit"]
+omit = [
+    "*/tests/*",
+    "*/migrations/*",
+    "*/__init__.py",
+    "*.pyi",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 50
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@abstractmethod",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"
 
 [build-system]
 requires = ["uv_build >= 0.10.10, <0.11.0"]

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/console/publish_command.py

@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING
 
 from fastapi_startkit.console import Command
 from cleo.helpers import option
-from fastapi_startkit.helpers.string import Str
+from fastapi_startkit.support import Str
 
 if TYPE_CHECKING:
     from fastapi_startkit.application import Application

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/facades/__init__.py

@@ -7,7 +7,6 @@ from .Url import Url
 from .Session import Session
 from .View import View
 from .Gate import Gate
-from .Auth import Auth
 from .Config import Config
 from .Loader import Loader
 from .Notification import Notification
@@ -16,4 +15,3 @@ from .Queue import Queue
 from .Cache import Cache
 from .RateLimiter import RateLimiter
 from .Broadcast import Broadcast
-from .Inertia import Inertia

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/loader/Loader.py

@@ -4,7 +4,6 @@ import inspect
 import pkgutil
 
 from ..exceptions import LoaderNotFound
-from ..utils.str import as_filepath
 from ..utils.structures import load
 
 
@@ -18,7 +17,7 @@ class Loader:
             files_or_directories = [files_or_directories]
 
         _modules = {}
-        module_paths = list(map(as_filepath, files_or_directories))
+        module_paths = list(map(lambda p: p.replace(".", "/"), files_or_directories))
         for module_loader, name, _ in pkgutil.iter_modules(module_paths):
             module = load(
                 f"{module_loader.path}/{name}.py",

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/logging/channels/DailyChannel.py

@@ -1,8 +1,9 @@
-from ..factory import DriverFactory
-from fastapi_startkit.facades import Config
-from fastapi_startkit.utils.filesystem import make_directory
 import os
+
+from fastapi_startkit.facades import Config
 from .BaseChannel import BaseChannel
+from ..factory import DriverFactory
+from ..file import make_directory
 
 
 class DailyChannel(BaseChannel):

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/logging/channels/SingleChannel.py

@@ -1,6 +1,6 @@
 from ..factory import DriverFactory
 from fastapi_startkit.facades import Config
-from fastapi_startkit.utils.filesystem import make_directory
+from ..file import make_directory
 from .BaseChannel import BaseChannel
 
 

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/logging/channels/SyslogChannel.py

@@ -1,6 +1,6 @@
 from ..factory import DriverFactory
 from fastapi_startkit.facades import Config
-from fastapi_startkit.utils.filesystem import make_directory
+from ..file import make_directory
 from .BaseChannel import BaseChannel
 
 

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/logging/drivers/LogTerminalDriver.py

@@ -1,8 +1,18 @@
-# from logging import Logger
+from .BaseDriver import BaseDriver
 
-from fastapi_startkit.utils.console import HasColoredOutput
 
-from .BaseDriver import BaseDriver
+class HasColoredOutput:
+    def success(self, message):
+        print("\033[92m {0} \033[0m".format(message))
+
+    def warning(self, message):
+        print("\033[93m {0} \033[0m".format(message))
+
+    def danger(self, message):
+        print("\033[91m {0} \033[0m".format(message))
+
+    def info(self, message):
+        return self.success(message)
 
 
 class LogTerminalDriver(BaseDriver, HasColoredOutput):

fastapi_startkit-0.30.0/src/fastapi_startkit/logging/file.py

@@ -0,0 +1,13 @@
+import os
+
+
+def make_directory(directory):
+    """Create a directory at the given path for a file if it does not exist"""
+    if not os.path.isfile(directory):
+        if not os.path.exists(os.path.dirname(directory)):
+            # Create the path to the model if it does not exist
+            os.makedirs(os.path.dirname(directory))
+
+        return True
+
+    return False

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/masoniteorm/collection/Collection.py

@@ -1,4 +1,4 @@
-from fastapi_startkit.collection import Collection as BaseCollection
+from fastapi_startkit.support.collection import Collection as BaseCollection
 
 
 class Collection(BaseCollection):

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/masoniteorm/commands/MakeMigrationCommand.py

@@ -3,7 +3,7 @@ import os
 import pathlib
 from inflection import tableize
 from cleo.helpers import argument, option
-from fastapi_startkit.helpers.string import Str
+from fastapi_startkit.support import Str
 from fastapi_startkit.console import Command
 
 

{fastapi_startkit-0.28.0 → fastapi_startkit-0.30.0}/src/fastapi_startkit/masoniteorm/models/model.py

@@ -91,6 +91,110 @@ class Model(Attribute, Relationship, ObservesEvents):
     def with_(cls, *eagers) -> "QueryBuilder":
         return cls.query().with_(*eagers)
 
+    @classmethod
+    def where(cls, column, *args) -> "QueryBuilder":
+        return cls.query().where(column, *args)
+
+    @classmethod
+    def or_where(cls, column, *args) -> "QueryBuilder":
+        return cls.query().or_where(column, *args)
+
+    @classmethod
+    def where_null(cls, column: str) -> "QueryBuilder":
+        return cls.query().where_null(column)
+
+    @classmethod
+    def where_not_null(cls, column: str) -> "QueryBuilder":
+        return cls.query().where_not_null(column)
+
+    @classmethod
+    def where_in(cls, column: str, values) -> "QueryBuilder":
+        return cls.query().where_in(column, values)
+
+    @classmethod
+    def where_not_in(cls, column: str, values) -> "QueryBuilder":
+        return cls.query().where_not_in(column, values)
+
+    @classmethod
+    def select(cls, *args) -> "QueryBuilder":
+        return cls.query().select(*args)
+
+    @classmethod
+    def limit(cls, limit: int) -> "QueryBuilder":
+        return cls.query().limit(limit)
+
+    @classmethod
+    def offset(cls, offset: int) -> "QueryBuilder":
+        return cls.query().offset(offset)
+
+    @classmethod
+    def order_by(cls, column: str, direction: str = "asc") -> "QueryBuilder":
+        return cls.query().order_by(column, direction)
+
+    @classmethod
+    def order_by_raw(cls, expression: str) -> "QueryBuilder":
+        return cls.query().order_by_raw(expression)
+
+    @classmethod
+    def latest(cls, column: str = "created_at") -> "QueryBuilder":
+        return cls.query().latest(column)
+
+    @classmethod
+    def oldest(cls, column: str = "created_at") -> "QueryBuilder":
+        return cls.query().oldest(column)
+
+    @classmethod
+    def group_by(cls, column: str) -> "QueryBuilder":
+        return cls.query().group_by(column)
+
+    @classmethod
+    def group_by_raw(cls, expression: str) -> "QueryBuilder":
+        return cls.query().group_by_raw(expression)
+
+    @classmethod
+    def having(cls, column: str, equality: str, value) -> "QueryBuilder":
+        return cls.query().having(column, equality, value)
+
+    @classmethod
+    def between(cls, column: str, low, high) -> "QueryBuilder":
+        return cls.query().between(column, low, high)
+
+    @classmethod
+    def not_between(cls, column: str, low, high) -> "QueryBuilder":
+        return cls.query().not_between(column, low, high)
+
+    @classmethod
+    def distinct(cls) -> "QueryBuilder":
+        return cls.query().distinct()
+
+    @classmethod
+    def join(cls, table: str, column1: str, equality: str, column2: str, clause: str = "join") -> "QueryBuilder":
+        return cls.query().join(table, column1, equality, column2, clause)
+
+    @classmethod
+    def left_join(cls, table: str, column1: str, equality: str, column2: str) -> "QueryBuilder":
+        return cls.query().left_join(table, column1, equality, column2)
+
+    @classmethod
+    def right_join(cls, table: str, column1: str, equality: str, column2: str) -> "QueryBuilder":
+        return cls.query().right_join(table, column1, equality, column2)
+
+    @classmethod
+    def where_column(cls, column1: str, column2: str) -> "QueryBuilder":
+        return cls.query().where_column(column1, column2)
+
+    @classmethod
+    def when(cls, condition, callback) -> "QueryBuilder":
+        return cls.query().when(condition, callback)
+
+    @classmethod
+    def where_exists(cls, builder: "QueryBuilder") -> "QueryBuilder":
+        return cls.query().where_exists(builder)
+
+    @classmethod
+    def or_where_exists(cls, builder: "QueryBuilder") -> "QueryBuilder":
+        return cls.query().or_where_exists(builder)
+
     @classmethod
     def where_has(cls, relation: str, callback=None) -> "QueryBuilder":
         return cls.query().where_has(relation, callback)

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/__init__.py

@@ -0,0 +1,25 @@
+"""FastAPI Startkit MCP module.
+
+Provides class-based building blocks for Model Context Protocol (MCP) servers
+that can be mounted directly on any FastAPI application.
+"""
+
+from .argument import Argument
+from .prompt import Prompt
+from .request import JsonRpcRequest
+from .resource import Resource
+from .response import Response
+from .server import Server
+from .tool import Tool
+from .providers.mcp_provider import McpProvider
+
+__all__ = [
+    "Argument",
+    "JsonRpcRequest",
+    "McpProvider",
+    "Prompt",
+    "Resource",
+    "Response",
+    "Server",
+    "Tool",
+]

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/argument.py

@@ -0,0 +1,20 @@
+"""Argument dataclass for MCP prompt arguments."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Argument:
+    """Represents a single argument accepted by a Prompt."""
+
+    name: str
+    description: Optional[str] = field(default=None)
+    required: bool = field(default=False)
+
+    def to_json(self) -> dict:
+        """Serialise to MCP-compatible JSON."""
+        data: dict = {"name": self.name, "required": self.required}
+        if self.description is not None:
+            data["description"] = self.description
+        return data

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/prompt.py

@@ -0,0 +1,45 @@
+"""Abstract base class for MCP prompts."""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from .argument import Argument
+from .response import Response
+
+
+class Prompt(ABC):
+    """Base class for MCP prompts.
+
+    Subclasses must set ``name`` and implement ``handle()``.
+    Override ``arguments()`` to declare accepted arguments.
+    Override ``should_register()`` to conditionally skip registration.
+    """
+
+    name: str
+    description: Optional[str] = None
+    title: Optional[str] = None
+
+    def arguments(self) -> list[Argument]:
+        """Return the list of arguments this prompt accepts."""
+        return []
+
+    def should_register(self) -> bool:
+        """Return False to prevent this prompt from being registered."""
+        return True
+
+    @abstractmethod
+    async def handle(self, arguments: dict) -> Response:
+        """Render the prompt with the given arguments and return a Response."""
+        raise NotImplementedError
+
+    def to_json(self) -> dict:
+        """Serialise to the MCP prompts/list format."""
+        data: dict = {"name": self.name}
+        if self.description is not None:
+            data["description"] = self.description
+        if self.title is not None:
+            data["title"] = self.title
+        args = self.arguments()
+        if args:
+            data["arguments"] = [arg.to_json() for arg in args]
+        return data

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/protocol.py

@@ -0,0 +1,143 @@
+"""Internal JSON-RPC 2.0 dispatcher for MCP."""
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .server import Server
+
+
+MCP_PROTOCOL_VERSION = "2024-11-05"
+
+
+class Protocol:
+    """Dispatches JSON-RPC 2.0 method calls to MCP handlers.
+
+    Handles the following methods:
+    - initialize
+    - tools/list
+    - tools/call
+    - prompts/list
+    - prompts/get
+    - resources/list
+    - resources/read
+    """
+
+    def __init__(self, server: "Server") -> None:
+        self._server = server
+
+    # ------------------------------------------------------------------
+    # Public dispatch entry point
+    # ------------------------------------------------------------------
+
+    async def dispatch(self, method: str, params: Optional[dict], request_id: Any) -> dict:
+        """Dispatch a JSON-RPC method and return a full JSON-RPC response dict."""
+        handler = {
+            "initialize": self._initialize,
+            "tools/list": self._tools_list,
+            "tools/call": self._tools_call,
+            "prompts/list": self._prompts_list,
+            "prompts/get": self._prompts_get,
+            "resources/list": self._resources_list,
+            "resources/read": self._resources_read,
+        }.get(method)
+
+        if handler is None:
+            return self._error(request_id, -32601, f"Method not found: {method}")
+
+        try:
+            result = await handler(params or {})
+            return {"jsonrpc": "2.0", "id": request_id, "result": result}
+        except Exception as exc:  # pragma: no cover
+            return self._error(request_id, -32000, str(exc))
+
+    # ------------------------------------------------------------------
+    # Handlers
+    # ------------------------------------------------------------------
+
+    async def _initialize(self, params: dict) -> dict:
+        server = self._server
+        result: dict = {
+            "protocolVersion": MCP_PROTOCOL_VERSION,
+            "serverInfo": {"name": server.name, "version": "1.0"},
+            "capabilities": {
+                "tools": {"listChanged": False},
+                "prompts": {"listChanged": False},
+                "resources": {"listChanged": False},
+            },
+        }
+        if getattr(server, "description", None):
+            result["description"] = server.description
+        if getattr(server, "instructions", None):
+            result["instructions"] = server.instructions
+        return result
+
+    async def _tools_list(self, params: dict) -> dict:
+        tools = self._server.tools() or []
+        return {"tools": [t().to_json() for t in tools]}
+
+    async def _tools_call(self, params: dict) -> dict:
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        tools = self._server.tools() or []
+        for tool_cls in tools:
+            tool = tool_cls()
+            if tool.name == name:
+                response = await tool.handle(arguments)
+                return {"content": response.to_content()}
+        return self._error_result(-32602, f"Tool not found: {name}")
+
+    async def _prompts_list(self, params: dict) -> dict:
+        prompts = self._server.prompts() or []
+        registered = [p().to_json() for p in prompts if p().should_register()]
+        return {"prompts": registered}
+
+    async def _prompts_get(self, params: dict) -> dict:
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        prompts = self._server.prompts() or []
+        for prompt_cls in prompts:
+            prompt = prompt_cls()
+            if prompt.name == name and prompt.should_register():
+                response = await prompt.handle(arguments)
+                messages = [{"role": "user", "content": item} for item in response.to_content()]
+                return {"messages": messages}
+        return self._error_result(-32602, f"Prompt not found: {name}")
+
+    async def _resources_list(self, params: dict) -> dict:
+        resources = self._server.resources() or []
+        return {"resources": [r().to_json() for r in resources]}
+
+    async def _resources_read(self, params: dict) -> dict:
+        uri = params.get("uri")
+        resources = self._server.resources() or []
+        for resource_cls in resources:
+            resource = resource_cls()
+            if resource.uri == uri:
+                content = await resource.read()
+                return {
+                    "contents": [
+                        {
+                            "uri": resource.uri,
+                            "mimeType": resource.mime_type,
+                            "text": content,
+                        }
+                    ]
+                }
+        return self._error_result(-32602, f"Resource not found: {uri}")
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _error(request_id: Any, code: int, message: str) -> dict:
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "error": {"code": code, "message": message},
+        }
+
+    @staticmethod
+    def _error_result(code: int, message: str) -> dict:
+        """Return an error payload as a *result* (for tool/prompt/resource not found)."""
+        return {"error": {"code": code, "message": message}}

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/providers/mcp_provider.py

@@ -0,0 +1,19 @@
+from fastapi_startkit.providers import Provider
+
+
+class McpProvider(Provider):
+    """Provider that bootstraps the MCP component for fastapi-startkit.
+
+    Register it alongside ``FastAPIProvider`` to make MCP available in
+    your application::
+
+        app = Application(providers=[FastAPIProvider, McpProvider])
+    """
+
+    provider_key = "mcp"
+
+    def register(self) -> None:
+        """Register MCP bindings into the container."""
+
+    def boot(self) -> None:
+        """Boot the MCP component."""

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/request.py

@@ -0,0 +1,19 @@
+"""JSON-RPC 2.0 request model."""
+
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel
+
+
+class JsonRpcRequest(BaseModel):
+    """Represents a JSON-RPC 2.0 request or notification."""
+
+    jsonrpc: str = "2.0"
+    method: str
+    params: Optional[dict[str, Any]] = None
+    id: Optional[Union[str, int]] = None
+
+    @property
+    def is_notification(self) -> bool:
+        """Return True when the request has no id (i.e. it is a notification)."""
+        return self.id is None

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/resource.py

@@ -0,0 +1,32 @@
+"""Abstract base class for MCP resources."""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class Resource(ABC):
+    """Base class for MCP resources.
+
+    Subclasses must set ``uri`` and ``name``, and implement ``read()``.
+    """
+
+    uri: str
+    name: str
+    description: Optional[str] = None
+    mime_type: str = "text/plain"
+
+    @abstractmethod
+    async def read(self, **kwargs) -> str:
+        """Return the resource content as a string."""
+        raise NotImplementedError
+
+    def to_json(self) -> dict:
+        """Serialise to the MCP resources/list format."""
+        data: dict = {
+            "uri": self.uri,
+            "name": self.name,
+            "mimeType": self.mime_type,
+        }
+        if self.description is not None:
+            data["description"] = self.description
+        return data

fastapi_startkit-0.30.0/src/fastapi_startkit/mcp/response.py

@@ -0,0 +1,30 @@
+"""Response wrapper for MCP tool and prompt outputs."""
+
+import json
+from typing import Any
+
+
+class Response:
+    """Wraps tool/prompt output into MCP content format."""
+
+    def __init__(self, content: list[dict]) -> None:
+        self._content = content
+
+    @classmethod
+    def text(cls, value: str) -> "Response":
+        """Create a plain-text response."""
+        return cls([{"type": "text", "text": value}])
+
+    @classmethod
+    def structure(cls, data: dict[str, Any]) -> "Response":
+        """Create a structured (resource-type) response."""
+        return cls([{"type": "resource", "resource": {"text": json.dumps(data), "mimeType": "application/json"}}])
+
+    @classmethod
+    def empty(cls) -> "Response":
+        """Create an empty response with no content."""
+        return cls([])
+
+    def to_content(self) -> list[dict]:
+        """Return the raw content list."""
+        return self._content