upnext 0.0.1__tar.gz

upnext-0.0.1/.gitignore

@@ -0,0 +1,111 @@
+# =============================================================================
+# Python
+# =============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.manifest
+pip-log.txt
+pip-delete-this-directory.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+*.mo
+*.pot
+.venv/
+venv/
+ENV/
+env/
+.pdm.toml
+.pdm-python
+.pdm-build/
+__pypackages__/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+cython_debug/
+.ruff_cache/
+.pypirc
+
+# =============================================================================
+# Node / Next.js
+# =============================================================================
+node_modules/
+.pnp
+.pnp.js
+.next/
+out/
+next-env.d.ts
+.source/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+*.tsbuildinfo
+.vercel
+
+# =============================================================================
+# Database
+# =============================================================================
+*.sqlite
+*.sqlite3
+*.sqlite3-journal
+db.sqlite
+db.sqlite3
+
+# =============================================================================
+# Environment & Secrets
+# =============================================================================
+.env
+.env*.local
+.env.prod
+
+# =============================================================================
+# IDE & OS
+# =============================================================================
+.DS_Store
+*.pem
+.idea/
+*.swp
+*.swo
+*~
+
+# =============================================================================
+# Testing & Coverage
+# =============================================================================
+coverage/
+coverage_html/
+test-results/
+playwright-report/
+blob-report/
+.vitest/
+
+# =============================================================================
+# tanstack start
+# =============================================================================
+.output/
+.tanstack/

upnext-0.0.1/Dockerfile

@@ -0,0 +1,29 @@
+# UpNext SDK + CLI
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy workspace files
+COPY pyproject.toml uv.lock ./
+COPY packages/shared ./packages/shared
+COPY packages/upnext ./packages/upnext
+COPY packages/server/pyproject.toml packages/server/README.md ./packages/server/
+COPY packages/server/src ./packages/server/src
+COPY packages/server/alembic.ini ./packages/server/alembic.ini
+COPY packages/server/alembic ./packages/server/alembic
+COPY packages/server/static ./packages/server/static
+
+# Install dependencies
+RUN uv sync --frozen --no-dev --package upnext
+
+# Set working directory
+WORKDIR /app/packages/upnext
+
+# Ensure Python output is not buffered
+ENV PYTHONUNBUFFERED=1
+
+# Default: show CLI help (no examples are bundled into the image)
+CMD ["uv", "run", "upnext", "--help"]

upnext-0.0.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: upnext
+Version: 0.0.1
+Summary: Background jobs and APIs for Python. Like Modal, but self-hostable.
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.11.0
+Requires-Dist: croniter>=6.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: redis>=5.2.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: upnext-server
+Requires-Dist: upnext-shared
+Requires-Dist: uvicorn>=0.34.0
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# UpNext Package
+
+Core SDK/runtime package for workers, tasks, APIs, and queue processing.
+
+## Package Validation
+
+From the workspace root:
+
+```bash
+./scripts/verify-upnext-package.sh
+```
+
+This runs the upnext package test suite with branch coverage and enforces the current minimum coverage gate.

upnext-0.0.1/README.md

@@ -0,0 +1,13 @@
+# UpNext Package
+
+Core SDK/runtime package for workers, tasks, APIs, and queue processing.
+
+## Package Validation
+
+From the workspace root:
+
+```bash
+./scripts/verify-upnext-package.sh
+```
+
+This runs the upnext package test suite with branch coverage and enforces the current minimum coverage gate.

upnext-0.0.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "upnext"
+dynamic = ["version"]
+description = "Background jobs and APIs for Python. Like Modal, but self-hostable."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.11.0",
+    "croniter>=6.0.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.10.0",
+    "pydantic-settings>=2.12.0",
+    "redis>=5.2.0",
+    "rich>=13.9.0",
+    "upnext-server",
+    "upnext-shared",
+    "typer>=0.15.0",
+    "uvicorn>=0.34.0",
+]
+
+[project.optional-dependencies]
+server = []
+
+[project.scripts]
+upnext = "upnext.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/upnext"]
+
+[tool.hatch.version]
+path = "../shared/src/shared/_version.py"
+
+[tool.uv.sources]
+"upnext-server" = { workspace = true }
+"upnext-shared" = { workspace = true }

