shipbook 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
shipbook/__init__.py ADDED
@@ -0,0 +1,50 @@
1
+ """Shipbook logging SDK for Python servers.
2
+
3
+ Attach Shipbook to the standard library ``logging`` and your logs ship to the
4
+ cloud — there is no separate Shipbook logging API::
5
+
6
+ import logging
7
+ import shipbook
8
+
9
+ shipbook.start(app_id="...", app_key="...")
10
+ logging.getLogger(__name__).info("hello from Python")
11
+ """
12
+
13
+ from ._inner_log import enable_inner_log
14
+ from .context import preserve_context, register_user
15
+ from .generated.version import SDK_VERSION, __version__
16
+ from .handler import ShipbookHandler
17
+ from .models.request_context import RequestContext
18
+ from .models.request_event import RequestKind, RequestOutcome
19
+ from .models.user import User
20
+ from .request_events import run_in_request
21
+ from .request_events import run_job as run_in_context
22
+ from .severity import Severity
23
+ from .shipbook import (
24
+ flush,
25
+ get_handler,
26
+ set_connection_url,
27
+ shutdown,
28
+ start,
29
+ )
30
+
31
+ __all__ = [
32
+ "start",
33
+ "shutdown",
34
+ "flush",
35
+ "get_handler",
36
+ "set_connection_url",
37
+ "register_user",
38
+ "run_in_context",
39
+ "run_in_request",
40
+ "preserve_context",
41
+ "enable_inner_log",
42
+ "ShipbookHandler",
43
+ "Severity",
44
+ "User",
45
+ "RequestContext",
46
+ "RequestKind",
47
+ "RequestOutcome",
48
+ "SDK_VERSION",
49
+ "__version__",
50
+ ]
shipbook/_inner_log.py ADDED
@@ -0,0 +1,23 @@
1
+ import logging
2
+ import sys
3
+ from typing import Optional
4
+
5
+ # The SDK's own diagnostics, off by default like the other SDKs' InnerLog. It never propagates:
6
+ # reaching the root logger would hand it to ShipbookHandler and ship the SDK's logs about shipping.
7
+ inner_log = logging.getLogger("shipbook.inner")
8
+ inner_log.propagate = False
9
+ inner_log.addHandler(logging.NullHandler())
10
+
11
+ _stderr_handler: Optional[logging.Handler] = None
12
+
13
+
14
+ def enable_inner_log(enable: bool) -> None:
15
+ global _stderr_handler
16
+ if enable and _stderr_handler is None:
17
+ _stderr_handler = logging.StreamHandler(sys.stderr)
18
+ _stderr_handler.setFormatter(logging.Formatter("Shipbook: %(message)s"))
19
+ inner_log.addHandler(_stderr_handler)
20
+ inner_log.setLevel(logging.DEBUG)
21
+ elif not enable and _stderr_handler is not None:
22
+ inner_log.removeHandler(_stderr_handler)
23
+ _stderr_handler = None
shipbook/_state.py ADDED
@@ -0,0 +1,14 @@
1
+ from typing import Optional
2
+
3
+ # The active runtime, set by shipbook.start(). The handler reads it lazily so a
4
+ # ShipbookHandler attached before start() (or after shutdown()) is simply inert.
5
+ _active: Optional[object] = None
6
+
7
+
8
+ def get_active():
9
+ return _active
10
+
11
+
12
+ def set_active(runtime) -> None:
13
+ global _active
14
+ _active = runtime
shipbook/_util.py ADDED
@@ -0,0 +1,23 @@
1
+ import itertools
2
+ from datetime import datetime, timezone
3
+
4
+ _order_counter = itertools.count(1)
5
+
6
+
7
+ def next_order_id() -> int:
8
+ """Process-global monotonic ordering id for logs. ``itertools.count`` is
9
+ thread-safe for a single ``next()`` call under CPython."""
10
+ return next(_order_counter)
11
+
12
+
13
+ def iso_now() -> str:
14
+ return to_iso(datetime.now(timezone.utc))
15
+
16
+
17
+ def to_iso(dt: datetime) -> str:
18
+ """ISO 8601 with millisecond precision and a ``Z`` suffix, matching
19
+ JavaScript's ``Date.toISOString()`` (the format the server parses)."""
20
+ if dt.tzinfo is None:
21
+ dt = dt.replace(tzinfo=timezone.utc)
22
+ dt = dt.astimezone(timezone.utc)
23
+ return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
@@ -0,0 +1,272 @@
1
+ import platform as _platform
2
+ import socket
3
+ import threading
4
+ import time
5
+ import uuid
6
+ from dataclasses import dataclass, field
7
+ from typing import Any, Optional, Union
8
+ from weakref import WeakKeyDictionary
9
+
10
+ from . import context
11
+ from ._inner_log import inner_log
12
+ from ._util import to_iso
13
+ from .config import Config
14
+ from .connection_client import ConnectionClient
15
+ from .generated.version import SDK_VERSION
16
+ from .models.exception import ExceptionLog
17
+ from .models.message import Message
18
+ from .models.request_context import RequestContext
19
+ from .models.request_event import RequestEvent, RequestEventPhase, RequestOutcome
20
+ from .models.session import DeviceInfo, Session
21
+ from .session_manager import SessionManager
22
+
23
+ MACHINE_UDID_KEY = "machine_udid"
24
+
25
+ _PLATFORM = "python"
26
+
27
+ Log = Union[Message, ExceptionLog, RequestEvent]
28
+
29
+
30
+ # Mobile's flushQueue, one per request: it goes up only with a log at or above flush_severity.
31
+ @dataclass
32
+ class _FlushQueue:
33
+ logs: list[dict[str, Any]] = field(default_factory=list)
34
+ saved: bool = False
35
+
36
+
37
+ class CloudUploader:
38
+ """Ships logs to ``sessions/ingest`` the way the mobile and Node SDKs do.
39
+
40
+ - Logs below ``flush_severity`` (and request events) wait in their request's flushQueue
41
+ and are saved only as the context of a later log at or above it (Accumulate).
42
+ - Saved logs go into an in-memory cloud queue: sessions keyed by id, each collecting
43
+ its logs. Nothing is written to disk, and each process has its own queue.
44
+ - A background thread uploads the queue ``max_time`` after the first save, or at once
45
+ when it holds ``max_batch_size`` items. A burst of errors is one upload.
46
+ """
47
+
48
+ def __init__(
49
+ self,
50
+ connection: ConnectionClient,
51
+ session_manager: SessionManager,
52
+ storage,
53
+ config: Config,
54
+ app_version: Optional[str] = None,
55
+ start_worker: bool = True,
56
+ ) -> None:
57
+ self._connection = connection
58
+ self._session_manager = session_manager
59
+ self._storage = storage
60
+ self._config = config
61
+ self._app_version = app_version
62
+
63
+ self._device_info = DeviceInfo(
64
+ udid=self._init_udid(), os=_PLATFORM, device_name=socket.gethostname()
65
+ )
66
+ self._os_name = _platform.system()
67
+ self._os_version = _platform.release()
68
+ self._sdk_version = f"python:{SDK_VERSION}"
69
+ self._start_worker = start_worker
70
+ self._reset_state()
71
+
72
+ def _reset_state(self) -> None:
73
+ self._lock = threading.Lock()
74
+ self._wake = threading.Condition(self._lock)
75
+ # One upload at a time; also what flush() waits on.
76
+ self._send_lock = threading.Lock()
77
+ self._cloud_queue: dict[str, dict[str, Any]] = {}
78
+ # Sessions in the cloud queue plus their logs: what max_batch_size and max_log_size measure.
79
+ self._queue_size = 0
80
+ # Keyed by context object: freed with the request, also when it never finishes.
81
+ self._flush_queues: WeakKeyDictionary[RequestContext, _FlushQueue] = WeakKeyDictionary()
82
+ self._deadline: Optional[float] = None
83
+ self._send_now = False
84
+ self._stopped = False
85
+ # One background session per process, for logs and requests outside any other context.
86
+ self.background_context = RequestContext(session_id=str(uuid.uuid4()), is_background=True)
87
+ self._thread: Optional[threading.Thread] = None
88
+ if self._start_worker:
89
+ self._thread = threading.Thread(target=self._run, name="shipbook-uploader", daemon=True)
90
+ self._thread.start()
91
+
92
+ def after_fork(self) -> None:
93
+ """In a forked child: the parent's thread is gone, its locks may be held."""
94
+ self._reset_state()
95
+
96
+ def set_config(self, config: Config) -> None:
97
+ self._config = config
98
+
99
+ def push(self, log: Log) -> None:
100
+ ctx = context.get() or self.background_context
101
+ data = log.to_dict()
102
+ if ctx.trace_id:
103
+ data["traceId"] = ctx.trace_id
104
+ if ctx.request_id:
105
+ data["requestId"] = ctx.request_id
106
+ # requestTime keeps a request's logs contiguous in the server's display-order sort.
107
+ data["requestTime"] = to_iso(ctx.start_time)
108
+
109
+ with self._lock:
110
+ session = self._session(ctx)
111
+ flush_queue = self._flush_queues.get(ctx)
112
+ if flush_queue is None:
113
+ flush_queue = self._flush_queues[ctx] = _FlushQueue()
114
+
115
+ if self._is_held(log, flush_queue):
116
+ flush_queue.logs.append(data)
117
+ if len(flush_queue.logs) > self._config.flush_size:
118
+ del flush_queue.logs[0]
119
+ return
120
+
121
+ # The flushQueue is this log's context: it is saved with it, in order.
122
+ saved = [*flush_queue.logs, data]
123
+ session["logs"].extend(saved)
124
+ self._queue_size += len(saved)
125
+ flush_queue.logs = []
126
+ flush_queue.saved = True
127
+ self._after_save()
128
+
129
+ def start_request(self, ctx: RequestContext) -> None:
130
+ """A request began in ``ctx``: queue its session and count it, whether or not it logs.
131
+ Counted on the session, not as a log, so the server adds it up and a request whose
132
+ logs all stay below flush_severity still counts."""
133
+ with self._lock:
134
+ self._session(ctx)["requests"] += 1
135
+
136
+ def _session(self, ctx: RequestContext) -> dict[str, Any]:
137
+ if self._queue_size >= self._config.max_log_size:
138
+ inner_log.debug("cloud queue over max_log_size, dropping it")
139
+ self._cloud_queue.clear()
140
+ self._queue_size = 0
141
+ queued = self._cloud_queue.get(ctx.session_id)
142
+ if queued is not None:
143
+ return queued
144
+
145
+ session = self._cloud_queue[ctx.session_id] = Session(
146
+ session_id=ctx.session_id,
147
+ platform=_PLATFORM,
148
+ time=to_iso(ctx.start_time),
149
+ device_info=self._device_info,
150
+ os_name=self._os_name,
151
+ os_version=self._os_version,
152
+ sdk_version=self._sdk_version,
153
+ app_version=self._app_version,
154
+ user=ctx.user,
155
+ attributes=ctx.attributes,
156
+ is_background=ctx.is_background,
157
+ job_name=ctx.job_name,
158
+ caller_session_link=ctx.caller_session_link,
159
+ ).to_dict()
160
+ self._queue_size += 1
161
+ self._after_save()
162
+ return session
163
+
164
+ def _is_held(self, log: Log, flush_queue: _FlushQueue) -> bool:
165
+ if isinstance(log, Message):
166
+ return self._config.flush_severity.value < log.severity.value
167
+ # A process keeps running after an exception: it's saved like an error, the timer sends it.
168
+ if isinstance(log, ExceptionLog):
169
+ return False
170
+ if log.event == RequestEventPhase.End:
171
+ # A failed request is saved like an error, start included, even if it logged nothing.
172
+ if log.outcome == RequestOutcome.Error:
173
+ return False
174
+ # A request whose logs went up keeps its end: it has the status, outcome, duration.
175
+ return not flush_queue.saved
176
+ return True
177
+
178
+ def _after_save(self) -> None:
179
+ if self._queue_size >= self._config.max_batch_size:
180
+ self._send_now = True
181
+ self._wake.notify()
182
+ elif self._deadline is None:
183
+ self._deadline = time.monotonic() + self._config.max_time
184
+ self._wake.notify()
185
+
186
+ def request_send(self) -> None:
187
+ """Wake the worker to send now, without waiting (e.g. once login has succeeded)."""
188
+ with self._lock:
189
+ self._send_now = True
190
+ self._wake.notify()
191
+
192
+ def flush(self, timeout: Optional[float] = None) -> bool:
193
+ """Send what's queued now and wait, at most ``timeout`` seconds. True when it finished."""
194
+ if timeout is None:
195
+ self._send()
196
+ return True
197
+ sender = threading.Thread(target=self._send, name="shipbook-flush", daemon=True)
198
+ sender.start()
199
+ sender.join(timeout)
200
+ return not sender.is_alive()
201
+
202
+ def shutdown(self, timeout: Optional[float] = None) -> None:
203
+ with self._lock:
204
+ self._stopped = True
205
+ self._wake.notify()
206
+ if self._thread is not None:
207
+ self._thread.join(1)
208
+ self.flush(timeout)
209
+
210
+ def _run(self) -> None:
211
+ while True:
212
+ with self._lock:
213
+ while not self._due():
214
+ wait = (
215
+ None
216
+ if self._deadline is None
217
+ else max(self._deadline - time.monotonic(), 0)
218
+ )
219
+ self._wake.wait(wait)
220
+ if self._stopped:
221
+ return
222
+ self._send()
223
+
224
+ def _due(self) -> bool:
225
+ if self._stopped or self._send_now:
226
+ return True
227
+ return self._deadline is not None and time.monotonic() >= self._deadline
228
+
229
+ def _send(self) -> None:
230
+ with self._send_lock:
231
+ with self._lock:
232
+ self._deadline = None
233
+ self._send_now = False
234
+ # No token: the queue stays (bounded by max_log_size) and a login sends it.
235
+ if not self._session_manager.get_token():
236
+ return
237
+ sessions = list(self._cloud_queue.values())
238
+ self._cloud_queue = {}
239
+ self._queue_size = 0
240
+ if not sessions:
241
+ return
242
+
243
+ resp = self._connection.request("sessions/ingest", {"sessions": sessions}, "POST")
244
+ if resp.ok:
245
+ return
246
+ inner_log.error("ingest failed: %s %s", resp.status, resp.text[:200])
247
+ # Unreachable or a server error: retry next window. A 4xx would fail the same way again.
248
+ if resp.status == 0 or resp.status >= 500:
249
+ self._requeue(sessions)
250
+
251
+ def _requeue(self, sessions: list[dict[str, Any]]) -> None:
252
+ with self._lock:
253
+ for session in sessions:
254
+ queued = self._cloud_queue.get(session["sessionId"])
255
+ if queued is None:
256
+ self._cloud_queue[session["sessionId"]] = session
257
+ self._queue_size += 1 + len(session["logs"])
258
+ else:
259
+ queued["logs"][:0] = session["logs"]
260
+ queued["requests"] += session["requests"]
261
+ self._queue_size += len(session["logs"])
262
+ if self._deadline is None:
263
+ self._deadline = time.monotonic() + self._config.max_time
264
+ self._wake.notify()
265
+
266
+ def _init_udid(self) -> str:
267
+ stored = self._storage.get_item(MACHINE_UDID_KEY)
268
+ if stored:
269
+ return stored.strip()
270
+ udid = str(uuid.uuid4())
271
+ self._storage.set_item(MACHINE_UDID_KEY, udid)
272
+ return udid
shipbook/config.py ADDED
@@ -0,0 +1,108 @@
1
+ from dataclasses import dataclass, field
2
+ from typing import Any, Optional
3
+
4
+ from .severity import Severity
5
+
6
+ # Appender types that mean "ship to Shipbook cloud". Console output on Python is
7
+ # the user's own logging handlers' job, so only cloud loggers gate what we send.
8
+ _CLOUD_TYPES = {"SBCloudAppender", "SLCloudAppender"}
9
+
10
+ DEFAULT_MAX_TIME = 3.0
11
+ DEFAULT_FLUSH_SIZE = 100 # per request, not per app as on mobile
12
+ DEFAULT_MAX_BATCH_SIZE = 1000
13
+ DEFAULT_MAX_LOG_SIZE = 5000
14
+ DEFAULT_CONFIG_REFRESH_INTERVAL = 300
15
+
16
+
17
+ @dataclass
18
+ class _Logger:
19
+ key: str
20
+ severity: Severity
21
+ call_stack_severity: Severity
22
+
23
+
24
+ @dataclass
25
+ class Config:
26
+ """Parsed server config. Holds only what the Python SDK acts on: which
27
+ tags/severities ship to cloud, and the cloud appender's flush knobs."""
28
+
29
+ loggers: list[_Logger] = field(default_factory=list)
30
+ max_time: float = DEFAULT_MAX_TIME
31
+ flush_severity: Severity = Severity.Warning
32
+ # Ring size of a request's flushQueue: logs held below flush_severity, as error context.
33
+ flush_size: int = DEFAULT_FLUSH_SIZE
34
+ # A server saves thousands within max_time: an upload also goes once the queue holds this many.
35
+ max_batch_size: int = DEFAULT_MAX_BATCH_SIZE
36
+ # While uploads can't drain the queue (no token, server down) it's emptied at this size.
37
+ max_log_size: int = DEFAULT_MAX_LOG_SIZE
38
+ config_refresh_interval: int = DEFAULT_CONFIG_REFRESH_INTERVAL
39
+ raw: Optional[dict[str, Any]] = None
40
+
41
+ @classmethod
42
+ def default(cls) -> "Config":
43
+ return cls.from_dict(
44
+ {
45
+ "appenders": [
46
+ {
47
+ "type": "SBCloudAppender",
48
+ "name": "cloud",
49
+ "config": {"maxTime": DEFAULT_MAX_TIME, "flushSeverity": "Warning"},
50
+ }
51
+ ],
52
+ "loggers": [{"name": "", "severity": "Verbose", "appenderRef": "cloud"}],
53
+ }
54
+ )
55
+
56
+ @classmethod
57
+ def from_dict(cls, data: dict[str, Any]) -> "Config":
58
+ appenders = data.get("appenders") or []
59
+ cloud_names = {a.get("name") for a in appenders if a.get("type") in _CLOUD_TYPES}
60
+
61
+ cloud_cfg: dict[str, Any] = {}
62
+ for a in appenders:
63
+ if a.get("type") in _CLOUD_TYPES and a.get("config"):
64
+ cloud_cfg = a["config"]
65
+ break
66
+
67
+ loggers = [
68
+ _Logger(
69
+ key=lg.get("name") or "",
70
+ severity=Severity.from_name(lg.get("severity", "Off")),
71
+ call_stack_severity=Severity.from_name(lg.get("callStackSeverity", "Off")),
72
+ )
73
+ for lg in (data.get("loggers") or [])
74
+ if lg.get("appenderRef") in cloud_names
75
+ ]
76
+
77
+ cfg = cls(loggers=loggers, raw=data)
78
+ if cloud_cfg.get("maxTime") is not None:
79
+ cfg.max_time = float(cloud_cfg["maxTime"])
80
+ if cloud_cfg.get("flushSeverity"):
81
+ cfg.flush_severity = Severity.from_name(cloud_cfg["flushSeverity"])
82
+ if cloud_cfg.get("flushSize") is not None:
83
+ cfg.flush_size = int(cloud_cfg["flushSize"])
84
+ if cloud_cfg.get("maxBatchSize") is not None:
85
+ cfg.max_batch_size = int(cloud_cfg["maxBatchSize"])
86
+ if cloud_cfg.get("maxLogSize") is not None:
87
+ cfg.max_log_size = int(cloud_cfg["maxLogSize"])
88
+ if data.get("configRefreshInterval") is not None:
89
+ cfg.config_refresh_interval = int(data["configRefreshInterval"])
90
+ return cfg
91
+
92
+ @property
93
+ def cloud_enabled(self) -> bool:
94
+ return any(lg.severity != Severity.Off for lg in self.loggers)
95
+
96
+ def should_ship(self, tag: str, severity: Severity) -> bool:
97
+ threshold = Severity.Off
98
+ for lg in self.loggers:
99
+ if tag.startswith(lg.key) and lg.severity.value > threshold.value:
100
+ threshold = lg.severity
101
+ return threshold != Severity.Off and severity.value <= threshold.value
102
+
103
+ def call_stack_severity(self, tag: str) -> Severity:
104
+ result = Severity.Off
105
+ for lg in self.loggers:
106
+ if tag.startswith(lg.key) and lg.call_stack_severity.value > result.value:
107
+ result = lg.call_stack_severity
108
+ return result
@@ -0,0 +1,84 @@
1
+ import json
2
+ import urllib.error
3
+ import urllib.request
4
+ from dataclasses import dataclass
5
+ from typing import Any, Callable, Optional
6
+
7
+ DEFAULT_BASE_URL = "https://api.shipbook.io/v2/"
8
+ _TIMEOUT = 30
9
+
10
+
11
+ @dataclass
12
+ class Response:
13
+ ok: bool
14
+ status: int
15
+ reason: str
16
+ data: Optional[Any] = None
17
+ text: str = ""
18
+
19
+
20
+ class ConnectionClient:
21
+ def __init__(self) -> None:
22
+ self.base_url = DEFAULT_BASE_URL
23
+ self._get_token: Callable[[], Optional[str]] = lambda: None
24
+ self._refresh_token: Callable[[], bool] = lambda: False
25
+
26
+ def set_deps(
27
+ self,
28
+ get_token: Callable[[], Optional[str]],
29
+ refresh_token: Callable[[], bool],
30
+ ) -> None:
31
+ self._get_token = get_token
32
+ self._refresh_token = refresh_token
33
+
34
+ def set_base_url(self, url: str) -> None:
35
+ self.base_url = url if url.endswith("/") else url + "/"
36
+
37
+ def request(
38
+ self,
39
+ path: str,
40
+ body: Optional[Any] = None,
41
+ method: str = "GET",
42
+ _retried: bool = False,
43
+ ) -> Response:
44
+ url = self.base_url + path
45
+ headers = {"Content-Type": "application/json"}
46
+ token = self._get_token()
47
+ if token:
48
+ headers["Authorization"] = f"Bearer {token}"
49
+
50
+ payload = json.dumps(body).encode("utf-8") if body is not None else None
51
+ req = urllib.request.Request(url, data=payload, headers=headers, method=method)
52
+
53
+ try:
54
+ with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:
55
+ raw = resp.read().decode("utf-8")
56
+ return Response(
57
+ ok=True,
58
+ status=resp.status,
59
+ reason=resp.reason,
60
+ data=self._parse(raw),
61
+ text=raw,
62
+ )
63
+ except urllib.error.HTTPError as e:
64
+ raw = e.read().decode("utf-8", errors="replace")
65
+ if e.code == 401 and not _retried and self._refresh_token():
66
+ return self.request(path, body, method, _retried=True)
67
+ return Response(
68
+ ok=False,
69
+ status=e.code,
70
+ reason=e.reason or "",
71
+ data=self._parse(raw),
72
+ text=raw,
73
+ )
74
+ except urllib.error.URLError as e:
75
+ return Response(ok=False, status=0, reason=str(e.reason), text=str(e.reason))
76
+
77
+ @staticmethod
78
+ def _parse(raw: str) -> Optional[Any]:
79
+ if not raw:
80
+ return None
81
+ try:
82
+ return json.loads(raw)
83
+ except json.JSONDecodeError:
84
+ return None
shipbook/context.py ADDED
@@ -0,0 +1,73 @@
1
+ import contextvars
2
+ import functools
3
+ from collections.abc import Iterator
4
+ from contextlib import contextmanager
5
+ from typing import Callable, Optional
6
+
7
+ from .models.request_context import RequestContext
8
+ from .models.user import User
9
+
10
+ _ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.ContextVar(
11
+ "shipbook_request_context", default=None
12
+ )
13
+
14
+
15
+ def get() -> Optional[RequestContext]:
16
+ return _ctx.get()
17
+
18
+
19
+ def set_context(context: RequestContext) -> contextvars.Token:
20
+ return _ctx.set(context)
21
+
22
+
23
+ def reset(token: contextvars.Token) -> None:
24
+ _ctx.reset(token)
25
+
26
+
27
+ @contextmanager
28
+ def run(context: RequestContext) -> Iterator[RequestContext]:
29
+ token = _ctx.set(context)
30
+ try:
31
+ yield context
32
+ finally:
33
+ _ctx.reset(token)
34
+
35
+
36
+ def preserve_context(fn: Callable) -> Callable:
37
+ """Wrap ``fn`` so it runs with the *current* Shipbook context even when
38
+ executed on another thread. Use when handing work to ``threading.Thread``
39
+ or an executor, which otherwise start with a fresh (background) context::
40
+
41
+ pool.submit(shipbook.preserve_context(do_work))
42
+ """
43
+ ctx = contextvars.copy_context()
44
+
45
+ @functools.wraps(fn)
46
+ def wrapper(*args, **kwargs):
47
+ return ctx.run(fn, *args, **kwargs)
48
+
49
+ return wrapper
50
+
51
+
52
+ def register_user(
53
+ user_id: str,
54
+ user_name: Optional[str] = None,
55
+ full_name: Optional[str] = None,
56
+ email: Optional[str] = None,
57
+ phone_number: Optional[str] = None,
58
+ additional_info: Optional[dict[str, str]] = None,
59
+ ) -> None:
60
+ """Attach user info to the current context (request or job). No-op with a
61
+ warning path is avoided: if there is no active context, the user is dropped
62
+ because a background/fallback session has no single owning user."""
63
+ context = _ctx.get()
64
+ if context is None:
65
+ return
66
+ context.user = User(
67
+ user_id=user_id,
68
+ user_name=user_name,
69
+ full_name=full_name,
70
+ email=email,
71
+ phone_number=phone_number,
72
+ additional_info=additional_info,
73
+ )
File without changes
@@ -0,0 +1,2 @@
1
+ __version__ = "0.2.0"
2
+ SDK_VERSION = __version__