pyferox 0.0.1__tar.gz

pyferox-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PyFerOx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyferox-0.0.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: pyferox
+Version: 0.0.1
+Summary: Transport-agnostic, async-first modular service application framework.
+Author: PyFerOx Maintainers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pablo0723/pyferox
+Project-URL: Repository, https://github.com/pablo0723/pyferox
+Project-URL: Issues, https://github.com/pablo0723/pyferox/issues
+Keywords: framework,service,cqrs,event-driven,async,backend
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anyio>=4.4.0
+Requires-Dist: msgspec>=0.20.0
+Requires-Dist: sqlalchemy>=2.0.30
+Provides-Extra: dev
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: aiosqlite>=0.20.0; extra == "dev"
+Provides-Extra: http
+Requires-Dist: uvicorn>=0.30.0; extra == "http"
+Dynamic: license-file
+
+# PyFerOx
+
+Transport-agnostic, async-first Python service framework built around:
+
+- typed command/query/event contracts
+- modular composition
+- execution middleware + lifecycle hooks
+- pluggable transports (HTTP, jobs/worker, RPC, scheduler)
+
+## Project Status
+
+Phase 1-3 implementation is complete according to repository audits:
+
+- [Phase 1 audit](phase1_audit.md)
+- [Phase 2 audit](phase2_audit.md)
+- [Phase 3 audit](phase3_audit.md)
+
+## Documentation
+
+Full user docs are in [`docs/`](docs/README.md).
+
+Recommended start:
+
+1. [Quickstart](docs/quickstart.md)
+2. [Core Concepts](docs/core-concepts.md)
+3. [HTTP, Auth, OpenAPI](docs/http-auth-openapi.md)
+4. [Persistence (SQLAlchemy)](docs/persistence-sqlalchemy.md)
+5. [Background and Distributed Runtime](docs/background-and-distributed-runtime.md)
+6. [Testing](docs/testing.md)
+7. [Configuration](docs/configuration.md)
+8. [CLI Reference](docs/cli.md)
+9. [Operations and Tuning](docs/operations-and-tuning.md)
+
+## Install
+
+```bash
+pip install -e ".[dev,http]"
+```
+
+## Minimal Example
+
+```python
+from pyferox import App, HTTPAdapter, Module, StructCommand, StructQuery, handle, singleton
+
+
+class UserRepo:
+    async def create(self, email: str, name: str) -> int:
+        return 1
+
+    async def get(self, user_id: int) -> dict[str, str]:
+        return {"id": str(user_id), "email": "user@example.com", "name": "User"}
+
+
+class CreateUser(StructCommand):
+    email: str
+    name: str
+
+
+class GetUser(StructQuery):
+    user_id: int
+
+
+@handle(CreateUser)
+async def create_user(cmd: CreateUser, users: UserRepo) -> dict[str, int]:
+    return {"id": await users.create(cmd.email, cmd.name)}
+
+
+@handle(GetUser)
+async def get_user(query: GetUser, users: UserRepo) -> dict[str, str]:
+    return await users.get(query.user_id)
+
+
+app = App(modules=[Module(handlers=[create_user, get_user], providers=[singleton(UserRepo())])])
+http = HTTPAdapter(app)
+http.command("POST", "/users", CreateUser, status_code=201)
+http.query("GET", "/users/{user_id}", GetUser)
+```
+
+PyFerOx is msgspec-backed. For new transport-facing contracts, prefer `StructCommand` / `StructQuery` / `StructEvent`. Dataclass contracts are still supported, but they are not the primary style to teach in user-facing examples.
+
+Run:
+
+```bash
+uvicorn app.main:http --reload
+```
+
+Or scaffold first:
+
+```bash
+pyferox create-project demo_service --template api
+cd demo_service
+pyferox run-dev --target app.main:http
+```

pyferox-0.0.1/README.md