upnext-0.0.1/src/upnext/__init__.py

@@ -0,0 +1,68 @@
+"""UpNext - Background job processing framework."""
+
+import asyncio
+
+from shared import __version__
+from shared.artifacts import ArtifactType
+
+from upnext.engine import run_services
+from upnext.sdk import (
+    Api,
+    Context,
+    Worker,
+    create_artifact,
+    create_artifact_sync,
+    get_current_context,
+)
+from upnext.types import SyncExecutor
+
+__all__ = [
+    "Api",
+    "ArtifactType",
+    "Context",
+    "Worker",
+    "SyncExecutor",
+    "__version__",
+    "create_artifact",
+    "create_artifact_sync",
+    "get_current_context",
+    "run",
+]
+
+
+def run(
+    *components: Api | Worker,
+    worker_timeout: float = 3.0,
+    api_timeout: float = 1.5,
+) -> None:
+    """Run one or more Api and/or Worker instances.
+
+    Handles signal coordination so Ctrl+C gracefully stops all components.
+
+    Args:
+        *components: Api and/or Worker instances to run.
+        worker_timeout: Seconds to wait for workers to finish active jobs before force-stopping (default 3.0).
+        api_timeout: Seconds to wait for APIs to finish requests before force-stopping (default 1.5).
+
+    Example:
+        import upnext
+
+        api = upnext.Api("my-api")
+        worker = upnext.Worker("my-worker")
+
+        upnext.run(api, worker)
+
+        # With custom timeouts (e.g., for long-running jobs):
+        upnext.run(api, worker, worker_timeout=30.0)
+    """
+    apis = [c for c in components if isinstance(c, Api)]
+    workers = [c for c in components if isinstance(c, Worker)]
+
+    try:
+        asyncio.run(
+            run_services(
+                apis, workers, worker_timeout=worker_timeout, api_timeout=api_timeout
+            )
+        )
+    except KeyboardInterrupt:
+        pass

upnext-0.0.1/src/upnext/cli/__init__.py

