specx 0.0.0a1__py3-none-any.whl

specx/__init__.py

@@ -0,0 +1 @@
+

specx/_internal/__init__.py

@@ -0,0 +1 @@
+

specx/_internal/exceptions.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class BaseSpecxError(Exception):
+    """Base for package errors raised by Specx internals and testing APIs."""

specx/_internal/python_ast/__init__.py

@@ -0,0 +1 @@
+

specx/_internal/python_ast/scanner.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PythonSourceFile:
+    """Parsed Python file and its lightweight static metadata."""
+
+    path: Path
+    tree: ast.Module
+    imports: frozenset[str]
+    aliases: dict[str, str]
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PythonAstProject:
+    """Static Python source index for a project under inspection."""
+
+    files: dict[Path, PythonSourceFile]
+
+    def source_file(self, path: Path) -> PythonSourceFile:
+        return self.files[path]
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PythonAstScanner:
+    """Parse project Python files once so rules can share AST metadata."""
+
+    project_root: Path
+    excluded_patterns: tuple[str, ...] = ()
+
+    def scan(self, roots: tuple[Path, ...]) -> PythonAstProject:
+        files: dict[Path, PythonSourceFile] = {}
+        for root in roots:
+            if not root.exists():
+                continue
+            for path in sorted(root.rglob("*.py")):
+                if self._is_excluded(path):
+                    continue
+                text = path.read_text(encoding="utf-8")
+                tree = ast.parse(text, filename=str(path))
+                files[path] = PythonSourceFile(
+                    path=path,
+                    tree=tree,
+                    imports=_imports(tree),
+                    aliases=_import_aliases(tree),
+                )
+        return PythonAstProject(files=files)
+
+    def _is_excluded(self, path: Path) -> bool:
+        relative = path.relative_to(self.project_root).as_posix()
+        return any(fnmatch(relative, pattern) for pattern in self.excluded_patterns)
+
+
+def _imports(tree: ast.Module) -> frozenset[str]:
+    modules: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            modules.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            module_name = "." * node.level + (node.module or "")
+            if module_name:
+                modules.add(module_name)
+            separator = "" if module_name == "" or module_name.endswith(".") else "."
+            modules.update(
+                f"{module_name}{separator}{alias.name}" for alias in node.names if alias.name != "*"
+            )
+    return frozenset(modules)
+
+
+def _import_aliases(tree: ast.Module) -> dict[str, str]:
+    aliases: dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                aliases[alias.asname or alias.name.split(".")[0]] = alias.name.split(".")[-1]
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                aliases[alias.asname or alias.name] = alias.name
+    return aliases

specx/foundation/__init__.py

@@ -0,0 +1 @@
+

specx/foundation/capability.py

@@ -0,0 +1,9 @@
+class BaseCapability:
+    """Base for small injectable collaborators narrower than services.
+
+    Capabilities do one focused thing, may be injected or faked, and do not own
+    application workflows, unit-of-work scopes, repositories, or gateways.
+
+    Example:
+        SlugGeneratingCapability creates slugs for display labels.
+    """

specx/foundation/command.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+from specx.foundation.dto import BaseDTO
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BaseCommand(BaseDTO):
+    """Base for use-case inputs that request state-changing work.
+
+    Example:
+        from dataclasses import dataclass
+
+        @dataclass(frozen=True, kw_only=True, slots=True)
+        class CreateTaskCommand(BaseCommand):
+            title: str
+    """

specx/foundation/configurator.py

@@ -0,0 +1,8 @@
+class BaseConfigurator:
+    """Base for bootstrap objects that apply configuration to runtime systems.
+
+    Example:
+        class LoggingConfigurator(BaseConfigurator):
+            def configure(self) -> None:
+                return None
+    """

specx/foundation/delivery/__init__.py

@@ -0,0 +1 @@
+

specx/foundation/delivery/controller.py

@@ -0,0 +1,18 @@
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+RegistryT = TypeVar("RegistryT")
+
+
+class BaseController(ABC, Generic[RegistryT]):
+    """Base for delivery controllers that register public routes.
+
+    Example:
+        class TasksController(BaseController[APIRouter]):
+            def register(self, registry: APIRouter) -> None:
+                registry.add_api_route("/api/v1/tasks", self.list_tasks)
+    """
+
+    @abstractmethod
+    def register(self, registry: RegistryT) -> None:
+        raise NotImplementedError

specx/foundation/delivery/fastapi/__init__.py

@@ -0,0 +1 @@
+

specx/foundation/delivery/fastapi/schema.py

