stratae 0.0.1a0__tar.gz

stratae-0.0.1a0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: stratae
+Version: 0.0.1a0
+Summary: A toolkit of composable tools for dependency injection, lifecycle management, and more.
+Author: Scott Wahl
+License: MIT
+Project-URL: Homepage, https://github.com/Eudaetics/stratae
+Project-URL: Repository, https://github.com/Eudaetics/stratae
+Project-URL: Issues, https://github.com/Eudaetics/stratae/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.2.0; extra == "dev"
+Requires-Dist: pyright>=1.1.403; extra == "dev"
+Requires-Dist: ruff>=0.12.2; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.4.1; extra == "test"
+Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
+Requires-Dist: pytest-cov>=6.1.1; extra == "test"
+Requires-Dist: pytest-mock>=3.14.1; extra == "test"
+Provides-Extra: asgi
+Requires-Dist: httpx>=0.28.1; extra == "asgi"
+Requires-Dist: fastapi>=0.100.0; extra == "asgi"
+
+# Stratae
+
+**Composable tools for dependency injection in Python. Fast, simple, and framework-agnostic.**
+
+Stratae is a toolkit designed of small, focused components that layer together to create more powerful systems. It's built to complement Python's 3.12+ features, leveraging decorators, contexts, and functions to create a system that works anywhere.
+
+Write your business logic once, use it everywhere: APIs, CLIs, workers, and tests.
+
+```bash
+pip install stratae
+```
+
+## Quick Start
+
+```python
+from stratae.depends import Depends, inject
+from stratae.lifecycle import Lifecycle
+
+lifecycle = Lifecycle(["application"])
+
+type Database = dict[str, list[dict[str, str]]]
+
+# Simple database connection (just a dict for demo)
+@lifecycle.cache('application')
+def get_database() -> Database:
+    return {"users": []}
+
+@inject
+def create_user(name: str, db: Database = Depends(get_database)):
+    user = {"name": name}
+    db["users"].append(user)
+    return user
+
+# Use anywhere: APIs, CLIs, workers, tests
+with lifecycle.start('application'):
+    user = create_user("Alice")
+    print(f"Created user: {user['name']}")
+```
+
+## Why Stratae?
+
+**Simple by design.** Stratae doesn't impose architectural patterns or force you into a framework. It provides focused tools that solve specific problems: dependency injection, lifecycle management, and context variables. Use what you need, ignore what you don't.
+
+**Zero lock-in.** Your business logic is just functions with decorators. Remove Stratae anytime by replacing `Depends()` with actual values. No container to untangle, no framework to escape.
+
+**Built for performance.** Stratae keeps overhead minimal through straightforward design:
+
+- Analyze dependencies once at decoration time
+- No runtime introspection or provider lookups
+- Direct function calls with minimal indirection
+
+The result is a system that minimizes overhead and stays out of your way. If you're using a system that has dependency injection, we encourage you to test it yourself. Change one small piece to use Stratae and see if it works for you.
+
+## Features
+
+### Dependency Injection
+
+Dependency injection in Stratae uses familiar decorator syntax that works with any callable. Use this to send values, objects, or anything into a function.
+
+```python
+from stratae.depends import Depends, inject
+
+def get_config():
+    return {"env": "dev", "mode": "strict"}
+
+# Decorate the function with inject to resolve dependencies
+@inject
+# Use Depends(...) to mark parameters for injection
+def endpoint(config: dict[str, str] = Depends(get_config)):
+    print(f"Environment: {config['env']}, Mode: {config['mode']}")
+
+endpoint()
+# Environment: dev, Mode: strict
+```
+
+### Lifecycle Management
+
+Use lifecycle management when you want to cache objects or guarantee resource cleanup for context managers. With managed resources, everything is cleaned up automatically at the end of a lifecycle scope.
+
+```python
+# Set up the lifecycle with your application scopes
+lifecycle = Lifecycle(['application', 'request'])
+
+# Lifecycle will cache the yielded value and return it for all calls within a request
+@lifecycle.cache('request')
+# Mark get_session as a contextmanager that will be auto-entered to get the session
+@managed
+def get_session():
+    session = Session()
+    try:
+        yield session
+        session.commit()
+    except:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+# Set up your lifecycle boundaries
+with lifecycle.start('application'):
+    with lifecycle.start('request'):
+        # Session is created at first call and cached automatically
+        # All get_session calls in this request will return the same session
+        db = get_session()
+        db.users.create_user('John')
+    with lifecycle.start('request'):
+        # New request, new session
+        db = get_session()
+```
+
+### Context Variables
+
+To enable decoupled systems, Stratae uses context variables for setting values that need to be shared among components. This is particularly useful for setting values at runtime that are needed deep in dependency chains. Change values at runtime, or even whole behavior, without needing to thread parameters or manipulate overrides.
+
+```python
+from stratae.context import Context
+
+lifecycle = Lifecycle('request')
+user_id = Context[int]("user_id")
+
+@lifecycle.cache('request')
+@inject
+def get_current_user(uid: int = Depends(user_id)) -> User:
+    return fetch_user(uid)
+
+@inject
+def create_post(
+    content: str,
+    user: User = Depends(get_current_user),
+) -> Post:
+    return Post(author=user, content=content)
+
+with lifecycle.start('request'), user_id.use(123):
+    post = create_post("Hello world!")
+```
+
+### Async Support
+
+Stratae is fully async compatible. Injection natively works with sync or async functions. Lifecycle offers versions for sync and async handling of resources.
+
+```python
+from stratae.depends import Depends, inject
+from stratae.lifecycle import AsyncLifecycle
+
+lifecycle = AsyncLifecycle(['application', 'request'])
+
+@lifecycle.cache('application')
+async def get_database() -> Database:
+    return await Database(url="postgresql://...")
+
+@inject
+async def create_user(
+    name: str,
+    db: Database = Depends(get_database),
+) -> User:
+    return await db.users.create(name=name)
+
+# Use anywhere: APIs, CLIs, workers, tests
+async with lifecycle.start('application'):
+    async with lifecycle.start('request'):
+        user = await create_user("Alice")
+```
+
+### Easy Testing
+
+With no complex configuration, testing functions decorated with Stratae is easy. The function signature isn't changed, just pass in the mocks you need.
+
+```python
+@inject
+def create_user(name: str, db = Depends(get_db)):
+    db.user.create(name=name)
+
+# Use normally
+create_user('Steve')
+
+# Test
+create_user('Jason', db=MockDB())
+```
+
+### Framework Agnostic
+
+Stratae doesn't have a complex framework to configure or objects to pass around. Write your business logic once with injection, then simply call those functions anywhere.
+
+```python
+# Business logic - framework-independent
+@inject
+async def create_user(
+    name: str,
+    db: Database = Depends(get_database),
+) -> User:
+    return await db.users.create(name=name)
+
+# FastAPI
+@app.post("/users")
+async def api_create(name: str):
+    return await create_user(name)
+
+# CLI
+@click.command()
+def cli_create(name: str):
+    asyncio.run(create_user(name))
+
+# Tests
+async def test_create():
+    user = await create_user("Alice", db=mock_db)
+```
+
+### Simple Integrations
+
+The design of Stratae means integrating with other tools or frameworks is typically easy. For FastAPI, an ASGI middleware that starts the request lifecycle is enough to add Stratae's lifecycle management.
+
+```python
+from fastapi import FastAPI
+from stratae.integrations import RequestLifecycleMiddleware
+from stratae.lifecycle import AsyncLifecycle, managed
+
+
+app = FastAPI()
+lifecycle = AsyncLifecycle(['request'])
+
+# Add the middleware that starts a lifecycle request
+app.add_middleware(RequestLifecycleMiddleware, lifecycle, 'request')
+
+# Everything that needs the session will get the same session
+@lifecycle.cache('request')
+@managed
+async def get_session():
+    session = AsyncSession()
+    try:
+        yield session
+        session.commit()
+    except:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+@inject
+async def create_user(
+    name: str,
+    # Using Stratae Depends
+    db: Session = Depends(get_session)
+):
+    await db.users.create(name=name)
+
+# Every request will get a new session
+@app.post('/users')
+async def post_user(name: str):
+    await create_user(name)
+```
+
+## Documentation
+
+More detailed documentation will be published soon.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+Before contributing, please:
+
+1. Check for open issues or open a new issue to start a discussion
+2. Fork the repository on GitHub
+3. Install development dependencies with `pip install -e ".[dev]"`
+4. Run pre-commit hooks with `pre-commit install`
+5. Make your changes following the project's coding style
+6. Write tests that cover your changes
+7. Update documentation if needed
+8. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

