snakeboot 0.5.2__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. {snakeboot-0.5.2 → snakeboot-0.6.0}/PKG-INFO +69 -3
  2. {snakeboot-0.5.2 → snakeboot-0.6.0}/README.md +65 -2
  3. {snakeboot-0.5.2 → snakeboot-0.6.0}/pyproject.toml +111 -2
  4. {snakeboot-0.5.2 → snakeboot-0.6.0}/pyproject.toml.orig +108 -2
  5. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/component_scan/__init__.py +4 -1
  6. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/component_scan/component_scan.py +70 -6
  7. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/__init__.py +7 -1
  8. snakeboot-0.6.0/src/snakeboot/configuration/rabbitmq_properties.py +39 -0
  9. snakeboot-0.6.0/src/snakeboot/configuration/scheduling_properties.py +16 -0
  10. snakeboot-0.6.0/src/snakeboot/django_application/background_work.py +56 -0
  11. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/django_settings.py +13 -2
  12. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/entry_points.py +22 -5
  13. snakeboot-0.6.0/src/snakeboot/django_application/management/commands/__init__.py +0 -0
  14. snakeboot-0.6.0/src/snakeboot/django_application/management/commands/run_lifecycle.py +50 -0
  15. snakeboot-0.6.0/src/snakeboot/lifecycle/__init__.py +33 -0
  16. snakeboot-0.6.0/src/snakeboot/lifecycle/application_components.py +21 -0
  17. snakeboot-0.6.0/src/snakeboot/lifecycle/application_lifecycle.py +43 -0
  18. snakeboot-0.6.0/src/snakeboot/lifecycle/application_lifecycle_injectable.py +26 -0
  19. snakeboot-0.6.0/src/snakeboot/lifecycle/application_ready_event.py +16 -0
  20. snakeboot-0.6.0/src/snakeboot/lifecycle/lifecycle.py +44 -0
  21. snakeboot-0.6.0/src/snakeboot/lifecycle/lifecycle_asgi_application.py +62 -0
  22. snakeboot-0.6.0/src/snakeboot/lifecycle/task_decorator.py +15 -0
  23. snakeboot-0.6.0/src/snakeboot/py.typed +0 -0
  24. snakeboot-0.6.0/src/snakeboot/rabbitmq/__init__.py +43 -0
  25. snakeboot-0.6.0/src/snakeboot/rabbitmq/message_conversion.py +61 -0
  26. snakeboot-0.6.0/src/snakeboot/rabbitmq/rabbit_connection_factory.py +37 -0
  27. snakeboot-0.6.0/src/snakeboot/rabbitmq/rabbit_listener.py +56 -0
  28. snakeboot-0.6.0/src/snakeboot/rabbitmq/rabbit_listener_containers.py +226 -0
  29. snakeboot-0.6.0/src/snakeboot/rabbitmq/rabbit_template.py +93 -0
  30. snakeboot-0.6.0/src/snakeboot/rabbitmq/rabbitmq_injectable.py +42 -0
  31. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/controller_scan.py +2 -17
  32. snakeboot-0.6.0/src/snakeboot/scheduling/__init__.py +18 -0
  33. snakeboot-0.6.0/src/snakeboot/scheduling/scheduled.py +69 -0
  34. snakeboot-0.6.0/src/snakeboot/scheduling/task_scheduler.py +112 -0
  35. snakeboot-0.6.0/src/snakeboot/scheduling/task_scheduler_injectable.py +33 -0
  36. {snakeboot-0.5.2 → snakeboot-0.6.0}/LICENSE +0 -0
  37. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/__init__.py +0 -0
  38. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/component_scan/application_root.py +0 -0
  39. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/cache_properties.py +0 -0
  40. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/configuration.py +0 -0
  41. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/configuration_errors.py +0 -0
  42. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/configuration_properties.py +0 -0
  43. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/configuration_sources.py +0 -0
  44. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/database_properties.py +0 -0
  45. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/django_properties.py +0 -0
  46. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/load_configuration.py +0 -0
  47. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/oauth2_properties.py +0 -0
  48. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/properties_rules.py +0 -0
  49. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/section.py +0 -0
  50. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/configuration/section_prefix.py +0 -0
  51. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django/__init__.py +0 -0
  52. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django/django_atomic_transaction_manager.py +0 -0
  53. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/__init__.py +0 -0
  54. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/apps.py +0 -0
  55. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/container_sections.py +0 -0
  56. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/django_configurer.py +0 -0
  57. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/installed_apps.py +0 -0
  58. /snakeboot-0.5.2/src/snakeboot/py.typed → /snakeboot-0.6.0/src/snakeboot/django_application/management/__init__.py +0 -0
  59. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/settings.py +0 -0
  60. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/django_application/transaction_manager.py +0 -0
  61. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/events/__init__.py +0 -0
  62. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/events/application_event_listener.py +0 -0
  63. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/events/application_event_publisher.py +0 -0
  64. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/events/application_event_publisher_injectable.py +0 -0
  65. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/events/event_listener_markers.py +0 -0
  66. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/oauth2/__init__.py +0 -0
  67. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/oauth2/jwt_bearer_authentication.py +0 -0
  68. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/openapi/__init__.py +0 -0
  69. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/openapi/openapi_definition.py +0 -0
  70. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/__init__.py +0 -0
  71. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/authenticated_principal.py +0 -0
  72. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/bearer_authentication.py +0 -0
  73. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/controller_endpoint_factory.py +0 -0
  74. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/error_answer.py +0 -0
  75. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/rest_api.py +0 -0
  76. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/rest_controller.py +0 -0
  77. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/rest_controller_advice.py +0 -0
  78. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/rest_controller_errors.py +0 -0
  79. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/rest_controller_mappings.py +0 -0
  80. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/route_markers.py +0 -0
  81. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/rest/urls.py +0 -0
  82. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/testing/__init__.py +0 -0
  83. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/testing/declared_classes.py +0 -0
  84. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/testing/recording_transaction_manager.py +0 -0
  85. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/transaction/__init__.py +0 -0
  86. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/transaction/after_commit.py +0 -0
  87. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/transaction/transaction_manager.py +0 -0
  88. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/transaction/transaction_manager_not_installed_error.py +0 -0
  89. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/transaction/transaction_manager_registry.py +0 -0
  90. {snakeboot-0.5.2 → snakeboot-0.6.0}/src/snakeboot/transaction/transactional.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: snakeboot