@@ -0,0 +1,93 @@
+# PyFerOx
+
+Transport-agnostic, async-first Python service framework built around:
+
+- typed command/query/event contracts
+- modular composition
+- execution middleware + lifecycle hooks
+- pluggable transports (HTTP, jobs/worker, RPC, scheduler)
+
+## Project Status
+
+Phase 1-3 implementation is complete according to repository audits:
+
+- [Phase 1 audit](phase1_audit.md)
+- [Phase 2 audit](phase2_audit.md)
+- [Phase 3 audit](phase3_audit.md)
+
+## Documentation
+
+Full user docs are in [`docs/`](docs/README.md).
+
+Recommended start:
+
+1. [Quickstart](docs/quickstart.md)
+2. [Core Concepts](docs/core-concepts.md)
+3. [HTTP, Auth, OpenAPI](docs/http-auth-openapi.md)
+4. [Persistence (SQLAlchemy)](docs/persistence-sqlalchemy.md)
+5. [Background and Distributed Runtime](docs/background-and-distributed-runtime.md)
+6. [Testing](docs/testing.md)
+7. [Configuration](docs/configuration.md)
+8. [CLI Reference](docs/cli.md)
+9. [Operations and Tuning](docs/operations-and-tuning.md)
+
+## Install
+
+```bash
+pip install -e ".[dev,http]"
+```
+
+## Minimal Example
+
+```python
+from pyferox import App, HTTPAdapter, Module, StructCommand, StructQuery, handle, singleton
+
+
+class UserRepo:
+    async def create(self, email: str, name: str) -> int:
+        return 1
+
+    async def get(self, user_id: int) -> dict[str, str]:
+        return {"id": str(user_id), "email": "user@example.com", "name": "User"}
+
+
+class CreateUser(StructCommand):
+    email: str
+    name: str
+
+
+class GetUser(StructQuery):
+    user_id: int
+
+
+@handle(CreateUser)
+async def create_user(cmd: CreateUser, users: UserRepo) -> dict[str, int]:
+    return {"id": await users.create(cmd.email, cmd.name)}
+
+
+@handle(GetUser)
+async def get_user(query: GetUser, users: UserRepo) -> dict[str, str]:
+    return await users.get(query.user_id)
+
+
+app = App(modules=[Module(handlers=[create_user, get_user], providers=[singleton(UserRepo())])])
+http = HTTPAdapter(app)
+http.command("POST", "/users", CreateUser, status_code=201)
+http.query("GET", "/users/{user_id}", GetUser)
+```
+
+PyFerOx is msgspec-backed. For new transport-facing contracts, prefer `StructCommand` / `StructQuery` / `StructEvent`. Dataclass contracts are still supported, but they are not the primary style to teach in user-facing examples.
+
+Run:
+
+```bash
+uvicorn app.main:http --reload
+```
+
+Or scaffold first:
+
+```bash
+pyferox create-project demo_service --template api
+cd demo_service
+pyferox run-dev --target app.main:http
+```

pyferox-0.0.1/pyferox/__init__.py