stratae-0.0.1a0/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+requires = ["setuptools>=80.9.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stratae"
+description = "A toolkit of composable tools for dependency injection, lifecycle management, and more."
+version = "0.0.1a"
+readme = "readme.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+authors = [
+    {name = "Scott Wahl"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Eudaetics/stratae"
+Repository = "https://github.com/Eudaetics/stratae"
+Issues = "https://github.com/Eudaetics/stratae/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit>=4.2.0",
+    "pyright>=1.1.403",
+    "ruff>=0.12.2",
+]
+test = [
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.0.0",
+    "pytest-cov>=6.1.1",
+    "pytest-mock>=3.14.1",
+]
+asgi = [
+    "httpx>=0.28.1",
+    "fastapi>=0.100.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stratae*"]
+
+[tool.ruff]
+lint.select = ["E", "F", "B", "I", "D", "S", "W"]
+lint.ignore = ["D203", "D212", "B008"]
+lint.external = ["S7497"]
+line-length = 100
+
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    # at least these three should be fine in tests:
+    "S101", # asserts allowed in tests...
+    "ARG", # Unused function args -> fixtures nevertheless are functionally relevant...
+    "FBT", # Don't care about booleans as positional arguments in tests, e.g. via @pytest.mark.parametrize()
+    "S311", # Not using cryptographic safe randomness in tests, just getting random values
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = "tests/"
+cache_dir = ".pytest_cache"
+addopts = [
+    "--cov=stratae/",
+    "--cov-report=html:coverage/cov.html",
+    "--no-cov-on-fail"
+]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "asgi: ASGI framework integration tests (requires fastapi, httpx)",
+]
+
+[tool.coverage.run]
+omit = [
+    "*/venv/*",
+    "*/.venv/*",
+    "*/migrations/*",
+    "*/alembic/*",
+    "*/_version.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "@(abc\\.)?abstractmethod",
+    "^\\s*\\.\\.\\.$",
+    "if TYPE_CHECKING:"
+]
+
+[tool.pyright]
+include = ["stratae", "tests"]
+exclude = ["**/__pycache__"]
+
+typeCheckingMode = "strict"
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = true
+reportUnusedClass = true
+reportUnusedFunction = true
+reportUnusedVariable = true
+reportDuplicateImport = true
+reportOptionalSubscript = true
+reportOptionalMemberAccess = true
+reportOptionalCall = true
+reportOptionalIterable = true
+reportUntypedFunctionDecorator = true
+
+# Python version
+pythonVersion = "3.12"