3
- Version: 0.5.2
3
+ Version: 0.6.0
4
4
  Summary: Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan, typed configuration with profiles and singleton REST controllers on Django Ninja, wired by wireup.
5
5
  Keywords: spring-boot,hexagonal-architecture,ddd,django,django-ninja,wireup,dependency-injection,transactional
6
6
  Author: Wouter Deketelaere
@@ -27,6 +27,8 @@ Requires-Dist: django>=6.1.1 ; extra == 'oauth2'
27
27
  Requires-Dist: django-ninja>=1.7.1 ; extra == 'oauth2'
28
28
  Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'oauth2'
29
29
  Requires-Dist: pyjwt[crypto]>=2.10.1 ; extra == 'oauth2'
30
+ Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'rabbitmq'
31
+ Requires-Dist: pika>=1.3.2 ; extra == 'rabbitmq'
30
32
  Requires-Python: >=3.13
31
33
  Project-URL: Homepage, https://github.com/KdG-OCDI/snakeboot
32
34
  Project-URL: Repository, https://github.com/KdG-OCDI/snakeboot
@@ -36,6 +38,7 @@ Provides-Extra: configuration
36
38
  Provides-Extra: django
37
39
  Provides-Extra: ninja
38
40
  Provides-Extra: oauth2
41
+ Provides-Extra: rabbitmq
39
42
  Description-Content-Type: text/markdown
40
43
 
41
44
  # snakeboot
@@ -59,6 +62,9 @@ classes you can read in an afternoon, and none of them knows anything about your
59
62
  | `DjangoConfigurer` | `WebMvcConfigurer` | `snakeboot[configuration,django]` |
60
63
  | `BearerAuthentication` | a `SecurityFilterChain` bean | `snakeboot[ninja]` |
61
64
  | `JwtBearerAuthentication`, `OAuth2Properties` | `spring-boot-starter-oauth2-resource-server`, `spring.security.oauth2.resourceserver.jwt.*` | `snakeboot[oauth2]` |
65
+ | `Lifecycle`, `ApplicationReadyEvent`, `run_lifecycle` | `SmartLifecycle`, `ApplicationReadyEvent`, an application without the web starter | wireup |
66
+ | `@scheduled`, `SchedulingProperties` | `@Scheduled` | `snakeboot[configuration,django]` |
67
+ | `@rabbit_listener`, `RabbitTemplate`, `RabbitProperties`, `RejectAndDontRequeueError` | `@RabbitListener`, `RabbitTemplate`, `spring.rabbitmq.*`, `AmqpRejectAndDontRequeueException` | `snakeboot[rabbitmq]` |
62
68
  | `@openapi_definition` | springdoc's `@OpenAPIDefinition` | nothing |
63
69
  | `rest_api`, `snakeboot.rest.urls` | the REST API and `/health` of the application | `snakeboot[ninja]` |
64
70
  | `RecordingTransactionManager`, `declared_classes` | spring-test | nothing |
@@ -70,6 +76,7 @@ so the application layer of a hexagonal application can use `@transactional` wit
70
76
 
71
77
  ```bash
72
78
  uv add "snakeboot[configuration,django,ninja]"
79
+ uv add "snakeboot[configuration,django,ninja,rabbitmq]" # with RabbitMQ
73
80
  ```
74
81
 
75
82
  ## A tour
@@ -77,7 +84,7 @@ uv add "snakeboot[configuration,django,ninja]"
77
84
  **The application.** A class marked with `@application_root`, like `@SpringBootApplication`, is the application.
78
85
  Its component scan decides what goes into the container: the package of the class, or the packages `base_packages`
79
86
  names. The scan skips Django's entry points (`wsgi.py`, `asgi.py`, migrations) and adds the components snakeboot
80
- provides itself (the event publisher). `run` starts it, like `SpringApplication.run`.
87
+ provides itself (the event publisher, the lifecycle, the scheduler). `run` starts it, like `SpringApplication.run`.
81
88
 
