jararaca 0.3.11a16__tar.gz → 0.3.12a0__tar.gz

{jararaca-0.3.11a16 → jararaca-0.3.12a0}/PKG-INFO

@@ -1,14 +1,14 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: jararaca
-Version: 0.3.11a16
+Version: 0.3.12a0
 Summary: A simple and fast API framework for Python
+Home-page: https://github.com/LuscasLeo/jararaca
 Author: Lucas S
 Author-email: me@luscasleo.dev
 Requires-Python: >=3.11,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: docs
 Provides-Extra: http
 Provides-Extra: opentelemetry

{jararaca-0.3.11a16 → jararaca-0.3.12a0}/docs/index.md

@@ -9,9 +9,9 @@ Jararaca is a powerful Python microservice framework that provides a comprehensi
 - 📦 **Dependency Injection**: Flexible dependency injection system with interceptors
 - 📊 **Database Integration**: SQLAlchemy integration with async support
 - 📡 **Message Bus**: RabbitMQ integration for event-driven architecture
-- 🔒 **Authentication**: Built-in JWT authentication with token blacklisting
+- ⚡ **Retry Mechanism**: Robust retry system with exponential backoff for resilient operations
 - 🔍 **Query Operations**: Advanced query capabilities with pagination and filtering
-- ⏱️ **Scheduled Tasks**: Cron-based task scheduling
+- ⏱️ **Scheduled Tasks**: Distributed cron-based task scheduling with message broker integration
 
 ## Installation
 
@@ -33,9 +33,27 @@ Starts a message bus worker that processes asynchronous messages from a message
 
 **Options:**
 
-- `--broker-url`: The URL for the message broker (required)
-- `--backend-url`: The URL for the message broker backend (required)
-- `--handlers`: Comma-separated list of handler names to listen to (optional)
+- `--broker-url`: The URL for the message broker (required) [env: BROKER_URL]
+- `--backend-url`: The URL for the message broker backend (required) [env: BACKEND_URL]
+- `--handlers`: Comma-separated list of handler names to listen to (optional) [env: HANDLERS]
+- `--reload`: Enable auto-reload when Python files change (for development) [env: RELOAD]
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src") [env: SRC_DIR]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- All options support environment variables as indicated above
+
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca&prefetch_count=1"
+export BACKEND_URL="redis://localhost:6379"
+export HANDLERS="send_email,process_payment"
+export RELOAD="true"
+jararaca worker
+```
+- `--reload`: Enable auto-reload when Python files change (for development)
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src")
 
 ### `server` - HTTP Server
 
@@ -43,11 +61,39 @@ Starts a message bus worker that processes asynchronous messages from a message
 jararaca server APP_PATH [OPTIONS]
 ```
 
-#### Perfer `uvicorn` for production
-
 Starts a FastAPI HTTP server for your microservice.
 