stratae-0.0.1a0/readme.md

@@ -0,0 +1,273 @@
+# Stratae
+
+**Composable tools for dependency injection in Python. Fast, simple, and framework-agnostic.**
+
+Stratae is a toolkit designed of small, focused components that layer together to create more powerful systems. It's built to complement Python's 3.12+ features, leveraging decorators, contexts, and functions to create a system that works anywhere.
+
+Write your business logic once, use it everywhere: APIs, CLIs, workers, and tests.
+
+```bash
+pip install stratae
+```
+
+## Quick Start
+
+```python
+from stratae.depends import Depends, inject
+from stratae.lifecycle import Lifecycle
+
+lifecycle = Lifecycle(["application"])
+
+type Database = dict[str, list[dict[str, str]]]
+
+# Simple database connection (just a dict for demo)
+@lifecycle.cache('application')
+def get_database() -> Database:
+    return {"users": []}
+
+@inject
+def create_user(name: str, db: Database = Depends(get_database)):
+    user = {"name": name}
+    db["users"].append(user)
+    return user
+
+# Use anywhere: APIs, CLIs, workers, tests
+with lifecycle.start('application'):
+    user = create_user("Alice")
+    print(f"Created user: {user['name']}")
+```
+
+## Why Stratae?
+
+**Simple by design.** Stratae doesn't impose architectural patterns or force you into a framework. It provides focused tools that solve specific problems: dependency injection, lifecycle management, and context variables. Use what you need, ignore what you don't.
+
+**Zero lock-in.** Your business logic is just functions with decorators. Remove Stratae anytime by replacing `Depends()` with actual values. No container to untangle, no framework to escape.
+
+**Built for performance.** Stratae keeps overhead minimal through straightforward design:
+
+- Analyze dependencies once at decoration time
+- No runtime introspection or provider lookups
+- Direct function calls with minimal indirection
+
+The result is a system that minimizes overhead and stays out of your way. If you're using a system that has dependency injection, we encourage you to test it yourself. Change one small piece to use Stratae and see if it works for you.
+
+## Features
+
+### Dependency Injection
+
+Dependency injection in Stratae uses familiar decorator syntax that works with any callable. Use this to send values, objects, or anything into a function.
+
+```python
+from stratae.depends import Depends, inject
+
+def get_config():
+    return {"env": "dev", "mode": "strict"}
+
+# Decorate the function with inject to resolve dependencies
+@inject
+# Use Depends(...) to mark parameters for injection
+def endpoint(config: dict[str, str] = Depends(get_config)):
+    print(f"Environment: {config['env']}, Mode: {config['mode']}")
+
+endpoint()
+# Environment: dev, Mode: strict
+```
+
+### Lifecycle Management
+
+Use lifecycle management when you want to cache objects or guarantee resource cleanup for context managers. With managed resources, everything is cleaned up automatically at the end of a lifecycle scope.
+
+```python
+# Set up the lifecycle with your application scopes
+lifecycle = Lifecycle(['application', 'request'])
+
+# Lifecycle will cache the yielded value and return it for all calls within a request
+@lifecycle.cache('request')
+# Mark get_session as a contextmanager that will be auto-entered to get the session
+@managed
+def get_session():
+    session = Session()
+    try:
+        yield session
+        session.commit()
+    except:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+# Set up your lifecycle boundaries
+with lifecycle.start('application'):
+    with lifecycle.start('request'):
+        # Session is created at first call and cached automatically
+        # All get_session calls in this request will return the same session
+        db = get_session()
+        db.users.create_user('John')
+    with lifecycle.start('request'):
+        # New request, new session
+        db = get_session()
+```
+
+### Context Variables
+
+To enable decoupled systems, Stratae uses context variables for setting values that need to be shared among components. This is particularly useful for setting values at runtime that are needed deep in dependency chains. Change values at runtime, or even whole behavior, without needing to thread parameters or manipulate overrides.
+
+```python
+from stratae.context import Context
+
+lifecycle = Lifecycle('request')
+user_id = Context[int]("user_id")
+
+@lifecycle.cache('request')
+@inject
+def get_current_user(uid: int = Depends(user_id)) -> User:
+    return fetch_user(uid)
+
+@inject
+def create_post(
+    content: str,
+    user: User = Depends(get_current_user),
+) -> Post:
+    return Post(author=user, content=content)
+
+with lifecycle.start('request'), user_id.use(123):
+    post = create_post("Hello world!")
+```
+
+### Async Support
+
+Stratae is fully async compatible. Injection natively works with sync or async functions. Lifecycle offers versions for sync and async handling of resources.
+
+```python
+from stratae.depends import Depends, inject
+from stratae.lifecycle import AsyncLifecycle
+
+lifecycle = AsyncLifecycle(['application', 'request'])
+
+@lifecycle.cache('application')
+async def get_database() -> Database:
+    return await Database(url="postgresql://...")
+
+@inject
+async def create_user(
+    name: str,
+    db: Database = Depends(get_database),
+) -> User:
+    return await db.users.create(name=name)
+
+# Use anywhere: APIs, CLIs, workers, tests
+async with lifecycle.start('application'):
+    async with lifecycle.start('request'):
+        user = await create_user("Alice")
+```
+
+### Easy Testing
+
+With no complex configuration, testing functions decorated with Stratae is easy. The function signature isn't changed, just pass in the mocks you need.
+
+```python
+@inject
+def create_user(name: str, db = Depends(get_db)):
+    db.user.create(name=name)
+
+# Use normally
+create_user('Steve')
+
+# Test
+create_user('Jason', db=MockDB())
+```
+
+### Framework Agnostic
+
+Stratae doesn't have a complex framework to configure or objects to pass around. Write your business logic once with injection, then simply call those functions anywhere.
+
+```python
+# Business logic - framework-independent
+@inject
+async def create_user(
+    name: str,
+    db: Database = Depends(get_database),
+) -> User:
+    return await db.users.create(name=name)
+
+# FastAPI
+@app.post("/users")
+async def api_create(name: str):
+    return await create_user(name)
+
+# CLI
+@click.command()
+def cli_create(name: str):
+    asyncio.run(create_user(name))
+
+# Tests
+async def test_create():
+    user = await create_user("Alice", db=mock_db)
+```
+
+### Simple Integrations
+
+The design of Stratae means integrating with other tools or frameworks is typically easy. For FastAPI, an ASGI middleware that starts the request lifecycle is enough to add Stratae's lifecycle management.
+
+```python
+from fastapi import FastAPI
+from stratae.integrations import RequestLifecycleMiddleware
+from stratae.lifecycle import AsyncLifecycle, managed
+
+
+app = FastAPI()
+lifecycle = AsyncLifecycle(['request'])
+
+# Add the middleware that starts a lifecycle request
+app.add_middleware(RequestLifecycleMiddleware, lifecycle, 'request')
+
+# Everything that needs the session will get the same session
+@lifecycle.cache('request')
+@managed
+async def get_session():
+    session = AsyncSession()
+    try:
+        yield session
+        session.commit()
+    except:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+@inject
+async def create_user(
+    name: str,
+    # Using Stratae Depends
+    db: Session = Depends(get_session)
+):
+    await db.users.create(name=name)
+
+# Every request will get a new session
+@app.post('/users')
+async def post_user(name: str):
+    await create_user(name)
+```
+
+## Documentation
+
+More detailed documentation will be published soon.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+Before contributing, please:
+
+1. Check for open issues or open a new issue to start a discussion
+2. Fork the repository on GitHub
+3. Install development dependencies with `pip install -e ".[dev]"`
+4. Run pre-commit hooks with `pre-commit install`
+5. Make your changes following the project's coding style
+6. Write tests that cover your changes
+7. Update documentation if needed
+8. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

stratae-0.0.1a0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+