pyclifer 0.4.1__py3-none-any.whl

pyclifer/__init__.py

@@ -0,0 +1,159 @@
+"""pyclifer — PYthon Command Line Interface Framework"""
+
+__app_name__ = "pyclifer"
+__version__ = "0.4.1"
+
+from click_extra import (
+    BOOL,
+    FLOAT,
+    INT,
+    STRING,
+    UUID,
+    Abort,
+    BadParameter,
+    Choice,
+    ClickException,
+    DateTime,
+    File,
+    FloatRange,
+    IntRange,
+    TimerOption,
+    Tuple,
+    UsageError,
+    argument,
+    confirm,
+    confirmation_option,
+    echo,
+    get_current_context,
+    make_pass_decorator,
+    pass_context,
+    pass_obj,
+    password_option,
+    prompt,
+    secho,
+    style,
+    unstyle,
+    version_option,
+)
+from click_extra import (
+    Path as ClickPath,
+)
+
+from .core.classes import CustomConfigOption, PycliferGroup, PycliferOption
+from .core.context import BaseContext
+from .core.decorators import (
+    app_group,
+    command,
+    group,
+    option,
+    output_filter_option,
+    pagination_options,
+    returns_response,
+)
+from .core.interfaces import BaseInterface
+from .core.log import (
+    PYCLIFER_LOG_LEVELS,
+    TRACE,
+    RichExtraFormatter,
+    RichExtraStreamHandler,
+    SecretsMasker,
+    add_trace_method,
+    configure_rich_logging,
+    get_configured_logger,
+    get_logger,
+    logger,
+)
+from .core.mixins import (
+    GlobalOptionsMixin,
+    HandleResponseMixin,
+    OutputFormatMixin,
+    RichHelpersMixin,
+)
+from .core.models import BaseModel
+from .core.output import (
+    BaseRenderer,
+    CliTable,
+    CliTableColumn,
+    ExceptionTable,
+    ExitCode,
+    OperationResult,
+    PaginatedResponse,
+    Response,
+    ResponseRenderer,
+)
+
+__all__ = [
+    "__app_name__",
+    "__version__",
+    # methods
+    "app_group",
+    "group",
+    "command",
+    "option",
+    # click_extra re-exports
+    "argument",
+    "pass_context",
+    "pass_obj",
+    "make_pass_decorator",
+    "get_current_context",
+    "Choice",
+    "ClickPath",
+    "File",
+    "INT",
+    "FLOAT",
+    "BOOL",
+    "STRING",
+    "UUID",
+    "DateTime",
+    "Tuple",
+    "IntRange",
+    "FloatRange",
+    "echo",
+    "secho",
+    "style",
+    "unstyle",
+    "confirm",
+    "prompt",
+    "ClickException",
+    "BadParameter",
+    "UsageError",
+    "Abort",
+    "TimerOption",
+    "version_option",
+    "confirmation_option",
+    "password_option",
+    "output_filter_option",
+    "pagination_options",
+    "returns_response",
+    "get_logger",
+    "logger",
+    "add_trace_method",
+    "get_configured_logger",
+    "configure_rich_logging",
+    # class
+    "BaseContext",
+    "BaseModel",
+    "ExitCode",
+    "OperationResult",
+    "PaginatedResponse",
+    "Response",
+    "BaseInterface",
+    "BaseRenderer",
+    "ResponseRenderer",
+    "CliTable",
+    "CliTableColumn",
+    "ExceptionTable",
+    "CustomConfigOption",
+    "PycliferGroup",
+    "PycliferOption",
+    "GlobalOptionsMixin",
+    "HandleResponseMixin",
+    "OutputFormatMixin",
+    "RichHelpersMixin",
+    "RichExtraFormatter",
+    "RichExtraStreamHandler",
+    "SecretsMasker",
+    # Constants
+    "PYCLIFER_LOG_LEVELS",
+    "TRACE",
+]

pyclifer/apps/__init__.py

@@ -0,0 +1,8 @@
+"""Folder apps in cli"""
+
+# Import each group here so cli.py can wire them with add_command.
+# Updated automatically by `pyclifer project add app`.
+from .demo import demo
+from .project import project
+
+groups = [project, demo]

pyclifer/apps/demo/__init__.py

@@ -0,0 +1,25 @@
+"""Demo app group."""
+
+from pyclifer import group
+
+from .apps.tasks import tasks
+from .apps.users import users
+from .commands import commands
+from .core.context import pass_demo_context
+from .core.options import project_option
+
+subgroups = [tasks, users]
+
+
+@group()
+@project_option
+@pass_demo_context
+def demo(ctx):
+    """Demo task manager — reference implementation of all pyclifer features."""
+
+
+for grp in subgroups:
+    demo.add_command(grp)
+
+for cmd in commands:
+    demo.add_command(cmd)