@@ -0,0 +1,75 @@
+"""UpNext CLI."""
+
+import typer
+
+from upnext.cli._console import console
+from upnext.cli.call import call
+from upnext.cli.list import list_cmd
+from upnext.cli.run import run
+from upnext.cli.server import (
+    db_current as server_db_current,
+)
+from upnext.cli.server import (
+    db_history as server_db_history,
+)
+from upnext.cli.server import (
+    db_upgrade as server_db_upgrade,
+)
+from upnext.cli.server import (
+    start as server_start,
+)
+
+app = typer.Typer(
+    name="upnext",
+    help="Easy background workers and APIs for Python.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        from upnext import __version__
+
+        console.print(f"[bold]upnext[/bold] [dim]{__version__}[/dim]")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version",
+    ),
+) -> None:
+    """Background jobs and APIs for Python."""
+
+
+# Register commands
+app.command()(run)
+app.command()(call)
+app.command("list")(list_cmd)
+
+server_app = typer.Typer(
+    help="Hosted UpNext server commands.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+server_app.command("start")(server_start)
+
+server_db_app = typer.Typer(
+    help="Database migration commands for the hosted server.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+server_db_app.command("upgrade")(server_db_upgrade)
+server_db_app.command("current")(server_db_current)
+server_db_app.command("history")(server_db_history)
+server_app.add_typer(server_db_app, name="db")
+
+app.add_typer(server_app, name="server")

upnext-0.0.1/src/upnext/cli/_console.py

@@ -0,0 +1,112 @@
+"""Shared console and formatting utilities."""
+
+import logging
+import os
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+# Force colors unless explicitly disabled (NO_COLOR standard)
+no_color = os.environ.get("NO_COLOR", "").lower() in ("1", "true", "yes")
+
+console = Console(
+    highlight=False,
+    force_terminal=not no_color,
+    no_color=no_color,
+)
+
+
+def header(title: str) -> None:
+    """Print a minimal header."""
+    console.print()
+    console.print(f"[bold]{title}[/bold]")
+    console.print()
+
+
+def success(msg: str) -> None:
+    """Print success message."""
+    console.print(f"  [green]✓[/green] {msg}")
+
+
+def error(msg: str) -> None:
+    """Print error message."""
+    console.print(f"  [red]✗[/red] {msg}")
+
+
+def warning(msg: str) -> None:
+    """Print warning message."""
+    console.print(f"  [yellow]![/yellow] {msg}")
+
+
+def info(msg: str) -> None:
+    """Print info message."""
+    console.print(f"  [dim]→[/dim] {msg}")
+
+
+def dim(msg: str) -> None:
+    """Print dimmed text."""
+    console.print(f"  [dim]{msg}[/dim]")
+
+
+def error_panel(msg: str, *, title: str = "Failed") -> None:
+    """Print a styled error panel."""
+    from rich.box import ROUNDED
+    from rich.panel import Panel
+    from rich.text import Text
+
+    lines: list[Text] = []
+    line = Text()
+    line.append("✗ ", style="red bold")
+    line.append(title, style="red")
+    lines.append(line)
+    lines.append(Text())
+    lines.append(Text(msg, style="dim"))
+
+    panel = Panel(
+        Text("\n").join(lines),
+        border_style="red dim",
+        box=ROUNDED,
+        padding=(0, 1),
+        expand=False,
+    )
+    console.print(panel)
+
+
+def nl() -> None:
+    """Print newline."""
+    console.print()
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure clean logging for upnext CLI."""
+    # Suppress noisy loggers
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    logging.getLogger("uvicorn.error").setLevel(logging.WARNING)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("aiohttp").setLevel(logging.WARNING)
+
+    # Set up rich handler for clean output
+    handler = RichHandler(
+        console=console,
+        show_time=False,
+        show_path=False,
+        rich_tracebacks=True,
+        markup=True,
+        keywords=[],
+    )
+
+    # Configure root logger
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        handlers=[handler],
+        force=True,
+    )
+
+    # Keep upnext loggers at appropriate level
+    logging.getLogger("upnext").setLevel(level)
+
+    # Allow engine worker logs during debugging
+    logging.getLogger("upnext.").setLevel(level)

upnext-0.0.1/src/upnext/cli/_display.py

@@ -0,0 +1,140 @@
+"""Shared display utilities for CLI commands."""
+
+from collections.abc import Callable
+
+import typer
+from rich.box import ROUNDED
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from upnext.cli._console import console, error, nl
+from upnext.engine.runner import run_services as run_services  # re-export
+from upnext.sdk.api import Api
+from upnext.sdk.worker import Worker
+
+# run_services was moved to upnext.engine.runner but re-exported here for backwards compatibility
+__all__ = ["run_services", "worker_lines", "print_services_panel", "filter_components"]
+
+
+def worker_lines(
+    worker: Worker,
+) -> list[Text]:
+    """Build display lines for a worker (name, handlers)."""
+    lines: list[Text] = []
+
+    # Worker name
+    line = Text(no_wrap=True, overflow="ellipsis")
+    line.append(f"{worker.name}", style="cyan bold")
+    lines.append(line)
+
+    # Handler lines
+    task_names = list(worker.tasks.keys())
+    cron_names = [c.display_name for c in worker.crons]
+    event_patterns = list(worker.events.keys())
+
+    def add_handler_line(label: str, count: int, names: list[str]) -> None:
+        line = Text(no_wrap=True, overflow="ellipsis")
+        label_text = f"   {label} ({count})"
+        line.append(f"{label_text:<18} ", style="bold")
+        line.append(", ".join(names), style="dim")
+        lines.append(line)
+
+    if task_names:
+        add_handler_line("tasks", len(task_names), task_names)
+    if cron_names:
+        add_handler_line("crons", len(cron_names), cron_names)
+    if event_patterns:
+        add_handler_line("events", len(event_patterns), event_patterns)
+
+    if not any([task_names, cron_names, event_patterns]):
+        line = Text(no_wrap=True, overflow="ellipsis")
+        line.append("   no handlers", style="dim")
+        lines.append(line)
+
+    return lines
+
+
+def print_services_panel(
+    apis: list[Api],
+    workers: list[Worker],
+    *,
+    title: str,
+    worker_line_fn: Callable[[Worker], list[Text]],
+    redis_url: str | None = None,
+) -> None:
+    """Print the startup panel showing APIs, workers, and Ctrl+C hint."""
+    lines: list[Text] = []
+
+    for api in apis:
+        line = Text(no_wrap=True, overflow="ellipsis")
+        line.append(f"{api.name}", style="cyan bold")
+        line.append(f"  http://{api.host}:{api.port}", style="dim")
+        lines.append(line)
+
+    # Blank line between APIs and workers
+    if apis and workers:
+        lines.append(Text())
+
+    for worker in workers:
+        lines.extend(worker_line_fn(worker))
+
+    # Blank line at bottom for spacing before panel border
+    lines.append(Text())
+
+    table = Table.grid(padding=0)
+    table.add_column(overflow="ellipsis", no_wrap=True)
+    for line in lines:
+        table.add_row(line)
+
+    # Build subtitle with redis status and Ctrl+C hint
+    subtitle_parts: list[str] = []
+    if redis_url:
+        subtitle_parts.append(f"[green]✓[/green] [dim]redis ({redis_url})[/dim]")
+    subtitle_parts.append("[dim]Ctrl+C to stop[/dim]")
+    subtitle = " [dim]·[/dim] ".join(subtitle_parts)
+
+    panel = Panel(
+        table,
+        title=f"[bold]{title}[/bold]",
+        title_align="left",
+        subtitle=subtitle,
+        subtitle_align="right",
+        border_style="dim",
+        box=ROUNDED,
+        padding=(0, 1),
+        expand=False,
+    )
+    console.print(panel)
+    nl()
+
+
+def filter_components(
+    apis: list[Api],
+    workers: list[Worker],
+    only: list[str] | None,
+) -> tuple[list[Api], list[Worker]]:
+    """Filter APIs and workers by name.
+
+    Raises typer.Exit(1) on unknown names or empty result.
+    """
+    if only:
+        only_set = set(only)
+        apis = [a for a in apis if a.name in only_set]
+        workers = [w for w in workers if w.name in only_set]
+
+        found_names = {a.name for a in apis} | {w.name for w in workers}
+        unknown = only_set - found_names
+        if unknown:
+            nl()
+            error(f"Unknown component(s): {', '.join(unknown)}")
+            nl()
+            raise typer.Exit(1)
+
+    if not apis and not workers:
+        nl()
+        error("No Api or Worker found in the specified files")
+        nl()
+        raise typer.Exit(1)
+
+    return apis, workers

upnext-0.0.1/src/upnext/cli/_loader.py

@@ -0,0 +1,68 @@
+"""Module loader utilities."""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import typer
+from upnext.cli._console import error
+from upnext.sdk.api import Api
+from upnext.sdk.worker import Worker
+
+
+def import_file(file_path: str) -> object:
+    """Import a Python file and return the module."""
+    path = Path(file_path).resolve()
+
+    if not path.exists():
+        error(f"File not found: {file_path}")
+        raise typer.Exit(1)
+
+    if path.suffix != ".py":
+        error(f"Not a Python file: {file_path}")
+        raise typer.Exit(1)
+
+    # Add parent directory to path so imports work
+    parent_dir = str(path.parent)
+    if parent_dir not in sys.path:
+        sys.path.insert(0, parent_dir)
+
+    # Also add cwd if different
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+
+    # Import the file as a module
+    module_name = path.stem
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        error(f"Could not load: {file_path}")
+        raise typer.Exit(1)
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+    return module
+
+
+def discover_objects(files: list[str]) -> tuple[list[Api], list[Worker]]:
+    """Import files and discover Api/Worker objects."""
+
+    apis: list[Api] = []
+    workers: list[Worker] = []
+
+    for file_path in files:
+        module = import_file(file_path)
+
+        for name in dir(module):
+            if name.startswith("_"):
+                continue
+
+            obj = getattr(module, name)
+            if isinstance(obj, Api):
+                apis.append(obj)
+            elif isinstance(obj, Worker):
+                workers.append(obj)
+
+    return apis, workers