crazy-workers 1.4.2__tar.gz → 1.5.0__tar.gz

{crazy_workers-1.4.2 → crazy_workers-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crazy-workers
-Version: 1.4.2
+Version: 1.5.0
 Summary: A Python library for managing background worker processes with persistent state, automatic recovery, and a CLI.
 Author: GioVanni Colasanto
 License: MIT
@@ -76,9 +76,11 @@ pip install .
 
 ```python
 # workers/my_worker.py
-import json, sys, time
+import time
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+from crazy_workers import parse_params
+
+params = parse_params()
 duration = params.get('duration', 60)
 
 for _ in range(duration):
@@ -176,15 +178,28 @@ Closes the database connection and clears internal process references. Does **no
 
 ## Worker Script Contract
 
-A worker receives its parameters as a JSON string in `sys.argv[1]`:
+A worker receives its parameters as a JSON string in `sys.argv[1]`. Use
+`parse_params` instead of decoding it by hand:
 
 ```python
-import json, sys
+from crazy_workers import parse_params
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+params = parse_params()
 # ... do work ...
 ```
 
+Without arguments it is lenient: a worker launched with no parameters gets
+`{}`. Pass `required=` to abort before any real work when a parameter the
+worker cannot run without is missing or empty — the worker exits with code 1
+and a message on stderr:
+
+```python
+params = parse_params(required=('device_id', 'output_dir'))
+```
+
+`parse_params(argv=...)` accepts an explicit argv list, which makes the
+parsing trivially testable without patching `sys.argv`.
+
 A worker is a separate process, so it cannot be handed a live object (e.g. a DB
 connection). Pass **configuration** instead: the manager's `worker_env` (and any
 per-call `env`) is injected as environment variables, so a worker reads, say,

{crazy_workers-1.4.2 → crazy_workers-1.5.0}/README.md

@@ -41,9 +41,11 @@ pip install .
 
 ```python
 # workers/my_worker.py
-import json, sys, time
+import time
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+from crazy_workers import parse_params
+
+params = parse_params()
 duration = params.get('duration', 60)
 
 for _ in range(duration):
@@ -141,15 +143,28 @@ Closes the database connection and clears internal process references. Does **no
 
 ## Worker Script Contract
 
-A worker receives its parameters as a JSON string in `sys.argv[1]`:
+A worker receives its parameters as a JSON string in `sys.argv[1]`. Use
+`parse_params` instead of decoding it by hand:
 
 ```python
-import json, sys
+from crazy_workers import parse_params
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+params = parse_params()
 # ... do work ...
 ```
 
+Without arguments it is lenient: a worker launched with no parameters gets
+`{}`. Pass `required=` to abort before any real work when a parameter the
+worker cannot run without is missing or empty — the worker exits with code 1
+and a message on stderr:
+
+```python
+params = parse_params(required=('device_id', 'output_dir'))
+```
+
+`parse_params(argv=...)` accepts an explicit argv list, which makes the
+parsing trivially testable without patching `sys.argv`.
+
 A worker is a separate process, so it cannot be handed a live object (e.g. a DB
 connection). Pass **configuration** instead: the manager's `worker_env` (and any
 per-call `env`) is injected as environment variables, so a worker reads, say,

crazy_workers-1.5.0/crazy_workers/__init__.py

@@ -0,0 +1,24 @@
+__all__ = ['WorkerManager', 'WorkerClient', 'WorkerStatus', 'DesiredStatus', 'parse_params']
+
+
+# Resolve exports lazily (PEP 562) so a worker doing `from crazy_workers import
+# parse_params` only imports the lightweight params module — not the control
+# plane (WorkerClient/WorkerManager) and its heavy SQLAlchemy dependencies.
+def __getattr__(name):
+  if name == 'parse_params':
+    from .params import parse_params
+
+    return parse_params
+  if name == 'WorkerManager':
+    from .core.manager import WorkerManager
+
+    return WorkerManager
+  if name == 'WorkerClient':
+    from .client import WorkerClient
+
+    return WorkerClient
+  if name in ('DesiredStatus', 'WorkerStatus'):
+    from .database import schema
+
+    return getattr(schema, name)
+  raise AttributeError(f'module {__name__!r} has no attribute {name!r}')