pyclifer/apps/demo/apps/tasks/__init__.py

@@ -0,0 +1,19 @@
+"""Tasks app group."""
+
+from pyclifer import group
+
+from .commands import commands
+
+subgroups = []
+
+
+@group()
+def tasks():
+    """Tasks group."""
+
+
+for grp in subgroups:
+    tasks.add_command(grp)
+
+for cmd in commands:
+    tasks.add_command(cmd)

pyclifer/apps/demo/apps/tasks/commands/__init__.py

@@ -0,0 +1,10 @@
+"""Commands for the Tasks app."""
+
+from .add import add
+from .complete import complete
+from .delete import delete
+from .list import list
+from .show import show
+from .sync import sync
+
+commands = [add, complete, delete, list, show, sync]

pyclifer/apps/demo/apps/tasks/commands/add.py

@@ -0,0 +1,27 @@
+from pyclifer import DateTime, Response, command, option
+
+from ....core.constants import PRIORITY_CHOICE
+from ....core.context import pass_demo_context
+from ..interfaces import TaskInterface
+
+
+@command()
+@option("--title", required=True, help="Task title.")
+@option("--description", default="", help="Task description.")
+@option("--priority", type=PRIORITY_CHOICE, default="medium", help="Task priority.")
+@option("--due", type=DateTime(formats=["%Y-%m-%d"]), default=None, help="Due date (YYYY-MM-DD).")
+@option("--tags", default="", help="Comma-separated list of tags.")
+@option("--assignee", default="", help="Assignee username.")
+@pass_demo_context
+def add(ctx, title, description, priority, due, tags, assignee) -> Response:
+    """Add a new task."""
+    tag_list = [t.strip() for t in tags.split(",") if t.strip()] if tags else []
+    return TaskInterface(ctx).respond(
+        "add_task",
+        title=title,
+        description=description,
+        priority=priority,
+        due_date=due.date() if due else None,
+        tags=tag_list,
+        assignee=assignee,
+    )

pyclifer/apps/demo/apps/tasks/commands/complete.py

@@ -0,0 +1,12 @@
+from pyclifer import Response, argument, command
+
+from ....core.context import pass_demo_context
+from ..interfaces import TaskInterface
+
+
+@command()
+@argument("task_id")
+@pass_demo_context
+def complete(ctx, task_id) -> Response:
+    """Mark a task as done."""
+    return TaskInterface(ctx).respond("complete_task", task_id=task_id)

pyclifer/apps/demo/apps/tasks/commands/delete.py

@@ -0,0 +1,15 @@
+from pyclifer import Abort, Response, argument, command, option
+
+from ....core.context import pass_demo_context
+from ..interfaces import TaskInterface
+
+
+@command()
+@argument("task_id")
+@option("--yes", "-y", is_flag=True, default=False, help="Skip confirmation prompt.")
+@pass_demo_context
+def delete(ctx, task_id, yes) -> Response:
+    """Delete a task permanently."""
+    if not yes and not ctx.ask_confirmation(f"Delete task '{task_id}'?"):
+        raise Abort()
+    return TaskInterface(ctx).respond("delete_task", task_id=task_id)

pyclifer/apps/demo/apps/tasks/commands/list.py

@@ -0,0 +1,38 @@
+from pyclifer import (
+    PaginatedResponse,
+    Response,
+    command,
+    option,
+    output_filter_option,
+    pagination_options,
+)
+
+from ....core.constants import PRIORITY_CHOICE, STATUS_CHOICE
+from ....core.context import pass_demo_context
+from ..interfaces import TaskInterface
+
+
+@command()
+@pagination_options()
+@output_filter_option()
+@option("--status", type=STATUS_CHOICE, default=None, help="Filter by status.")
+@option("--priority", type=PRIORITY_CHOICE, default=None, help="Filter by priority.")
+@pass_demo_context
+def list(ctx, status, priority) -> Response:
+    """List all tasks with optional filtering and pagination."""
+    response = TaskInterface(ctx).respond("list_tasks", status=status, priority=priority)
+    page = ctx.click.meta.get("pyclifer.page", 1)
+    limit = ctx.click.meta.get("pyclifer.limit", 20)
+    results = response.data.get("results", [])
+    total = len(results)
+    start = (page - 1) * limit
+    return PaginatedResponse(
+        success=response.success,
+        message=response.message,
+        data={"results": results[start : start + limit]},
+        error_code=response.error_code,
+        renderer=response.renderer,
+        page=page,
+        limit=limit,
+        total=total,
+    )

