quebec 0.1.1__cp39-abi3-win_amd64.whl → 0.2.1__cp39-abi3-win_amd64.whl

quebec/__init__.py

@@ -1,12 +1,13 @@
 from .quebec import * # NOQA
+from . import quebec
+from .quebec import Quebec, ActiveJob
 import logging
 import time
 import queue
 import threading
-from functools import wraps
-from typing import Callable, List, Tuple, Type, Any, Optional
-import dataclasses
-from .logger import job_id_var
+from datetime import datetime, timedelta, timezone
+from typing import List, Type, Any, Optional, Union
+from .logger import job_id_var, queue_var
 
 __doc__ = quebec.__doc__
 if hasattr(quebec, "__all__"):
@@ -15,15 +16,60 @@ if hasattr(quebec, "__all__"):
 logger = logging.getLogger(__name__)
 
 
-class TestJob:
-    def perform(self):
-        pass
+class JobBuilder:
+    """Builder for configuring job options before enqueueing.
+
+    This allows chaining configuration like:
+        MyJob.set(wait=3600).perform_later(qc, arg1, arg2)
+        MyJob.set(queue='high', priority=10).perform_later(qc, arg1)
+    """
+
+    def __init__(self, job_class: Type, **options):
+        self.job_class = job_class
+        self.options = options
+
+    def _calculate_scheduled_at(self) -> Optional[datetime]:
+        """Calculate scheduled_at from wait or wait_until options."""
+        wait = self.options.get('wait')
+        wait_until = self.options.get('wait_until')
+
+        if wait_until is not None:
+            if isinstance(wait_until, datetime):
+                # Ensure timezone-aware for correct timestamp conversion
+                if wait_until.tzinfo is None:
+                    # Assume naive datetime is UTC
+                    wait_until = wait_until.replace(tzinfo=timezone.utc)
+                return wait_until
+            raise ValueError("wait_until must be a datetime object")
+
+        if wait is not None:
+            # Use timezone-aware UTC datetime
+            now = datetime.now(timezone.utc)
+            if isinstance(wait, (int, float)):
+                return now + timedelta(seconds=wait)
+            elif isinstance(wait, timedelta):
+                return now + wait
+            raise ValueError("wait must be a number (seconds) or timedelta")
+
+        return None
+
+    def perform_later(self, qc: 'Quebec', *args, **kwargs) -> 'ActiveJob':
+        """Enqueue the job with configured options."""
+        scheduled_at = self._calculate_scheduled_at()
+
+        # Pass internal options via kwargs (will be filtered out before serialization)
+        if scheduled_at is not None:
+            kwargs['_scheduled_at'] = scheduled_at.timestamp()
+
+        if 'queue' in self.options:
+            kwargs['_queue'] = self.options['queue']
+
+        if 'priority' in self.options:
+            kwargs['_priority'] = self.options['priority']
+
+        # Call the original perform_later
+        return self.job_class.perform_later(qc, *args, **kwargs)
 
-# @dataclasses.dataclass
-# class RetryStrategy:
-#     wait: int = 3 # seconds
-#     attempts: int = 5 # attempts
-#     # exceptions: tuple = (Exception,)
 
 class NoNewOverrideMeta(type):
     def __new__(cls, name, bases, dct):
@@ -34,7 +80,37 @@ class NoNewOverrideMeta(type):
         return super().__new__(cls, name, bases, dct)
 
 class BaseClass(ActiveJob, metaclass=NoNewOverrideMeta):
-    pass
+    @classmethod
+    def set(cls, wait: Union[int, float, timedelta] = None,
+            wait_until: datetime = None,
+            queue: str = None,
+            priority: int = None) -> JobBuilder:
+        """Configure job options before enqueueing.
+
+        Args:
+            wait: Delay in seconds (int/float) or timedelta before running
+            wait_until: Specific datetime when the job should run
+            queue: Queue name to enqueue the job to
+            priority: Job priority (lower number = higher priority)
+
+        Returns:
+            JobBuilder instance for chaining with perform_later
+
+        Example:
+            MyJob.set(wait=3600).perform_later(qc, arg1)  # Run in 1 hour
+            MyJob.set(wait_until=tomorrow).perform_later(qc, arg1)
+            MyJob.set(queue='critical', priority=1).perform_later(qc, arg1)
+        """
+        options = {}
+        if wait is not None:
+            options['wait'] = wait
+        if wait_until is not None:
+            options['wait_until'] = wait_until
+        if queue is not None:
+            options['queue'] = queue
+        if priority is not None:
+            options['priority'] = priority
+        return JobBuilder(cls, **options)
 
 
 class ThreadedRunner:
