stapel-tasks 0.1.1__tar.gz

stapel_tasks-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_tasks-0.1.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: stapel-tasks
+Version: 0.1.1
+Summary: Generic tasks and kanban boards for the Stapel framework
+Author: Stapel
+License: MIT
+Project-URL: Homepage, https://stapel.dev
+Project-URL: Repository, https://github.com/usestapel/stapel-tasks
+Project-URL: Documentation, https://github.com/usestapel/stapel-tasks/blob/main/MODULE.md
+Project-URL: Changelog, https://github.com/usestapel/stapel-tasks/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/usestapel/stapel-tasks/issues
+Keywords: django,stapel,tasks,kanban,boards,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.9,>=0.8
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: drf-spectacular>=0.27
+Provides-Extra: attributes
+Requires-Dist: stapel-attributes<0.4,>=0.3; extra == "attributes"
+Provides-Extra: all
+Requires-Dist: stapel-attributes<0.4,>=0.3; extra == "all"
+Dynamic: license-file
+
+# stapel-tasks
+
+Generic tasks and kanban boards for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices without
+changing module code.
+
+A **generic task domain** — Board / Column / Task / ChecklistItem /
+TaskComment, a REST surface, a full outbox event surface, and custom fields
+via stapel-attributes. It is useful to any project by itself (a team runs a
+board by hand), and it is the substrate an orchestrator *projects* onto: an
+external state machine drives cards through opaque `origin_*` handles and the
+`MOVE_POLICY` seam — the module knows nothing about the machine.
+
+## Install
+
+```bash
+pip install stapel-tasks              # core
+pip install "stapel-tasks[attributes]"  # + typed custom-field validation
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_tasks",
+]
+
+# urls.py
+path("tasks/", include("stapel_tasks.urls"))
+```
+
+> **Requires** a stapel-core whose background `taskstore` app uses the label
+> `stapel_taskstore` — this module owns the Django label `stapel_tasks`. See
+> MODULE.md.
+
+## Concepts
+
+- **Board** — an ordered set of columns and the cards on them. Owns the
+  custom-field *schema* (`feature_defs`) and optional workflow `settings`.
+- **Column** — a status. Its `key` is the card's status; its `category`
+  (`backlog/active/review/waiting/done`) is the fixed machine semantic.
+- **Task (card)** — status = its column; order within the column is a
+  fractional `position` (drag-and-drop moves write one row). Custom-field
+  values live in `features`; a projecting system writes `origin_meta`.
+- **Move** — drag-and-drop is a `move` validated by `MOVE_POLICY`:
+  `allow` / `deny(reason_key)` / `defer` (the managed-card path).
+
+```python
+from stapel_tasks import services
+
+board = services.create_board(name="Team", preset="simple")
+card = services.create_task(board=board, title="Ship it")
+services.move_task(card, to_column=board.columns.get(key="done"))  # emits task.completed
+```
+
+## comm surface
+
+| Kind | Name | Purpose |
+|---|---|---|
+| Emit | `task.created` / `task.updated` / `task.moved` / `task.assigned` / `task.completed` / `task.comment_added` / `task.checklist_item_changed` / `task.archived` | Card lifecycle facts (via the outbox) |
+| Consume | `user.deleted` | GDPR anonymization |
+| Function | `tasks.get` / `tasks.list_board` / `tasks.create` / `tasks.move` / `tasks.comment` | Machine interface / MCP-tool candidates |
+
+## Settings (`STAPEL_TASKS`)
+
+| Key | Default | What it customizes |
+|---|---|---|
+| `SCOPE_PROVIDER` | single global scope, allow-all | Tenancy resolution/filtering + permissions |
+| `MOVE_POLICY` | allow any move (honours `transitions`) | Drag-and-drop authorization |
+| `BOARD_PRESETS` | `{}` (merged over built-in `simple`) | Board-shape presets |
+| `STORE_UNKNOWN_FEATURES` | `True` | Keep raw custom fields when attributes is absent |
+| `DEFAULT_PAGE_SIZE` | `100` | Card-list page size |
+
+See **MODULE.md** for the full seam map (providers, registries, serializer
+seams, comm tables, anti-patterns, override-vs-upstream).
+
+## License
+
+MIT