pyclifer/apps/demo/apps/tasks/commands/show.py

@@ -0,0 +1,12 @@
+from pyclifer import Response, argument, command
+
+from ....core.context import pass_demo_context
+from ..interfaces import TaskInterface
+
+
+@command()
+@argument("task_id")
+@pass_demo_context
+def show(ctx, task_id) -> Response:
+    """Show details of a specific task."""
+    return TaskInterface(ctx).respond("show_task", task_id=task_id)

pyclifer/apps/demo/apps/tasks/commands/sync.py

@@ -0,0 +1,16 @@
+from pyclifer import Response, command, option
+
+from ....core.context import pass_demo_context
+from ..interfaces import TaskInterface
+
+
+@command()
+@option(
+    "--source",
+    default="https://remote.example.com/tasks",
+    help="URL of the remote task source. Supports embedded credentials.",
+)
+@pass_demo_context
+def sync(ctx, source) -> Response:
+    """Sync tasks from a remote source."""
+    return TaskInterface(ctx).respond("sync_tasks", source=source)

pyclifer/apps/demo/apps/tasks/interfaces.py

@@ -0,0 +1,208 @@
+"""Interface for the Tasks app."""
+
+from __future__ import annotations
+
+import datetime
+import time
+import uuid
+from collections.abc import Iterator
+
+from pyclifer import BaseInterface, ExitCode, OperationResult, get_logger
+
+from ...core.context import DemoContext
+from .models import Task
+from .renderers import (
+    TaskAddRenderer,
+    TaskCompleteRenderer,
+    TaskDeleteRenderer,
+    TaskDetailRenderer,
+    TaskListRenderer,
+    TaskSyncRenderer,
+)
+
+logger = get_logger(__name__)
+
+_FAKE_SYNC_TITLES = [
+    "Fix login bug",
+    "Update documentation",
+    "Review open PRs",
+    "Deploy to staging",
+    "Write integration tests",
+    "Refactor auth module",
+    "Add rate limiting",
+    "Update dependencies",
+]
+
+
+class TaskInterface(BaseInterface):
+    """Interface for Tasks business logic."""
+
+    ctx: DemoContext
+
+    renderers = {
+        "list_tasks": TaskListRenderer,
+        "add_task": TaskAddRenderer,
+        "show_task": TaskDetailRenderer,
+        "complete_task": TaskCompleteRenderer,
+        "delete_task": TaskDeleteRenderer,
+        "sync_tasks": TaskSyncRenderer,
+        # --- renderers --- (used by `pyclifer project add command` — do not remove)
+    }
+
+    def list_tasks(
+        self,
+        status: str | None = None,
+        priority: str | None = None,
+    ) -> list[OperationResult]:
+        """Return all tasks, optionally filtered by status and priority.
+
+        Pagination is handled at the command level via PaginatedResponse.
+
+        Args:
+            status: Only return tasks with this status. None means no filter.
+            priority: Only return tasks with this priority. None means no filter.
+
+        Returns:
+            One OperationResult per matching task.
+        """
+        tasks = self.ctx.storage.get_tasks()
+        if status:
+            tasks = [t for t in tasks if t.status == status]
+        if priority:
+            tasks = [t for t in tasks if t.priority == priority]
+        logger.debug("list tasks: %d results (status=%s priority=%s)", len(tasks), status, priority)
+        return [OperationResult.ok(item=t.id, data=t) for t in tasks]
+
+    def add_task(
+        self,
+        title: str = "",
+        description: str = "",
+        priority: str = "medium",
+        due_date: datetime.date | None = None,
+        tags: list[str] | None = None,
+        assignee: str = "",
+    ) -> list[OperationResult]:
+        """Create and persist a new task.
+
+        Args:
+            title: Short task title.
+            description: Optional longer description.
+            priority: One of lows, medium, high.
+            due_date: Optional due date.
+            tags: Optional list of tag strings.
+            assignee: Optional assignee name.
+
+        Returns:
+            A single OperationResult with the new task as data.
+        """
+        task = Task(
+            id=str(uuid.uuid4()),
+            title=title,
+            description=description,
+            priority=priority,
+            due_date=due_date,
+            tags=tags or [],
+            assignee=assignee,
+            created_at=datetime.datetime.now(),
+        )
+        self.ctx.storage.upsert_task(task)
+        logger.debug("add task: created %s", task.id)
+        return [OperationResult.ok(item=task.id, message=f"Task '{title}' created.", data=task)]
+
+    def show_task(self, task_id: str = "") -> list[OperationResult]:
+        """Return a single task by id.
+
+        Args:
+            task_id: UUID of the task to retrieve.
+
+        Returns:
+            A single OperationResult with the task as data, or an error result
+            with error_code 404 when not found.
+        """
+        task = self.ctx.storage.get_task(task_id)
+        if task is None:
+            return [
+                OperationResult.error(
+                    item=task_id,
+                    message=f"Task '{task_id}' not found.",
+                    error_code=ExitCode.NOT_FOUND,
+                )
+            ]
+        return [OperationResult.ok(item=task.id, data=task)]
+
+    def complete_task(self, task_id: str = "") -> list[OperationResult]:
+        """Mark a task as done.
+
+        Args:
+            task_id: UUID of the task to complete.
+
+        Returns:
+            A successful result, or an error result when the task is not found
+            or already done.
+        """
+        task = self.ctx.storage.get_task(task_id)
+        if task is None:
+            return [
+                OperationResult.error(
+                    item=task_id,
+                    message=f"Task '{task_id}' not found.",
+                    error_code=ExitCode.NOT_FOUND,
+                )
+            ]
+        if task.status == "done":
+            return [
+                OperationResult.error(item=task_id, message=f"Task '{task_id}' is already done.")
+            ]
+        task.status = "done"
+        self.ctx.storage.upsert_task(task)
+        logger.debug("complete task: %s marked done", task_id)
+        return [OperationResult.ok(item=task_id, message=f"Task '{task.title}' marked as done.")]
+
+    def delete_task(self, task_id: str = "") -> list[OperationResult]:
+        """Delete a task permanently.
+
+        Args:
+            task_id: UUID of the task to delete.
+
+        Returns:
+            A successful result, or an error result with error_code 404 when
+            the task is not found.
+        """
+        found = self.ctx.storage.delete_task(task_id)
+        if not found:
+            return [
+                OperationResult.error(
+                    item=task_id,
+                    message=f"Task '{task_id}' not found.",
+                    error_code=ExitCode.NOT_FOUND,
+                )
+            ]
+        logger.debug("delete task: %s removed", task_id)
+        return [OperationResult.ok(item=task_id, message=f"Task '{task_id}' deleted.")]
+
+    def sync_tasks(
+        self, source: str = "https://remote.example.com/tasks"
+    ) -> Iterator[OperationResult]:
+        """Simulate a live sync from a remote source, yielding one result per task.
+
+        Yields one OperationResult every 0.1 s to drive the streaming renderer.
+        Credentials embedded in the URL are masked before logging.
+
+        Args:
+            source: URL of the remote task source. May contain embedded credentials.
+
+        Yields:
+            One OperationResult per imported task.
+        """
+        logger.debug("sync tasks from %s", source)
+        for title in _FAKE_SYNC_TITLES:
+            time.sleep(0.1)
+            task = Task(
+                id=str(uuid.uuid4()),
+                title=title,
+                created_at=datetime.datetime.now(),
+            )
+            self.ctx.storage.upsert_task(task)
+            yield OperationResult.ok(item=task.id, data=task, message=f"Synced: {title}")
+
+    # --- commands --- (used by `pyclifer project add command` — do not remove)

