bustan 1.0.0__tar.gz

bustan-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moses Gameli <https://mosesgameli.com>
+
+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.

bustan-1.0.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: bustan
+Version: 1.0.0
+Summary: NestJS-inspired application architecture on top of Starlette
+Keywords: asgi,dependency injection,starlette,web framework
+Author: mosesgameli
+Author-email: mosesgameli <mosesgameli20@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: anyio>=4.9.0,<5.0.0
+Requires-Dist: dependency-injector>=4.46.0,<5.0.0
+Requires-Dist: starlette>=1.0.0,<2.0.0
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/bustanhq/bustan
+Project-URL: Issues, https://github.com/bustanhq/bustan/issues
+Project-URL: Documentation, https://bustan.dev
+Project-URL: Changelog, https://github.com/bustanhq/bustan/blob/main/CHANGELOG.md
+Project-URL: Support, https://github.com/bustanhq/bustan/issues
+Description-Content-Type: text/markdown
+
+# bustan
+
+bustan is an architecture-first Python web framework for teams that like Starlette's runtime but want stronger application structure.
+
+It brings NestJS-style modules, controllers, providers, constructor injection, lifecycle hooks, and a request pipeline to Python, while keeping direct access to Starlette when you need an escape hatch.
+
+## Why bustan
+
+- Use modules as real composition boundaries instead of ad hoc import graphs.
+- Keep controllers thin and move business logic into DI-managed providers.
+- Apply guards, pipes, interceptors, and exception filters in a predictable order.
+- Build on top of Starlette instead of replacing the ASGI layer with a closed runtime.
+- Test applications with focused module builders and provider overrides.
+
+## Status
+
+- `bustan` is alpha and still pre-`0.1.0`.
+- The first public compatibility target is `0.1.0` alpha.
+- Package metadata currently targets Python `>=3.13`.
+- The Python floor is intentionally narrow while the public surface, packaging, and release process are still settling.
+- Python `3.13` remains the floor because the project is still tightening its first public contract and release automation around one supported runtime before widening support.
+- Compatibility is currently promised only for `bustan`, `bustan.errors`, and `bustan.testing`.
+- Internal modules such as `bustan.container`, `bustan.routing`, `bustan.params`, and `bustan.metadata` are still implementation details.
+- Alpha stability means behavior may still change between pre-`0.1.0` releases, but the project is already treating `bustan`, `bustan.errors`, and `bustan.testing` as the intended long-term public surface.
+- No benchmark suite or benchmark claims are published yet.
+
+## Installation
+
+### Use from source today
+
+This repository is ready to use directly in a local development environment:
+
+```bash
+uv sync --group dev
+```
+
+That installs the framework, test dependencies, linting, typing, and the local CLI entry point.
+
+### Use the CLI from a source checkout
+
+```bash
+uv run bustan new my-app
+```
+
+`create` is available as an alias:
+
+```bash
+uv run bustan create my-app
+```
+
+### Use as a published package
+
+Once the PyPI distribution name is confirmed and published, the intended install path is:
+
+```bash
+uv add bustan
+# or
+pip install bustan
+```
+
+Once published, the CLI entry point will also be usable through `uvx`:
+
+```bash
+uvx bustan create my-app
+```
+
+The distribution name `bustan` still needs to be confirmed at publish time. The current repository is prepared for that name, but the final PyPI availability check should happen immediately before the first release.
+
+## Five-Minute Quickstart
+
+Create an application module, one provider, and one controller:
+
+```python
+from bustan import controller, create_app, get, injectable, module
+
+
+@Injectable
+class GreetingService:
+	def greet(self) -> dict[str, str]:
+		return {"message": "hello from bustan"}
+
+
+@Controller("/hello")
+class GreetingController:
+	def __init__(self, greeting_service: GreetingService) -> None:
+		self.greeting_service = greeting_service
+
+	@Get("/")
+	def read_greeting(self) -> dict[str, str]:
+		return self.greeting_service.greet()
+
+
+@Module(
+	controllers=[GreetingController],
+	providers=[GreetingService],
+	exports=[GreetingService],
+)
+class AppModule:
+	pass
+
+
+app = create_app(AppModule)
+```
+
+Run it locally:
+
+```bash
+uv run uvicorn app:app --reload
+```
+
+Call the route:
+
+```bash
+curl http://127.0.0.1:8000/hello
+```
+
+Expected response:
+
+```json
+{"message":"hello from bustan"}
+```
+
+## What You Get Today
+
+The current implementation already includes:
+
+- module discovery and validation
+- export-based provider visibility across modules
+- constructor injection for providers and controllers
+- controller route compilation into Starlette
+- response coercion for `Response`, `dict`, `list`, dataclass instances, and `None`
+- request binding for `Request`, path params, query params, and JSON body input
+- request-scoped providers with per-request caching
+- guards, pipes, interceptors, and exception filters
+- module and application lifecycle hooks wired through Starlette lifespan
+- test helpers for temporary modules, test apps, and provider overrides
+- an initial CLI scaffold for new applications
+
+## Supported Public API
+
+The first compatibility boundary is intentionally small.
+
+Stable import paths:
+
+- `bustan`
+- `bustan.errors`
+- `bustan.testing`
+
+Example supported imports:
+
+```python
+from bustan import __version__, controller, create_app, get, injectable, module
+from bustan.errors import ProviderResolutionError
+from bustan.testing import create_test_app, override_provider
+```
+
+The generated API reference for the stable surface lives in [docs/API_REFERENCE.md](docs/API_REFERENCE.md).
+
+## Guides
+
+- [docs/README.md](docs/README.md)
+- [docs/FIRST_APP.md](docs/FIRST_APP.md)
+- [docs/ROUTING.md](docs/ROUTING.md)
+- [docs/REQUEST_PIPELINE.md](docs/REQUEST_PIPELINE.md)
+- [docs/REQUEST_SCOPED_PROVIDERS.md](docs/REQUEST_SCOPED_PROVIDERS.md)
+- [docs/LIFECYCLE.md](docs/LIFECYCLE.md)
+- [docs/STABILITY.md](docs/STABILITY.md)
+- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
+- [docs/COMPARISONS.md](docs/COMPARISONS.md)
+- [docs/ESCAPE_HATCHES.md](docs/ESCAPE_HATCHES.md)
+- [docs/VERSIONING.md](docs/VERSIONING.md)
+
+## Open Source Project Docs
+
+- [docs/README.md](docs/README.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- [SECURITY.md](SECURITY.md)
+- [GOVERNANCE.md](GOVERNANCE.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md)
+
+## Examples
+
+The repository includes focused examples beyond the minimal quickstart:
+
+- `examples/blog_api/app.py`: a small reference-style blog API with request context and module exports
+- `examples/multi_module_app/app.py`: feature modules with exported providers
+- `examples/graph_inspection/app.py`: print the discovered module graph
+- `examples/request_scope_pipeline_app/app.py`: request-scoped providers shared across guards, interceptors, and controllers
+- `examples/testing_overrides/app.py`: test-time provider overrides with `bustan.testing`
+
+Run them with:
+
+```bash
+uv run python examples/blog_api/app.py
+uv run python examples/graph_inspection/app.py
+uv run python examples/request_scope_pipeline_app/app.py
+uv run python examples/testing_overrides/app.py
+```
+
+## Testing Utilities
+
+`bustan.testing` is the intended entry point for test-time application assembly.
+
+Use `create_test_app()` to start an app with one or more providers replaced:
+
+```python
+from bustan.testing import create_test_app
+
+
+application = create_test_app(
+	AppModule,
+	provider_overrides={GreetingService: FakeGreetingService()},
+)
+```
+
+Use `override_provider()` when you want a scoped override that is restored automatically:
+
+```python
+from bustan.testing import override_provider
+
+
+with override_provider(application, GreetingService, FakeGreetingService()):
+	...
+```
+
+Use `create_test_module()` when you want a temporary module class for an isolated test instead of declaring one manually.
+
+## Support
+
+Use GitHub Issues for questions, bug reports, feature requests, and adoption feedback:
+
+- https://github.com/bustanhq/bustan/issues
+
+Do not use public issues for sensitive security reports. Follow the private disclosure guidance in [SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+Near-term priorities for the first public adoption push:
+
+- publish and verify the first PyPI release end to end
+- widen runtime support beyond Python `3.13` once release automation is routine
+- collect external adopter feedback before calling any release stable
+- publish a fuller reference app or companion tutorial repository
+- move to a dedicated docs site if the docs set outgrow README-driven discovery
+
+## Development
+
+Install hooks once after cloning if you want local pre-commit and pre-push checks:
+
+```bash
+uv run lefthook install
+```
+
+For full contributor expectations, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Run the main checks with:
+
+```bash
+uv run python scripts/generate_api_reference.py --check
+uv run python scripts/check_markdown_links.py
+uv run ruff check .
+uv run ty check src tests examples scripts
+uv run pytest
+uv run pytest --cov=bustan --cov-report=term-missing --cov-report=xml
+```
+
+## Project Direction
+
+`bustan` is trying to be opinionated about application structure, not to hide Starlette or compete on benchmark claims.
+
+If you want a small ASGI core with explicit module boundaries, DI-managed services, and a predictable request pipeline, that is the target use case.
+

bustan-1.0.0/README.md

@@ -0,0 +1,274 @@
+# bustan
+
+bustan is an architecture-first Python web framework for teams that like Starlette's runtime but want stronger application structure.
+
+It brings NestJS-style modules, controllers, providers, constructor injection, lifecycle hooks, and a request pipeline to Python, while keeping direct access to Starlette when you need an escape hatch.
+
+## Why bustan
+
+- Use modules as real composition boundaries instead of ad hoc import graphs.
+- Keep controllers thin and move business logic into DI-managed providers.
+- Apply guards, pipes, interceptors, and exception filters in a predictable order.
+- Build on top of Starlette instead of replacing the ASGI layer with a closed runtime.
+- Test applications with focused module builders and provider overrides.
+
+## Status
+
+- `bustan` is alpha and still pre-`0.1.0`.
+- The first public compatibility target is `0.1.0` alpha.
+- Package metadata currently targets Python `>=3.13`.
+- The Python floor is intentionally narrow while the public surface, packaging, and release process are still settling.
+- Python `3.13` remains the floor because the project is still tightening its first public contract and release automation around one supported runtime before widening support.
+- Compatibility is currently promised only for `bustan`, `bustan.errors`, and `bustan.testing`.
+- Internal modules such as `bustan.container`, `bustan.routing`, `bustan.params`, and `bustan.metadata` are still implementation details.
+- Alpha stability means behavior may still change between pre-`0.1.0` releases, but the project is already treating `bustan`, `bustan.errors`, and `bustan.testing` as the intended long-term public surface.
+- No benchmark suite or benchmark claims are published yet.
+
+## Installation
+
+### Use from source today
+
+This repository is ready to use directly in a local development environment:
+
+```bash
+uv sync --group dev
+```
+
+That installs the framework, test dependencies, linting, typing, and the local CLI entry point.
+
+### Use the CLI from a source checkout
+
+```bash
+uv run bustan new my-app
+```
+
+`create` is available as an alias:
+
+```bash
+uv run bustan create my-app
+```
+
+### Use as a published package
+
+Once the PyPI distribution name is confirmed and published, the intended install path is:
+
+```bash
+uv add bustan
+# or
+pip install bustan
+```
+
+Once published, the CLI entry point will also be usable through `uvx`:
+
+```bash
+uvx bustan create my-app
+```
+
+The distribution name `bustan` still needs to be confirmed at publish time. The current repository is prepared for that name, but the final PyPI availability check should happen immediately before the first release.
+
+## Five-Minute Quickstart
+
+Create an application module, one provider, and one controller:
+
+```python
+from bustan import controller, create_app, get, injectable, module
+
+
+@Injectable
+class GreetingService:
+	def greet(self) -> dict[str, str]:
+		return {"message": "hello from bustan"}
+
+
+@Controller("/hello")
+class GreetingController:
+	def __init__(self, greeting_service: GreetingService) -> None:
+		self.greeting_service = greeting_service
+
+	@Get("/")
+	def read_greeting(self) -> dict[str, str]:
+		return self.greeting_service.greet()
+
+
+@Module(
+	controllers=[GreetingController],
+	providers=[GreetingService],
+	exports=[GreetingService],
+)
+class AppModule:
+	pass
+
+
+app = create_app(AppModule)
+```
+
+Run it locally:
+
+```bash
+uv run uvicorn app:app --reload
+```
+
+Call the route:
+
+```bash
+curl http://127.0.0.1:8000/hello
+```
+
+Expected response:
+
+```json
+{"message":"hello from bustan"}
+```
+
+## What You Get Today
+
+The current implementation already includes:
+
+- module discovery and validation
+- export-based provider visibility across modules
+- constructor injection for providers and controllers
+- controller route compilation into Starlette
+- response coercion for `Response`, `dict`, `list`, dataclass instances, and `None`
+- request binding for `Request`, path params, query params, and JSON body input
+- request-scoped providers with per-request caching
+- guards, pipes, interceptors, and exception filters
+- module and application lifecycle hooks wired through Starlette lifespan
+- test helpers for temporary modules, test apps, and provider overrides
+- an initial CLI scaffold for new applications
+
+## Supported Public API
+
+The first compatibility boundary is intentionally small.
+
+Stable import paths:
+
+- `bustan`
+- `bustan.errors`
+- `bustan.testing`
+
+Example supported imports:
+
+```python
+from bustan import __version__, controller, create_app, get, injectable, module
+from bustan.errors import ProviderResolutionError
+from bustan.testing import create_test_app, override_provider
+```
+
+The generated API reference for the stable surface lives in [docs/API_REFERENCE.md](docs/API_REFERENCE.md).
+
+## Guides
+
+- [docs/README.md](docs/README.md)
+- [docs/FIRST_APP.md](docs/FIRST_APP.md)
+- [docs/ROUTING.md](docs/ROUTING.md)
+- [docs/REQUEST_PIPELINE.md](docs/REQUEST_PIPELINE.md)
+- [docs/REQUEST_SCOPED_PROVIDERS.md](docs/REQUEST_SCOPED_PROVIDERS.md)
+- [docs/LIFECYCLE.md](docs/LIFECYCLE.md)
+- [docs/STABILITY.md](docs/STABILITY.md)
+- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
+- [docs/COMPARISONS.md](docs/COMPARISONS.md)
+- [docs/ESCAPE_HATCHES.md](docs/ESCAPE_HATCHES.md)
+- [docs/VERSIONING.md](docs/VERSIONING.md)
+
+## Open Source Project Docs
+
+- [docs/README.md](docs/README.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- [SECURITY.md](SECURITY.md)
+- [GOVERNANCE.md](GOVERNANCE.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md)
+
+## Examples
+
+The repository includes focused examples beyond the minimal quickstart:
+
+- `examples/blog_api/app.py`: a small reference-style blog API with request context and module exports
+- `examples/multi_module_app/app.py`: feature modules with exported providers
+- `examples/graph_inspection/app.py`: print the discovered module graph
+- `examples/request_scope_pipeline_app/app.py`: request-scoped providers shared across guards, interceptors, and controllers
+- `examples/testing_overrides/app.py`: test-time provider overrides with `bustan.testing`
+
+Run them with:
+
+```bash
+uv run python examples/blog_api/app.py
+uv run python examples/graph_inspection/app.py
+uv run python examples/request_scope_pipeline_app/app.py
+uv run python examples/testing_overrides/app.py
+```
+
+## Testing Utilities
+
+`bustan.testing` is the intended entry point for test-time application assembly.
+
+Use `create_test_app()` to start an app with one or more providers replaced:
+
+```python
+from bustan.testing import create_test_app
+
+
+application = create_test_app(
+	AppModule,
+	provider_overrides={GreetingService: FakeGreetingService()},
+)
+```
+
+Use `override_provider()` when you want a scoped override that is restored automatically:
+
+```python
+from bustan.testing import override_provider
+
+
+with override_provider(application, GreetingService, FakeGreetingService()):
+	...
+```
+
+Use `create_test_module()` when you want a temporary module class for an isolated test instead of declaring one manually.
+
+## Support
+
+Use GitHub Issues for questions, bug reports, feature requests, and adoption feedback:
+
+- https://github.com/bustanhq/bustan/issues
+
+Do not use public issues for sensitive security reports. Follow the private disclosure guidance in [SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+Near-term priorities for the first public adoption push:
+
+- publish and verify the first PyPI release end to end
+- widen runtime support beyond Python `3.13` once release automation is routine
+- collect external adopter feedback before calling any release stable
+- publish a fuller reference app or companion tutorial repository
+- move to a dedicated docs site if the docs set outgrow README-driven discovery
+
+## Development
+
+Install hooks once after cloning if you want local pre-commit and pre-push checks:
+
+```bash
+uv run lefthook install
+```
+
+For full contributor expectations, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Run the main checks with:
+
+```bash
+uv run python scripts/generate_api_reference.py --check
+uv run python scripts/check_markdown_links.py
+uv run ruff check .
+uv run ty check src tests examples scripts
+uv run pytest
+uv run pytest --cov=bustan --cov-report=term-missing --cov-report=xml
+```
+
+## Project Direction
+
+`bustan` is trying to be opinionated about application structure, not to hide Starlette or compete on benchmark claims.
+
+If you want a small ASGI core with explicit module boundaries, DI-managed services, and a predictable request pipeline, that is the target use case.
+

bustan-1.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "bustan"
+version = "1.0.0"
+description = "NestJS-inspired application architecture on top of Starlette"
+keywords = ["asgi", "dependency injection", "starlette", "web framework"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "mosesgameli", email = "mosesgameli20@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "anyio>=4.9.0,<5.0.0",
+    "dependency-injector>=4.46.0,<5.0.0",
+    "starlette>=1.0.0,<2.0.0",
+]
+
+[project.scripts]
+bustan = "bustan.cli:main"
+
+[project.urls]
+Repository = "https://github.com/bustanhq/bustan"
+Issues = "https://github.com/bustanhq/bustan/issues"
+Documentation = "https://bustan.dev"
+Changelog = "https://github.com/bustanhq/bustan/blob/main/CHANGELOG.md"
+Support = "https://github.com/bustanhq/bustan/issues"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.0,<1.0.0",
+    "lefthook>=2.1.4",
+    "pytest>=9.0.2,<10.0.0",
+    "pytest-cov>=7.1.0,<8.0.0",
+    "ruff>=0.15.9,<0.16.0",
+    "ty",
+    "uvicorn>=0.34.0,<1.0.0",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["bustan"]
+
+[tool.coverage.report]
+fail_under = 84
+show_missing = true
+skip_covered = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[build-system]
+requires = ["uv_build>=0.11.1,<0.12.0"]
+build-backend = "uv_build"

bustan-1.0.0/src/bustan/__init__.py

@@ -0,0 +1,41 @@
+"""Supported public API for the bustan package."""
+
+from ._version import __version__
+from .application import bootstrap, create_app
+from .decorators import (
+    Controller,
+    Delete,
+    Get,
+    Injectable,
+    Module,
+    Patch,
+    Post,
+    Put,
+    UseFilters,
+    UseGuards,
+    UseInterceptors,
+    UsePipes,
+)
+from .pipeline import ExceptionFilter, Guard, Interceptor, Pipe
+
+__all__ = (
+    "__version__",
+    "ExceptionFilter",
+    "Guard",
+    "Interceptor",
+    "Pipe",
+    "bootstrap",
+    "Controller",
+    "create_app",
+    "Delete",
+    "Get",
+    "Injectable",
+    "Module",
+    "Patch",
+    "Post",
+    "Put",
+    "UseFilters",
+    "UseGuards",
+    "UseInterceptors",
+    "UsePipes",
+)