django-neolith 0.1.0a1__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.
- django_neolith-0.1.0a1/.gitignore +12 -0
- django_neolith-0.1.0a1/CHANGELOG.md +30 -0
- django_neolith-0.1.0a1/CODE_OF_CONDUCT.md +89 -0
- django_neolith-0.1.0a1/CONTRIBUTING.md +134 -0
- django_neolith-0.1.0a1/LICENSE +29 -0
- django_neolith-0.1.0a1/PKG-INFO +199 -0
- django_neolith-0.1.0a1/README.md +171 -0
- django_neolith-0.1.0a1/VISION.md +47 -0
- django_neolith-0.1.0a1/docs/adr/0001-record-architecture-decisions.md +24 -0
- django_neolith-0.1.0a1/docs/adr/0002-django-app-is-the-unit-of-deployment.md +31 -0
- django_neolith-0.1.0a1/docs/adr/0003-apps-communicate-through-contracts.md +31 -0
- django_neolith-0.1.0a1/docs/adr/0004-each-app-owns-its-data.md +33 -0
- django_neolith-0.1.0a1/docs/adr/0005-small-required-core.md +28 -0
- django_neolith-0.1.0a1/docs/adr/0006-contracts-are-typed-and-published-as-openapi.md +28 -0
- django_neolith-0.1.0a1/docs/adr/0007-in-process-transport-serializes.md +47 -0
- django_neolith-0.1.0a1/docs/adr/0008-typed-contract-errors-in-both-modes.md +64 -0
- django_neolith-0.1.0a1/docs/adr/0009-one-database-alias-per-app.md +179 -0
- django_neolith-0.1.0a1/docs/adr/0010-pluggable-principal-resolution.md +56 -0
- django_neolith-0.1.0a1/docs/adr/0011-django-ninja-for-contract-endpoints.md +26 -0
- django_neolith-0.1.0a1/docs/adr/0012-supported-python-and-django-versions.md +35 -0
- django_neolith-0.1.0a1/docs/adr/0013-license.md +26 -0
- django_neolith-0.1.0a1/docs/adr/0014-pluggable-connector-transports.md +36 -0
- django_neolith-0.1.0a1/docs/adr/0015-specification-first-django-reference-implementation.md +32 -0
- django_neolith-0.1.0a1/docs/adr/0016-an-app-may-run-attached-and-detached-at-once.md +32 -0
- django_neolith-0.1.0a1/docs/adr/0017-call-context-explicit-at-the-action-ambient-for-propagation.md +238 -0
- django_neolith-0.1.0a1/docs/adr/0018-requirement-ids-and-spec-to-test-traceability.md +64 -0
- django_neolith-0.1.0a1/docs/adr/0019-wire-encodings-of-the-portable-forms.md +54 -0
- django_neolith-0.1.0a1/docs/adr/0020-wire-forms-pydantic-writes-otherwise-are-neolith-annotated-types.md +45 -0
- django_neolith-0.1.0a1/docs/adr/0021-an-app-declares-itself-on-its-neolithappconfig.md +432 -0
- django_neolith-0.1.0a1/docs/adr/0022-the-app-host-builds-settings-and-checks-before-it-serves.md +267 -0
- django_neolith-0.1.0a1/docs/adr/0023-a-request-principal-comes-from-ordered-backends.md +428 -0
- django_neolith-0.1.0a1/docs/adr/0024-user-documentation-is-built-with-sphinx-from-this-repository.md +46 -0
- django_neolith-0.1.0a1/docs/adr/README.md +41 -0
- django_neolith-0.1.0a1/docs/adr/template.md +21 -0
- django_neolith-0.1.0a1/docs/assets/neolith-wordmark-dark.svg +18 -0
- django_neolith-0.1.0a1/docs/assets/neolith-wordmark-light.svg +18 -0
- django_neolith-0.1.0a1/docs/django-host.md +45 -0
- django_neolith-0.1.0a1/docs/open-questions.md +24 -0
- django_neolith-0.1.0a1/docs/principles.md +55 -0
- django_neolith-0.1.0a1/docs/roadmap.md +73 -0
- django_neolith-0.1.0a1/docs/site/_ext/neolith_docs.py +509 -0
- django_neolith-0.1.0a1/docs/site/_templates/neolith-footer.html +1 -0
- django_neolith-0.1.0a1/docs/site/concepts/index.md +30 -0
- django_neolith-0.1.0a1/docs/site/conf.py +88 -0
- django_neolith-0.1.0a1/docs/site/index.md +33 -0
- django_neolith-0.1.0a1/docs/site/project/index.md +14 -0
- django_neolith-0.1.0a1/docs/site/reference/index.md +13 -0
- django_neolith-0.1.0a1/pyproject.toml +190 -0
- django_neolith-0.1.0a1/scripts/__init__.py +1 -0
- django_neolith-0.1.0a1/scripts/bench_send.py +131 -0
- django_neolith-0.1.0a1/scripts/citations.py +164 -0
- django_neolith-0.1.0a1/scripts/docs.py +1452 -0
- django_neolith-0.1.0a1/scripts/spec_trace.py +633 -0
- django_neolith-0.1.0a1/scripts/spec_trace_plugin.py +138 -0
- django_neolith-0.1.0a1/spec/00-overview.md +55 -0
- django_neolith-0.1.0a1/spec/01-contracts.md +173 -0
- django_neolith-0.1.0a1/spec/02-transports.md +216 -0
- django_neolith-0.1.0a1/spec/03-http-transport.md +131 -0
- django_neolith-0.1.0a1/spec/04-events.md +9 -0
- django_neolith-0.1.0a1/spec/05-app-declaration.md +133 -0
- django_neolith-0.1.0a1/spec/06-conformance.md +19 -0
- django_neolith-0.1.0a1/spec/README.md +24 -0
- django_neolith-0.1.0a1/src/neolith/__init__.py +40 -0
- django_neolith-0.1.0a1/src/neolith/_checker.py +325 -0
- django_neolith-0.1.0a1/src/neolith/_checks.py +362 -0
- django_neolith-0.1.0a1/src/neolith/_compat.py +10 -0
- django_neolith-0.1.0a1/src/neolith/_connector.py +687 -0
- django_neolith-0.1.0a1/src/neolith/_context.py +852 -0
- django_neolith-0.1.0a1/src/neolith/_contracts.py +1134 -0
- django_neolith-0.1.0a1/src/neolith/_crossing.py +548 -0
- django_neolith-0.1.0a1/src/neolith/_declaration.py +777 -0
- django_neolith-0.1.0a1/src/neolith/_forms.py +322 -0
- django_neolith-0.1.0a1/src/neolith/_host.py +917 -0
- django_neolith-0.1.0a1/src/neolith/_jcs.py +235 -0
- django_neolith-0.1.0a1/src/neolith/_portable.py +1475 -0
- django_neolith-0.1.0a1/src/neolith/_serving.py +199 -0
- django_neolith-0.1.0a1/src/neolith/apps.py +8 -0
- django_neolith-0.1.0a1/src/neolith/middleware.py +336 -0
- django_neolith-0.1.0a1/src/neolith/py.typed +0 -0
- django_neolith-0.1.0a1/src/neolith/routers.py +88 -0
- django_neolith-0.1.0a1/tests/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/__init__.py +13 -0
- django_neolith-0.1.0a1/tests/app_db/archive/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/archive/apps.py +7 -0
- django_neolith-0.1.0a1/tests/app_db/billing/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/billing/apps.py +7 -0
- django_neolith-0.1.0a1/tests/app_db/billing/migrations/0001_initial.py +27 -0
- django_neolith-0.1.0a1/tests/app_db/billing/migrations/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/billing/models.py +8 -0
- django_neolith-0.1.0a1/tests/app_db/ledger/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/ledger/apps.py +7 -0
- django_neolith-0.1.0a1/tests/app_db/ledger/migrations/0001_initial.py +69 -0
- django_neolith-0.1.0a1/tests/app_db/ledger/migrations/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/ledger/models.py +24 -0
- django_neolith-0.1.0a1/tests/app_db/legacy/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/legacy/apps.py +7 -0
- django_neolith-0.1.0a1/tests/app_db/legacy/migrations/0001_initial.py +39 -0
- django_neolith-0.1.0a1/tests/app_db/legacy/migrations/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/legacy/models.py +12 -0
- django_neolith-0.1.0a1/tests/app_db/notes/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/notes/apps.py +6 -0
- django_neolith-0.1.0a1/tests/app_db/short_names/__init__.py +3 -0
- django_neolith-0.1.0a1/tests/app_db/short_names/base.py +12 -0
- django_neolith-0.1.0a1/tests/app_db/stray/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/app_db/stray/apps.py +6 -0
- django_neolith-0.1.0a1/tests/app_db/stray/models.py +10 -0
- django_neolith-0.1.0a1/tests/broken_middleware.py +3 -0
- django_neolith-0.1.0a1/tests/conftest.py +49 -0
- django_neolith-0.1.0a1/tests/data/jcs_vectors.js +66 -0
- django_neolith-0.1.0a1/tests/data/jcs_vectors.json +677 -0
- django_neolith-0.1.0a1/tests/declaration_contracts.py +57 -0
- django_neolith-0.1.0a1/tests/host_apps/__init__.py +12 -0
- django_neolith-0.1.0a1/tests/host_apps/couriers/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/host_apps/couriers/apps.py +14 -0
- django_neolith-0.1.0a1/tests/host_apps/couriers/services.py +24 -0
- django_neolith-0.1.0a1/tests/host_apps/stock/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/host_apps/stock/apps.py +16 -0
- django_neolith-0.1.0a1/tests/host_apps/stock/services.py +13 -0
- django_neolith-0.1.0a1/tests/host_apps/stock/views.py +36 -0
- django_neolith-0.1.0a1/tests/host_apps/web/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/host_apps/web/apps.py +8 -0
- django_neolith-0.1.0a1/tests/host_apps/web/views.py +232 -0
- django_neolith-0.1.0a1/tests/hosting.py +64 -0
- django_neolith-0.1.0a1/tests/plain_app/__init__.py +1 -0
- django_neolith-0.1.0a1/tests/plain_app/views.py +9 -0
- django_neolith-0.1.0a1/tests/request_admin/__init__.py +3 -0
- django_neolith-0.1.0a1/tests/request_admin/depot/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/request_admin/depot/admin.py +11 -0
- django_neolith-0.1.0a1/tests/request_admin/depot/apps.py +9 -0
- django_neolith-0.1.0a1/tests/request_admin/depot/models.py +19 -0
- django_neolith-0.1.0a1/tests/request_admin/project_admin.py +38 -0
- django_neolith-0.1.0a1/tests/request_admin/shop/__init__.py +0 -0
- django_neolith-0.1.0a1/tests/request_admin/shop/admin.py +35 -0
- django_neolith-0.1.0a1/tests/request_admin/shop/apps.py +9 -0
- django_neolith-0.1.0a1/tests/request_admin/shop/feeds.py +11 -0
- django_neolith-0.1.0a1/tests/request_admin/shop/models.py +57 -0
- django_neolith-0.1.0a1/tests/request_admin/shop/views.py +9 -0
- django_neolith-0.1.0a1/tests/request_admin/urls.py +6 -0
- django_neolith-0.1.0a1/tests/request_site.py +181 -0
- django_neolith-0.1.0a1/tests/request_urls.py +66 -0
- django_neolith-0.1.0a1/tests/settings.py +16 -0
- django_neolith-0.1.0a1/tests/spec_trace.toml +21 -0
- django_neolith-0.1.0a1/tests/strategies.py +73 -0
- django_neolith-0.1.0a1/tests/test_api_docs.py +1216 -0
- django_neolith-0.1.0a1/tests/test_app_database.py +1184 -0
- django_neolith-0.1.0a1/tests/test_call_context.py +2150 -0
- django_neolith-0.1.0a1/tests/test_calling_app.py +590 -0
- django_neolith-0.1.0a1/tests/test_command_scope.py +1234 -0
- django_neolith-0.1.0a1/tests/test_connector.py +829 -0
- django_neolith-0.1.0a1/tests/test_contract_round_trip.py +502 -0
- django_neolith-0.1.0a1/tests/test_contracts.py +2364 -0
- django_neolith-0.1.0a1/tests/test_contracts_red_team.py +723 -0
- django_neolith-0.1.0a1/tests/test_crossing.py +1565 -0
- django_neolith-0.1.0a1/tests/test_declaration.py +1816 -0
- django_neolith-0.1.0a1/tests/test_docs.py +1620 -0
- django_neolith-0.1.0a1/tests/test_error_delivery.py +668 -0
- django_neolith-0.1.0a1/tests/test_errors.py +1247 -0
- django_neolith-0.1.0a1/tests/test_host.py +1435 -0
- django_neolith-0.1.0a1/tests/test_host_checks.py +286 -0
- django_neolith-0.1.0a1/tests/test_jcs.py +383 -0
- django_neolith-0.1.0a1/tests/test_package.py +160 -0
- django_neolith-0.1.0a1/tests/test_principal.py +424 -0
- django_neolith-0.1.0a1/tests/test_readme.py +177 -0
- django_neolith-0.1.0a1/tests/test_request_admin.py +512 -0
- django_neolith-0.1.0a1/tests/test_request_root.py +1449 -0
- django_neolith-0.1.0a1/tests/test_send_side_check.py +2261 -0
- django_neolith-0.1.0a1/tests/test_spec_trace.py +742 -0
- django_neolith-0.1.0a1/tests/test_spec_trace_plugin.py +321 -0
- django_neolith-0.1.0a1/tests/test_wire_encodings.py +1024 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are recorded in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0, a minor release may contain breaking changes; each one is listed under *Changed* or *Removed* and never made silently.
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.1.0a1] - 2026-11-16
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Contracts (spec 01): `@contract` on a `Protocol` class, `@action` with `idempotent=`, `@implements`, and `Contract.of(...)` with a neutral description of the actions and their JSON Schemas. Identities, action names, request and reply types and implementations are checked when the module is imported, and fail with `ContractDefinitionError`.
|
|
14
|
+
- Contract errors (spec 01, [ADR 0008](docs/adr/0008-typed-contract-errors-in-both-modes.md)): `ContractError` with a `kind`, a `message` and a detail in `data`, and `@action(errors={...})` to declare an action's own error kinds with their detail records. Declared kinds are checked when the contract is declared, may not use a standard or reserved kind's name, and appear in the neutral description. A kind the receiver does not know is held with an untyped, read-only detail.
|
|
15
|
+
- `Action` gains `errors`, a frozen mapping from each declared kind to its detail record, empty by default.
|
|
16
|
+
- `@action` marks a method once, and implementation methods are not marked, including through wrappers such as `functools.cache` or `property`. `@implements` reads the implementation class statically, so it never evaluates a lazy attribute.
|
|
17
|
+
- Wire encodings (spec 01, [ADR 0019](docs/adr/0019-wire-encodings-of-the-portable-forms.md)): the neutral description states each form's range or pattern. Integers are limited to ±(2^53 − 1) and numbers to the finite doubles. `neolith.Duration`, `neolith.Decimal128` and `neolith.Binary` ([ADR 0020](docs/adr/0020-wire-forms-pydantic-writes-otherwise-are-neolith-annotated-types.md)) are `Annotated` types for durations, decimals and bytes that read and write exactly their wire forms (`"1.500s"`, `"-12.50"`, `"_w=="`); a plain `timedelta`, `Decimal` or `bytes` field is refused, naming the type to use. `Binary` reads base64url from JSON text only, so a receiver validates the text itself (`model_validate_json`). A default is refused unless Pydantic writes it in its form.
|
|
18
|
+
- The call context ([ADR 0017](docs/adr/0017-call-context-explicit-at-the-action-ambient-for-propagation.md)): `neolith.CallContext`, a frozen value with the principal, the trace, the deadline, the idempotency key and the calling app of one call, and `neolith.Principal`, a frozen issuer, subject and claims. An implementation's action that reads the context takes it after the request, as `(self, request, ctx: CallContext)`; `@implements` accepts that shape and `(self, request)`, and no other.
|
|
19
|
+
- App declaration (spec 05, [ADR 0021](docs/adr/0021-an-app-declares-itself-on-its-neolithappconfig.md)): `NeolithAppConfig`, whose subclass declares an app in class attributes: `name`, `label` (the app's name), and optionally `provides`, `requires`, `resources` and `batteries`, each a tuple. `Provided(<contract class>, implementation="<module>.<Class>", principal_from=(...))` is one entry of `provides`, with the calling apps that may assert a principal. The class is checked when it is defined, and `DeclarationError`, a subclass of Django's `ImproperlyConfigured`, lists every refusal of one class. A config class holds no other public name and cannot be subclassed once it declares. A declared app in Django's global registry needs `"neolith"` in `INSTALLED_APPS`.
|
|
20
|
+
- The host's set-up (spec 05, [ADR 0021](docs/adr/0021-an-app-declares-itself-on-its-neolithappconfig.md), [ADR 0022](docs/adr/0022-the-app-host-builds-settings-and-checks-before-it-serves.md)): `"neolith"` is an installed app whose `ready()` resolves every hosted app's `requires` to a provider in the host and validates every provided contract's implementation: imported by its own `<module>.<Class>` path inside the providing app, checked against the contract and built once with no arguments. Every refusal, with each unknown identity that `connect()` was asked for, is listed in one `DeclarationError`. A later set-up with the same hosted apps builds a fresh table, and one with other hosted apps is refused.
|
|
21
|
+
- `neolith.connect("<contract>.v<N>")` returns a `neolith.Connector` that holds only its identity and may be made at import. Only `connect()` makes one: the class cannot be called or subclassed. A call through it is `neolith.UsageError`, a `RuntimeError`, until set-up has passed, as is an identity the host does not know once it is set up.
|
|
22
|
+
- The calling app (spec 02, [ADR 0017](docs/adr/0017-call-context-explicit-at-the-action-ambient-for-propagation.md) Decision 6, [ADR 0021](docs/adr/0021-an-app-declares-itself-on-its-neolithappconfig.md) Decision 9): a call from a scope whose app does not require the contract is `neolith.UsageError` before its principal is resolved, and an app with no declaration requires nothing. In-process, the provider's side refuses a call from no app with `unauthenticated`, and one carrying a principal from a calling app its `principal_from` does not list with `permission_denied`, before the action runs; a call with no principal is not checked against the list. A connector call made in no scope, or in one that has closed, raises `neolith.UsageError` instead of a plain `RuntimeError`.
|
|
23
|
+
- The command scope (spec 02, [ADR 0022](docs/adr/0022-the-app-host-builds-settings-and-checks-before-it-serves.md) Decision 8): `with neolith.command_scope("<label>", principal=..., timeout=...):` opens a root for a hosted app, for a command or background work. Its calls call as that app, with the principal given and a deadline only when a timeout is given, counted from entry, under a new trace; a scope opened inside another takes nothing from it. It closes on exit, however the block ends, and is entered once. An app that is not hosted, a host not yet set up and a second entry are `neolith.UsageError`, as is an exit where the scope is not current, or is current in another context than it was entered in, such as a scope held across a generator's `yield`; that scope still closes, and a signal to stop the block ends with propagates with the report as a note. The refusals for a call outside `requires` and for a missing or closed scope now name `neolith.command_scope`.
|
|
24
|
+
- The request root (spec 02, [ADR 0017](docs/adr/0017-call-context-explicit-at-the-action-ambient-for-propagation.md) Decision 4, [ADR 0022](docs/adr/0022-the-app-host-builds-settings-and-checks-before-it-serves.md) Decision 6): `neolith.middleware.RootMiddleware`, listed first in `MIDDLEWARE` and once, opens a root for each request with the deadline `NEOLITH["REQUEST_DEADLINE"]` (30 seconds when absent, none when `None`), counted from the request's start. Once the view is resolved, the root belongs to the app whose code serves it, a class-based view's `view_class`, a partial its function's, a wrapper defined in an installed app other than Django's own that app's code whatever `functools.wraps` copied onto it, a wrapper whose code is no app's, one Django supplies such as `login_required` or one in the project, the code it wraps, a copied `view_class` or `model_admin` trusted only on the function that set it, and wrappers judged recursively so they compose, and a wrapper's `__wrapped__` followed only into a hosted app's code; for an admin view, the most derived class of its `ModelAdmin` in a hosted app or the project, or the model's app when there is none (an app's wrapper over that view is its own app's code); a view in no installed app, and anything that runs before the view is resolved, calls from no app and is refused. The root stays open while a streamed body runs, and the body's own closers run inside it; it closes when the response is done, so a call kept past it is `neolith.UsageError`. A `FileResponse` over a plain file is left unwrapped for `wsgi.file_wrapper`; any other file-like object is read inside the root.
|
|
25
|
+
- The host's checks before it serves (spec 05): set-up runs the system checks tagged `neolith` and raises every error in one `ImproperlyConfigured`, whatever `SILENCED_SYSTEM_CHECKS` says: `neolith.E001` for a missing `NEOLITH`, one that is not a `dict`, an unknown key or a `REQUEST_DEADLINE` outside a finite 0.001 to 9999999.999 seconds; `neolith.E006` for a `MIDDLEWARE` without the root middleware first, or with it twice. Set-up and the root middleware's constructor judge `MIDDLEWARE` by one rule, counting the class under any path or a subclass; the constructor also refuses a process whose host is not set up; a request that arrives while the host is not set up is refused. `neolith.W001` warns about a registered admin whose code is in no installed app, by the rule the binding uses, and set-up logs it unless it is silenced.
|
|
26
|
+
- Each app's database (spec 05, [ADR 0009](docs/adr/0009-one-database-alias-per-app.md)): a hosted app that declares the `database` resource lives on its own alias, named by its label. `neolith.routers.AppRouter` keeps its models there and sends every other label to `default`, from labels alone: reads, writes and migrations go to the label's home, and relations are allowed only within one home, so two apps cannot share a transaction. Set-up refuses a hosted app with models and no `database` (`neolith.E014`) and a table name that `default`'s backend shortened (`neolith.E017`).
|
|
27
|
+
- Runtime dependency on Pydantic v2 ([ADR 0006](docs/adr/0006-contracts-are-typed-and-published-as-openapi.md)).
|
|
28
|
+
|
|
29
|
+
[Unreleased]: https://github.com/stack314/django-neolith/compare/v0.1.0a1...HEAD
|
|
30
|
+
[0.1.0a1]: https://github.com/stack314/django-neolith/releases/tag/v0.1.0a1
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Contributor Covenant 3.0 Code of Conduct
|
|
2
|
+
|
|
3
|
+
## Our Pledge
|
|
4
|
+
|
|
5
|
+
We pledge to make our community welcoming, safe, and equitable for all.
|
|
6
|
+
|
|
7
|
+
We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Encouraged Behaviors
|
|
11
|
+
|
|
12
|
+
While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
|
|
13
|
+
|
|
14
|
+
With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
|
|
15
|
+
|
|
16
|
+
1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
|
|
17
|
+
2. Engaging **kindly and honestly** with others.
|
|
18
|
+
3. Respecting **different viewpoints** and experiences.
|
|
19
|
+
4. **Taking responsibility** for our actions and contributions.
|
|
20
|
+
5. Gracefully giving and accepting **constructive feedback**.
|
|
21
|
+
6. Committing to **repairing harm** when it occurs.
|
|
22
|
+
7. Behaving in other ways that promote and sustain the **well-being of our community**.
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Restricted Behaviors
|
|
26
|
+
|
|
27
|
+
We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
|
|
28
|
+
|
|
29
|
+
1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
|
|
30
|
+
2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
|
|
31
|
+
3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
|
|
32
|
+
4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
|
|
33
|
+
5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
|
|
34
|
+
6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
|
|
35
|
+
7. Behaving in other ways that **threaten the well-being** of our community.
|
|
36
|
+
|
|
37
|
+
### Other Restrictions
|
|
38
|
+
|
|
39
|
+
1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
|
|
40
|
+
2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
|
|
41
|
+
3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
|
|
42
|
+
4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
## Reporting an Issue
|
|
46
|
+
|
|
47
|
+
Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
|
|
48
|
+
|
|
49
|
+
When an incident does occur, it is important to report it promptly. To report a possible violation, email the maintainer at [conduct@stack314.com](mailto:conduct@stack314.com).
|
|
50
|
+
|
|
51
|
+
Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
## Addressing and Repairing Harm
|
|
55
|
+
|
|
56
|
+
If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
|
|
57
|
+
|
|
58
|
+
1) Warning
|
|
59
|
+
1) Event: A violation involving a single incident or series of incidents.
|
|
60
|
+
2) Consequence: A private, written warning from the Community Moderators.
|
|
61
|
+
3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
|
|
62
|
+
2) Temporarily Limited Activities
|
|
63
|
+
1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
|
|
64
|
+
2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
|
|
65
|
+
3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
|
|
66
|
+
3) Temporary Suspension
|
|
67
|
+
1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
|
|
68
|
+
2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
|
|
69
|
+
3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
|
|
70
|
+
4) Permanent Ban
|
|
71
|
+
1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
|
|
72
|
+
2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
|
|
73
|
+
3) Repair: There is no possible repair in cases of this severity.
|
|
74
|
+
|
|
75
|
+
This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
## Scope
|
|
79
|
+
|
|
80
|
+
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
## Attribution
|
|
84
|
+
|
|
85
|
+
This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
|
|
86
|
+
|
|
87
|
+
Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
|
|
88
|
+
|
|
89
|
+
For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Contributing to django-neolith
|
|
2
|
+
|
|
3
|
+
Thank you for considering a contribution. This document is the standard every pull request is reviewed against, including the maintainer's own. Each rule has an ID such as **K2**, so a review can say exactly which rule a change meets or misses.
|
|
4
|
+
|
|
5
|
+
Neolith is young. It is in alpha, and the specification and the reference implementation are being written together. That makes design discussion as valuable as code right now.
|
|
6
|
+
|
|
7
|
+
Everyone taking part is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
|
|
8
|
+
|
|
9
|
+
## Before you start
|
|
10
|
+
|
|
11
|
+
- **S1.** Small, obvious fixes (a typo, a broken link, a wrong example) can go straight to a pull request.
|
|
12
|
+
- **S2.** For anything else, open an issue first. Describe the problem before the solution, and agree on the approach before writing code. This saves you from building something that conflicts with a recorded decision.
|
|
13
|
+
- **S3.** If the change is hard to reverse, shapes public API, adds a runtime dependency or changes what the specification means, it needs a decision record (**D1**). Propose it in the issue or in the same pull request.
|
|
14
|
+
- **S4.** For a roadmap step, the issue holds the plan: the specification documents the step implements, the decisions and open questions it depends on, and a task list that names the requirement IDs each task covers (**P5**). A plan does not settle an open question or a Proposed decision record; that takes a record the maintainer accepts.
|
|
15
|
+
|
|
16
|
+
## Decisions
|
|
17
|
+
|
|
18
|
+
The [vision](VISION.md), the [guiding principles](docs/principles.md) and the Accepted [architecture decision records](docs/adr/README.md) are binding. They are how the project settles arguments once instead of in every review. Proposed records are working assumptions: follow them by default, and challenge them in the pull request or an issue.
|
|
19
|
+
|
|
20
|
+
- **D1.** A change that contradicts a principle or an Accepted decision record must come with a new decision record that explains why. Use the [template](docs/adr/template.md) and the next free number, with status Proposed. The maintainer accepts or rejects it.
|
|
21
|
+
- **D2.** An Accepted record's decision is never edited. To reverse it, write a new record and mark the old one `Superseded by NNNN`. To narrow part of it, the new record quotes the sentences it narrows, and the old record gains a line under its status, `Narrowed by NNNN (Decision k)`; nothing else in it changes. Typos and broken links in an Accepted record may be fixed.
|
|
22
|
+
- **D3.** Record numbers are never reused, including for rejected records.
|
|
23
|
+
- **D4.** When an item in [open questions](docs/open-questions.md) is settled, the same pull request records the decision and removes the item.
|
|
24
|
+
|
|
25
|
+
## Specification
|
|
26
|
+
|
|
27
|
+
Neolith is defined by a specification under `spec/`, written independently of Django and Python. django-neolith is its reference implementation ([ADR 0015](docs/adr/0015-specification-first-django-reference-implementation.md)).
|
|
28
|
+
|
|
29
|
+
- **P1.** A change to behaviour the specification defines updates the specification in the same pull request. On `main`, the code and the specification never disagree.
|
|
30
|
+
- **P2.** Specification text names no Django or Python construct. Framework-specific detail belongs in the implementation's documentation.
|
|
31
|
+
- **P3.** The normative words MUST, MUST NOT, REQUIRED, SHOULD and MAY are used in capitals, with their RFC 2119 meaning, only in `spec/`.
|
|
32
|
+
- **P4.** A change to the specification changes the conformance tests to match, in the same pull request.
|
|
33
|
+
- **P5.** Every statement in `spec/` that uses a normative word carries a requirement ID, such as **CON-4**, in its document's area as listed in `spec/README.md`. One ID marks one requirement. Each item of a list introduced by a normative lead-in (a final sentence with a normative word that ends in a colon or comes right before a list) carries its own ID, and the lead-in carries none. Headings use no normative word. IDs are never renumbered or reused. A withdrawn requirement stays in place in the form `~~**CON-4.** <statement>~~ Withdrawn in spec 0.2: <reason>.`
|
|
34
|
+
- **P6.** A pull request that adds, changes or withdraws a requirement lists those IDs in the *Spec trace* section of its description, with the tests that cite them.
|
|
35
|
+
|
|
36
|
+
## Code
|
|
37
|
+
|
|
38
|
+
These rules apply to the `neolith` package. Tests and examples follow them too, except where a rule says otherwise.
|
|
39
|
+
|
|
40
|
+
- **K1.** The public API is fully type-annotated, and the type checker passes with no new ignores. An ignore that is unavoidable carries a comment saying why.
|
|
41
|
+
- **K2.** Fail at startup, not at first use. Misconfiguration, an unsatisfied contract requirement or a contract that does not match its implementation is detected at import or when the host starts, with a message that names the cause.
|
|
42
|
+
- **K3.** No placeholders in shipped code: no `TODO`, `FIXME`, stub bodies or `NotImplementedError` on a reachable path. Unfinished work stays on a branch or in an issue. The `...` body of a contract action is a declaration and is allowed.
|
|
43
|
+
- **K4.** No deprecated APIs. Neolith does not use a Python or Django feature that is deprecated or scheduled for removal when a newer approach exists. Code that differs by version lives only in `neolith._compat` ([ADR 0012](docs/adr/0012-supported-python-and-django-versions.md)).
|
|
44
|
+
- **K5.** No new runtime dependency without an Accepted decision record. Every dependency becomes a dependency of every adopter. Development-only dependencies need a one-line reason in the pull request.
|
|
45
|
+
- **K6.** No hidden state. Process-wide state is owned by the app host and documented. The context variable through which outgoing calls find their call context is such state, and app code never reads it directly ([ADR 0017](docs/adr/0017-call-context-explicit-at-the-action-ambient-for-propagation.md)).
|
|
46
|
+
- **K7.** Errors that cross a contract are contract errors with a defined kind. A transport's own exceptions never reach the caller ([ADR 0008](docs/adr/0008-typed-contract-errors-in-both-modes.md)).
|
|
47
|
+
- **K8.** The boundary applies to our own code. An example or test app imports another app's contract package only, never its models, services or signals ([ADR 0003](docs/adr/0003-apps-communicate-through-contracts.md)).
|
|
48
|
+
- **K9.** Secure by default. No secrets in code, tests or fixtures. No disabled TLS verification or authentication outside test code. Every value arriving over a transport is validated before it reaches an implementation.
|
|
49
|
+
- **K10.** Performance claims come with a measurement. A change made for speed shows the benchmark and its numbers in the pull request.
|
|
50
|
+
|
|
51
|
+
## Tests
|
|
52
|
+
|
|
53
|
+
- **T1.** Every behaviour change ships with tests. A bug fix ships with a regression test that fails without the fix.
|
|
54
|
+
- **T2.** Contract behaviour is tested through the shared contract suite, which runs over every transport. A test that exercises only one transport needs a reason.
|
|
55
|
+
- **T3.** Tests are deterministic. No sleeping to wait for something, no network beyond the local machine, and no dependence on test order.
|
|
56
|
+
- **T4.** The full CI matrix passes before review is requested. Deprecation warnings are errors ([ADR 0012](docs/adr/0012-supported-python-and-django-versions.md)).
|
|
57
|
+
- **T5.** A test that verifies a requirement cites it with the `spec` marker, for example `@pytest.mark.spec("CON-4")`. A test that cites an unknown or withdrawn ID fails the build. Coverage comes from the test run: only a test that ran and passed covers a requirement. Once a document's coverage is enforced, from the roadmap step that implements it, every requirement in it stated with MUST, MUST NOT or REQUIRED is covered, or has an entry under `[not-tested]` in `tests/spec_trace.toml` that gives the reason.
|
|
58
|
+
|
|
59
|
+
### Running the checks locally
|
|
60
|
+
|
|
61
|
+
You need Python 3.12 or newer and pip 25.1 or newer, which reads the dependency groups in `pyproject.toml`.
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
python -m venv .venv
|
|
65
|
+
. .venv/bin/activate
|
|
66
|
+
python -m pip install --upgrade pip
|
|
67
|
+
python -m pip install -e . --group dev
|
|
68
|
+
pytest --spec-report=spec-report.json
|
|
69
|
+
ruff check . && ruff format --check .
|
|
70
|
+
mypy
|
|
71
|
+
python scripts/spec_trace.py --report spec-report.json
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`scripts/spec_trace.py` checks the requirement IDs in `spec/`, reads which requirements the passing tests cite from the report pytest wrote, and prints the trace (**P5**, **T5**). CI runs the same commands on Django 5.2 with Python 3.12 and on the newest supported pair, on x86-64 and arm64 ([ADR 0012](docs/adr/0012-supported-python-and-django-versions.md)). To try another Django locally, add it to the install line, for example `"Django~=5.2.0"`.
|
|
75
|
+
|
|
76
|
+
To build the documentation site and check it against the site's rules ([ADR 0024](docs/adr/0024-user-documentation-is-built-with-sphinx-from-this-repository.md)), you need Python 3.13 or newer:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
python -m pip install -e . --group docs
|
|
80
|
+
python scripts/docs.py check
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`python scripts/docs.py serve` builds the site and serves it at `http://127.0.0.1:8000/`. Until the repository is public, run the check before requesting review.
|
|
84
|
+
|
|
85
|
+
## Writing
|
|
86
|
+
|
|
87
|
+
These rules apply to documentation, docstrings, error messages, commit messages and pull request text.
|
|
88
|
+
|
|
89
|
+
- **W1.** Each core concept has one name: *app*, *contract*, *action*, *contract package*, *provider*, *connector*, *transport*, *event*, *declaration*, *app host* (*host* for short), and *mode* (*attached* or *detached*). Do not give these concepts other names. For example, say "HTTP transport", not "HTTP binding". Do not call a connector a *client*, a transport an *adapter*, or a contract an *interface* or *port*. Ordinary uses of those words are fine, such as "the transport interface". In plain prose, *service* means an app deployed detached. Each term is defined in [spec 00](spec/00-overview.md#terms). W1 is provisional until [open question 3](docs/open-questions.md) is closed.
|
|
90
|
+
- **W2.** Describe trade-offs. Do not call Django, other projects or other approaches wrong. Credit prior work where it is relevant.
|
|
91
|
+
- **W3.** No unverifiable claims, such as *first*, *only*, *fastest* or *best*, unless a source is linked.
|
|
92
|
+
- **W4.** The principles, decision records and specification never address the reader as *you*. Guides and this document may.
|
|
93
|
+
- **W5.** The vision, principles and decision records stay abstract, with names like `<contract>.v1`. Concrete examples belong in the specification and guides, and should vary rather than repeat one domain.
|
|
94
|
+
- **W6.** Plain language. Short sentences, one idea each. Prefer a list to a long paragraph when items are parallel.
|
|
95
|
+
|
|
96
|
+
## Privacy
|
|
97
|
+
|
|
98
|
+
- **X1.** Nothing committed or posted to this repository refers to private or environment-specific things: internal or chat links, session links, hostnames, machine or hardware names, personal file paths, or credentials. This includes commit trailers that carry such references, which must be removed before pushing. Ordinary trailers such as `Co-authored-by` are fine.
|
|
99
|
+
|
|
100
|
+
## Commits and pull requests
|
|
101
|
+
|
|
102
|
+
- **G1.** Work on a branch named `<type>/<short-name>`, for example `fix/connector-timeout`. Never push to `main`.
|
|
103
|
+
- **G2.** Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/). Types: `feat`, `fix`, `docs`, `spec`, `test`, `refactor`, `perf`, `build`, `ci`, `chore`. The subject is imperative, starts in lower case after the type, and is at most 72 characters. The body says why.
|
|
104
|
+
- **G3.** One logical change per pull request. Unrelated clean-up goes in its own pull request.
|
|
105
|
+
- **G4.** The pull request description opens with a summary of three or four bullets. It then says what changed and why, links the issue or decision record, names every specification document and decision record it touches, and says how the change was verified.
|
|
106
|
+
- **G5.** Pull requests are squash-merged. The pull request title becomes the commit subject, so it follows **G2**.
|
|
107
|
+
- **G6.** A breaking change uses `!` after the type, for example `feat!:`, and has a *Breaking changes* section in the description. Before 1.0, breaking changes are allowed but never silent.
|
|
108
|
+
- **G7.** Merging needs the maintainer's approval, and every review comment answered or resolved.
|
|
109
|
+
|
|
110
|
+
## How review works
|
|
111
|
+
|
|
112
|
+
Every pull request is reviewed against this document. Review comments cite the rule they apply, for example "**K2**: this is only detected on the first call". A pull request that breaks a rule is changed, or the exception is agreed in writing in the pull request by the maintainer.
|
|
113
|
+
|
|
114
|
+
Reviewers look in this order, because an early problem can make later ones moot:
|
|
115
|
+
|
|
116
|
+
1. **Decisions and specification** (D, P): does the change fit what is recorded, and is a new record needed?
|
|
117
|
+
2. **Correctness and tests** (K, T): does it work, fail safely, and prove it?
|
|
118
|
+
3. **Writing and privacy** (W, X).
|
|
119
|
+
4. **Hygiene** (G).
|
|
120
|
+
|
|
121
|
+
## Responsibility
|
|
122
|
+
|
|
123
|
+
- **R1.** You are responsible for every line you submit, however it was produced, including with AI tools. You should be able to explain any part of the change and why it is needed.
|
|
124
|
+
- **R2.** The maintainers use AI tools too, and are held to R1 the same way.
|
|
125
|
+
|
|
126
|
+
Be respectful and assume good faith, in issues, reviews and everywhere else in the project.
|
|
127
|
+
|
|
128
|
+
## Reporting a security issue
|
|
129
|
+
|
|
130
|
+
Do not open a public issue. Report it privately through the repository's Security tab ("Report a vulnerability"). You will get a reply before any details are made public.
|
|
131
|
+
|
|
132
|
+
## License
|
|
133
|
+
|
|
134
|
+
Contributions are accepted under the project's [BSD 3-Clause License](LICENSE). By submitting a pull request, you agree that your contribution is licensed under it.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, Vignesh Pai and django-neolith contributors
|
|
4
|
+
All rights reserved.
|
|
5
|
+
|
|
6
|
+
Redistribution and use in source and binary forms, with or without
|
|
7
|
+
modification, are permitted provided that the following conditions are met:
|
|
8
|
+
|
|
9
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
10
|
+
list of conditions and the following disclaimer.
|
|
11
|
+
|
|
12
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
13
|
+
this list of conditions and the following disclaimer in the documentation
|
|
14
|
+
and/or other materials provided with the distribution.
|
|
15
|
+
|
|
16
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
17
|
+
contributors may be used to endorse or promote products derived from
|
|
18
|
+
this software without specific prior written permission.
|
|
19
|
+
|
|
20
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
21
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
22
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
23
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
24
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
25
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
26
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
27
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
28
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
29
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: django-neolith
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Deploy Django apps, not Django projects.
|
|
5
|
+
Project-URL: Repository, https://github.com/stack314/django-neolith
|
|
6
|
+
Project-URL: Issues, https://github.com/stack314/django-neolith/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/stack314/django-neolith/blob/main/CHANGELOG.md
|
|
8
|
+
Author: Vignesh Pai and django-neolith contributors
|
|
9
|
+
License-Expression: BSD-3-Clause
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Framework :: Django
|
|
13
|
+
Classifier: Framework :: Django :: 5.2
|
|
14
|
+
Classifier: Framework :: Django :: 6.1
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: >=3.12
|
|
25
|
+
Requires-Dist: django>=5.2
|
|
26
|
+
Requires-Dist: pydantic<3,>=2.12
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
<div align="center">
|
|
30
|
+
|
|
31
|
+
<h1>
|
|
32
|
+
<picture>
|
|
33
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/neolith-wordmark-dark.svg">
|
|
34
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/assets/neolith-wordmark-light.svg">
|
|
35
|
+
<img alt="django-neolith" src="https://raw.githubusercontent.com/stack314/django-neolith/main/docs/assets/neolith-wordmark-light.svg" width="360">
|
|
36
|
+
</picture>
|
|
37
|
+
</h1>
|
|
38
|
+
|
|
39
|
+
<p><strong>Deploy Django apps, not Django projects.</strong></p>
|
|
40
|
+
|
|
41
|
+
<p>
|
|
42
|
+
<a href="https://github.com/stack314/django-neolith/actions/workflows/ci.yml?query=branch%3Amain"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/stack314/django-neolith/ci.yml?branch=main&label=CI"></a>
|
|
43
|
+
<a href="https://pypi.org/project/django-neolith/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/django-neolith"></a>
|
|
44
|
+
<a href="https://pypi.org/project/django-neolith/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/django-neolith"></a>
|
|
45
|
+
<a href="https://pypi.org/project/django-neolith/"><img alt="Django versions" src="https://img.shields.io/pypi/frameworkversions/django/django-neolith"></a>
|
|
46
|
+
<a href="https://github.com/stack314/django-neolith/blob/main/LICENSE"><img alt="License: BSD-3-Clause" src="https://img.shields.io/badge/license-BSD--3--Clause-blue"></a>
|
|
47
|
+
<a href="https://github.com/astral-sh/ruff"><img alt="Code style: Ruff" src="https://img.shields.io/badge/code%20style-ruff-261230"></a>
|
|
48
|
+
<a href="https://mypy-lang.org/"><img alt="Checked with mypy" src="https://img.shields.io/badge/mypy-checked-2a6db2"></a>
|
|
49
|
+
</p>
|
|
50
|
+
|
|
51
|
+
</div>
|
|
52
|
+
|
|
53
|
+
**Status: alpha (0.1.0a1). The API may change before 0.1.**
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
pip install --pre django-neolith
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## What it is
|
|
60
|
+
|
|
61
|
+
Neolith makes the Django app, not the Django project, the unit of deployment. An app can run inside a shared process or on its own as a service, with its models, migrations, admin and tests intact, and without changing its code. Apps talk to each other only through typed contracts, so the same code and the same tests hold in both arrangements. Neolith is defined by a [specification](https://github.com/stack314/django-neolith/blob/main/spec/README.md) that is independent of Django and of Python, and django-neolith is its reference implementation.
|
|
62
|
+
|
|
63
|
+
## Features
|
|
64
|
+
|
|
65
|
+
What works on `main` today. The [changelog](https://github.com/stack314/django-neolith/blob/main/CHANGELOG.md) has the details.
|
|
66
|
+
|
|
67
|
+
- **Typed contracts.** A contract is a `Protocol` class with `@contract` and `@action`, and an implementation is marked with `@implements`. Request and reply types are Pydantic models in a portable type system, and every check runs when the module is imported.
|
|
68
|
+
- **Typed errors.** `ContractError` carries a `kind`, a message and a detail. An action can declare its own error kinds with their detail records.
|
|
69
|
+
- **Calls cross as JSON, in-process too.** Every request, reply and error detail is written and read through its declared type, so an in-process call carries exactly what a remote one will.
|
|
70
|
+
- **App declaration.** An app declares what it provides, requires and owns on its `NeolithAppConfig`, and the declaration is checked when the class is defined.
|
|
71
|
+
- **Checks before serving.** At start-up the host resolves every required contract to a provider and validates each implementation, listing every refusal in one error; once those pass, it runs its system checks on the settings and reports all their errors together.
|
|
72
|
+
- **One database per app.** `neolith.routers.AppRouter` keeps each app's data on a database alias of its own.
|
|
73
|
+
- **Call context.** A principal, a trace, a deadline and the calling app travel with each call. A root is opened for each request by `RootMiddleware`, and for a command or background work by `command_scope`.
|
|
74
|
+
|
|
75
|
+
Not yet on `main`: `neolith run <app>`, the HTTP transport, the conformance suite and events. See the roadmap below.
|
|
76
|
+
|
|
77
|
+
## A short example
|
|
78
|
+
|
|
79
|
+
A contract, in a contract package other apps may import:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
# inventory/contracts.py
|
|
83
|
+
from typing import Protocol
|
|
84
|
+
|
|
85
|
+
from pydantic import BaseModel
|
|
86
|
+
|
|
87
|
+
from neolith import action, contract
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class ReserveRequest(BaseModel):
|
|
91
|
+
sku: str
|
|
92
|
+
qty: int
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
class ReserveReply(BaseModel):
|
|
96
|
+
reserved: int
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
@contract("inventory.v1")
|
|
100
|
+
class Inventory(Protocol):
|
|
101
|
+
@action(idempotent=True)
|
|
102
|
+
def reserve(self, request: ReserveRequest) -> ReserveReply: ...
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Its implementation, private to the app that provides it:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
# inventory/services.py
|
|
109
|
+
from neolith import CallContext, implements
|
|
110
|
+
|
|
111
|
+
from inventory.contracts import Inventory, ReserveReply, ReserveRequest
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
@implements(Inventory)
|
|
115
|
+
class InventoryService:
|
|
116
|
+
def reserve(self, request: ReserveRequest, ctx: CallContext) -> ReserveReply:
|
|
117
|
+
return ReserveReply(reserved=request.qty)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The two apps' declarations:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
# inventory/apps.py
|
|
124
|
+
from neolith import NeolithAppConfig, Provided
|
|
125
|
+
|
|
126
|
+
from inventory.contracts import Inventory
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
class InventoryConfig(NeolithAppConfig):
|
|
130
|
+
name = "inventory"
|
|
131
|
+
label = "inventory"
|
|
132
|
+
provides = (
|
|
133
|
+
Provided(
|
|
134
|
+
Inventory,
|
|
135
|
+
implementation="inventory.services.InventoryService",
|
|
136
|
+
principal_from=("shop",), # apps that may pass a principal on their calls
|
|
137
|
+
),
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
# shop/apps.py
|
|
142
|
+
from neolith import NeolithAppConfig
|
|
143
|
+
|
|
144
|
+
from inventory.contracts import Inventory
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
class ShopConfig(NeolithAppConfig):
|
|
148
|
+
name = "shop"
|
|
149
|
+
label = "shop"
|
|
150
|
+
requires = (Inventory,)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
And a call from the shop app, which knows the contract and nothing else of inventory:
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
# shop/orders.py
|
|
157
|
+
from neolith import ContractError, connect
|
|
158
|
+
|
|
159
|
+
from inventory.contracts import ReserveRequest
|
|
160
|
+
|
|
161
|
+
inventory = connect("inventory.v1")
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def place_order(sku: str, qty: int) -> int:
|
|
165
|
+
try:
|
|
166
|
+
reply = inventory.reserve(ReserveRequest(sku=sku, qty=qty))
|
|
167
|
+
except ContractError as error:
|
|
168
|
+
print(error.kind) # "unavailable", "conflict", ...
|
|
169
|
+
raise
|
|
170
|
+
return reply.reserved
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The settings neolith checks before the host serves, beside the project's usual ones such as `DATABASES`:
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
# settings.py
|
|
177
|
+
INSTALLED_APPS = ["inventory", "shop", "neolith"]
|
|
178
|
+
MIDDLEWARE = ["neolith.middleware.RootMiddleware"] # first, and listed once
|
|
179
|
+
NEOLITH = {}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
With these, a view in the shop app can call `place_order` directly; a command opens its root first, with `neolith.command_scope("shop")`. A test runs every Python block on this page under these settings.
|
|
183
|
+
|
|
184
|
+
## Roadmap
|
|
185
|
+
|
|
186
|
+
The steps to 0.1 are in the [roadmap](https://github.com/stack314/django-neolith/blob/main/docs/roadmap.md).
|
|
187
|
+
|
|
188
|
+
## Links
|
|
189
|
+
|
|
190
|
+
- [Vision](https://github.com/stack314/django-neolith/blob/main/VISION.md)
|
|
191
|
+
- [Specification](https://github.com/stack314/django-neolith/blob/main/spec/README.md) (draft 0.1)
|
|
192
|
+
- [Roadmap to 0.1](https://github.com/stack314/django-neolith/blob/main/docs/roadmap.md)
|
|
193
|
+
- [Guiding principles](https://github.com/stack314/django-neolith/blob/main/docs/principles.md)
|
|
194
|
+
- [Architecture decision records](https://github.com/stack314/django-neolith/blob/main/docs/adr/README.md)
|
|
195
|
+
- [Open questions](https://github.com/stack314/django-neolith/blob/main/docs/open-questions.md)
|
|
196
|
+
- [Contributing](https://github.com/stack314/django-neolith/blob/main/CONTRIBUTING.md)
|
|
197
|
+
- [Code of conduct](https://github.com/stack314/django-neolith/blob/main/CODE_OF_CONDUCT.md)
|
|
198
|
+
|
|
199
|
+
Licensed under the [BSD 3-Clause License](https://github.com/stack314/django-neolith/blob/main/LICENSE).
|