@@ -0,0 +1,363 @@
+"""PyFerOx service framework public API."""
+
+# Package namespaces (discoverable grouped imports)
+from pyferox import (
+    auth,
+    cache,
+    config,
+    core,
+    db,
+    events,
+    http,
+    jobs,
+    ops,
+    reliability,
+    rpc,
+    schema,
+    scheduler,
+    testing,
+    workflow,
+)
+
+# Core runtime and composition
+from pyferox.core import (
+    App,
+    AppState,
+    ExecutionContext,
+    LifecycleManager,
+    Module,
+    ModuleDefinition,
+    ProviderRegistry,
+    TransportRegistry,
+    module_diagnostics,
+)
+
+# Messaging and handler contracts
+from pyferox.core import (
+    Command,
+    Event,
+    ListQuery,
+    Message,
+    PageParams,
+    Query,
+    StructCommand,
+    StructEvent,
+    StructQuery,
+    SortDirection,
+    SortField,
+    build_page_params,
+    contract,
+    get_contract_metadata,
+    parse_sort,
+)
+
+# Dispatch, middleware, dependency injection
+from pyferox.core import (
+    Dispatcher,
+    ExceptionHook,
+    Middleware,
+    ResolutionError,
+    Scope,
+    SyncPolicy,
+    handle,
+    listen,
+    provider,
+    singleton,
+)
+
+# Results, errors, transport mapping
+from pyferox.core import (
+    AuthError,
+    ConflictError,
+    DomainError,
+    Empty,
+    ForbiddenError,
+    FrameworkError,
+    HandlerNotFoundError,
+    InfrastructureError,
+    NotFoundError,
+    Paginated,
+    PermissionDeniedError,
+    PyFerOxError,
+    Response,
+    RouteConflictError,
+    Streamed,
+    Success,
+    UnauthorizedError,
+    ValidationError,
+    map_exception_to_transport,
+    normalize_execution_exception,
+    to_payload,
+)
+
+# HTTP transport
+from pyferox.http import HTTPAdapter
+
+# Schema layer
+from pyferox.schema import (
+    DTO,
+    Schema,
+    SchemaModel,
+    TypedSchema,
+    format_validation_error,
+    get_schema_metadata,
+    parse_input,
+    schema_metadata,
+    serialize_output,
+)
+
+# Auth contracts and implementations
+from pyferox.auth import (
+    AccessToken,
+    AuthBackend,
+    Identity,
+    InMemorySessionStore,
+    PermissionChecker,
+    Principal,
+    Session,
+    SessionAuthBackend,
+    SessionStore,
+    requires,
+)
+
+# Jobs runtime
+from pyferox.jobs import (
+    InMemoryJobQueue,
+    Job,
+    JobDispatcher,
+    JobExecutionResult,
+    JobQueue,
+    JobStatus,
+    LocalJobWorker,
+    StructJob,
+    WorkerRuntime,
+    create_worker_runtime,
+)
+
+# Cache abstractions
+from pyferox.cache import Cache, InMemoryCache
+
+# Phase 3 distributed runtime
+from pyferox.events import (
+    DistributedEventBus,
+    EventBroker,
+    EventDispatchResult,
+    EventEnvelope,
+    EventResultStatus,
+    InMemoryEventBroker,
+    LocalEventBus,
+    event_metadata,
+)
+from pyferox.ops import (
+    CheckStatus,
+    HealthCheckResult,
+    HealthRegistry,
+    HealthReport,
+    InMemoryTraceCollector,
+    TraceCollector,
+    TraceSpan,
+    TracingMiddleware,
+)
+from pyferox.reliability import (
+    IdempotencyStore,
+    InMemoryIdempotencyStore,
+    RetryClassifier,
+    RetryDecision,
+    RetryDisposition,
+    RetryPolicy,
+    default_retry_classifier,
+)
+from pyferox.rpc import InMemoryRPCTransport, RPCClient, RPCError, RPCRequest, RPCResponse, RPCServer, RPCTransport
+from pyferox.scheduler import ScheduleRunResult, ScheduleResultStatus, ScheduledTask, SchedulerRuntime
+from pyferox.workflow import Workflow, WorkflowContext, WorkflowExecutionResult, WorkflowStatus, WorkflowStep
+
+# DB persistence and migrations
+from pyferox.db import (
+    DBSessionMiddleware,
+    MigrationResult,
+    Repository,
+    SQLAlchemySettings,
+    UnitOfWork,
+    migration_current,
+    migration_downgrade,
+    migration_init,
+    migration_revision,
+    migration_upgrade,
+    run_alembic,
+    sqlalchemy_module,
+)
+
+# Testing helpers
+from pyferox.testing import FakeDispatcher, TestHTTPClient, create_test_app, create_test_module, override_dependencies
+
+__all__ = [
+    # Namespaces
+    "auth",
+    "cache",
+    "config",
+    "core",
+    "db",
+    "events",
+    "http",
+    "jobs",
+    "ops",
+    "reliability",
+    "rpc",
+    "schema",
+    "scheduler",
+    "testing",
+    "workflow",
+    # Core runtime
+    "App",
+    "AppState",
+    "ExecutionContext",
+    "LifecycleManager",
+    "Module",
+    "ModuleDefinition",
+    "ProviderRegistry",
+    "TransportRegistry",
+    "module_diagnostics",
+    # Contracts
+    "Command",
+    "Event",
+    "ListQuery",
+    "Message",
+    "PageParams",
+    "Query",
+    "StructCommand",
+    "StructEvent",
+    "StructQuery",
+    "SortDirection",
+    "SortField",
+    "build_page_params",
+    "contract",
+    "get_contract_metadata",
+    "parse_sort",
+    # Dispatch and DI
+    "Dispatcher",
+    "ExceptionHook",
+    "Middleware",
+    "ResolutionError",
+    "Scope",
+    "SyncPolicy",
+    "handle",
+    "listen",
+    "provider",
+    "singleton",
+    # Results and errors
+    "AuthError",
+    "ConflictError",
+    "DomainError",
+    "Empty",
+    "ForbiddenError",
+    "FrameworkError",
+    "HandlerNotFoundError",
+    "InfrastructureError",
+    "NotFoundError",
+    "Paginated",
+    "PermissionDeniedError",
+    "PyFerOxError",
+    "Response",
+    "RouteConflictError",
+    "Streamed",
+    "Success",
+    "UnauthorizedError",
+    "ValidationError",
+    "map_exception_to_transport",
+    "normalize_execution_exception",
+    "to_payload",
+    # HTTP and schema
+    "HTTPAdapter",
+    "DTO",
+    "Schema",
+    "SchemaModel",
+    "TypedSchema",
+    "format_validation_error",
+    "get_schema_metadata",
+    "parse_input",
+    "schema_metadata",
+    "serialize_output",
+    # Auth
+    "AccessToken",
+    "AuthBackend",
+    "Identity",
+    "InMemorySessionStore",
+    "PermissionChecker",
+    "Principal",
+    "Session",
+    "SessionAuthBackend",
+    "SessionStore",
+    "requires",
+    # Jobs and cache
+    "InMemoryJobQueue",
+    "Job",
+    "JobDispatcher",
+    "JobExecutionResult",
+    "JobQueue",
+    "JobStatus",
+    "LocalJobWorker",
+    "StructJob",
+    "WorkerRuntime",
+    "create_worker_runtime",
+    "Cache",
+    "InMemoryCache",
+    # Distributed runtime
+    "DistributedEventBus",
+    "EventBroker",
+    "EventDispatchResult",
+    "EventEnvelope",
+    "EventResultStatus",
+    "InMemoryEventBroker",
+    "LocalEventBus",
+    "event_metadata",
+    "CheckStatus",
+    "HealthCheckResult",
+    "HealthRegistry",
+    "HealthReport",
+    "InMemoryTraceCollector",
+    "TraceCollector",
+    "TraceSpan",
+    "TracingMiddleware",
+    "IdempotencyStore",
+    "InMemoryIdempotencyStore",
+    "RetryClassifier",
+    "RetryDecision",
+    "RetryDisposition",
+    "RetryPolicy",
+    "default_retry_classifier",
+    "InMemoryRPCTransport",
+    "RPCClient",
+    "RPCError",
+    "RPCRequest",
+    "RPCResponse",
+    "RPCServer",
+    "RPCTransport",
+    "ScheduleRunResult",
+    "ScheduleResultStatus",
+    "ScheduledTask",
+    "SchedulerRuntime",
+    "Workflow",
+    "WorkflowContext",
+    "WorkflowExecutionResult",
+    "WorkflowStatus",
+    "WorkflowStep",
+    # DB
+    "DBSessionMiddleware",
+    "MigrationResult",
+    "Repository",
+    "SQLAlchemySettings",
+    "UnitOfWork",
+    "migration_current",
+    "migration_downgrade",
+    "migration_init",
+    "migration_revision",
+    "migration_upgrade",
+    "run_alembic",
+    "sqlalchemy_module",
+    # Testing
+    "FakeDispatcher",
+    "TestHTTPClient",
+    "create_test_app",
+    "create_test_module",
+    "override_dependencies",
+]