82
89
  ```python
83
90
  # myapp/myapp_application.py
@@ -238,9 +245,68 @@ jwks_uri = "http://keycloak:8080/realms/kareldegames/protocol/openid-connect/cer
238
245
  audience = "tictactoe" # the `aud` the tokens must hold
239
246
  ```
240
247
 
248
+ **What runs beside the requests.** Django knows no moment "the server starts"; uvicorn does, and says so with ASGI's
249
+ `lifespan`, which `asgi_application` answers. Then every `Lifecycle` component starts, like a `SmartLifecycle` bean,
250
+ and `ApplicationReadyEvent` goes to the event listeners; when uvicorn stops, they stop. Management commands
251
+ (`migrate`), WSGI and the tests start nothing. `python -m myapp run_lifecycle` runs the same lifecycle without a web
252
+ server, until SIGTERM: a process that only listens and schedules, like Spring Boot without the web starter.
253
+
254
+ ```python
255
+ @application_event_listener
256
+ class RegisterOnStartup:
257
+ @event_listener(ApplicationReadyEvent) # once, when the application has started
258
+ def register(self, _event: ApplicationReadyEvent) -> None: ...
259
+ ```
260
+
261
+ **Scheduled methods.** `@scheduled` on a method of a component runs it periodically, like `@Scheduled`: with a fixed
262
+ rate or a fixed delay, on one thread, each run between fresh database connections. A method that raises is logged and
263
+ runs again at its next turn. `[scheduling] auto_startup = false` keeps a process from running them.
264
+
265
+ ```python
266
+ @injectable
267
+ class AbortExpiredGamesJob:
268
+ @scheduled(fixed_delay=timedelta(seconds=2))
269
+ def abort_expired_games(self) -> None: ...
270
+ ```
271
+
272
+ **RabbitMQ.** With the table `[rabbitmq]` (extra `snakeboot[rabbitmq]`, through pika), `@rabbit_listener` makes a
273
+ method of a component consume a queue, like `@RabbitListener` with `@QueueBinding`: the durable topic exchange, the
274
+ queue and the binding are declared at start-up, the JSON body becomes the pydantic model, `dict` or `bytes` the method
275
+ takes, and each listener has a thread and a connection of its own. Returning acknowledges the message;
276
+ `RejectAndDontRequeueError` or an unreadable body refuses it for good; another failure is tried three times, a second
277
+ apart, then refused, as Spring Boot's `retry.enabled` does. The `RabbitTemplate` sends persistent JSON, confirmed by the
278
+ broker. `[rabbitmq.listener] auto_startup = false` keeps a process from consuming. Under uvicorn every worker process
279
+ runs its own listeners and scheduled methods, like Spring's `concurrency`: RabbitMQ gives each message to one of them,
280
+ and a scheduled method runs once per process.
281
+
282
+ ```python
283
+ @injectable
284
+ class GameStartedListener:
285
+ def __init__(self, start_game: StartGameUseCase) -> None:
286
+ self._start_game = start_game
287
+
288
+ @rabbit_listener(queue="tictactoe.game-started", exchange="games", routing_key="game.tictactoe.started")
289
+ def on_game_started(self, message: GameStartedMessage) -> None: ... # a pydantic model
290
+
291
+
292
+ # an adapter that sends
293
+ self._rabbit.convert_and_send("games", "game.tictactoe.finished", event, message_id=f"{game_id}.finished")
294
+ ```
295
+
296
+ ```toml
297
+ [rabbitmq]
298
+ host = "rabbitmq"
299
+ port = 5672
300
+ username = "guest" # the password comes from RABBITMQ__PASSWORD
301
+ virtual_host = "/"
302
+
303
+ [rabbitmq.listener]
304
+ auto_startup = true
305
+ ```
306
+
241
307
  ## Design rules
242
308
 
243
- * Imitate the basics, not all of Spring: no AOP, no scheduling, no message brokers.
309
+ * Imitate the basics, not all of Spring: no AOP, no cron, no message broker other than RabbitMQ.
244
310
  * Fail at start-up, not at the first request: a broken controller, listener, root or configuration stops the application.
245
311
  * Each package knows as little as possible; `uv run lint-imports` enforces it.
246
312
 
@@ -19,6 +19,9 @@ classes you can read in an afternoon, and none of them knows anything about your
19
19
  | `DjangoConfigurer` | `WebMvcConfigurer` | `snakeboot[configuration,django]` |
20
20
  | `BearerAuthentication` | a `SecurityFilterChain` bean | `snakeboot[ninja]` |
21
21
  | `JwtBearerAuthentication`, `OAuth2Properties` | `spring-boot-starter-oauth2-resource-server`, `spring.security.oauth2.resourceserver.jwt.*` | `snakeboot[oauth2]` |
22
+ | `Lifecycle`, `ApplicationReadyEvent`, `run_lifecycle` | `SmartLifecycle`, `ApplicationReadyEvent`, an application without the web starter | wireup |
23
+ | `@scheduled`, `SchedulingProperties` | `@Scheduled` | `snakeboot[configuration,django]` |
24
+ | `@rabbit_listener`, `RabbitTemplate`, `RabbitProperties`, `RejectAndDontRequeueError` | `@RabbitListener`, `RabbitTemplate`, `spring.rabbitmq.*`, `AmqpRejectAndDontRequeueException` | `snakeboot[rabbitmq]` |
22
25
  | `@openapi_definition` | springdoc's `@OpenAPIDefinition` | nothing |