pyclifer/apps/demo/apps/tasks/models.py

@@ -0,0 +1,61 @@
+"""Data models for the Tasks app."""
+
+from __future__ import annotations
+
+import datetime
+
+import pydantic
+
+from pyclifer import BaseModel
+
+from ...core.constants import PRIORITIES, STATUSES
+
+
+class Task(BaseModel):
+    """Single task in the demo task manager."""
+
+    id: str
+    title: str
+    description: str = ""
+    priority: str = "medium"
+    status: str = "open"
+    due_date: datetime.date | None = None
+    tags: list[str] = []
+    assignee: str = ""
+    created_at: datetime.datetime
+
+    @pydantic.field_validator("priority")
+    @classmethod
+    def validate_priority(cls, v: str) -> str:
+        """Reject priority values outside the allowed set.
+
+        Args:
+            v: The raw priority string.
+
+        Returns:
+            The validated priority string.
+
+        Raises:
+            ValueError: When v is not in PRIORITIES.
+        """
+        if v not in PRIORITIES:
+            raise ValueError(f"priority must be one of {PRIORITIES}, got {v!r}")
+        return v
+
+    @pydantic.field_validator("status")
+    @classmethod
+    def validate_status(cls, v: str) -> str:
+        """Reject status values outside the allowed set.
+
+        Args:
+            v: The raw status string.
+
+        Returns:
+            The validated status string.
+
+        Raises:
+            ValueError: When v is not in STATUSES.
+        """
+        if v not in STATUSES:
+            raise ValueError(f"status must be one of {STATUSES}, got {v!r}")
+        return v