@@ -54,14 +130,16 @@ class ThreadedRunner:
                 self.queue.task_done()
                 self.execution.tid = str(threading.get_ident())
 
-                # Inject job_id into the context before execution, clean up after execution.
-                token = job_id_var.set(str(self.execution.jid))
+                # Inject jid and queue into context before execution, clean up after
+                jid_token = job_id_var.set(self.execution.jid)
+                queue_token = queue_var.set(self.execution.queue)
                 self.execution.perform()
                 logger.debug(self.execution.metric)
-                job_id_var.reset(token)
+                queue_var.reset(queue_token)
+                job_id_var.reset(jid_token)
             except queue.Empty:
-                time.sleep(0.1)
-            except (queue.ShutDown, KeyboardInterrupt) as e:
+                pass  # No job available, just continue waiting
+            except (queue.ShutDown, KeyboardInterrupt):
                 break
             except Exception as e:
                 logger.error(f"Unexpected exception in ThreadedRunner: {e}", exc_info=True)
@@ -78,28 +156,153 @@ class ThreadedRunner:
         except Exception as e:
             logger.error(f"Error in cleanup: {e}", exc_info=True)
 
-# def rescue_from(func):
-#     @wraps(func)
-#     def wrapper(self, *args, **kwargs):
-#         # 这里可以访问到 self
-#         print(f"Before calling {func.__name__}")
-#         result = func(self, *args, **kwargs)
-#         print(f"After calling {func.__name__}")
-#         return result
-#     return wrapper
-
-# def rescue_from(*exceptions: Type[Exception]):
-#     print(f">>>>>>>>>>>>> {exceptions}")
-#     def decorator(func: Callable[[Any, Exception], None]):
-#         @wraps(func)
-#         def wrapper(self, *args, **kwargs):
-#             print(f"registering {self} with {exceptions}")
-#             print(self.rescue_strategies)
-#             return func(self, *args, **kwargs)
-#         # cls.rescue_strategies.append(RescueStrategy(exceptions, func))
-#         print(decorator.__class__)
-#         # print(dir(func))
-#         # print(dir(wrapper))
-#         print(f"--------------------------- rescue_from {exceptions} {func}")
-#         return wrapper
-#     return decorator
+
+# Runtime state for Quebec instances (PyO3 classes don't support dynamic attributes)
+_quebec_state: dict = {}
+
+
+def _quebec_start(
+    self,
+    *,
+    create_tables: bool = False,
+    control_plane: Optional[str] = None,
+    spawn: Optional[List[str]] = None,
+    threads: int = 1,
+):
+    """Non-blocking start. Returns immediately after all components are started.
+
+    Args:
+        create_tables: Whether to create database tables (default False).
+                       Set to True only if the current user has DDL permissions.
+        control_plane: Control plane listen address, e.g. '127.0.0.1:5006'.
+        spawn: List of components to spawn. Options: 'worker', 'dispatcher', 'scheduler'.
+               None means spawn all components.
+        threads: Number of worker threads to run jobs (default 1).
+
+    Example:
+        qc.start()
+        # ... do other work ...
+        qc.wait()  # Block until shutdown
+    """
+    if create_tables:
+        self.create_table()
+
+    self.setup_signal_handler()
+
+    if control_plane:
+        self.start_control_plane(control_plane)
+
+    # Spawn components based on spawn parameter
+    if spawn is None:
+        self.spawn_all()
+    else:
+        for component in spawn:
+            if component == 'worker':
+                self.spawn_job_claim_poller()
+            elif component == 'dispatcher':
+                self.spawn_dispatcher()
+            elif component == 'scheduler':
+                self.spawn_scheduler()
+            else:
+                raise ValueError(f"Unknown component: {component}")
+
+    # Set up threading infrastructure
+    shutdown_event = threading.Event()
+    job_queue = queue.Queue()
+
+    # Register internal shutdown handler to signal the event
+    @self.on_shutdown
+    def _internal_shutdown_handler():
+        shutdown_event.set()
+
+    if threads > 0:
+        self.feed_jobs_to_queue(job_queue)
+
+    def run_worker():
+        runner = ThreadedRunner(job_queue, shutdown_event)
+        runner.run()
+
+    # Start worker threads as daemon so program can exit after start()
+    worker_threads = []
+    for i in range(threads):
+        t = threading.Thread(target=run_worker, name=f'quebec-worker-{i}', daemon=True)
+        t.start()
+        worker_threads.append(t)
+
+    # Store state by instance id
+    _quebec_state[id(self)] = {
+        'shutdown_event': shutdown_event,
+        'job_queue': job_queue,
+        'worker_threads': worker_threads,
+    }
+
+    return self  # Enable chaining: qc.start().wait()
+
+
+def _quebec_wait(self):
+    """Block until shutdown signal is received.
+
+    Call this after start() to wait for graceful shutdown.
+
+    Example:
+        qc.start()
+        # ... do other work ...
+        qc.wait()
+    """
+    state = _quebec_state.get(id(self))
+    if state is None:
+        raise RuntimeError("Quebec not started. Call start() first.")
+
+    try:
+        while not state['shutdown_event'].is_set():
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        logger.debug('KeyboardInterrupt, shutting down...')
+        self.graceful_shutdown()
+    finally:
+        # Wait for worker threads to finish
+        for t in state['worker_threads']:
+            t.join(timeout=5.0)
+        _quebec_state.pop(id(self), None)
+
+
+def _quebec_run(
+    self,
+    *,
+    create_tables: bool = False,
+    control_plane: Optional[str] = None,
+    spawn: Optional[List[str]] = None,
+    threads: int = 1,
+):
+    """Blocking run. Starts all components and waits until shutdown.
+
+    This is equivalent to calling start() followed by wait().
+
+    Args:
+        create_tables: Whether to create database tables (default False).
+                       Set to True only if the current user has DDL permissions.
+        control_plane: Control plane listen address, e.g. '127.0.0.1:5006'.
+        spawn: List of components to spawn. Options: 'worker', 'dispatcher', 'scheduler'.
+               None means spawn all components.
+        threads: Number of worker threads to run jobs (default 1).
+
+    Example:
+        qc.run()  # Start all components and block
+        qc.run(create_tables=True)  # Create tables and start all
+        qc.run(spawn=['worker'])  # Only start worker
+        qc.run(spawn=['worker', 'dispatcher'], control_plane='127.0.0.1:5006')
+        qc.run(threads=4)  # Run with 4 worker threads
+    """
+    self.start(
+        create_tables=create_tables,
+        control_plane=control_plane,
+        spawn=spawn,
+        threads=threads,
+    )
+    self.wait()
+
+
+# Attach methods to Quebec class
+Quebec.start = _quebec_start
+Quebec.wait = _quebec_wait
+Quebec.run = _quebec_run

