snakeboot 0.1.2__tar.gz

snakeboot-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wouter Deketelaere
+
+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.

snakeboot-0.1.2/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: snakeboot
+Version: 0.1.2
+Summary: Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan and singleton REST controllers on Django Ninja, wired by wireup.
+Keywords: spring-boot,hexagonal-architecture,ddd,django,django-ninja,wireup,dependency-injection,transactional
+Author: Wouter Deketelaere
+Author-email: Wouter Deketelaere <wouter.deketelaere@kdg.be>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: wireup>=2.12.0
+Requires-Dist: django>=6.1.1 ; extra == 'django'
+Requires-Dist: django>=6.1.1 ; extra == 'ninja'
+Requires-Dist: django-ninja>=1.7.1 ; extra == 'ninja'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/KdG-OCDI/snakeboot
+Project-URL: Repository, https://github.com/KdG-OCDI/snakeboot
+Project-URL: Issues, https://github.com/KdG-OCDI/snakeboot/issues
+Project-URL: Changelog, https://github.com/KdG-OCDI/snakeboot/blob/main/CHANGELOG.md
+Provides-Extra: django
+Provides-Extra: ninja
+Description-Content-Type: text/markdown
+
+# snakeboot
+
+Spring Boot ergonomics for hexagonal Python applications built with Django, Django Ninja and
+[wireup](https://github.com/maldoinc/wireup).
+
+snakeboot imitates the basics of Spring Boot, not Spring itself. Each part is a handful of small
+classes you can read in an afternoon, and none of them knows anything about your domain.
+
+| snakeboot | Spring Boot | Needs |
+|---|---|---|
+| `@transactional`, `after_commit` | `@Transactional`, `@TransactionalEventListener(AFTER_COMMIT)` | nothing |
+| `@application_root`, `ComponentScan` | `@SpringBootApplication`, `@ComponentScan` | nothing |
+| `ApplicationEventPublisher`, `@event_listener`, `@transactional_event_listener` | the same names | wireup |
+| `@rest_controller`, `@route.get`, `@rest_controller_advice`, `@exception_handler` | `@RestController`, `@GetMapping`, `@RestControllerAdvice`, `@ExceptionHandler` | `snakeboot[ninja]` |
+| `DjangoAtomicTransactionManager` | `PlatformTransactionManager` for JDBC | `snakeboot[django]` |
+| `RecordingTransactionManager`, `declared_classes` | spring-test | nothing |
+
+The transaction, component scan and testing packages import nothing but the standard library,
+so the application layer of a hexagonal application can use `@transactional` without importing Django.
+
+## Install
+
+```bash
+uv add "snakeboot[django,ninja]"
+```
+
+## A tour
+
+**The application root.** The component scan starts in the package of the marked class, like
+`@SpringBootApplication`. It skips Django's entry points (`wsgi.py`, `asgi.py`, migrations) and
+adds the components snakeboot provides itself (the event publisher).
+
+```python
+# myapp/myapp_application.py
+@application_root
+class MyApplication: ...
+
+
+# settings.py: the setting wireup needs anyway
+WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names()], auto_inject_views=False)
+```
+
+**Transactions.** A use case declares its boundary; composition chooses the technology.
+
+```python
+@injectable
+class CancelRegistrationUseCase:
+    @transactional
+    def execute(self, request: CancelRegistrationRequestDTO) -> None:
+        workshop = self._workshops.get(...)
+        workshop.cancel_registration(...)
+        self._workshops.save(workshop)
+        self._events.publish_all(workshop.pull_events())
+
+
+# composition, at start-up
+TransactionManagerRegistry.install(DjangoAtomicTransactionManager())
+```
+
+**Application events.** Listeners react to facts after the commit, so a rolled-back change never
+reaches anyone, and a failing listener cannot undo a committed one.
+
+```python
+@application_event_listener
+class ParticipantNotificationListener:
+    def __init__(self, notifications: NotificationPort) -> None:
+        self._notifications = notifications
+
+    @transactional_event_listener(WaitlistedParticipantPromoted)
+    def notify_promoted(self, event: WaitlistedParticipantPromoted) -> None: ...
+```
+
+**REST controllers.** Singleton classes with constructor injection, found by the component scan.
+Two endpoints for the same URL, or two answers for one error, stop the start-up.
+
+```python
+@rest_controller("/workshops", tags=["workshops"])
+class WorkshopRestController:
+    def __init__(self, enrollment: EnrollmentFacadePort) -> None:
+        self._enrollment = enrollment
+
+    @route.get("/{workshop_id}", response=WorkshopViewDTO)
+    def get_workshop(self, request: HttpRequest, workshop_id: str) -> WorkshopViewDTO: ...
+
+
+@rest_controller_advice
+class EnrollmentRestErrorAdvice:
+    @exception_handler(WorkshopNotFoundError, status=404)
+    def answer_not_found(self, error: Exception) -> dict[str, str]:
+        return error_answer(error)  # {"code": "workshop_not_found", "detail": "..."}
+
+
+# urls.py
+mounted = RestControllerMounter().mount(api, scan=settings.WIREUP.injectables or ())
+```
+
+## Design rules
+
+* Imitate the basics, not all of Spring: no AOP, no profiles, no scheduling, no message brokers.
+* Fail at start-up, not at the first request: a broken controller, listener or root stops the application.
+* Each package knows as little as possible; `uv run lint-imports` enforces it.
+
+## Develop
+
+```bash
+uv sync
+uv run pre-commit install
+uv run pytest            # tests, including the import contracts
+uv run ruff check        # Clean Code rules
+uv run mypy              # strict
+```

snakeboot-0.1.2/README.md

@@ -0,0 +1,111 @@
+# snakeboot
+
+Spring Boot ergonomics for hexagonal Python applications built with Django, Django Ninja and
+[wireup](https://github.com/maldoinc/wireup).
+
+snakeboot imitates the basics of Spring Boot, not Spring itself. Each part is a handful of small
+classes you can read in an afternoon, and none of them knows anything about your domain.
+
+| snakeboot | Spring Boot | Needs |
+|---|---|---|
+| `@transactional`, `after_commit` | `@Transactional`, `@TransactionalEventListener(AFTER_COMMIT)` | nothing |
+| `@application_root`, `ComponentScan` | `@SpringBootApplication`, `@ComponentScan` | nothing |
+| `ApplicationEventPublisher`, `@event_listener`, `@transactional_event_listener` | the same names | wireup |
+| `@rest_controller`, `@route.get`, `@rest_controller_advice`, `@exception_handler` | `@RestController`, `@GetMapping`, `@RestControllerAdvice`, `@ExceptionHandler` | `snakeboot[ninja]` |
+| `DjangoAtomicTransactionManager` | `PlatformTransactionManager` for JDBC | `snakeboot[django]` |
+| `RecordingTransactionManager`, `declared_classes` | spring-test | nothing |
+
+The transaction, component scan and testing packages import nothing but the standard library,
+so the application layer of a hexagonal application can use `@transactional` without importing Django.
+
+## Install
+
+```bash
+uv add "snakeboot[django,ninja]"
+```
+
+## A tour
+
+**The application root.** The component scan starts in the package of the marked class, like
+`@SpringBootApplication`. It skips Django's entry points (`wsgi.py`, `asgi.py`, migrations) and
+adds the components snakeboot provides itself (the event publisher).
+
+```python
+# myapp/myapp_application.py
+@application_root
+class MyApplication: ...
+
+
+# settings.py: the setting wireup needs anyway
+WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names()], auto_inject_views=False)
+```
+
+**Transactions.** A use case declares its boundary; composition chooses the technology.
+
+```python
+@injectable
+class CancelRegistrationUseCase:
+    @transactional
+    def execute(self, request: CancelRegistrationRequestDTO) -> None:
+        workshop = self._workshops.get(...)
+        workshop.cancel_registration(...)
+        self._workshops.save(workshop)
+        self._events.publish_all(workshop.pull_events())
+
+
+# composition, at start-up
+TransactionManagerRegistry.install(DjangoAtomicTransactionManager())
+```
+
+**Application events.** Listeners react to facts after the commit, so a rolled-back change never
+reaches anyone, and a failing listener cannot undo a committed one.
+
+```python
+@application_event_listener
+class ParticipantNotificationListener:
+    def __init__(self, notifications: NotificationPort) -> None:
+        self._notifications = notifications
+
+    @transactional_event_listener(WaitlistedParticipantPromoted)
+    def notify_promoted(self, event: WaitlistedParticipantPromoted) -> None: ...
+```
+
+**REST controllers.** Singleton classes with constructor injection, found by the component scan.
+Two endpoints for the same URL, or two answers for one error, stop the start-up.
+
+```python
+@rest_controller("/workshops", tags=["workshops"])
+class WorkshopRestController:
+    def __init__(self, enrollment: EnrollmentFacadePort) -> None:
+        self._enrollment = enrollment
+
+    @route.get("/{workshop_id}", response=WorkshopViewDTO)
+    def get_workshop(self, request: HttpRequest, workshop_id: str) -> WorkshopViewDTO: ...
+
+
+@rest_controller_advice
+class EnrollmentRestErrorAdvice:
+    @exception_handler(WorkshopNotFoundError, status=404)
+    def answer_not_found(self, error: Exception) -> dict[str, str]:
+        return error_answer(error)  # {"code": "workshop_not_found", "detail": "..."}
+
+
+# urls.py
+mounted = RestControllerMounter().mount(api, scan=settings.WIREUP.injectables or ())
+```
+
+## Design rules
+
+* Imitate the basics, not all of Spring: no AOP, no profiles, no scheduling, no message brokers.
+* Fail at start-up, not at the first request: a broken controller, listener or root stops the application.
+* Each package knows as little as possible; `uv run lint-imports` enforces it.
+
+## Develop
+
+```bash
+uv sync
+uv run pre-commit install
+uv run pytest            # tests, including the import contracts
+uv run ruff check        # Clean Code rules
+uv run mypy              # strict
+```

snakeboot-0.1.2/pyproject.toml

@@ -0,0 +1,246 @@
+[project]
+name = "snakeboot"
+version = "0.1.2"
+description = "Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan and singleton REST controllers on Django Ninja, wired by wireup."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+dependencies = ["wireup>=2.12.0"]
+keywords = [
+    "spring-boot",
+    "hexagonal-architecture",
+    "ddd",
+    "django",
+    "django-ninja",
+    "wireup",
+    "dependency-injection",
+    "transactional",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Wouter Deketelaere"
+email = "wouter.deketelaere@kdg.be"
+
+[project.urls]
+Homepage = "https://github.com/KdG-OCDI/snakeboot"
+Repository = "https://github.com/KdG-OCDI/snakeboot"
+Issues = "https://github.com/KdG-OCDI/snakeboot/issues"
+Changelog = "https://github.com/KdG-OCDI/snakeboot/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+django = ["django>=6.1.1"]
+ninja = [
+    "django>=6.1.1",
+    "django-ninja>=1.7.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "django>=6.1.1",
+    "django-ninja>=1.7.1",
+    "django-stubs>=6.1.2",
+    "import-linter>=2.15",
+    "mypy>=2.4.0",
+    "pre-commit>=4.7.0",
+    "pytest>=9.1.1",
+    "pytest-django>=4.14.0",
+    "ruff>=0.17.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+DJANGO_SETTINGS_MODULE = "tests.django_settings"
+pythonpath = ["."]
+django_find_project = false
+
+[tool.importlinter]
+root_package = "snakeboot"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "transaction knows no framework and no other part of snakeboot"
+type = "forbidden"
+source_modules = ["snakeboot.transaction"]
+forbidden_modules = [
+    "django",
+    "ninja",
+    "wireup",
+    "snakeboot.component_scan",
+    "snakeboot.events",
+    "snakeboot.rest",
+    "snakeboot.django",
+    "snakeboot.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "component_scan is standard library only, so settings can use it before Django starts"
+type = "forbidden"
+source_modules = ["snakeboot.component_scan"]
+forbidden_modules = [
+    "django",
+    "ninja",
+    "wireup",
+    "snakeboot.transaction",
+    "snakeboot.events",
+    "snakeboot.rest",
+    "snakeboot.django",
+    "snakeboot.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "events knows wireup and transaction, but no web or ORM framework"
+type = "forbidden"
+source_modules = ["snakeboot.events"]
+forbidden_modules = [
+    "django",
+    "ninja",
+    "pydantic",
+    "snakeboot.component_scan",
+    "snakeboot.rest",
+    "snakeboot.django",
+    "snakeboot.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "rest knows Ninja and wireup, but not the transaction and event libraries"
+type = "forbidden"
+source_modules = ["snakeboot.rest"]
+forbidden_modules = [
+    "snakeboot.transaction",
+    "snakeboot.events",
+    "snakeboot.component_scan",
+    "snakeboot.django",
+    "snakeboot.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "django adapts transaction to Django, nothing else"
+type = "forbidden"
+source_modules = ["snakeboot.django"]
+forbidden_modules = [
+    "ninja",
+    "wireup",
+    "snakeboot.component_scan",
+    "snakeboot.events",
+    "snakeboot.rest",
+    "snakeboot.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "testing helpers run without a framework"
+type = "forbidden"
+source_modules = ["snakeboot.testing"]
+forbidden_modules = [
+    "django",
+    "ninja",
+    "wireup",
+    "snakeboot.rest",
+    "snakeboot.events",
+    "snakeboot.django",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "A",
+    "C4",
+    "SIM",
+    "RET",
+    "PIE",
+    "PERF",
+    "C90",
+    "PL",
+    "FBT",
+    "ARG",
+    "ERA",
+    "T20",
+    "BLE",
+    "DJ",
+    "PT",
+    "D101",
+    "D102",
+    "D103",
+    "D106",
+    "RUF",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 8
+
+[tool.ruff.lint.pylint]
+max-args = 5
+max-positional-args = 3
+max-branches = 8
+max-returns = 4
+max-statements = 25
+
+[tool.ruff.lint.pydocstyle]
+ignore-decorators = ["typing.override"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D",
+    "PLR2004",
+    "PLR0913",
+    "PLR0917",
+    "ARG",
+    "FBT",
+]
+"**/models.py" = [
+    "D106",
+    "RUF012",
+]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+files = [
+    "src",
+    "tests",
+]
+mypy_path = "src"
+explicit_package_bases = true
+enable_error_code = [
+    "explicit-override",
+    "ignore-without-code",
+    "redundant-expr",
+    "truthy-bool",
+    "possibly-undefined",
+]
+plugins = ["mypy_django_plugin.main"]
+
+[tool.django-stubs]
+django_settings_module = "tests.django_settings"