+**Options:**
+
+- `--host`: Host to bind the server (default: "0.0.0.0") [env: HOST]
+- `--port`: Port to bind the server (default: 8000) [env: PORT]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- `HOST`: Host to bind the server
+- `PORT`: Port to bind the server
+
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export HOST="127.0.0.1"
+export PORT="8080"
+jararaca server
+```
+
+#### Alternative: Using `uvicorn` directly
+
+For production environments, you can create an ASGI application and run it with uvicorn:
+
 ```python
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.types import Lifespan
+
+from jararaca.presentation.http_microservice import HttpMicroservice
+from jararaca.presentation.server import create_http_server
+
+
 def fastapi_factory(lifespan: Lifespan[FastAPI]) -> FastAPI:
     app = FastAPI(
         lifespan=lifespan,
@@ -78,26 +124,37 @@ Then run the server with:
 uvicorn app_module:asgi_app
 ```
 
-Starts a FastAPI HTTP server for your microservice.
-
-**Options:**
-
-- `--host`: Host to bind the server (default: "0.0.0.0")
-- `--port`: Port to bind the server (default: 8000)
-
-### `scheduler` - Task Scheduler
+### `beat` - Task Scheduler
 
 ```bash
-jararaca scheduler APP_PATH [OPTIONS]
+jararaca beat APP_PATH [OPTIONS]
 ```
 
 Runs scheduled tasks defined in your application using cron expressions.
 
 **Options:**
 
-- `--interval`: Polling interval in seconds (default: 1)
+- `--interval`: Polling interval in seconds (default: 1) [env: INTERVAL]
+- `--broker-url`: The URL for the message broker (required) [env: BROKER_URL]
+- `--backend-url`: The URL for the message broker backend (required) [env: BACKEND_URL]
+- `--actions`: Comma-separated list of action names to run (optional) [env: ACTIONS]
+- `--reload`: Enable auto-reload when Python files change (for development) [env: RELOAD]
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src") [env: SRC_DIR]
 
-### `scheduler_v2` - Enhanced Task Scheduler
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- All options support environment variables as indicated above
+
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export INTERVAL="5"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca&prefetch_count=1"
+export BACKEND_URL="redis://localhost:6379"
+export ACTIONS="send_emails,process_payments"
+export RELOAD="true"
+jararaca beat
+```
 
 ```bash
 jararaca scheduler_v2 APP_PATH [OPTIONS]
@@ -121,8 +178,14 @@ Generates TypeScript interfaces from your Python models to ensure type safety be
 
 **Options:**
 
-- `--watch`: Watch for file changes and regenerate TypeScript interfaces automatically
-- `--src-dir`: Source directory to watch for changes (default: "src")
+- `--watch`: Watch for file changes and regenerate TypeScript interfaces automatically [env: WATCH]
+- `--src-dir`: Source directory to watch for changes (default: "src") [env: SRC_DIR]
+- `--stdout`: Print generated interfaces to stdout instead of writing to a file [env: STDOUT]
+- `--post-process`: Command to run after generating the interfaces, {file} will be replaced with the output file path [env: POST_PROCESS]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- All options support environment variables as indicated above
 
 **Example with watch mode:**
 
@@ -132,6 +195,15 @@ jararaca gen-tsi app.module:app interfaces.ts --watch
 
 This will generate the TypeScript interfaces initially and then watch for any changes to Python files in the src directory, automatically regenerating the interfaces when changes are detected. You can stop watching with Ctrl+C.
 
+**Example with environment variables:**
+```bash
+export APP_PATH="app.module:app"
+export FILE_PATH="interfaces.ts"
+export WATCH="true"
+export SRC_DIR="src"
+jararaca gen-tsi
+```
+
 **Note:** To use the watch feature, you need to install the watchdog package:
 
 ```bash
@@ -152,6 +224,57 @@ jararaca gen-entity ENTITY_NAME FILE_PATH
 
 Generates a new entity file template with proper naming conventions in different formats (snake_case, PascalCase, kebab-case).
 
+**Environment Variables:**
+- `ENTITY_NAME`: The name of the entity to generate
+- `FILE_PATH`: The path where the entity file should be created
+
+**Example:**
+
+```bash
+# Using command line arguments
+jararaca gen-entity User user.py
+
+# Using environment variables
+export ENTITY_NAME="User"
+export FILE_PATH="user.py"
+jararaca gen-entity
+```
+
+### `declare` - Declare Message Infrastructure
+
+```bash
+jararaca declare APP_PATH [OPTIONS]
+```
+
+Declares RabbitMQ infrastructure (exchanges and queues) for message handlers and schedulers without starting the actual consumption processes.
+
+**Options:**
+- `--broker-url`: Broker URL (e.g., amqp://guest:guest@localhost/) [env: BROKER_URL]
+- `-i, --interactive-mode`: Enable interactive mode for queue declaration [env: INTERACTIVE_MODE]
+- `-f, --force`: Force recreation by deleting existing exchanges and queues [env: FORCE]
+
+**Environment Variables:**
+- `APP_PATH`: The application module path
+- `BROKER_URL`: The broker URL
+- `INTERACTIVE_MODE`: Enable interactive mode
+- `FORCE`: Force recreation of infrastructure
+
+**Examples:**
+
+```bash
+# Declare infrastructure
+jararaca declare myapp:app --broker-url amqp://guest:guest@localhost/
+
+# Force recreation of queues and exchanges
+jararaca declare myapp:app --broker-url amqp://guest:guest@localhost/ --force
+
+# Using environment variables
+export APP_PATH="myapp:app"
+export BROKER_URL="amqp://guest:guest@localhost/"
+export FORCE="true"
+jararaca declare
+```
+
 ## Quick Start
 
 Here's a basic example of how to create a microservice with Jararaca:

{jararaca-0.3.11a16 → jararaca-0.3.12a0}/docs/messagebus.md

@@ -455,12 +455,30 @@ jararaca worker APP_PATH [OPTIONS]
 
 Options:
 
-- `--url`: AMQP URL (default: "amqp://guest:guest@localhost/")
-- `--username`: AMQP username (optional)
-- `--password`: AMQP password (optional)
-- `--exchange`: Exchange name (default: "jararaca_ex")
-- `--queue`: Queue name (default: "jararaca_q")
-- `--prefetch-count`: Number of messages to prefetch (default: 1)
+- `--broker-url`: The URL for the message broker (required) [env: BROKER_URL]
+- `--backend-url`: The URL for the message broker backend (required) [env: BACKEND_URL]
+- `--handlers`: Comma-separated list of handler names to listen to (optional) [env: HANDLERS]
+- `--reload`: Enable auto-reload when Python files change (for development) [env: RELOAD]
+- `--src-dir`: The source directory to watch for changes when --reload is enabled (default: "src") [env: SRC_DIR]
+
+Examples:
+
+```bash
+# Standard worker execution
+jararaca worker myapp.main:app --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379"
+
+# With auto-reload for development
+jararaca worker myapp.main:app --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379" --reload
+
+# Using environment variables
+export APP_PATH="myapp.main:app"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca"
+export BACKEND_URL="redis://localhost:6379"
+export RELOAD="true"
+export SRC_DIR="src"
+export RELOAD="true"
+jararaca worker
+```
 
 ## Conclusion
 

{jararaca-0.3.11a16 → jararaca-0.3.12a0}/docs/scheduler.md

@@ -12,22 +12,16 @@ The Jararaca scheduler allows you to:
 - Distribute scheduled tasks across multiple instances
 - Handle delayed message execution
 
-The scheduler has two implementations:
-1. **Basic Scheduler** - Simple scheduler for local execution
-2. **Enhanced Scheduler (V2)** - Distributed scheduler with improved backend support and message broker integration
+The scheduler is implemented through the BeatWorker which provides distributed task scheduling via a message broker:
 
 ```mermaid
 graph TD
-    A[Microservice] --> B[Scheduler System]
-    B --> C[Basic Scheduler]
-    B --> D[Enhanced Scheduler V2]
-
-    C --> E[Local Task Execution]
-    D --> F[Message Broker]
-    F --> G[Workers]
-    D --> H[Backend Store]
-    H --> I[Last Execution Time]
-    H --> J[Delayed Messages]
+    A[Microservice] --> B[BeatWorker]
+    B --> C[Message Broker]
+    B --> D[Backend Store]
+    C --> E[Message Processing]
+    D --> F[Last Execution Time]
+    D --> G[Delayed Messages]
 ```
 
 ## Using the Scheduler
@@ -73,31 +67,57 @@ Jararaca uses standard cron expressions for scheduling. Here are some examples:
 - `0 0 * * 0` - Run at midnight every Sunday
 - `0 0 1 * *` - Run at midnight on the first day of every month
 
-## Basic Scheduler Implementation
+## Using the BeatWorker Scheduler
 
-The basic scheduler is suitable for simpler applications where tasks run locally:
+The BeatWorker scheduler provides distributed task execution through a message broker:
 
 ```python
 from jararaca import Microservice, ScheduledAction
+from jararaca.scheduler.beat_worker import BeatWorker
 
 app = Microservice(
     # Your microservice configuration
 )
 
 # Run the scheduler
-from jararaca.scheduler.scheduler import Scheduler
-
-scheduler = Scheduler(app, interval=1)
-scheduler.run()
+beat_worker = BeatWorker(
+    app=app,
+    interval=1,
+    backend_url="redis://localhost:6379",
+    broker_url="amqp://guest:guest@localhost:5672/?exchange=jararaca",
+    scheduled_action_names=None  # Optional set of action names to run
+)
+beat_worker.run()
 ```
 
-## Enhanced Scheduler V2 Implementation
+You can also use the CLI command to run the scheduler:
 
-The V2 scheduler adds support for distributed execution and message broker integration, making it ideal for more complex applications:
+```bash
+# Standard beat scheduler execution
+jararaca beat app_module:app --interval 1 --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379"
+
+# With auto-reload for development (automatically restarts when Python files change)
+jararaca beat app_module:app --interval 1 --broker-url "amqp://guest:guest@localhost:5672/?exchange=jararaca" --backend-url "redis://localhost:6379" --reload
+
+# Using environment variables
+export APP_PATH="app_module:app"
+export INTERVAL="1"
+export BROKER_URL="amqp://guest:guest@localhost:5672/?exchange=jararaca"
+export BACKEND_URL="redis://localhost:6379"
+export RELOAD="true"
+export SRC_DIR="src"
+jararaca beat
+```
 
-```python
-from jararaca import Microservice, ScheduledAction
-from jararaca.scheduler.scheduler_v2 import SchedulerV2
+All command options support environment variables:
+- `APP_PATH`: The application module path [required]
+- `INTERVAL`: Polling interval in seconds [default: 1]
+- `BROKER_URL`: The URL for the message broker [required]
+- `BACKEND_URL`: The URL for the message broker backend [required]
+- `ACTIONS`: Comma-separated list of action names to run [optional]
+- `RELOAD`: Enable auto-reload when Python files change [optional]
+- `SRC_DIR`: The source directory to watch for changes when using reload [default: "src"]
+```
 
 app = Microservice(
     # Your microservice configuration

{jararaca-0.3.11a16 → jararaca-0.3.12a0}/docs/websocket.md

@@ -57,24 +57,38 @@ class WebSocketMessage(WebSocketMessageBase):
 
 ### 3. WebSocketConnectionManager
 
-Manages WebSocket connections, rooms, and message distribution:
+A Protocol that defines the interface for managing WebSocket connections:
 
+```python
+class WebSocketConnectionManager(Protocol):
+    async def broadcast(self, message: bytes) -> None: ...
+    async def send(self, rooms: list[str], message: WebSocketMessageBase) -> None: ...
+    async def join(self, rooms: list[str], websocket: WebSocket) -> None: ...
+    async def add_websocket(self, websocket: WebSocket) -> None: ...
+    async def remove_websocket(self, websocket: WebSocket) -> None: ...
+```
+
+The WebSocketConnectionManager:
 - Maintains a registry of active WebSocket connections
 - Groups connections into named rooms
 - Provides methods for broadcasting and sending targeted messages
 
-### 4. WebSocketConnectionBackend
+### 4. Context-based WebSocket Access
 
-A protocol defining the contract for backend implementations:
+Jararaca uses context variables to provide access to WebSocket functionality anywhere in your application:
 
 ```python
-class WebSocketConnectionBackend(Protocol):
-    async def broadcast(self, message: bytes) -> None: ...
-    async def send(self, rooms: list[str], message: bytes) -> None: ...
-    def configure(
-        self, broadcast: BroadcastFunc, send: SendFunc, shutdown_event: asyncio.Event
-    ) -> None: ...
-    async def shutdown(self) -> None: ...
+from jararaca.presentation.websocket.context import use_ws_manager, use_ws_message_sender
+
+# Send a message to specific rooms
+async def notify_users(message_data: dict, room_id: str):
+    message = UserNotificationMessage(**message_data)
+    await use_ws_message_sender().send([room_id], message)
+
+# Or directly from a WebSocketMessage instance
+async def send_update(update_data: dict, room_id: str):
+    message = SystemUpdateMessage(**update_data)
+    await message.send(room_id)
 ```
 
 ### 5. RedisWebSocketConnectionBackend

{jararaca-0.3.11a16 → jararaca-0.3.12a0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "jararaca"
-version = "0.3.11a16"
+version = "0.3.12a0"
 description = "A simple and fast API framework for Python"
 authors = ["Lucas S <me@luscasleo.dev>"]
 readme = "README.md"

{jararaca-0.3.11a16 → jararaca-0.3.12a0}/src/jararaca/cli.py

@@ -7,7 +7,7 @@ import sys
 import time
 from codecs import StreamWriter
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 from urllib.parse import parse_qs, urlparse
 
 import aio_pika
@@ -421,25 +421,42 @@ def cli() -> None:
 @click.option(
     "--handlers",
     type=str,
+    envvar="HANDLERS",
     help="Comma-separated list of handler names to listen to. If not specified, all handlers will be used.",
 )
+@click.option(
+    "--reload",
+    is_flag=True,
+    envvar="RELOAD",
+    help="Enable auto-reload when Python files change.",
+)
+@click.option(
+    "--src-dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    default="src",
+    envvar="SRC_DIR",
+    help="The source directory to watch for changes when --reload is enabled.",
+)
 def worker(
-    app_path: str, broker_url: str, backend_url: str, handlers: str | None
+    app_path: str,
+    broker_url: str,
+    backend_url: str,
+    handlers: str | None,
+    reload: bool,
+    src_dir: str,
 ) -> None:
     """Start a message bus worker that processes asynchronous messages from a message queue."""
-    app = find_microservice_by_module_path(app_path)
-
-    # Parse handler names if provided
-    handler_names: set[str] | None = None
-    if handlers:
-        handler_names = {name.strip() for name in handlers.split(",") if name.strip()}
 
-    worker_mod.MessageBusWorker(
-        app=app,
-        broker_url=broker_url,
-        backend_url=backend_url,
-        handler_names=handler_names,
-    ).start_sync()
+    if reload:
+        process_args = {
+            "app_path": app_path,
+            "broker_url": broker_url,
+            "backend_url": backend_url,
+            "handlers": handlers,
+        }
+        run_with_reload_watcher(process_args, run_worker_process, src_dir)
+    else:
+        run_worker_process(app_path, broker_url, backend_url, handlers)
 
 
 @cli.command()
@@ -485,51 +502,68 @@ def server(app_path: str, host: str, port: int) -> None:
 @click.argument(
     "app_path",
     type=str,
+    envvar="APP_PATH",
 )
 @click.option(
     "--interval",
     type=int,
     default=1,
     required=True,
+    envvar="INTERVAL",
 )
 @click.option(
     "--broker-url",
     type=str,
     required=True,
+    envvar="BROKER_URL",
 )
 @click.option(
     "--backend-url",
     type=str,
     required=True,
+    envvar="BACKEND_URL",
 )
 @click.option(
     "--actions",
     type=str,
+    envvar="ACTIONS",
     help="Comma-separated list of action names to run (only run actions with these names)",
 )
+@click.option(
+    "--reload",
+    is_flag=True,
+    envvar="RELOAD",
+    help="Enable auto-reload when Python files change.",
+)
+@click.option(
+    "--src-dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    default="src",
+    envvar="SRC_DIR",
+    help="The source directory to watch for changes when --reload is enabled.",
+)
 def beat(
     interval: int,
     broker_url: str,
     backend_url: str,
     app_path: str,
     actions: str | None = None,
+    reload: bool = False,
+    src_dir: str = "src",
 ) -> None:
-
-    app = find_microservice_by_module_path(app_path)
-
-    # Parse scheduler names if provided
-    scheduler_names: set[str] | None = None
-    if actions:
-        scheduler_names = {name.strip() for name in actions.split(",") if name.strip()}
-
-    beat_worker = BeatWorker(
-        app=app,
-        interval=interval,
-        backend_url=backend_url,
-        broker_url=broker_url,
-        scheduled_action_names=scheduler_names,
-    )
-    beat_worker.run()
+    """Start a scheduler that dispatches scheduled actions to workers."""
+
+    if reload:
+        process_args = {
+            "app_path": app_path,
+            "interval": interval,
+            "broker_url": broker_url,
+            "backend_url": backend_url,
+            "actions": actions,
+        }
+        run_with_reload_watcher(process_args, run_beat_process, src_dir)
+    else:
+        run_beat_process(app_path, interval, broker_url, backend_url, actions)
 
 
 def generate_interfaces(
@@ -588,29 +622,35 @@ def generate_interfaces(
 @click.argument(
     "app_path",
     type=str,
+    envvar="APP_PATH",
 )
 @click.argument(
     "file_path",
     type=click.Path(file_okay=True, dir_okay=False),
     required=False,
+    envvar="FILE_PATH",
 )
 @click.option(
     "--watch",
     is_flag=True,
+    envvar="WATCH",
 )
 @click.option(
     "--src-dir",
     type=click.Path(exists=True, file_okay=False, dir_okay=True),
     default="src",
+    envvar="SRC_DIR",
 )
 @click.option(
     "--stdout",
     is_flag=True,
+    envvar="STDOUT",
     help="Print generated interfaces to stdout instead of writing to a file",
 )
 @click.option(
     "--post-process",
     type=str,
+    envvar="POST_PROCESS",
     help="Command to run after generating the interfaces, {file} will be replaced with the output file path",
 )
 def gen_tsi(
@@ -730,10 +770,11 @@ def camel_case_to_pascal_case(name: str) -> str:
 
 
 @cli.command()
-@click.argument("entity_name", type=click.STRING)
+@click.argument("entity_name", type=click.STRING, envvar="ENTITY_NAME")
 @click.argument(
     "file_path",
     type=click.File("w"),
+    envvar="FILE_PATH",
 )
 def gen_entity(entity_name: str, file_path: StreamWriter) -> None:
 
@@ -769,6 +810,7 @@ def gen_entity(entity_name: str, file_path: StreamWriter) -> None:
     "--interactive-mode",
     is_flag=True,
     default=False,
+    envvar="INTERACTIVE_MODE",
     help="Enable interactive mode for queue declaration (confirm before deleting existing queues)",
 )
 @click.option(
@@ -776,6 +818,7 @@ def gen_entity(entity_name: str, file_path: StreamWriter) -> None:
     "--force",
     is_flag=True,
     default=False,
+    envvar="FORCE",
     help="Force recreation by deleting existing exchanges and queues before declaring them",
 )
 def declare(
@@ -835,3 +878,143 @@ def declare(
             raise
 
     asyncio.run(run_declarations())
+
+
+def run_worker_process(
+    app_path: str, broker_url: str, backend_url: str, handlers: str | None
+) -> None:
+    """Run a worker process with the given parameters."""
+    app = find_microservice_by_module_path(app_path)
+
+    # Parse handler names if provided
+    handler_names: set[str] | None = None
+    if handlers:
+        handler_names = {name.strip() for name in handlers.split(",") if name.strip()}
+
+    click.echo(f"Starting worker for {app_path}...")
+    worker_mod.MessageBusWorker(
+        app=app,
+        broker_url=broker_url,
+        backend_url=backend_url,
+        handler_names=handler_names,
+    ).start_sync()
+
+
+def run_beat_process(
+    app_path: str, interval: int, broker_url: str, backend_url: str, actions: str | None
+) -> None:
+    """Run a beat scheduler process with the given parameters."""
+    app = find_microservice_by_module_path(app_path)
+
+    # Parse scheduler names if provided
+    scheduler_names: set[str] | None = None
+    if actions:
+        scheduler_names = {name.strip() for name in actions.split(",") if name.strip()}
+
+    click.echo(f"Starting beat scheduler for {app_path}...")
+    beat_worker = BeatWorker(
+        app=app,
+        interval=interval,
+        backend_url=backend_url,
+        broker_url=broker_url,
+        scheduled_action_names=scheduler_names,
+    )
+    beat_worker.run()
+
+
+def run_with_reload_watcher(
+    process_args: dict[str, Any],
+    process_target: Callable[..., Any],
+    src_dir: str = "src",
+) -> None:
+    """
+    Run a process with a file watcher that will restart it when Python files change.
+
+    Args:
+        process_args: Arguments to pass to the process function
+        process_target: The function to run as the process
+        src_dir: The directory to watch for changes
+    """
+    try:
+        from watchdog.events import FileSystemEvent, FileSystemEventHandler
+        from watchdog.observers import Observer
+    except ImportError:
+        click.echo(
+            "Watchdog is required for reload mode. Install it with: pip install watchdog",
+            file=sys.stderr,
+        )
+        return
+
+    # Run the initial process
+    process = multiprocessing.get_context("spawn").Process(
+        target=process_target,
+        kwargs=process_args,
+        daemon=False,  # Non-daemon to ensure it completes properly
+    )
+    process.start()  # Set up file system event handler
+
+    class PyFileChangeHandler(FileSystemEventHandler):
+        def __init__(self) -> None:
+            self.last_modified_time = time.time()
+            self.debounce_seconds = 1.0  # Debounce to avoid multiple restarts
+            self.active_process = process
+
+        def on_modified(self, event: FileSystemEvent) -> None:
+            src_path = (
+                event.src_path
+                if isinstance(event.src_path, str)
+                else str(event.src_path)
+            )
+
+            # Ignore non-Python files and directories
+            if event.is_directory or not src_path.endswith(".py"):
+                return
+
+            # Debounce to avoid multiple restarts
+            current_time = time.time()
+            if current_time - self.last_modified_time < self.debounce_seconds:
+                return
+            self.last_modified_time = current_time
+
+            click.echo(f"Detected change in {src_path}")
+            click.echo("Restarting process...")
+
+            # Terminate the current process
+            if self.active_process and self.active_process.is_alive():
+                self.active_process.terminate()
+                self.active_process.join(timeout=5)
+
+                # If process doesn't terminate, kill it
+                if self.active_process.is_alive():
+                    click.echo("Process did not terminate gracefully, killing it")
+                    self.active_process.kill()
+                    self.active_process.join()
+
+            # Create a new process
+            self.active_process = multiprocessing.get_context("spawn").Process(
+                target=process_target,
+                kwargs=process_args,
+                daemon=False,
+            )
+            self.active_process.start()
+
+    # Set up observer
+    observer = Observer()
+    observer.schedule(PyFileChangeHandler(), src_dir, recursive=True)  # type: ignore[no-untyped-call]
+    observer.start()  # type: ignore[no-untyped-call]
+
+    click.echo(f"Watching for changes in {os.path.abspath(src_dir)}...")
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        observer.stop()  # type: ignore[no-untyped-call]
+        if process.is_alive():
+            click.echo("Stopping process...")
+            process.terminate()
+            process.join(timeout=5)
+            if process.is_alive():
+                process.kill()
+                process.join()
+        click.echo("Reload mode stopped")
+    observer.join()