pyferox-0.0.1/pyferox/auth/__init__.py

@@ -0,0 +1,26 @@
+"""Authentication and authorization contracts."""
+
+from pyferox.auth.contracts import (
+    AccessToken,
+    AuthBackend,
+    Identity,
+    PermissionChecker,
+    Principal,
+    Session,
+    SessionStore,
+    requires,
+)
+from pyferox.auth.session import InMemorySessionStore, SessionAuthBackend
+
+__all__ = [
+    "AccessToken",
+    "AuthBackend",
+    "Identity",
+    "InMemorySessionStore",
+    "PermissionChecker",
+    "Principal",
+    "Session",
+    "SessionAuthBackend",
+    "SessionStore",
+    "requires",
+]

pyferox-0.0.1/pyferox/auth/contracts.py

@@ -0,0 +1,79 @@
+"""Core auth interfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Protocol
+
+
+@dataclass(slots=True)
+class Identity:
+    subject: str
+    email: str | None = None
+
+
+@dataclass(slots=True)
+class Principal:
+    identity: Identity
+    roles: set[str] = field(default_factory=set)
+    permissions: set[str] = field(default_factory=set)
+
+
+@dataclass(slots=True)
+class AccessToken:
+    token: str
+    subject: str
+    expires_at: datetime | None = None
+    scopes: set[str] = field(default_factory=set)
+
+    def is_expired(self, *, now: datetime | None = None) -> bool:
+        if self.expires_at is None:
+            return False
+        current = now or datetime.now(tz=timezone.utc)
+        return self.expires_at <= current
+
+
+@dataclass(slots=True)
+class Session:
+    session_id: str
+    subject: str
+    expires_at: datetime | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def is_expired(self, *, now: datetime | None = None) -> bool:
+        if self.expires_at is None:
+            return False
+        current = now or datetime.now(tz=timezone.utc)
+        return self.expires_at <= current
+
+
+class AuthBackend(Protocol):
+    async def authenticate(self, token: str | None) -> Principal | None:
+        ...
+
+
+class PermissionChecker(Protocol):
+    async def allowed(self, principal: Principal | None, permission: str) -> bool:
+        ...
+
+
+class SessionStore(Protocol):
+    async def get(self, session_id: str) -> Session | None:
+        ...
+
+    async def set(self, session: Session) -> None:
+        ...
+
+    async def revoke(self, session_id: str) -> None:
+        ...
+
+
+def requires(permission: str):
+    """Declare handler-level permission requirement."""
+
+    def decorator(fn: Any) -> Any:
+        setattr(fn, "__pyferox_permission__", permission)
+        return fn
+
+    return decorator