stapel_tasks-0.1.1/README.md

@@ -0,0 +1,78 @@
+# stapel-tasks
+
+Generic tasks and kanban boards for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices without
+changing module code.
+
+A **generic task domain** — Board / Column / Task / ChecklistItem /
+TaskComment, a REST surface, a full outbox event surface, and custom fields
+via stapel-attributes. It is useful to any project by itself (a team runs a
+board by hand), and it is the substrate an orchestrator *projects* onto: an
+external state machine drives cards through opaque `origin_*` handles and the
+`MOVE_POLICY` seam — the module knows nothing about the machine.
+
+## Install
+
+```bash
+pip install stapel-tasks              # core
+pip install "stapel-tasks[attributes]"  # + typed custom-field validation
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_tasks",
+]
+
+# urls.py
+path("tasks/", include("stapel_tasks.urls"))
+```
+
+> **Requires** a stapel-core whose background `taskstore` app uses the label
+> `stapel_taskstore` — this module owns the Django label `stapel_tasks`. See
+> MODULE.md.
+
+## Concepts
+
+- **Board** — an ordered set of columns and the cards on them. Owns the
+  custom-field *schema* (`feature_defs`) and optional workflow `settings`.
+- **Column** — a status. Its `key` is the card's status; its `category`
+  (`backlog/active/review/waiting/done`) is the fixed machine semantic.
+- **Task (card)** — status = its column; order within the column is a
+  fractional `position` (drag-and-drop moves write one row). Custom-field
+  values live in `features`; a projecting system writes `origin_meta`.
+- **Move** — drag-and-drop is a `move` validated by `MOVE_POLICY`:
+  `allow` / `deny(reason_key)` / `defer` (the managed-card path).
+
+```python
+from stapel_tasks import services
+
+board = services.create_board(name="Team", preset="simple")
+card = services.create_task(board=board, title="Ship it")
+services.move_task(card, to_column=board.columns.get(key="done"))  # emits task.completed
+```
+
+## comm surface
+
+| Kind | Name | Purpose |
+|---|---|---|
+| Emit | `task.created` / `task.updated` / `task.moved` / `task.assigned` / `task.completed` / `task.comment_added` / `task.checklist_item_changed` / `task.archived` | Card lifecycle facts (via the outbox) |
+| Consume | `user.deleted` | GDPR anonymization |
+| Function | `tasks.get` / `tasks.list_board` / `tasks.create` / `tasks.move` / `tasks.comment` | Machine interface / MCP-tool candidates |
+
+## Settings (`STAPEL_TASKS`)
+
+| Key | Default | What it customizes |
+|---|---|---|
+| `SCOPE_PROVIDER` | single global scope, allow-all | Tenancy resolution/filtering + permissions |
+| `MOVE_POLICY` | allow any move (honours `transitions`) | Drag-and-drop authorization |
+| `BOARD_PRESETS` | `{}` (merged over built-in `simple`) | Board-shape presets |
+| `STORE_UNKNOWN_FEATURES` | `True` | Keep raw custom fields when attributes is absent |
+| `DEFAULT_PAGE_SIZE` | `100` | Card-list page size |
+
+See **MODULE.md** for the full seam map (providers, registries, serializer
+seams, comm tables, anti-patterns, override-vs-upstream).
+
+## License
+
+MIT

stapel_tasks-0.1.1/__init__.py