@@ -0,0 +1,15 @@
+from typing import ClassVar
+
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseFastAPISchema(BaseModel):
+    """Base for FastAPI request and response schemas.
+
+    Example:
+        class TaskResponseSchema(BaseFastAPISchema):
+            id: int
+            title: str
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", from_attributes=True)

specx/foundation/delivery/service.py

@@ -0,0 +1,8 @@
+class BaseDeliveryService:
+    """Base for delivery-only helper services such as auth or rate limiting.
+
+    Example:
+        class ApiKeyParsingService(BaseDeliveryService):
+            def parse(self, *, header: str) -> str:
+                return header.removeprefix("Bearer ")
+    """

specx/foundation/dto.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BaseDTO:
+    """Base for application payloads returned by core use cases.
+
+    Example:
+        from dataclasses import dataclass
+
+        @dataclass(frozen=True, kw_only=True, slots=True)
+        class TaskDTO(BaseDTO):
+            id: int
+            title: str
+    """

specx/foundation/effect_service.py

@@ -0,0 +1,12 @@
+class BaseEffectService:
+    """Base for helpers that perform or coordinate side effects.
+
+    Effect services may mutate owned state through an active unit of work passed
+    by a use case, or call outbound gateways with real side effects. They must
+    not open unit-of-work scopes or own transaction lifecycle.
+
+    Example:
+        class TaskCompletionService(BaseEffectService):
+            async def complete(self, *, task_id: int) -> TaskDTO:
+                return TaskDTO(id=task_id, title="Done")
+    """

specx/foundation/entity.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BaseEntity:
+    """Base for framework-free core state.
+
+    Example:
+        from dataclasses import dataclass
+
+        @dataclass(frozen=True, kw_only=True, slots=True)
+        class TaskEntity(BaseEntity):
+            id: int
+            title: str
+    """

specx/foundation/enums.py

@@ -0,0 +1,10 @@
+from enum import StrEnum
+
+
+class BaseStrEnum(StrEnum):
+    """Base for string enums used by settings and application values.
+
+    Example:
+        class EnvironmentEnum(BaseStrEnum):
+            LOCAL = "local"
+    """

specx/foundation/exceptions.py

@@ -0,0 +1,16 @@
+class BaseApplicationError(Exception):
+    """Base for application errors translated by delivery layers.
+
+    Example:
+        class TaskNotFoundError(BaseApplicationError):
+            task_id: int
+    """
+
+
+class BaseApplicationValueError(ValueError):
+    """Base for invalid application values rejected before persistence.
+
+    Example:
+        class InvalidTaskTitleValueError(BaseApplicationValueError):
+            title: str
+    """

specx/foundation/factory.py

@@ -0,0 +1,8 @@
+class BaseFactory:
+    """Base for classes that compose or create runtime objects.
+
+    Example:
+        class FastAPIFactory(BaseFactory):
+            def __call__(self) -> FastAPI:
+                return FastAPI()
+    """

specx/foundation/gateway.py

@@ -0,0 +1,9 @@
+class BaseGateway:
+    """Base for outbound business capability ports.
+
+    Gateways are core-facing interfaces to external systems. A gateway should
+    expose business language, not SDK, HTTP, queue, or vendor details.
+
+    Example:
+        EmailGateway sends transactional emails.
+    """

specx/foundation/infrastructure/__init__.py

@@ -0,0 +1 @@
+

specx/foundation/infrastructure/sqlalchemy/__init__.py

@@ -0,0 +1 @@
+

specx/foundation/infrastructure/sqlalchemy/model.py

@@ -0,0 +1,23 @@
+from typing import ClassVar
+
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+
+class BaseSQLAlchemyModel(DeclarativeBase):
+    """Base for SQLAlchemy declarative models.
+
+    Example:
+        class TaskModel(BaseSQLAlchemyModel):
+            __tablename__ = "tasks"
+    """
+
+    metadata: ClassVar[MetaData] = MetaData(
+        naming_convention={
+            "ix": "ix_%(column_0_label)s",
+            "uq": "uq_%(table_name)s_%(column_0_name)s",
+            "ck": "ck_%(table_name)s_%(constraint_name)s",
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+            "pk": "pk_%(table_name)s",
+        },
+    )

specx/foundation/pure_service.py

@@ -0,0 +1,12 @@
+class BasePureService:
+    """Base for deterministic business helpers.
+
+    Pure services do not perform I/O, use repositories, call gateways, or
+    depend on unit-of-work objects, settings, clocks, UUID generators, random
+    numbers, HTTP clients, SQLAlchemy, Redis, or SDKs.
+
+    Example:
+        class TaskTitleNormalizerService(BasePureService):
+            def normalize(self, *, title: str) -> str:
+                return " ".join(title.split())
+    """

specx/foundation/query.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+from specx.foundation.dto import BaseDTO
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BaseQuery(BaseDTO):
+    """Base for use-case inputs that request read-only results.
+
+    Example:
+        from dataclasses import dataclass
+
+        @dataclass(frozen=True, kw_only=True, slots=True)
+        class GetTaskQuery(BaseQuery):
+            task_id: int
+    """

specx/foundation/read_service.py

@@ -0,0 +1,12 @@
+class BaseReadService:
+    """Base for read-only orchestration helpers.
+
+    Read services may read from repositories or read gateways, usually through
+    an active unit of work passed by the caller. They may map entities to DTOs,
+    but must not commit, roll back, publish, send email, or call write APIs.
+
+    Example:
+        class TaskLookupService(BaseReadService):
+            async def get(self, *, task_id: int) -> TaskDTO:
+                return TaskDTO(id=task_id, title="Ship")
+    """

specx/foundation/repository.py

@@ -0,0 +1,8 @@
+class BaseRepository:
+    """Base for core repository ports and their infrastructure adapters.
+
+    Example:
+        class TaskRepository(BaseRepository):
+            async def get(self, *, task_id: int) -> TaskEntity | None:
+                return None
+    """

specx/foundation/settings.py

@@ -0,0 +1,17 @@
+from typing import ClassVar
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class BaseRuntimeSettings(BaseSettings):
+    """Base for runtime settings loaded from environment variables.
+
+    Example:
+        class DatabaseSettings(BaseRuntimeSettings):
+            database_url: str = "sqlite+aiosqlite:///./app.sqlite3"
+    """
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_file=".env",
+        extra="ignore",
+    )

specx/foundation/unit_of_work.py

@@ -0,0 +1,7 @@
+class BaseUnitOfWork:
+    """Base for active transaction objects exposed inside manager scopes.
+
+    Example:
+        async with manager as unit_of_work:
+            task = await unit_of_work.tasks.get(task_id=1)
+    """

specx/foundation/unit_of_work_manager.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from types import TracebackType
+from typing import Generic, Literal, TypeVar
+
+from specx.foundation.unit_of_work import BaseUnitOfWork
+
+UnitOfWorkT = TypeVar("UnitOfWorkT", bound=BaseUnitOfWork)
+
+
+class BaseUnitOfWorkManager(ABC, Generic[UnitOfWorkT]):
+    """Base for managers that open, finish, and close active units of work.
+
+    Example:
+        async with task_unit_of_work_manager as unit_of_work:
+            task = await unit_of_work.tasks.get(task_id=1)
+    """
+
+    @abstractmethod
+    async def __aenter__(self) -> UnitOfWorkT:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        raise NotImplementedError

specx/foundation/use_case.py

@@ -0,0 +1,8 @@
+class BaseUseCase:
+    """Base for externally meaningful application actions.
+
+    Example:
+        class CreateTaskUseCase(BaseUseCase):
+            async def execute(self, *, command: CreateTaskCommand) -> TaskDTO:
+                return TaskDTO(id=1, title=command.title)
+    """

specx/py.typed

@@ -0,0 +1 @@
+

specx/testing/__init__.py

@@ -0,0 +1 @@
+

specx/testing/architecture/__init__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from specx.testing.architecture.checker import assert_specx_architecture, check_specx_architecture
+from specx.testing.architecture.context import ArchitectureContext
+from specx.testing.architecture.models import (
+    RuleIdentifier,
+    SpecxArchitectureConfig,
+    SpecxArchitectureReport,
+    SpecxArchitectureViolation,
+    SpecxConfigurationError,
+)
+from specx.testing.architecture.registry import SpecxRuleRegistryError
+from specx.testing.architecture.rule import BaseRule
+from specx.testing.architecture.rule_id import SpecxRuleId
+
+__all__ = [
+    "ArchitectureContext",
+    "BaseRule",
+    "RuleIdentifier",
+    "SpecxArchitectureConfig",
+    "SpecxArchitectureReport",
+    "SpecxArchitectureViolation",
+    "SpecxConfigurationError",
+    "SpecxRuleId",
+    "SpecxRuleRegistryError",
+    "assert_specx_architecture",
+    "check_specx_architecture",
+]

specx/testing/architecture/checker.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from specx._internal.python_ast.scanner import PythonAstScanner
+from specx.testing.architecture.context import ArchitectureContext
+from specx.testing.architecture.models import (
+    SpecxArchitectureConfig,
+    SpecxArchitectureReport,
+    SpecxArchitectureViolation,
+)
+from specx.testing.architecture.registry import SpecxRuleRegistry
+
+
+def check_specx_architecture(config: SpecxArchitectureConfig) -> SpecxArchitectureReport:
+    """Run enabled Specx architecture rules and return a grouped report."""
+
+    scanner = PythonAstScanner(
+        project_root=config.project_root,
+        excluded_patterns=config.path_exclusions,
+    )
+    ast_project = scanner.scan(roots=(config.project_root / "src", config.project_root / "tests"))
+    context = ArchitectureContext(config=config, ast_project=ast_project)
+    registry = SpecxRuleRegistry.build(extra_rules=config.extra_rules)
+    violations: list[SpecxArchitectureViolation] = []
+
+    for rule_type in registry.enabled_rules(disabled_rules=config.disabled_rules):
+        rule = rule_type()
+        violations.extend(rule.check(context))
+
+    return SpecxArchitectureReport(
+        project_root=config.project_root,
+        violations=tuple(violations),
+    )
+
+
+def assert_specx_architecture(config: SpecxArchitectureConfig) -> None:
+    """Assert that a project satisfies every enabled Specx architecture rule."""
+
+    report = check_specx_architecture(config)
+    if report.has_violations:
+        raise AssertionError(report.format())