{crazy_workers-1.4.2 → crazy_workers-1.5.0}/crazy_workers/cli/commands/status.py

@@ -6,12 +6,13 @@ from datetime import datetime
 from rich.panel import Panel
 from rich.table import Table
 
+from ...core.engine import resolve_system_pid
 from ..ui import console
 
 
 def show_status(client, workers_dir, json_mode=False):
   """Observability hub: the target state store plus the worker table (desired vs actual)."""
-  workers = _merge_with_filesystem(client.list(), workers_dir)
+  workers = _with_system_pids(_merge_with_filesystem(client.list(), workers_dir))
 
   if json_mode:
     sys.stdout.write(json.dumps({'workers': workers}) + '\n')
@@ -70,6 +71,25 @@ def _merge_with_filesystem(db_workers, workers_dir):
   return results
 
 
+def _with_system_pids(workers):
+  results = []
+  for worker in workers:
+    enriched = dict(worker)
+    enriched['system_pid'] = resolve_system_pid(enriched.get('pid'), worker_key=enriched.get('worker_key'))
+    results.append(enriched)
+  return results
+
+
+def _format_pid(worker):
+  pid = worker.get('pid')
+  system_pid = worker.get('system_pid')
+  if not pid:
+    return '-'
+  if system_pid and system_pid != pid:
+    return f'{system_pid} [dim](ns {pid})[/dim]'
+  return str(pid)
+
+
 def _build_table(workers):
   table = Table(
     title='[bold cyan]Workers — desired vs actual[/bold cyan]', border_style='cyan', header_style='bold magenta'
@@ -114,7 +134,7 @@ def _build_table(workers):
       w['worker_type'],
       f'[{desired_style}]{desired}[/{desired_style}]',
       f'[{status_style}]{status}[/{status_style}]',
-      str(w['pid']) if w['pid'] else '-',
+      _format_pid(w),
       last_action,
       params_str,
     )

{crazy_workers-1.4.2 → crazy_workers-1.5.0}/crazy_workers/core/engine.py

@@ -1,4 +1,5 @@
 import logging
+import os
 import psutil
 import subprocess
 
@@ -64,6 +65,81 @@ def is_process_running(pid):
     return False
 
 