23
26
  | `rest_api`, `snakeboot.rest.urls` | the REST API and `/health` of the application | `snakeboot[ninja]` |
24
27
  | `RecordingTransactionManager`, `declared_classes` | spring-test | nothing |
@@ -30,6 +33,7 @@ so the application layer of a hexagonal application can use `@transactional` wit
30
33
 
31
34
  ```bash
32
35
  uv add "snakeboot[configuration,django,ninja]"
36
+ uv add "snakeboot[configuration,django,ninja,rabbitmq]" # with RabbitMQ
33
37
  ```
34
38
 
35
39
  ## A tour
@@ -37,7 +41,7 @@ uv add "snakeboot[configuration,django,ninja]"
37
41
  **The application.** A class marked with `@application_root`, like `@SpringBootApplication`, is the application.
38
42
  Its component scan decides what goes into the container: the package of the class, or the packages `base_packages`
39
43
  names. The scan skips Django's entry points (`wsgi.py`, `asgi.py`, migrations) and adds the components snakeboot
40
- provides itself (the event publisher). `run` starts it, like `SpringApplication.run`.
44
+ provides itself (the event publisher, the lifecycle, the scheduler). `run` starts it, like `SpringApplication.run`.
41
45
 
42
46
  ```python
43
47
  # myapp/myapp_application.py
@@ -198,9 +202,68 @@ jwks_uri = "http://keycloak:8080/realms/kareldegames/protocol/openid-connect/cer
198
202
  audience = "tictactoe" # the `aud` the tokens must hold
199
203
  ```
200
204
 
205
+ **What runs beside the requests.** Django knows no moment "the server starts"; uvicorn does, and says so with ASGI's
206
+ `lifespan`, which `asgi_application` answers. Then every `Lifecycle` component starts, like a `SmartLifecycle` bean,
207
+ and `ApplicationReadyEvent` goes to the event listeners; when uvicorn stops, they stop. Management commands
208
+ (`migrate`), WSGI and the tests start nothing. `python -m myapp run_lifecycle` runs the same lifecycle without a web
209
+ server, until SIGTERM: a process that only listens and schedules, like Spring Boot without the web starter.
210
+
211
+ ```python
212
+ @application_event_listener
213
+ class RegisterOnStartup:
214
+ @event_listener(ApplicationReadyEvent) # once, when the application has started
215
+ def register(self, _event: ApplicationReadyEvent) -> None: ...
216
+ ```
217
+
218
+ **Scheduled methods.** `@scheduled` on a method of a component runs it periodically, like `@Scheduled`: with a fixed
219
+ rate or a fixed delay, on one thread, each run between fresh database connections. A method that raises is logged and
220
+ runs again at its next turn. `[scheduling] auto_startup = false` keeps a process from running them.
221
+
222
+ ```python
223
+ @injectable
224
+ class AbortExpiredGamesJob:
225
+ @scheduled(fixed_delay=timedelta(seconds=2))
226
+ def abort_expired_games(self) -> None: ...
227
+ ```
228
+
229
+ **RabbitMQ.** With the table `[rabbitmq]` (extra `snakeboot[rabbitmq]`, through pika), `@rabbit_listener` makes a
230
+ method of a component consume a queue, like `@RabbitListener` with `@QueueBinding`: the durable topic exchange, the
231
+ queue and the binding are declared at start-up, the JSON body becomes the pydantic model, `dict` or `bytes` the method
232
+ takes, and each listener has a thread and a connection of its own. Returning acknowledges the message;
233
+ `RejectAndDontRequeueError` or an unreadable body refuses it for good; another failure is tried three times, a second
234
+ apart, then refused, as Spring Boot's `retry.enabled` does. The `RabbitTemplate` sends persistent JSON, confirmed by the
235
+ broker. `[rabbitmq.listener] auto_startup = false` keeps a process from consuming. Under uvicorn every worker process
236
+ runs its own listeners and scheduled methods, like Spring's `concurrency`: RabbitMQ gives each message to one of them,
237
+ and a scheduled method runs once per process.
238
+
239
+ ```python
240
+ @injectable
241
+ class GameStartedListener:
242
+ def __init__(self, start_game: StartGameUseCase) -> None:
243
+ self._start_game = start_game
244
+
245
+ @rabbit_listener(queue="tictactoe.game-started", exchange="games", routing_key="game.tictactoe.started")
246
+ def on_game_started(self, message: GameStartedMessage) -> None: ... # a pydantic model
247
+
248
+
249
+ # an adapter that sends
250
+ self._rabbit.convert_and_send("games", "game.tictactoe.finished", event, message_id=f"{game_id}.finished")
251
+ ```
252
+
253
+ ```toml
254
+ [rabbitmq]
255
+ host = "rabbitmq"
256
+ port = 5672
257
+ username = "guest" # the password comes from RABBITMQ__PASSWORD
258
+ virtual_host = "/"
259
+
260
+ [rabbitmq.listener]
261
+ auto_startup = true
262
+ ```
263
+
201
264
  ## Design rules