@@ -0,0 +1,41 @@
+"""stapel-tasks — Generic tasks and kanban boards for the Stapel framework.
+
+A *generic* task domain: Board / Column / Task / ChecklistItem / TaskComment,
+a REST surface, a workflow-as-data-lite model (columns carry a fixed
+``category`` enum), custom fields via stapel-attributes (a soft seam that
+works without it), and a full event surface through the transactional outbox.
+
+The module deliberately knows nothing about any orchestrator / pipeline FSM.
+External state machines *project* into it through the opaque
+``origin_type``/``origin_ref``/``origin_meta`` handles and the ``MOVE_POLICY``
+seam — see MODULE.md §"Projection seam".
+
+Public API (lazily exported, PEP 562 — importing this package never pulls in
+Django or requires configured settings):
+
+- ``tasks_settings`` — resolved app settings (``stapel_tasks.conf``).
+"""
+
+__all__ = [
+    "tasks_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_tasks` stays Django-free.
+_LAZY_EXPORTS = {
+    "tasks_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_tasks-0.1.1/actions.py

@@ -0,0 +1,24 @@
+"""Action subscriptions of stapel-tasks.
+
+Handlers must be idempotent: delivery is at-least-once (outbox retries,
+broker redelivery). Consumes contracts live in ``schemas/consumes/``.
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase this module's PII when an account deletion is executed: drop the
+    user's card assignments and anonymize the cards/comments they authored."""
+    from .gdpr import TasksGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    TasksGDPRProvider().delete(user_id)
+    logger.info("tasks data anonymized for deleted user %s", user_id)

stapel_tasks-0.1.1/admin.py

@@ -0,0 +1,45 @@
+"""Admin registrations for stapel-tasks (observability; kept minimal)."""
+from django.contrib import admin
+
+from .models import Board, ChecklistItem, Column, Task, TaskComment
+
+
+class ColumnInline(admin.TabularInline):
+    model = Column
+    extra = 0
+    fields = ("key", "name", "category", "order", "wip_limit")
+
+
+@admin.register(Board)
+class BoardAdmin(admin.ModelAdmin):
+    list_display = ("name", "workspace_id", "is_archived", "created_at")
+    list_filter = ("is_archived",)
+    search_fields = ("name", "slug")
+    inlines = [ColumnInline]
+
+
+@admin.register(Task)
+class TaskAdmin(admin.ModelAdmin):
+    list_display = (
+        "title",
+        "board",
+        "column",
+        "origin_type",
+        "is_archived",
+        "created_at",
+    )
+    list_filter = ("origin_type", "is_archived")
+    search_fields = ("title", "origin_ref")
+    raw_id_fields = ("board", "column", "creator", "parent")
+
+
+@admin.register(ChecklistItem)
+class ChecklistItemAdmin(admin.ModelAdmin):
+    list_display = ("text", "task", "state", "order")
+    list_filter = ("state",)
+
+
+@admin.register(TaskComment)
+class TaskCommentAdmin(admin.ModelAdmin):
+    list_display = ("task", "author", "is_deleted", "created_at")
+    list_filter = ("is_deleted",)

stapel_tasks-0.1.1/apps.py

@@ -0,0 +1,33 @@
+from django.apps import AppConfig
+
+
+class TasksConfig(AppConfig):
+    # Canonical Django label for the generic task domain. stapel-core's
+    # background-task persistence app (``stapel_core.django.taskstore``)
+    # historically claimed the label ``stapel_tasks`` too — the two are
+    # unrelated ("comm Task" = async background function vs. this user-facing
+    # task/kanban domain). Core renames its taskstore label to
+    # ``stapel_taskstore`` so this module can own ``stapel_tasks`` (see
+    # MODULE.md §"stapel-core requirement").
+    name = "stapel_tasks"
+    label = "stapel_tasks"
+    verbose_name = "Tasks and kanban boards"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import-time side effects: comm functions/actions, system checks,
+        # error-key registration, and the built-in board presets. Each lives
+        # in its own module.
+        from . import actions  # noqa: F401
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+        from . import functions  # noqa: F401
+        from . import presets  # noqa: F401
+
+        # GDPR: register the per-app data handler (monolith in-process mode).
+        from stapel_core.gdpr import gdpr_registry
+
+        from .gdpr import TasksGDPRProvider
+
+        if not any(p.section == "tasks" for p in gdpr_registry.providers):
+            gdpr_registry.register(TasksGDPRProvider())

stapel_tasks-0.1.1/checks.py

@@ -0,0 +1,87 @@
+"""Django system checks for stapel-tasks configuration.
+
+Policy (docs/library-standard.md §3.7): E-level for configuration the
+service cannot run with; W-level for entries that only degrade lazily.
+
+- SCOPE_PROVIDER unimportable / not a ScopeProvider -> E (every request
+  needs it to resolve/filter scope and check permissions).
+- MOVE_POLICY unimportable / not a MovePolicy -> E (every move needs it).
+- BOARD_PRESETS entries must be callable or None -> E (board creation from a
+  broken preset would crash).
+"""
+from django.core import checks
+
+
+@checks.register(checks.Tags.compatibility)
+def check_scope_provider(app_configs, **kwargs):
+    from .conf import tasks_settings
+    from .scope import ScopeProvider
+
+    try:
+        provider = tasks_settings.SCOPE_PROVIDER
+    except Exception as exc:
+        return [
+            checks.Error(
+                f"STAPEL_TASKS['SCOPE_PROVIDER'] could not be imported: {exc}",
+                id="stapel_tasks.E001",
+            )
+        ]
+    target = provider if isinstance(provider, type) else type(provider)
+    if not issubclass(target, ScopeProvider):
+        return [
+            checks.Error(
+                "STAPEL_TASKS['SCOPE_PROVIDER'] must be a ScopeProvider subclass",
+                id="stapel_tasks.E002",
+            )
+        ]
+    return []
+
+
+@checks.register(checks.Tags.compatibility)
+def check_move_policy(app_configs, **kwargs):
+    from .conf import tasks_settings
+    from .policy import MovePolicy
+
+    try:
+        policy = tasks_settings.MOVE_POLICY
+    except Exception as exc:
+        return [
+            checks.Error(
+                f"STAPEL_TASKS['MOVE_POLICY'] could not be imported: {exc}",
+                id="stapel_tasks.E003",
+            )
+        ]
+    target = policy if isinstance(policy, type) else type(policy)
+    if not issubclass(target, MovePolicy):
+        return [
+            checks.Error(
+                "STAPEL_TASKS['MOVE_POLICY'] must be a MovePolicy subclass",
+                id="stapel_tasks.E004",
+            )
+        ]
+    return []
+
+
+@checks.register(checks.Tags.compatibility)
+def check_board_presets(app_configs, **kwargs):
+    from .conf import tasks_settings
+
+    presets = tasks_settings.BOARD_PRESETS
+    if not isinstance(presets, dict):
+        return [
+            checks.Error(
+                "STAPEL_TASKS['BOARD_PRESETS'] must be a dict of "
+                "{key: callable|None}.",
+                id="stapel_tasks.E005",
+            )
+        ]
+    bad = [k for k, v in presets.items() if v is not None and not callable(v)]
+    if bad:
+        return [
+            checks.Error(
+                f"STAPEL_TASKS['BOARD_PRESETS'] values must be callable or None; "
+                f"offending keys: {bad}",
+                id="stapel_tasks.E006",
+            )
+        ]
+    return []

stapel_tasks-0.1.1/conf.py

@@ -0,0 +1,53 @@
+"""Settings namespace for stapel-tasks.
+
+All configuration is read through ``tasks_settings`` (lazily, at call time)
+— never via module-level ``os.getenv`` (values would freeze at import).
+Resolution order per key: ``settings.STAPEL_TASKS`` dict -> flat Django
+setting of the same name -> environment variable -> default below.
+
+Dotted-path keys listed in ``import_strings`` are resolved with
+``import_string`` — the fork-free escape hatch for swappable behavior.
+
+The extension seams (see MODULE.md):
+
+- ``SCOPE_PROVIDER`` — resolves the opaque ``workspace_id`` from a request,
+  filters querysets by it, and answers permission questions
+  (viewer/member/admin). The default is a single-global-scope allow-all
+  provider; a workspaces-aware host swaps it. The library never interprets
+  the scope itself.
+- ``MOVE_POLICY`` — decides whether a card may move from one column to
+  another (drag-and-drop / ``tasks.move``): ``allow`` / ``deny(reason_key)``
+  / ``defer``. ``defer`` is the managed-card path — the move is accepted for
+  processing but not applied (an external orchestrator will move it). The
+  default allows any move.
+- ``BOARD_PRESETS`` — board-shape presets merged OVER the built-ins
+  (``simple``). A value is a callable ``() -> list[ColumnSpec]``; ``None``
+  removes a built-in. Register at runtime with ``register_board_preset``.
+- ``STORE_UNKNOWN_FEATURES`` — when stapel-attributes is not installed (or a
+  board declares no ``feature_defs``), whether the feature seam stores the
+  submitted custom-field DTO verbatim (``True``) or drops it (``False``).
+"""
+from stapel_core.conf import AppSettings
+
+tasks_settings = AppSettings(
+    "STAPEL_TASKS",
+    defaults={
+        # Dotted path to a ScopeProvider (resolve/filter/permission seam).
+        # The default is a no-op single global scope that allows everything.
+        "SCOPE_PROVIDER": "stapel_tasks.scope.DefaultScopeProvider",
+        # Dotted path to a MovePolicy. The default allows any move.
+        "MOVE_POLICY": "stapel_tasks.policy.AllowAllMovePolicy",
+        # Board presets merged OVER presets.BUILTIN_PRESETS. A value is a
+        # zero-arg callable returning a list of ColumnSpec; None removes a
+        # built-in.
+        "BOARD_PRESETS": {},
+        # Default page size for the paginated board/task listing.
+        "DEFAULT_PAGE_SIZE": 100,
+        # When attributes is absent, keep the raw custom-field DTO on the
+        # card (soft seam) rather than dropping it.
+        "STORE_UNKNOWN_FEATURES": True,
+    },
+    import_strings=("SCOPE_PROVIDER", "MOVE_POLICY"),
+)
+
+__all__ = ["tasks_settings"]

stapel_tasks-0.1.1/conftest.py

@@ -0,0 +1,132 @@
+def pytest_configure(config):
+    from django.conf import settings
+
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.admin",
+                "django.contrib.messages",
+                "stapel_core.django.users",
+                "rest_framework",
+                "stapel_tasks",
+            ],
+            # NOTE: stapel_core.django.taskstore is deliberately NOT installed.
+            # It historically claimed the Django label `stapel_tasks` (an
+            # unrelated background-task persistence app); this module owns that
+            # label. See MODULE.md §"stapel-core requirement".
+            AUTH_USER_MODEL="users.User",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            ROOT_URLCONF="stapel_tasks.tests.urls",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                }
+            },
+            # Synchronous in-process comm with schema validation ON, so the
+            # committed contracts in schemas/ are enforced by the tests.
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            STAPEL_COMM={
+                "OUTBOX_ENABLED": False,
+                "ACTION_TRANSPORT": "inprocess",
+                "VALIDATE_SCHEMAS": True,
+            },
+            MIGRATION_MODULES={
+                "users": None,
+                "stapel_tasks": None,
+            },
+        )
+        import django
+
+        django.setup()
+
+        from stapel_core.comm.schemas import autoload_schemas
+
+        autoload_schemas()
+
+
+import pytest  # noqa: E402
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+
+    return APIClient()
+
+
+@pytest.fixture
+def user(db):
+    from django.contrib.auth import get_user_model
+
+    return get_user_model().objects.create_user(
+        username="alice", email="alice@example.com", password="x"
+    )
+
+
+@pytest.fixture
+def other_user(db):
+    from django.contrib.auth import get_user_model
+
+    return get_user_model().objects.create_user(
+        username="bob", email="bob@example.com", password="x"
+    )
+
+
+@pytest.fixture
+def auth_client(api_client, user):
+    api_client.force_authenticate(user=user)
+    return api_client
+
+
+@pytest.fixture(autouse=True)
+def _reset_board_presets():
+    """Keep the board preset registry clean between tests."""
+    from stapel_tasks.presets import reset_presets
+
+    reset_presets()
+    yield
+    reset_presets()
+
+
+@pytest.fixture
+def captured_events():
+    """Subscribe to task emits (in-process) and collect Event envelopes.
+    Delivery is synchronous with OUTBOX disabled, so the list is populated by
+    the time emit() returns."""
+    from stapel_core.comm import action_registry, subscribe_action
+
+    collected = []
+
+    def _handler(event):
+        collected.append(event)
+
+    names = [
+        "task.created",
+        "task.updated",
+        "task.moved",
+        "task.assigned",
+        "task.completed",
+        "task.comment_added",
+        "task.checklist_item_changed",
+        "task.archived",
+    ]
+    for name in names:
+        subscribe_action(name, _handler)
+    try:
+        yield collected
+    finally:
+        for name in names:
+            handlers = action_registry._subscribers.get(name, [])
+            if _handler in handlers:
+                handlers.remove(_handler)