kanban-core 2.1.0__py3-none-any.whl

kanban/__init__.py

@@ -0,0 +1,26 @@
+"""Public API for the kanban business module."""
+
+from .exceptions import (
+    ConcurrencyError,
+    InvalidPersistenceStateError,
+    KanbanError,
+    NotFoundError,
+    PermissionError,
+    ValidationError,
+)
+from .facade import BoardView, CardView, ColumnView, KanbanFacade
+
+__version__ = "2.1.0"
+
+__all__ = [
+    "BoardView",
+    "CardView",
+    "ColumnView",
+    "ConcurrencyError",
+    "InvalidPersistenceStateError",
+    "KanbanError",
+    "KanbanFacade",
+    "NotFoundError",
+    "PermissionError",
+    "ValidationError",
+]

kanban/events.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from copy import deepcopy
+from dataclasses import dataclass, field, fields, is_dataclass
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Protocol
+
+# ============= EVENTS SYSTEM =============
+
+
+class EventRegistry:
+    """Singleton-by-explicit-dependency; avoids module-global state."""
+
+    def __init__(self, builtin: dict[str, str] | None = None):
+        self._events: dict[str, str] = dict(builtin) if builtin is not None else {}
+
+    def register(self, code: str, description: str) -> None:
+        if code in self._events:
+            raise ValueError(f"Event {code!r} already registered")
+        self._events[code] = description
+
+    def __contains__(self, code: str) -> bool:
+        return code in self._events
+
+    def __iter__(self) -> Iterator[str]:
+        yield from self._events.keys()
+
+
+builtin_events = {
+    "board.created": "Board created",
+    "board.updated": "Board updated",
+    "board.deleted": "Board deleted",
+    "column.created": "Column created",
+    "column.updated": "Column updated",
+    "column.deleted": "Column deleted",
+    "column.moved": "Column moved",
+    "card.created": "Card created",
+    "card.updated": "Card updated",
+    "card.deleted": "Card deleted",
+    "card.moved": "Card moved",
+    "card.blocked": "Card blocked",
+    "card.unblocked": "Card unblocked",
+    "wip.limit.reached": "WIP limit reached",
+    "workflow.transition": "Workflow transition",
+    "automation.triggered": "Automation triggered",
+    "automation.failed": "Automation failed",
+}
+
+CORE_EVENTS = EventRegistry(builtin_events)
+CARD_MOVED = "card.moved"
+CARD_UPDATED = "card.updated"
+CARD_CREATED = "card.created"
+CARD_DELETED = "card.deleted"
+COLUMN_UPDATED = "column.updated"
+COLUMN_CREATED = "column.created"
+COLUMN_DELETED = "column.deleted"
+BOARD_CREATED = "board.created"
+BOARD_UPDATED = "board.updated"
+BOARD_DELETED = "board.deleted"
+CARD_BLOCKED = "card.blocked"
+CARD_UNBLOCKED = "card.unblocked"
+
+
+@dataclass(frozen=True)
+class Event:
+    """Immutable event object. Handlers receive a copy."""
+
+    type: str
+    entity_id: str
+    entity_type: str
+    id: str
+    timestamp: datetime
+    data: dict[str, Any] = field(default_factory=dict)
+    user_id: str | None = None
+    schema_version: int = 1
+    correlation_id: str | None = None
+    causation_id: str | None = None
+    aggregate_version: int | None = None
+
+    def __post_init__(self) -> None:
+        # A frozen dataclass does not make nested dictionaries immutable. Detach the
+        # payload from the caller so later mutations cannot rewrite event history.
+        object.__setattr__(self, "data", deepcopy(self.data))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converts the event to a dictionary with serializable types."""
+
+        def _serialize_value(v: Any) -> Any:
+            if isinstance(v, set):
+                return sorted((_serialize_value(item) for item in v), key=repr)
+            if isinstance(v, list | tuple):
+                return [_serialize_value(item) for item in v]
+            if isinstance(v, Mapping):
+                return {key: _serialize_value(value) for key, value in v.items()}
+            if isinstance(v, datetime):
+                return v.isoformat()
+            if isinstance(v, timedelta):
+                return v.total_seconds()
+            if isinstance(v, Enum):
+                return _serialize_value(v.value)
+            if is_dataclass(v) and not isinstance(v, type):
+                return {
+                    item.name: _serialize_value(getattr(v, item.name))
+                    for item in fields(v)
+                }
+            return v
+
+        return {
+            "id": self.id,
+            "type": self.type,
+            "entity_id": self.entity_id,
+            "entity_type": self.entity_type,
+            "timestamp": self.timestamp.isoformat(),
+            "user_id": self.user_id,
+            "schema_version": self.schema_version,
+            "correlation_id": self.correlation_id,
+            "causation_id": self.causation_id,
+            "aggregate_version": self.aggregate_version,
+            "data": _serialize_value(self.data),
+        }
+
+
+class EventPublisher(Protocol):
+    """Outbound port used only after the aggregate commit succeeds."""
+
+    def publish(self, event: Event) -> None: ...

kanban/exceptions.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any, Protocol, runtime_checkable
+
+# ============= TYPE ALIASES & EXCEPTIONS =============
+
+Validator = Callable[[Any], None]
+
+
+class KanbanError(Exception):
+    """Base exception for all library errors."""
+
+
+class ValidationError(KanbanError):
+    """For business rule violations."""
+
+
+class PermissionError(KanbanError):
+    """For authorization failures."""
+
+
+class NotFoundError(KanbanError):
+    """For when an entity cannot be found."""
+
+
+class ConcurrencyError(KanbanError):
+    """For optimistic locking failures (lost updates)."""
+
+
+class InvalidPersistenceStateError(KanbanError):
+    """Persisted state violates business-module invariants."""
+
+
+@runtime_checkable
+class Clock(Protocol):
+    def __call__(self) -> datetime: ...
+
+
+def utc_clock() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@runtime_checkable
+class IDFactory(Protocol):
+    def __call__(self) -> str: ...
+
+
+def uuid4_factory() -> str:
+    return str(uuid.uuid4())

kanban/facade.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from .exceptions import Clock, IDFactory, utc_clock, uuid4_factory
+from .models import Board, Card, Column
+from .permissions import Permission, PermissionPolicy, SimplePermissionPolicy
+from .policies import WorkflowPolicy
+from .repositories import KanbanRepository, restore_board
+from .services import (
+    BoardAdminService,
+    CardSearcher,
+    CardWorkflowService,
+    InMemoryCardSearcher,
+    SyncAutomationRunner,
+    _KanbanServiceCore,
+)
+from .spi.automation import AutomationRunner
+from .unit_of_work import KanbanUnitOfWork
+
+
+@dataclass(frozen=True, slots=True)
+class CardView:
+    id: str
+    column_id: str
+    title: str
+    description: str
+    position: int
+    blocked_by: frozenset[str]
+    blocks: frozenset[str]
+    assignee_ids: frozenset[str]
+    due_date: datetime | None
+    size: float | None
+    archived: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnView:
+    id: str
+    name: str
+    position: int
+    card_ids: tuple[str, ...]
+    color: str | None
+    wip_limit: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class BoardView:
+    id: str
+    version: int
+    name: str
+    description: str
+    columns: tuple[ColumnView, ...]
+    cards: tuple[CardView, ...]
+    created_at: datetime | None
+    updated_at: datetime | None
+    owner_id: str | None
+    team_ids: frozenset[str]
+
+    def column_named(self, name: str) -> ColumnView | None:
+        return next((column for column in self.columns if column.name == name), None)
+
+    def card(self, card_id: str) -> CardView | None:
+        return next((card for card in self.cards if card.id == card_id), None)
+
+
+def _card_view(card: Card, board: Board) -> CardView:
+    column = board.column_for_card(card.id)
+    return CardView(
+        id=card.id,
+        column_id=column.id,
+        title=card.title,
+        description=card.description,
+        position=column.card_ids.index(card.id),
+        blocked_by=frozenset(card.blocked_by),
+        blocks=frozenset(card.blocks),
+        assignee_ids=frozenset(card.assignee_ids),
+        due_date=card.due_date,
+        size=card.size,
+        archived=card.archived,
+    )
+
+
+def _column_view(column: Column) -> ColumnView:
+    return ColumnView(
+        id=column.id,
+        name=column.name,
+        position=column.position,
+        card_ids=tuple(column.card_ids),
+        color=column.color,
+        wip_limit=column.policy.wip_limit,
+    )
+
+
+def _board_view(board: Board) -> BoardView:
+    cards = [
+        card
+        for column in board.get_columns_ordered()
+        for card in board.get_cards_in_column(column.id)
+    ]
+    return BoardView(
+        id=board.id,
+        version=board.version,
+        name=board.name,
+        description=board.description,
+        columns=tuple(_column_view(column) for column in board.get_columns_ordered()),
+        cards=tuple(_card_view(card, board) for card in cards),
+        created_at=board.created_at,
+        updated_at=board.updated_at,
+        owner_id=board.owner_id,
+        team_ids=frozenset(board.team_ids),
+    )
+
+
+class KanbanFacade:
+    """The complete public business capability surface for kanban-core."""
+
+    def __init__(
+        self,
+        repository: KanbanRepository,
+        unit_of_work: KanbanUnitOfWork,
+        permission_checker: PermissionPolicy | None = None,
+        searcher: CardSearcher | None = None,
+        automation_runner: AutomationRunner | None = None,
+        clock: Clock | None = None,
+        id_factory: IDFactory | None = None,
+        workflow_policy: WorkflowPolicy | None = None,
+    ) -> None:
+        core = _KanbanServiceCore(
+            repository=repository,
+            unit_of_work=unit_of_work,
+            permission_checker=permission_checker or SimplePermissionPolicy(),
+            searcher=searcher or InMemoryCardSearcher(),
+            automation_runner=automation_runner or SyncAutomationRunner(),
+            clock=clock or utc_clock,
+            id_factory=id_factory or uuid4_factory,
+            workflow_policy=workflow_policy,
+        )
+        self._core = core
+        self._admin = BoardAdminService(core)
+        self._cards = CardWorkflowService(core)
+
+    def create_board(
+        self, user_id: str, name: str, columns: list[str] | None = None
+    ) -> BoardView:
+        return _board_view(self._admin.create_board(name, user_id, columns))
+
+    def get_board(self, user_id: str, board_id: str) -> BoardView:
+        board = self._core.get_board_and_check_permission(
+            board_id, user_id, Permission.VIEW_BOARD
+        )
+        return _board_view(board)
+
+    def list_boards(self, user_id: str) -> list[BoardView]:
+        boards = [restore_board(item) for item in self._core.repository.list_all()]
+        return [
+            _board_view(board)
+            for board in boards
+            if self._core.is_allowed(user_id, board, Permission.VIEW_BOARD)
+        ]
+
+    def update_board(self, user_id: str, board_id: str, **changes: Any) -> BoardView:
+        return _board_view(self._admin.update_board(board_id, user_id, **changes))
+
+    def delete_board(self, user_id: str, board_id: str) -> None:
+        self._admin.delete_board(board_id, user_id)
+
+    def add_column(
+        self,
+        user_id: str,
+        board_id: str,
+        name: str,
+        position: int | None = None,
+    ) -> ColumnView:
+        return _column_view(
+            self._admin.create_column(board_id, user_id, name, position)
+        )
+
+    def update_column(
+        self, user_id: str, board_id: str, column_id: str, **changes: Any
+    ) -> ColumnView:
+        return _column_view(
+            self._admin.update_column(board_id, column_id, user_id, **changes)
+        )
+
+    def delete_column(self, user_id: str, board_id: str, column_id: str) -> None:
+        self._admin.delete_column(board_id, column_id, user_id)
+
+    def add_card(
+        self,
+        user_id: str,
+        board_id: str,
+        column_id: str,
+        title: str,
+        **fields: Any,
+    ) -> CardView:
+        card = self._cards.create_card(board_id, column_id, title, user_id, **fields)
+        board = self._core.get_board_and_check_permission(
+            board_id, user_id, Permission.VIEW_BOARD
+        )
+        return _card_view(card, board)
+
+    def update_card(
+        self, user_id: str, board_id: str, card_id: str, **changes: Any
+    ) -> CardView:
+        card = self._cards.update_card(board_id, card_id, user_id, **changes)
+        board = self._core.get_board_and_check_permission(
+            board_id, user_id, Permission.VIEW_BOARD
+        )
+        return _card_view(card, board)
+
+    def move_card(
+        self,
+        user_id: str,
+        board_id: str,
+        card_id: str,
+        to_column_id: str,
+        position: int | None = None,
+    ) -> CardView:
+        card = self._cards.move_card(board_id, card_id, to_column_id, position, user_id)
+        board = self._core.get_board_and_check_permission(
+            board_id, user_id, Permission.VIEW_BOARD
+        )
+        return _card_view(card, board)
+
+    def delete_card(self, user_id: str, board_id: str, card_id: str) -> None:
+        self._cards.delete_card(board_id, card_id, user_id)
+
+    def block_card(
+        self,
+        user_id: str,
+        board_id: str,
+        card_to_block_id: str,
+        blocking_card_id: str,
+    ) -> None:
+        self._cards.block_card_dependency(
+            board_id, blocking_card_id, card_to_block_id, user_id
+        )
+
+    def unblock_card(
+        self,
+        user_id: str,
+        board_id: str,
+        card_to_unblock_id: str,
+        blocking_card_id: str,
+    ) -> None:
+        self._cards.unblock_card_dependency(
+            board_id, blocking_card_id, card_to_unblock_id, user_id
+        )
+
+    def search_cards(
+        self, user_id: str, board_id: str, **filters: Any
+    ) -> list[CardView]:
+        board = self._core.get_board_and_check_permission(
+            board_id, user_id, Permission.VIEW_BOARD
+        )
+        card_ids = self._core.searcher.search(
+            self._core.search_context(board), **filters
+        )
+        return [_card_view(board.cards[card_id], board) for card_id in card_ids]

kanban/models.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from .exceptions import ValidationError
+
+# ============= CORE DOMAIN MODELS =============
+
+
+@dataclass
+class Card:
+    """Core card/item entity."""
+
+    id: str
+    title: str = ""
+    description: str = ""
+    blocked_by: set[str] = field(default_factory=set)
+    blocks: set[str] = field(default_factory=set)
+    assignee_ids: set[str] = field(default_factory=set)
+    due_date: datetime | None = None
+    size: float | None = None
+    archived: bool = False
+
+    def is_blocked(self) -> bool:
+        return bool(self.blocked_by)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "description": self.description,
+            "blocked_by": sorted(self.blocked_by),
+            "blocks": sorted(self.blocks),
+            "assignee_ids": sorted(self.assignee_ids),
+            "due_date": self.due_date.isoformat() if self.due_date else None,
+            "size": self.size,
+            "archived": self.archived,
+        }
+
+
+@dataclass
+class ColumnPolicy:
+    """Rules for column behavior."""
+
+    wip_limit: int | None = None
+
+
+@dataclass
+class Column:
+    """Board column/list."""
+
+    id: str
+    board_id: str
+    name: str = ""
+    position: int = 0
+    policy: ColumnPolicy = field(default_factory=ColumnPolicy)
+    card_ids: list[str] = field(default_factory=list)
+    color: str | None = None
+
+    def can_accept_card(self, is_new_entry: bool) -> tuple[bool, str | None]:
+        if (
+            is_new_entry
+            and self.policy.wip_limit is not None
+            and len(self.card_ids) >= self.policy.wip_limit
+        ):
+            return False, f"WIP limit of {self.policy.wip_limit} would be exceeded."
+        return True, None
+
+
+@dataclass
+class Board:
+    """Kanban board entity"""
+
+    id: str
+    version: int = 1
+    name: str = ""
+    description: str = ""
+    columns: dict[str, Column] = field(default_factory=dict)
+    cards: dict[str, Card] = field(default_factory=dict)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    owner_id: str | None = None
+    team_ids: set[str] = field(default_factory=set)
+
+    def get_columns_ordered(self) -> list[Column]:
+        return sorted(self.columns.values(), key=lambda c: c.position)
+
+    def column_for_card(self, card_id: str) -> Column:
+        for column in self.columns.values():
+            if card_id in column.card_ids:
+                return column
+        raise ValidationError(f"Card '{card_id}' is not assigned to a column")
+
+    def get_cards_in_column(self, column_id: str) -> list[Card]:
+        column = self.columns.get(column_id)
+        if not column:
+            return []
+        return [
+            self.cards[card_id] for card_id in column.card_ids if card_id in self.cards
+        ]

kanban/permissions.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Protocol
+
+
+class Permission(Enum):
+    VIEW_BOARD = auto()
+    EDIT_BOARD = auto()
+    DELETE_BOARD = auto()
+    CREATE_CARD = auto()
+    EDIT_CARD = auto()
+    MOVE_CARD = auto()
+    DELETE_CARD = auto()
+    CREATE_COLUMN = auto()
+    EDIT_COLUMN = auto()
+    DELETE_COLUMN = auto()
+    MANAGE_USERS = auto()
+    MANAGE_AUTOMATION = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionContext:
+    board_id: str
+    owner_id: str
+    team_ids: frozenset[str]
+
+
+class PermissionPolicy(Protocol):
+    def has_permission(
+        self, user_id: str, context: PermissionContext, permission: Permission
+    ) -> bool: ...
+
+
+class SimplePermissionPolicy:
+    DEFAULT_MEMBER_PERMISSIONS = {
+        Permission.VIEW_BOARD,
+        Permission.CREATE_CARD,
+        Permission.EDIT_CARD,
+        Permission.MOVE_CARD,
+        Permission.DELETE_CARD,
+        Permission.CREATE_COLUMN,
+        Permission.EDIT_COLUMN,
+        Permission.DELETE_COLUMN,
+    }
+
+    def __init__(self, member_permissions: set[Permission] | None = None):
+        self.member_permissions = (
+            set(member_permissions)
+            if member_permissions is not None
+            else set(self.DEFAULT_MEMBER_PERMISSIONS)
+        )
+
+    def has_permission(
+        self, user_id: str, context: PermissionContext, permission: Permission
+    ) -> bool:
+        if not user_id:
+            return False
+        if context.owner_id == user_id:
+            return True
+        if user_id in context.team_ids:
+            return permission in self.member_permissions
+        return False

kanban/policies.py

@@ -0,0 +1,66 @@
+"""Public, read-only extension points for organization-specific workflow rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class CardPolicyContext:
+    """A detached card snapshot supplied to an external workflow policy."""
+
+    board_id: str
+    user_id: str
+    card_id: str
+    column_id: str
+    title: str
+    description: str
+    assignee_ids: frozenset[str]
+    due_date: datetime | None
+    size: float | None
+    archived: bool
+
+
+@dataclass(frozen=True, slots=True)
+class CardMovePolicyContext:
+    """The proposed card transition, before the aggregate is mutated."""
+
+    card: CardPolicyContext
+    from_column_id: str
+    to_column_id: str
+    position: int
+
+
+class WorkflowPolicy(Protocol):
+    """Optional policy port for deployment-specific card lifecycle rules.
+
+    Implementations validate only. They must not persist data, publish events, or
+    mutate the supplied contexts. A rejected operation should raise
+    ``kanban.ValidationError`` (or a subclass).
+    """
+
+    def validate_create(self, context: CardPolicyContext) -> None: ...
+
+    def validate_update(self, context: CardPolicyContext) -> None: ...
+
+    def validate_move(self, context: CardMovePolicyContext) -> None: ...
+
+    def validate_delete(self, context: CardPolicyContext) -> None: ...
+
+
+class AllowAllWorkflowPolicy:
+    """Default policy; structural domain invariants still apply."""
+
+    def validate_create(self, context: CardPolicyContext) -> None:
+        pass
+
+    def validate_update(self, context: CardPolicyContext) -> None:
+        pass
+
+    def validate_move(self, context: CardMovePolicyContext) -> None:
+        pass
+
+    def validate_delete(self, context: CardPolicyContext) -> None:
+        pass