quebec/logger.py

@@ -4,13 +4,16 @@ from datetime import datetime, timezone
 from typing import Optional
 
 job_id_var: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("job_id", default=None)
+queue_var: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("queue", default=None)
 
 class ContextFilter(logging.Filter):
     def filter(self, record: logging.LogRecord) -> bool:
         try:
             record.job_id = job_id_var.get(None)
+            record.queue = queue_var.get(None)
         except Exception:
             record.job_id = None
+            record.queue = None
         return True
 
 class QuebecFormatter(logging.Formatter):
@@ -22,8 +25,12 @@ class QuebecFormatter(logging.Formatter):
         record.asctime = self.formatTime(record)
         record.message = record.getMessage()
         jid = getattr(record, 'job_id', None)
-        ctx = f" [jid={jid}]" if jid not in (None, '', '-') else ""
-        origin = f"[{record.name}:{record.filename}:{record.lineno}:{record.thread}]"
+        queue = getattr(record, 'queue', None)
+        if jid not in (None, '', '-'):
+            ctx = f' {{queue="{queue}" jid="{jid}" tid="{record.thread}"}}:'
+        else:
+            ctx = ""
+        origin = f"{record.name}:{record.filename}: {record.lineno}:"
         return f"{record.asctime} {record.levelname:>5}{ctx} {origin} {record.message}"
 
 