202
265
 
203
- * Imitate the basics, not all of Spring: no AOP, no scheduling, no message brokers.
266
+ * Imitate the basics, not all of Spring: no AOP, no cron, no message broker other than RabbitMQ.
204
267
  * Fail at start-up, not at the first request: a broken controller, listener, root or configuration stops the application.
205
268
  * Each package knows as little as possible; `uv run lint-imports` enforces it.
206
269
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "snakeboot"
3
- version = "0.5.2"
3
+ version = "0.6.0"
4
4
  description = "Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan, typed configuration with profiles and singleton REST controllers on Django Ninja, wired by wireup."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -54,6 +54,10 @@ oauth2 = [
54
54
  "pydantic-settings>=2.16.0,<3",
55
55
  "pyjwt[crypto]>=2.10.1",
56
56
  ]
57
+ rabbitmq = [
58
+ "pydantic-settings>=2.16.0,<3",
59
+ "pika>=1.3.2",
60
+ ]
57
61
 
58
62
  [build-system]
59
63
  requires = ["uv_build>=0.12.19,<0.13.0"]
@@ -66,6 +70,7 @@ dev = [
66
70
  "django-stubs>=6.1.2",
67
71
  "import-linter>=2.15",
68
72
  "mypy>=2.4.0",
73
+ "pika>=1.3.2",
69
74
  "pre-commit>=4.7.0",
70
75
  "pydantic-settings>=2.16.0,<3",
71
76
  "pyjwt[crypto]>=2.10.1",
@@ -90,6 +95,10 @@ name = "transaction knows no framework and no other part of snakeboot"
90
95
  type = "forbidden"
91
96
  source_modules = ["snakeboot.transaction"]
92
97
  forbidden_modules = [
98
+ "snakeboot.rabbitmq",
99
+ "pika",
100
+ "snakeboot.scheduling",
101
+ "snakeboot.lifecycle",
93
102
  "django",
94
103
  "ninja",
95
104
  "wireup",
@@ -111,6 +120,10 @@ name = "component_scan is standard library only, so settings can use it before D
111
120
  type = "forbidden"
112
121
  source_modules = ["snakeboot.component_scan"]
113
122
  forbidden_modules = [
123
+ "snakeboot.rabbitmq",
124
+ "pika",
125
+ "snakeboot.scheduling",
126
+ "snakeboot.lifecycle",
114
127
  "django",
115
128
  "ninja",
116
129
  "wireup",
@@ -132,6 +145,10 @@ name = "events knows wireup and transaction, but no web or ORM framework"
132
145
  type = "forbidden"
133
146
  source_modules = ["snakeboot.events"]
134
147
  forbidden_modules = [
148
+ "snakeboot.rabbitmq",
149
+ "pika",
150
+ "snakeboot.scheduling",
151
+ "snakeboot.lifecycle",
135
152
  "django",
136
153
  "ninja",
137
154
  "pydantic",
@@ -150,6 +167,10 @@ name = "rest knows Ninja, wireup and the component scan, but not the transaction
150
167
  type = "forbidden"
151
168
  source_modules = ["snakeboot.rest"]
152
169
  forbidden_modules = [
170
+ "snakeboot.rabbitmq",
171
+ "pika",
172
+ "snakeboot.scheduling",
173
+ "snakeboot.lifecycle",
153
174
  "snakeboot.configuration",
154
175
  "snakeboot.transaction",
155
176
  "snakeboot.events",
@@ -165,6 +186,10 @@ name = "django adapts transaction to Django, nothing else"
165
186
  type = "forbidden"
166
187
  source_modules = ["snakeboot.django"]
167
188
  forbidden_modules = [
189
+ "snakeboot.rabbitmq",
190
+ "pika",
191
+ "snakeboot.scheduling",
192
+ "snakeboot.lifecycle",
168
193
  "ninja",
169
194
  "wireup",
170
195
  "snakeboot.configuration",
@@ -182,6 +207,10 @@ name = "testing helpers run without a framework"
182
207
  type = "forbidden"
183
208
  source_modules = ["snakeboot.testing"]
184
209
  forbidden_modules = [
210
+ "snakeboot.rabbitmq",
211
+ "pika",
212
+ "snakeboot.scheduling",
213
+ "snakeboot.lifecycle",
185
214
  "django",
186
215
  "ninja",
187
216
  "wireup",
@@ -201,6 +230,10 @@ name = "configuration knows Pydantic Settings and wireup, but no web or ORM fram
201
230
  type = "forbidden"
202
231
  source_modules = ["snakeboot.configuration"]
203
232
  forbidden_modules = [
233
+ "snakeboot.rabbitmq",
234
+ "pika",
235
+ "snakeboot.scheduling",
236
+ "snakeboot.lifecycle",
204
237
  "django",
205
238
  "ninja",
206
239
  "snakeboot.transaction",
@@ -215,10 +248,13 @@ forbidden_modules = [
215
248
  ]
216
249
 
217
250
  [[tool.importlinter.contracts]]
218
- name = "django_application starts the container, the configuration and the transactions on Django, and nothing else"
251
+ name = "django_application starts the container, the configuration, the transactions and the lifecycle on Django, and nothing else"
219
252
  type = "forbidden"
220
253
  source_modules = ["snakeboot.django_application"]
221
254
  forbidden_modules = [
255
+ "snakeboot.rabbitmq",
256
+ "pika",
257
+ "snakeboot.scheduling",
222
258
  "ninja",
223
259
  "snakeboot.events",
224
260
  "snakeboot.rest",
@@ -232,6 +268,10 @@ name = "openapi is standard library only, so an application class can use it bef
232
268
  type = "forbidden"
233
269
  source_modules = ["snakeboot.openapi"]
234
270
  forbidden_modules = [
271
+ "snakeboot.rabbitmq",
272
+ "pika",
273
+ "snakeboot.scheduling",
274
+ "snakeboot.lifecycle",
235
275
  "django",
236
276
  "ninja",
237
277
  "wireup",
@@ -254,6 +294,10 @@ name = "oauth2 knows the REST library, the configuration and PyJWT, but no ORM,
254
294
  type = "forbidden"
255
295
  source_modules = ["snakeboot.oauth2"]
256
296
  forbidden_modules = [
297
+ "snakeboot.rabbitmq",
298
+ "pika",
299
+ "snakeboot.scheduling",
300
+ "snakeboot.lifecycle",
257
301
  "snakeboot.transaction",
258
302
  "snakeboot.events",
259
303
  "snakeboot.django",
@@ -261,6 +305,60 @@ forbidden_modules = [
261
305
  "snakeboot.testing",
262
306
  ]
263
307
 
308
+ [[tool.importlinter.contracts]]
309
+ name = "lifecycle knows wireup, the event library and the component scan, but no web or ORM framework"
310
+ type = "forbidden"
311
+ source_modules = ["snakeboot.lifecycle"]
312
+ forbidden_modules = [
313
+ "snakeboot.rabbitmq",
314
+ "pika",
315
+ "snakeboot.scheduling",
316
+ "django",
317
+ "ninja",
318
+ "pydantic",
319
+ "pydantic_settings",
320
+ "snakeboot.configuration",
321
+ "snakeboot.rest",
322
+ "snakeboot.django",
323
+ "snakeboot.django_application",
324
+ "snakeboot.testing",
325
+ "snakeboot.oauth2",
326
+ "jwt",
327
+ ]
328
+
329
+ [[tool.importlinter.contracts]]
330
+ name = "scheduling knows wireup, the lifecycle and the configuration, but no web or ORM framework"
331
+ type = "forbidden"
332
+ source_modules = ["snakeboot.scheduling"]
333
+ forbidden_modules = [
334
+ "snakeboot.rabbitmq",
335
+ "pika",
336
+ "django",
337
+ "ninja",
338
+ "snakeboot.rest",
339
+ "snakeboot.django",
340
+ "snakeboot.django_application",
341
+ "snakeboot.testing",
342
+ "snakeboot.oauth2",
343
+ "jwt",
344
+ ]
345
+
346
+ [[tool.importlinter.contracts]]
347
+ name = "rabbitmq knows pika, Pydantic, wireup, the lifecycle and the configuration, but no web or ORM framework"
348
+ type = "forbidden"
349
+ source_modules = ["snakeboot.rabbitmq"]
350
+ forbidden_modules = [
351
+ "django",
352
+ "ninja",
353
+ "snakeboot.rest",
354
+ "snakeboot.django",
355
+ "snakeboot.django_application",
356
+ "snakeboot.scheduling",
357
+ "snakeboot.testing",
358
+ "snakeboot.oauth2",
359
+ "jwt",
360
+ ]
361
+
264
362
  [tool.ruff]
265
363
  line-length = 120
266
364
  target-version = "py313"
@@ -345,5 +443,16 @@ enable_error_code = [
345
443
  ]
346
444
  plugins = ["mypy_django_plugin.main"]
347
445
 
446
+ [[tool.mypy.overrides]]
447
+ module = [
448
+ "pika",
449
+ "pika.*",
450
+ ]
451
+ ignore_missing_imports = true
452
+
453
+ [[tool.mypy.overrides]]
454
+ module = ["tests.lifecycle.test_lifecycle_asgi_application"]
455
+ disallow_untyped_calls = false
456
+
348
457
  [tool.django-stubs]
349
458
  django_settings_module = "tests.django_settings"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "snakeboot"
3
- version = "0.5.2"
3
+ version = "0.6.0"
4
4
  description = "Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan, typed configuration with profiles and singleton REST controllers on Django Ninja, wired by wireup."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -42,6 +42,8 @@ ninja = ["django>=6.1.1", "django-ninja>=1.7.1"]
42
42
  configuration = ["pydantic-settings>=2.16.0,<3"]
43
43
  # Accept the JWT access tokens of an OAuth2 authorization server, such as Keycloak (snakeboot.oauth2).
44
44
  oauth2 = ["django>=6.1.1", "django-ninja>=1.7.1", "pydantic-settings>=2.16.0,<3", "pyjwt[crypto]>=2.10.1"]
45
+ # @rabbit_listener methods and a RabbitTemplate on RabbitMQ, through pika (snakeboot.rabbitmq).
46
+ rabbitmq = ["pydantic-settings>=2.16.0,<3", "pika>=1.3.2"]
45
47
 
46
48
  [build-system]
47
49
  requires = ["uv_build>=0.12.19,<0.13.0"]
@@ -54,6 +56,7 @@ dev = [
54
56
  "django-stubs>=6.1.2",
55
57
  "import-linter>=2.15",
56
58
  "mypy>=2.4.0",
59
+ "pika>=1.3.2",
57
60
  "pre-commit>=4.7.0",
58
61
  "pydantic-settings>=2.16.0,<3",
59
62
  "pyjwt[crypto]>=2.10.1",
@@ -83,6 +86,10 @@ name = "transaction knows no framework and no other part of snakeboot"
83
86
  type = "forbidden"
84
87
  source_modules = ["snakeboot.transaction"]
85
88
  forbidden_modules = [
89
+ "snakeboot.rabbitmq",
90
+ "pika",
91
+ "snakeboot.scheduling",
92
+ "snakeboot.lifecycle",
86
93
  "django",
87
94
  "ninja",
88
95
  "wireup",
@@ -104,6 +111,10 @@ name = "component_scan is standard library only, so settings can use it before D
104
111
  type = "forbidden"
105
112
  source_modules = ["snakeboot.component_scan"]
106
113
  forbidden_modules = [
114
+ "snakeboot.rabbitmq",
115
+ "pika",
116
+ "snakeboot.scheduling",
117
+ "snakeboot.lifecycle",
107
118
  "django",
108
119
  "ninja",
109
120
  "wireup",
@@ -125,6 +136,10 @@ name = "events knows wireup and transaction, but no web or ORM framework"
125
136
  type = "forbidden"
126
137
  source_modules = ["snakeboot.events"]
127
138
  forbidden_modules = [
139
+ "snakeboot.rabbitmq",
140
+ "pika",
141
+ "snakeboot.scheduling",
142
+ "snakeboot.lifecycle",
128
143
  "django",
129
144
  "ninja",
130
145
  "pydantic",
@@ -143,6 +158,10 @@ name = "rest knows Ninja, wireup and the component scan, but not the transaction
143
158
  type = "forbidden"
144
159
  source_modules = ["snakeboot.rest"]
145
160
  forbidden_modules = [
161
+ "snakeboot.rabbitmq",
162
+ "pika",
163
+ "snakeboot.scheduling",
164
+ "snakeboot.lifecycle",
146
165
  "snakeboot.configuration",
147
166
  "snakeboot.transaction",
148
167
  "snakeboot.events",
@@ -158,6 +177,10 @@ name = "django adapts transaction to Django, nothing else"
158
177
  type = "forbidden"
159
178
  source_modules = ["snakeboot.django"]
160
179
  forbidden_modules = [
180
+ "snakeboot.rabbitmq",
181
+ "pika",
182
+ "snakeboot.scheduling",
183
+ "snakeboot.lifecycle",
161
184
  "ninja",
162
185
  "wireup",
163
186
  "snakeboot.configuration",
@@ -175,6 +198,10 @@ name = "testing helpers run without a framework"
175
198
  type = "forbidden"
176
199
  source_modules = ["snakeboot.testing"]
177
200
  forbidden_modules = [
201
+ "snakeboot.rabbitmq",
202
+ "pika",
203
+ "snakeboot.scheduling",
204
+ "snakeboot.lifecycle",
178
205
  "django",
179
206
  "ninja",
180
207
  "wireup",
@@ -194,6 +221,10 @@ name = "configuration knows Pydantic Settings and wireup, but no web or ORM fram
194
221
  type = "forbidden"
195
222
  source_modules = ["snakeboot.configuration"]
196
223
  forbidden_modules = [
224
+ "snakeboot.rabbitmq",
225
+ "pika",
226
+ "snakeboot.scheduling",
227
+ "snakeboot.lifecycle",
197
228
  "django",
198
229
  "ninja",
199
230
  "snakeboot.transaction",
@@ -208,10 +239,13 @@ forbidden_modules = [
208
239
  ]
209
240
 
210
241
  [[tool.importlinter.contracts]]
211
- name = "django_application starts the container, the configuration and the transactions on Django, and nothing else"
242
+ name = "django_application starts the container, the configuration, the transactions and the lifecycle on Django, and nothing else"
212
243
  type = "forbidden"
213
244
  source_modules = ["snakeboot.django_application"]
214
245
  forbidden_modules = [
246
+ "snakeboot.rabbitmq",
247
+ "pika",
248
+ "snakeboot.scheduling",
215
249
  "ninja",
216
250
  "snakeboot.events",
217
251
  "snakeboot.rest",
@@ -225,6 +259,10 @@ name = "openapi is standard library only, so an application class can use it bef
225
259
  type = "forbidden"
226
260
  source_modules = ["snakeboot.openapi"]
227
261
  forbidden_modules = [
262
+ "snakeboot.rabbitmq",
263
+ "pika",
264
+ "snakeboot.scheduling",
265
+ "snakeboot.lifecycle",
228
266
  "django",
229
267
  "ninja",
230
268
  "wireup",
@@ -247,6 +285,10 @@ name = "oauth2 knows the REST library, the configuration and PyJWT, but no ORM,
247
285
  type = "forbidden"
248
286
  source_modules = ["snakeboot.oauth2"]
249
287
  forbidden_modules = [
288
+ "snakeboot.rabbitmq",
289
+ "pika",
290
+ "snakeboot.scheduling",
291
+ "snakeboot.lifecycle",
250
292
  "snakeboot.transaction",
251
293
  "snakeboot.events",
252
294
  "snakeboot.django",
@@ -254,6 +296,60 @@ forbidden_modules = [
254
296
  "snakeboot.testing",
255
297
  ]
256
298
 
299
+ [[tool.importlinter.contracts]]
300
+ name = "lifecycle knows wireup, the event library and the component scan, but no web or ORM framework"
301
+ type = "forbidden"
302
+ source_modules = ["snakeboot.lifecycle"]
303
+ forbidden_modules = [
304
+ "snakeboot.rabbitmq",
305
+ "pika",
306
+ "snakeboot.scheduling",
307
+ "django",
308
+ "ninja",
309
+ "pydantic",
310
+ "pydantic_settings",
311
+ "snakeboot.configuration",
312
+ "snakeboot.rest",
313
+ "snakeboot.django",
314
+ "snakeboot.django_application",
315
+ "snakeboot.testing",
316
+ "snakeboot.oauth2",
317
+ "jwt",
318
+ ]
319
+
320
+ [[tool.importlinter.contracts]]
321
+ name = "scheduling knows wireup, the lifecycle and the configuration, but no web or ORM framework"
322
+ type = "forbidden"
323
+ source_modules = ["snakeboot.scheduling"]
324
+ forbidden_modules = [
325
+ "snakeboot.rabbitmq",
326
+ "pika",
327
+ "django",
328
+ "ninja",
329
+ "snakeboot.rest",
330
+ "snakeboot.django",
331
+ "snakeboot.django_application",
332
+ "snakeboot.testing",
333
+ "snakeboot.oauth2",
334
+ "jwt",
335
+ ]
336
+
337
+ [[tool.importlinter.contracts]]
338
+ name = "rabbitmq knows pika, Pydantic, wireup, the lifecycle and the configuration, but no web or ORM framework"
339
+ type = "forbidden"
340
+ source_modules = ["snakeboot.rabbitmq"]
341
+ forbidden_modules = [
342
+ "django",
343
+ "ninja",
344
+ "snakeboot.rest",
345
+ "snakeboot.django",
346
+ "snakeboot.django_application",
347
+ "snakeboot.scheduling",
348
+ "snakeboot.testing",
349
+ "snakeboot.oauth2",
350
+ "jwt",
351
+ ]
352
+
257
353
  # ---------------------------------------------------------------------------
258
354
  # Code contracts: the Clean Code rules in AGENTS.md, enforced by Ruff and mypy.
259
355
  # ---------------------------------------------------------------------------
@@ -297,5 +393,15 @@ explicit_package_bases = true
297
393
  enable_error_code = ["explicit-override", "ignore-without-code", "redundant-expr", "truthy-bool", "possibly-undefined"]
298
394
  plugins = ["mypy_django_plugin.main"]
299
395
 
396
+ [[tool.mypy.overrides]]
397
+ # pika has annotations, but no py.typed marker.
398
+ module = ["pika", "pika.*"]
399
+ ignore_missing_imports = true
400
+
401
+ [[tool.mypy.overrides]]
402
+ # asgiref.testing.ApplicationCommunicator, which drives an ASGI application in the lifespan tests, has no annotations.
403
+ module = ["tests.lifecycle.test_lifecycle_asgi_application"]
404
+ disallow_untyped_calls = false
405
+
300
406
  [tool.django-stubs]
301
407
  django_settings_module = "tests.django_settings"
@@ -7,7 +7,8 @@
7
7
  WIREUP = WireupSettings(injectables=[*ComponentScan.of(MyApplication).module_names()])
8
8
 
9
9
  Standard library only: it finds module names without importing them, so settings can use it
10
- before Django has started.
10
+ before Django has started. Once Django has started, `classes_marked` and `methods_marked` find what
11
+ decorators marked, like Spring's `MethodIntrospector`.
11
12
  """
12
13
 
13
14
  from snakeboot.component_scan.application_root import application_package, application_root
@@ -16,6 +17,7 @@ from snakeboot.component_scan.component_scan import (
16
17
  SNAKEBOOT_AUTO_CONFIGURATION,
17
18
  ComponentScan,
18
19
  InvalidApplicationRootError,
20
+ MarkedMethod,
19
21
  )
20
22
 
21
23
  __all__ = [
@@ -23,6 +25,7 @@ __all__ = [
23
25
  "SNAKEBOOT_AUTO_CONFIGURATION",
24
26
  "ComponentScan",
25
27
  "InvalidApplicationRootError",
28
+ "MarkedMethod",
26
29
  "application_package",
27
30
  "application_root",
28
31
  ]