+def resolve_system_pid(pid, worker_key=None):
+  """Return the most-native PID visible for ``pid``.
+
+  ``pid`` remains the control PID used by the current process namespace. On
+  Linux, ``CRAZY_WORKERS_HOST_PROC`` can point at a read-only host procfs mount
+  (for example /host/proc in Docker) so status can show the host PID. Without
+  that mount, /proc exposes NSpid when PID namespaces are visible; its first
+  value is the PID in the outermost namespace visible to this procfs mount. On
+  Windows and ordinary Linux hosts this is just ``pid``.
+  """
+  if pid is None:
+    return None
+  if os.name != 'posix':
+    return pid
+
+  host_pid = _resolve_from_host_proc(pid, worker_key=worker_key)
+  if host_pid is not None:
+    return host_pid
+
+  try:
+    with open(f'/proc/{pid}/status', encoding='utf-8') as f:
+      for line in f:
+        if line.startswith('NSpid:'):
+          values = [int(value) for value in line.split()[1:]]
+          return values[0] if values else pid
+  except (OSError, ValueError):
+    return pid
+
+  return pid
+
+
+def _resolve_from_host_proc(pid, worker_key=None):
+  host_proc = os.environ.get('CRAZY_WORKERS_HOST_PROC')
+  if not host_proc:
+    return None
+  if not os.path.isdir(host_proc):
+    return None
+
+  for entry in os.listdir(host_proc):
+    if not entry.isdigit():
+      continue
+
+    status_path = os.path.join(host_proc, entry, 'status')
+    try:
+      with open(status_path, encoding='utf-8') as f:
+        nspid = _read_nspid(f)
+    except (OSError, ValueError):
+      continue
+
+    if not nspid or nspid[-1] != pid:
+      continue
+    if worker_key and not _host_proc_cmdline_matches(host_proc, entry, worker_key):
+      continue
+    return nspid[0]
+
+  return None
+
+
+def _read_nspid(lines):
+  for line in lines:
+    if line.startswith('NSpid:'):
+      return [int(value) for value in line.split()[1:]]
+  return None
+
+
+def _host_proc_cmdline_matches(host_proc, host_pid, worker_key):
+  try:
+    with open(os.path.join(host_proc, host_pid, 'cmdline'), 'rb') as f:
+      raw = f.read()
+  except OSError:
+    return False
+  parts = [part.decode(errors='ignore') for part in raw.split(b'\0') if part]
+  return worker_key_token(worker_key) in parts
+
+
 def terminate_process(pid, timeout=5, popen_process=None, exclude_pids=None):
   """Gracefully terminates a process and its non-managed children.
 

crazy_workers-1.5.0/crazy_workers/params.py

@@ -0,0 +1,45 @@
+"""Worker-side parsing of the JSON parameters the daemon passes on argv.
+
+The manager spawns every worker as ``python -m crazy_workers._bootstrap
+<worker_path> <json_params>`` and the bootstrap restores ``sys.argv`` to
+``[worker_path, json_params]``. This module is the worker-side counterpart of
+that contract: call :func:`parse_params` at the top of a worker's ``main()``
+instead of re-implementing the argv/JSON boilerplate in every worker script.
+"""
+
+import json
+import sys
+
+
+def parse_params(argv=None, required=()):
+  """Return the parameters dict the daemon passed to this worker.
+
+  Without ``required`` a worker launched with no parameters gets ``{}`` — the
+  lenient mode for workers whose parameters are all optional. With ``required``
+  a missing argv, malformed JSON, or a missing/empty required key aborts the
+  worker with a message on stderr (``SystemExit``, exit code 1) before it does
+  any real work. A key counts as missing when it is absent, ``None``, or an
+  empty string; a falsy-but-present value like ``0`` or ``False`` is kept.
+
+  ``argv`` defaults to ``sys.argv``; pass a list explicitly in tests.
+  """
+  argv = sys.argv if argv is None else argv
+
+  if len(argv) < 2:
+    if required:
+      raise SystemExit(f'Missing required parameters: {", ".join(required)}')
+    return {}
+
+  try:
+    params = json.loads(argv[1])
+  except json.JSONDecodeError as error:
+    raise SystemExit(f'Invalid JSON parameters: {error}')
+
+  if not isinstance(params, dict):
+    raise SystemExit('Invalid JSON parameters: expected a JSON object')
+
+  missing = [key for key in required if key not in params or params[key] in (None, '')]
+  if missing:
+    raise SystemExit(f'Missing required parameters: {", ".join(missing)}')
+
+  return params

{crazy_workers-1.4.2 → crazy_workers-1.5.0}/crazy_workers.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crazy-workers
-Version: 1.4.2
+Version: 1.5.0
 Summary: A Python library for managing background worker processes with persistent state, automatic recovery, and a CLI.
 Author: GioVanni Colasanto
 License: MIT
@@ -76,9 +76,11 @@ pip install .
 
 ```python
 # workers/my_worker.py
-import json, sys, time
+import time
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+from crazy_workers import parse_params
+
+params = parse_params()
 duration = params.get('duration', 60)
 
 for _ in range(duration):
@@ -176,15 +178,28 @@ Closes the database connection and clears internal process references. Does **no
 
 ## Worker Script Contract
 
-A worker receives its parameters as a JSON string in `sys.argv[1]`:
+A worker receives its parameters as a JSON string in `sys.argv[1]`. Use
+`parse_params` instead of decoding it by hand:
 
 ```python
-import json, sys
+from crazy_workers import parse_params
 
-params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+params = parse_params()
 # ... do work ...
 ```
 
+Without arguments it is lenient: a worker launched with no parameters gets
+`{}`. Pass `required=` to abort before any real work when a parameter the
+worker cannot run without is missing or empty — the worker exits with code 1
+and a message on stderr:
+
+```python
+params = parse_params(required=('device_id', 'output_dir'))
+```
+
+`parse_params(argv=...)` accepts an explicit argv list, which makes the
+parsing trivially testable without patching `sys.argv`.
+
 A worker is a separate process, so it cannot be handed a live object (e.g. a DB
 connection). Pass **configuration** instead: the manager's `worker_env` (and any
 per-call `env`) is injected as environment variables, so a worker reads, say,

{crazy_workers-1.4.2 → crazy_workers-1.5.0}/crazy_workers.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 crazy_workers/__init__.py
 crazy_workers/_bootstrap.py
 crazy_workers/client.py
+crazy_workers/params.py
 crazy_workers.egg-info/PKG-INFO
 crazy_workers.egg-info/SOURCES.txt
 crazy_workers.egg-info/dependency_links.txt
@@ -45,4 +46,5 @@ crazy_workers/database/schema.py
 crazy_workers/database/storage.py
 crazy_workers/testing/__init__.py
 crazy_workers/testing/backends.py
-crazy_workers/testing/polling.py
+crazy_workers/testing/polling.py
+tests/test_params.py

{crazy_workers-1.4.2 → crazy_workers-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crazy-workers"
-version = "1.4.2"
+version = "1.5.0"
 description = "A Python library for managing background worker processes with persistent state, automatic recovery, and a CLI."
 readme = "README.md"
 authors = [{ name = "GioVanni Colasanto" }]
@@ -63,7 +63,7 @@ omit = ["*/venv/*", "*/build/*", "tests/*"]
 [tool.coverage.report]
 show_missing = true
 skip_covered = false
-fail_under = 95
+fail_under = 90
 
 [tool.ruff]
 line-length = 120

crazy_workers-1.5.0/tests/test_params.py

@@ -0,0 +1,51 @@
+import unittest
+from unittest.mock import patch
+
+from crazy_workers import parse_params
+
+
+class TestParseParams(unittest.TestCase):
+  def test_no_argv_returns_empty_dict(self):
+    self.assertEqual(parse_params(['worker.py']), {})
+
+  def test_no_argv_with_required_exits(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py'], required=('device_id', 'output_dir'))
+    self.assertEqual(ctx.exception.code, 'Missing required parameters: device_id, output_dir')
+
+  def test_invalid_json_exits(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', 'not json'])
+    self.assertIn('Invalid JSON parameters', str(ctx.exception.code))
+
+  def test_non_object_json_exits(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', '[1, 2, 3]'])
+    self.assertEqual(ctx.exception.code, 'Invalid JSON parameters: expected a JSON object')
+
+  def test_returns_parsed_params(self):
+    self.assertEqual(parse_params(['worker.py', '{"device_id": "7"}']), {'device_id': '7'})
+
+  def test_required_present_returns_params(self):
+    argv = ['worker.py', '{"device_id": "7", "output_dir": "/out"}']
+    params = parse_params(argv, required=('device_id', 'output_dir'))
+    self.assertEqual(params, {'device_id': '7', 'output_dir': '/out'})
+
+  def test_required_missing_exits_naming_keys(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', '{"device_id": "7"}'], required=('device_id', 'output_dir'))
+    self.assertEqual(ctx.exception.code, 'Missing required parameters: output_dir')
+
+  def test_required_empty_value_counts_as_missing(self):
+    with self.assertRaises(SystemExit) as ctx:
+      parse_params(['worker.py', '{"device_id": ""}'], required=('device_id',))
+    self.assertEqual(ctx.exception.code, 'Missing required parameters: device_id')
+
+  def test_required_falsy_but_present_value_is_kept(self):
+    argv = ['worker.py', '{"retries": 0, "verbose": false}']
+    params = parse_params(argv, required=('retries', 'verbose'))
+    self.assertEqual(params, {'retries': 0, 'verbose': False})
+
+  def test_defaults_to_sys_argv(self):
+    with patch('sys.argv', ['worker.py', '{"interval": 5}']):
+      self.assertEqual(parse_params(), {'interval': 5})

crazy_workers-1.4.2/crazy_workers/__init__.py

@@ -1,6 +0,0 @@
-from .client import WorkerClient
-from .core.manager import WorkerManager
-from .database.schema import DesiredStatus, WorkerStatus
-
-
-__all__ = ['WorkerManager', 'WorkerClient', 'WorkerStatus', 'DesiredStatus']