{quebec-0.1.1.dist-info → quebec-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quebec
-Version: 0.1.1
+Version: 0.2.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -17,9 +17,13 @@ Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX
 Classifier: Operating System :: Unix
 Classifier: Operating System :: MacOS
-Requires-Dist: pytest<5.0.0 ; extra == 'test'
-Requires-Dist: pytest-cov[all] ; extra == 'test'
+Requires-Dist: pytest>=7.0.0 ; extra == 'test'
+Requires-Dist: pytest-cov ; extra == 'test'
+Requires-Dist: sphinx>=7.0 ; extra == 'docs'
+Requires-Dist: shibuya ; extra == 'docs'
+Requires-Dist: myst-parser ; extra == 'docs'
 Provides-Extra: test
+Provides-Extra: docs
 License-File: LICENSE
 Summary: Quebec is a simple background task queue for processing asynchronous tasks.
 Keywords: solid_queue,postgresql,mysql,sqlite,queue
@@ -57,6 +61,12 @@ This project is inspired by [Solid Queue](https://github.com/rails/solid_queue).
 - Signal handling
 - Lifecycle hooks
 
+### Control Plane
+
+Built-in web dashboard for monitoring jobs, queues, and workers in real-time.
+
+![Control Plane](docs/images/control-plane.png)
+
 ## Database Support
 
 - SQLite
@@ -65,11 +75,67 @@ This project is inspired by [Solid Queue](https://github.com/rails/solid_queue).
 
 ## Quick Start
 
+```python
+import logging
+from pathlib import Path
+from quebec.logger import setup_logging
+
+setup_logging(level=logging.DEBUG)
+
+import quebec
+
+db_path = Path('demo.db')
+qc = quebec.Quebec(f'sqlite://{db_path}?mode=rwc')
+
+
+@qc.register_job
+class FakeJob(quebec.BaseClass):
+    def perform(self, *args, **kwargs):
+        self.logger.info(f"Processing job {self.id}: args={args}, kwargs={kwargs}")
+
+
+if __name__ == "__main__":
+    # Enqueue a job
+    FakeJob.perform_later(qc, 123, foo='bar')
+
+    # Start Quebec (handles signal, spawns workers, runs main loop)
+    qc.run(
+        create_tables=not db_path.exists(),
+        control_plane='127.0.0.1:5006',  # Optional: web dashboard
+    )
+```
+
+Or run the quickstart script directly:
+
 ```bash
 curl -O https://raw.githubusercontent.com/ratazzi/quebec/refs/heads/master/quickstart.py
 uv run quickstart.py
 ```
 
+### `qc.run()` Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `create_tables` | `bool` | `False` | Create database tables (requires DDL permissions) |
+| `control_plane` | `str` | `None` | Web dashboard address, e.g. `'127.0.0.1:5006'` |
+| `spawn` | `list[str]` | `None` | Components to spawn: `['worker', 'dispatcher', 'scheduler']`. `None` = all |
+| `threads` | `int` | `1` | Number of worker threads to run jobs |
+
+### Delayed Jobs
+
+```python
+from datetime import timedelta
+
+# Run after 1 hour
+FakeJob.set(wait=3600).perform_later(qc, arg1)
+
+# Run at specific time
+FakeJob.set(wait_until=tomorrow_9am).perform_later(qc, arg1)
+
+# Override queue and priority
+FakeJob.set(queue='critical', priority=1).perform_later(qc, arg1)
+```
+
 ## Lifecycle Hooks
 
 Quebec provides several lifecycle hooks that you can use to execute code at different stages of the application lifecycle:

quebec-0.2.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+quebec-0.2.1.dist-info/METADATA,sha256=yXF8dzOOSwTX5sv_sZTdfrEAt5ZTZC0vVN-724RjdwA,5061
+quebec-0.2.1.dist-info/WHEEL,sha256=W8IbRrW6aFuwgkpVWKTtkIq8XwJIIpO5tHf4goK_jm8,95
+quebec-0.2.1.dist-info/licenses/LICENSE,sha256=EMUpCdp2I-buVSjzgRTpd6TZDSnUcm1Pi4w8vOiwsQk,1095
+quebec/__init__.py,sha256=382fYpy2xb2oAoEG-sRJVLXVjHr7ltkWcy7WBhSv3zM,10665
+quebec/logger.py,sha256=gX0O1S77HWEQ2bkTFBV3kolSonvTP0p41xYV7WLmBNY,1806
+quebec/quebec.pyd,sha256=kuy16xPzzlpjQIVm3HmMjoI9p_jv4K1oLumQurUy7RU,26043904
+quebec-0.2.1.dist-info/RECORD,,

{quebec-0.1.1.dist-info → quebec-0.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.9.6)
+Generator: maturin (1.10.2)
 Root-Is-Purelib: false
 Tag: cp39-abi3-win_amd64

quebec-0.1.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-quebec-0.1.1.dist-info/METADATA,sha256=nkuSuqBEUtMBB3KLLOXkEIPGpOiHrAtrCwoozOiOwDE,3187
-quebec-0.1.1.dist-info/WHEEL,sha256=dtDRtmb8ugdlQQiOTIfQg6qwccecUkp34WgpWvjGLGA,94
-quebec-0.1.1.dist-info/licenses/LICENSE,sha256=EMUpCdp2I-buVSjzgRTpd6TZDSnUcm1Pi4w8vOiwsQk,1095
-quebec/__init__.py,sha256=m8fQfMwoOohuOiIwqxXHSpvZ6mNBShYladtzmaHSh18,3575
-quebec/logger.py,sha256=NuT2rxzUNaoRRF0eR5K-vKBgEY_JJr12NuXJtJBW7eM,1509
-quebec/quebec.pyd,sha256=v8UaURJt3a6UV8X5QDYLyNRQPeUt_A1rr5pS4OOk99Q,26780160
-quebec-0.1.1.dist-info/RECORD,,