didntrun-sdk 1.0.0__tar.gz

didntrun_sdk-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/

didntrun_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Štětka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

didntrun_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.5
+Name: didntrun-sdk
+Version: 1.0.0
+Summary: First-party Python client for the didnt.run ping API: correct, non-blocking instrumentation by default.
+Project-URL: Homepage, https://didnt.run
+Project-URL: Source, https://gitlab.com/robert.stetka/didnt-run-sdk-python
+Author: Robert Štětka
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cron,didnt.run,healthcheck,heartbeat,monitoring,watchdog
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: contract
+Requires-Dist: psycopg[binary]>=3.2; extra == 'contract'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# didntrun-sdk — Python client for didnt.run
+
+Instrument a scheduled job against didnt.run with one line. The SDK's contract: **your job is never
+slowed beyond a hard time budget and never failed by the watchdog** — every transport problem is
+swallowed and logged, by default through Python's `logging` module, or through a logger you supply.
+
+## Install
+
+```bash
+pip install didntrun-sdk
+```
+
+## Use
+
+```python
+import os
+from didntrun import Watchdog
+
+# One env var wires everything: https://{ping-token}@it.didnt.run[?budget_ms=2000&connect_timeout_ms=1000]
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"])
+```
+
+> Your DSN is shown once, ready to copy, when you issue a ping token in the didnt.run admin UI.
+
+```python
+# Recommended: bracket the work. ONE completion ping — measured duration on success,
+# exception context on failure (the exception is re-raised; your job's semantics don't change).
+with wd.run("app.daily-report"):
+    generate()
+
+# Or the decorator form:
+@wd.watch("app.daily-report")
+def daily_report():
+    ...
+
+# Or fire the bare "I ran" ping yourself:
+wd.ping("app.daily-report")
+wd.ping("app.daily-report", duration_ms=1234)
+
+# Or send explicit lifecycle pings — manual bracketing when start and finish
+# live in different processes or code paths (see "Lifecycle bracketing"):
+wd.start("app.daily-report")
+wd.success("app.daily-report", duration_ms=1234)
+wd.fail("app.daily-report")
+```
+
+`ping()` returns `bool` (delivered vs. swallowed) if you want to observe delivery; you never have to.
+
+### Job identity
+
+```python
+@wd.watch()          # id defaults to f"{fn.__module__}.{fn.__qualname__}"
+def daily_report():
+    ...
+```
+
+**This is identity-defining.** Moving `daily_report` to another module registers a NEW job — the old
+one goes stale and will alert. Prefer the explicit-id form (`@wd.watch("app.daily-report")`); every
+example above uses it for that reason. Ids are normalized the same way the PHP SDK
+normalizes them — leading `\` stripped, `\` → `.`, empty rejected — and capped at 255 **bytes**, which
+is the length the server measures, dropping a trailing partial UTF-8 character rather than splitting
+one. The mapping is kept for parity rather than necessity: Python identifiers are already dotted, so
+it is a no-op for a native id.
+
+### Failure semantics
+
+- Misconfiguration (a malformed DSN, an empty token, a token outside the accept set, a base URL with a
+  query, a fragment or an unparseable port, a DSN option that is not a plain positive integer) raises
+  `ValueError` **at construction**, and `@wd.watch()` raises `ValueError` **at decoration** when the
+  function it wraps is an `async def` or a generator (see "No `async`/`await`"). Both are wiring time,
+  before any job runs. After that, nothing raises except the wrapped work's own exception inside
+  `run()` / `watch()`, re-raised unchanged.
+- Each ping gets a wall-clock budget (default 2 s, connect 1 s) with one retry inside it — see
+  "Delivery and retries" below for exactly which failures qualify. `401` is logged at ERROR (your token
+  is wrong); every other rejection at WARNING.
+- Oversized `meta` (> 64 KiB body) is dropped; the ping still goes out.
+
+### Wiring
+
+```python
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"])
+```
+
+Construct once at startup, wherever your app already wires singletons, and hand `wd` around — there's
+no framework glue to install; `Watchdog` is a plain object.
+
+Bring your own HTTP client (optional): implement the `Transport` protocol — it's `typing.Protocol`, not
+an ABC, so nothing has to import from this package. The whole surface is one method:
+
+```python
+from collections.abc import Mapping
+
+import requests
+from didntrun.transport import Transport, TransportResult, TimeBudget
+
+class RequestsTransport(Transport):
+    def post(self, url: str, headers: Mapping[str, str], body: bytes, budget: TimeBudget) -> TransportResult:
+        try:
+            resp = requests.post(
+                url, headers=dict(headers), data=body, allow_redirects=False,
+                timeout=(budget.connect_ms / 1000, max(budget.total_ms, 1) / 1000),
+            )
+            return TransportResult.response(resp.status_code)
+        except requests.RequestException as e:
+            return TransportResult.failure(str(e))
+
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"], transport=RequestsTransport())
+```
+
+Note the time budget is then only as good as your client's own timeout config — the default
+`HttpClientTransport` (stdlib `http.client`) is deliberately the one thing this package doesn't
+outsource: it never follows redirects and enforces the budget by tracking a deadline on
+`time.monotonic()` rather than relying on a per-socket-operation `timeout=`.
+
+### Lifecycle bracketing
+
+`run()` / `watch()` send one completion ping by default. Opt into **bracketing** and they also emit a
+`start` ping *before* the work runs: the `start` anchor is duration-immune, so it tightens the inferred
+cadence for jobs whose duration is non-trivial or variable (a terminal-only anchor drifts with run
+length).
+
+Enable it globally (constructor arg, or the `lifecycle` DSN param) with a per-call override:
+
+```python
+# Global default via DSN: https://{token}@it.didnt.run?lifecycle=true
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"])
+with wd.run("app.daily-report"):        # start + completion
+    generate()
+
+# Per-call override wins (None = inherit the instance default):
+with wd.run("app.daily-report", lifecycle=True):
+    generate()
+```
+
+A bracketed run has **two** budget windows — one ping before the work, one after — so its worst-case
+added wall-clock is ~2× the per-ping budget, straddling the work. For work a single `with` block can't
+wrap (it spans processes, or start and finish live in different code), call `start()` / `success()` /
+`fail()` directly instead.
+
+**Server requirement:** bracketing needs a ping-api that understands lifecycle kinds. Against an older,
+kind-blind self-hosted server, leave `lifecycle` **off** — a separate `start` ping would double-count
+runs in schedule inference.
+
+**No `async`/`await`.** There's no async HTTP client in the stdlib, and shipping one would break the
+zero-dependency promise. `@wd.watch()` **refuses** an `async def` or a generator function outright,
+with a `ValueError` at decoration: a synchronous wrapper around a coroutine function gets the
+coroutine object back immediately, so the completion ping would go out before the work had executed a
+line — reporting success for a job that has not run yet, and feeding a 0 ms duration into the
+hung-detection baseline. Await the work inside a sync wrapper, or keep the ping off the loop thread:
+
+```python
+await asyncio.to_thread(wd.ping, "app.daily-report")
+```
+
+## Logging
+
+Every failure is swallowed and logged. By default the SDK logs through the standard `logging` module —
+`logging.getLogger("didntrun")` — with **no handler attached**, so with nothing else configured in your
+process, Python's own `logging.lastResort` emits WARNING and above to **stderr**. Under a plain cron
+invocation that's exactly what you want: your cron runner captures or mails it.
+
+Attach your own handler to redirect it, the same as any other library logger:
+
+```python
+import logging
+
+logging.getLogger("didntrun").addHandler(logging.FileHandler("/var/log/didntrun.log"))
+```
+
+To silence it completely:
+
+```python
+logging.getLogger("didntrun").addHandler(logging.NullHandler())
+```
+
+A ping that is never delivered is the one failure you cannot see from the server side — it looks
+identical to a job that died before pinging. Leaving logging on is what tells the two apart.
+
+Each failure is written as exactly one line, so a log is safe to grep and count — that's also how the
+PHP SDK's deferred time-budget question gets settled for this one: count `ping rejected` against
+`ping not delivered`. Control characters in a value you passed — a newline or a tab inside an
+`external_id`, say — appear as `?` rather than breaking the line in two, and the same context is also
+passed as `extra=` for handlers that render structured fields. Your ping token never appears in a log
+line either, including inside an error string authored by a transport.
+
+**stderr records carry no timestamp** — `logging.lastResort` uses a bare handler with no `Formatter`, so
+a message on stderr says only what happened, not when. Counting failures over a week works either way,
+but correlating a specific lost ping with a specific alert needs a timestamp — either attach a real
+handler (above) or have your cron wrapper stamp the stream.
+
+## Delivery and retries
+
+A ping is retried **once** when the failure could plausibly succeed on a second attempt:
+
+| Outcome | Retried? |
+| --- | --- |
+| Connection refused / DNS failure / timeout | yes |
+| `408 Request Timeout`, any `5xx` | yes |
+| `429 Too Many Requests` | no |
+| Any other `4xx` (`400`, `401`, `404`, …) | no |
+
+One retry in total, never one per category. The retry has to fit inside the same time budget as the
+first attempt (2 s by default), so against a slow server there may be no room for it — the SDK will
+never exceed the budget to get a ping through.
+
+## CLI
+
+Installing the package also installs `didnt-run` — a console script, no separate install step:
+
+```
+didnt-run ping <id> [--duration-ms N] [--meta k=v]...
+didnt-run run  <id> [--lifecycle] [--capture-stderr] -- <cmd> [args...]
+```
+
+Reads `DIDNT_RUN_DSN` from the environment, or `--dsn`. `run` wraps a shell command in your crontab:
+
+```cron
+*/5 * * * * didnt-run run app.nightly-backup -- pg_dump -Fc mydb > /backups/mydb.dump
+```
+
+- **It exits with the wrapped command's exit code.** The crontab's semantics, and any `&&` chained
+  after it, are unchanged.
+- **stdout and stderr pass straight through**, so cron mail still works. `--capture-stderr` *tees*
+  rather than swallows, keeping the last 512 bytes for `meta` — it defaults to **off**, because a
+  command's stderr is a population you didn't write and can't predict (`curl`, `pg_dump`, `rsync` all
+  print connection strings on failure on their own); a denylist of secret-looking patterns goes stale
+  the day some tool prints a new one, so the safe default is off and the opt-in is explicit.
+- **A watchdog failure never changes the exit code.** A missing or malformed `DIDNT_RUN_DSN` logs to
+  stderr and the command still runs, uninstrumented — an already-registered job that stops pinging is
+  exactly what the watchdog alerts on. A command that can't be executed at all follows the
+  shell's own convention: **127** when it is not found, **126** when it is found but not executable.
+  The same code goes into the `fail` ping's `exit_code` meta and out as the wrapper's exit status.
+
+A malformed `--meta` on `run` is reported on stderr and dropped — the command still runs. It was the
+only watchdog-side input on that path that could stop a backup, and a metadata typo is the least
+important of them. `didnt-run ping` has nothing to protect, so misconfiguration there exits `2`.
+`--meta k=v` values are always strings; no type coercion is attempted.
+
+## Requirements
+
+Python ≥ 3.11. Zero runtime dependencies — the SDK is stdlib only.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Development happens in the didnt.run monorepo; this repository is a read-only subtree split. Please
+report issues against the SDK there rather than opening merge requests here.

didntrun_sdk-1.0.0/README.md

@@ -0,0 +1,248 @@
+# didntrun-sdk — Python client for didnt.run
+
+Instrument a scheduled job against didnt.run with one line. The SDK's contract: **your job is never
+slowed beyond a hard time budget and never failed by the watchdog** — every transport problem is
+swallowed and logged, by default through Python's `logging` module, or through a logger you supply.
+
+## Install
+
+```bash
+pip install didntrun-sdk
+```
+
+## Use
+
+```python
+import os
+from didntrun import Watchdog
+
+# One env var wires everything: https://{ping-token}@it.didnt.run[?budget_ms=2000&connect_timeout_ms=1000]
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"])
+```
+
+> Your DSN is shown once, ready to copy, when you issue a ping token in the didnt.run admin UI.
+
+```python
+# Recommended: bracket the work. ONE completion ping — measured duration on success,
+# exception context on failure (the exception is re-raised; your job's semantics don't change).
+with wd.run("app.daily-report"):
+    generate()
+
+# Or the decorator form:
+@wd.watch("app.daily-report")
+def daily_report():
+    ...
+
+# Or fire the bare "I ran" ping yourself:
+wd.ping("app.daily-report")
+wd.ping("app.daily-report", duration_ms=1234)
+
+# Or send explicit lifecycle pings — manual bracketing when start and finish
+# live in different processes or code paths (see "Lifecycle bracketing"):
+wd.start("app.daily-report")
+wd.success("app.daily-report", duration_ms=1234)
+wd.fail("app.daily-report")
+```
+
+`ping()` returns `bool` (delivered vs. swallowed) if you want to observe delivery; you never have to.
+
+### Job identity
+
+```python
+@wd.watch()          # id defaults to f"{fn.__module__}.{fn.__qualname__}"
+def daily_report():
+    ...
+```
+
+**This is identity-defining.** Moving `daily_report` to another module registers a NEW job — the old
+one goes stale and will alert. Prefer the explicit-id form (`@wd.watch("app.daily-report")`); every
+example above uses it for that reason. Ids are normalized the same way the PHP SDK
+normalizes them — leading `\` stripped, `\` → `.`, empty rejected — and capped at 255 **bytes**, which
+is the length the server measures, dropping a trailing partial UTF-8 character rather than splitting
+one. The mapping is kept for parity rather than necessity: Python identifiers are already dotted, so
+it is a no-op for a native id.
+
+### Failure semantics
+
+- Misconfiguration (a malformed DSN, an empty token, a token outside the accept set, a base URL with a
+  query, a fragment or an unparseable port, a DSN option that is not a plain positive integer) raises
+  `ValueError` **at construction**, and `@wd.watch()` raises `ValueError` **at decoration** when the
+  function it wraps is an `async def` or a generator (see "No `async`/`await`"). Both are wiring time,
+  before any job runs. After that, nothing raises except the wrapped work's own exception inside
+  `run()` / `watch()`, re-raised unchanged.
+- Each ping gets a wall-clock budget (default 2 s, connect 1 s) with one retry inside it — see
+  "Delivery and retries" below for exactly which failures qualify. `401` is logged at ERROR (your token
+  is wrong); every other rejection at WARNING.
+- Oversized `meta` (> 64 KiB body) is dropped; the ping still goes out.
+
+### Wiring
+
+```python
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"])
+```
+
+Construct once at startup, wherever your app already wires singletons, and hand `wd` around — there's
+no framework glue to install; `Watchdog` is a plain object.
+
+Bring your own HTTP client (optional): implement the `Transport` protocol — it's `typing.Protocol`, not
+an ABC, so nothing has to import from this package. The whole surface is one method:
+
+```python
+from collections.abc import Mapping
+
+import requests
+from didntrun.transport import Transport, TransportResult, TimeBudget
+
+class RequestsTransport(Transport):
+    def post(self, url: str, headers: Mapping[str, str], body: bytes, budget: TimeBudget) -> TransportResult:
+        try:
+            resp = requests.post(
+                url, headers=dict(headers), data=body, allow_redirects=False,
+                timeout=(budget.connect_ms / 1000, max(budget.total_ms, 1) / 1000),
+            )
+            return TransportResult.response(resp.status_code)
+        except requests.RequestException as e:
+            return TransportResult.failure(str(e))
+
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"], transport=RequestsTransport())
+```
+
+Note the time budget is then only as good as your client's own timeout config — the default
+`HttpClientTransport` (stdlib `http.client`) is deliberately the one thing this package doesn't
+outsource: it never follows redirects and enforces the budget by tracking a deadline on
+`time.monotonic()` rather than relying on a per-socket-operation `timeout=`.
+
+### Lifecycle bracketing
+
+`run()` / `watch()` send one completion ping by default. Opt into **bracketing** and they also emit a
+`start` ping *before* the work runs: the `start` anchor is duration-immune, so it tightens the inferred
+cadence for jobs whose duration is non-trivial or variable (a terminal-only anchor drifts with run
+length).
+
+Enable it globally (constructor arg, or the `lifecycle` DSN param) with a per-call override:
+
+```python
+# Global default via DSN: https://{token}@it.didnt.run?lifecycle=true
+wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"])
+with wd.run("app.daily-report"):        # start + completion
+    generate()
+
+# Per-call override wins (None = inherit the instance default):
+with wd.run("app.daily-report", lifecycle=True):
+    generate()
+```
+
+A bracketed run has **two** budget windows — one ping before the work, one after — so its worst-case
+added wall-clock is ~2× the per-ping budget, straddling the work. For work a single `with` block can't
+wrap (it spans processes, or start and finish live in different code), call `start()` / `success()` /
+`fail()` directly instead.
+
+**Server requirement:** bracketing needs a ping-api that understands lifecycle kinds. Against an older,
+kind-blind self-hosted server, leave `lifecycle` **off** — a separate `start` ping would double-count
+runs in schedule inference.
+
+**No `async`/`await`.** There's no async HTTP client in the stdlib, and shipping one would break the
+zero-dependency promise. `@wd.watch()` **refuses** an `async def` or a generator function outright,
+with a `ValueError` at decoration: a synchronous wrapper around a coroutine function gets the
+coroutine object back immediately, so the completion ping would go out before the work had executed a
+line — reporting success for a job that has not run yet, and feeding a 0 ms duration into the
+hung-detection baseline. Await the work inside a sync wrapper, or keep the ping off the loop thread:
+
+```python
+await asyncio.to_thread(wd.ping, "app.daily-report")
+```
+
+## Logging
+
+Every failure is swallowed and logged. By default the SDK logs through the standard `logging` module —
+`logging.getLogger("didntrun")` — with **no handler attached**, so with nothing else configured in your
+process, Python's own `logging.lastResort` emits WARNING and above to **stderr**. Under a plain cron
+invocation that's exactly what you want: your cron runner captures or mails it.
+
+Attach your own handler to redirect it, the same as any other library logger:
+
+```python
+import logging
+
+logging.getLogger("didntrun").addHandler(logging.FileHandler("/var/log/didntrun.log"))
+```
+
+To silence it completely:
+
+```python
+logging.getLogger("didntrun").addHandler(logging.NullHandler())
+```
+
+A ping that is never delivered is the one failure you cannot see from the server side — it looks
+identical to a job that died before pinging. Leaving logging on is what tells the two apart.
+
+Each failure is written as exactly one line, so a log is safe to grep and count — that's also how the
+PHP SDK's deferred time-budget question gets settled for this one: count `ping rejected` against
+`ping not delivered`. Control characters in a value you passed — a newline or a tab inside an
+`external_id`, say — appear as `?` rather than breaking the line in two, and the same context is also
+passed as `extra=` for handlers that render structured fields. Your ping token never appears in a log
+line either, including inside an error string authored by a transport.
+
+**stderr records carry no timestamp** — `logging.lastResort` uses a bare handler with no `Formatter`, so
+a message on stderr says only what happened, not when. Counting failures over a week works either way,
+but correlating a specific lost ping with a specific alert needs a timestamp — either attach a real
+handler (above) or have your cron wrapper stamp the stream.
+
+## Delivery and retries
+
+A ping is retried **once** when the failure could plausibly succeed on a second attempt:
+
+| Outcome | Retried? |
+| --- | --- |
+| Connection refused / DNS failure / timeout | yes |
+| `408 Request Timeout`, any `5xx` | yes |
+| `429 Too Many Requests` | no |
+| Any other `4xx` (`400`, `401`, `404`, …) | no |
+
+One retry in total, never one per category. The retry has to fit inside the same time budget as the
+first attempt (2 s by default), so against a slow server there may be no room for it — the SDK will
+never exceed the budget to get a ping through.
+
+## CLI
+
+Installing the package also installs `didnt-run` — a console script, no separate install step:
+
+```
+didnt-run ping <id> [--duration-ms N] [--meta k=v]...
+didnt-run run  <id> [--lifecycle] [--capture-stderr] -- <cmd> [args...]
+```
+
+Reads `DIDNT_RUN_DSN` from the environment, or `--dsn`. `run` wraps a shell command in your crontab:
+
+```cron
+*/5 * * * * didnt-run run app.nightly-backup -- pg_dump -Fc mydb > /backups/mydb.dump
+```
+
+- **It exits with the wrapped command's exit code.** The crontab's semantics, and any `&&` chained
+  after it, are unchanged.
+- **stdout and stderr pass straight through**, so cron mail still works. `--capture-stderr` *tees*
+  rather than swallows, keeping the last 512 bytes for `meta` — it defaults to **off**, because a
+  command's stderr is a population you didn't write and can't predict (`curl`, `pg_dump`, `rsync` all
+  print connection strings on failure on their own); a denylist of secret-looking patterns goes stale
+  the day some tool prints a new one, so the safe default is off and the opt-in is explicit.
+- **A watchdog failure never changes the exit code.** A missing or malformed `DIDNT_RUN_DSN` logs to
+  stderr and the command still runs, uninstrumented — an already-registered job that stops pinging is
+  exactly what the watchdog alerts on. A command that can't be executed at all follows the
+  shell's own convention: **127** when it is not found, **126** when it is found but not executable.
+  The same code goes into the `fail` ping's `exit_code` meta and out as the wrapper's exit status.
+
+A malformed `--meta` on `run` is reported on stderr and dropped — the command still runs. It was the
+only watchdog-side input on that path that could stop a backup, and a metadata typo is the least
+important of them. `didnt-run ping` has nothing to protect, so misconfiguration there exits `2`.
+`--meta k=v` values are always strings; no type coercion is attempted.
+
+## Requirements
+
+Python ≥ 3.11. Zero runtime dependencies — the SDK is stdlib only.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Development happens in the didnt.run monorepo; this repository is a read-only subtree split. Please
+report issues against the SDK there rather than opening merge requests here.

didntrun_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "didntrun-sdk"
+version = "1.0.0"
+description = "First-party Python client for the didnt.run ping API: correct, non-blocking instrumentation by default."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Robert Štětka" }]
+keywords = ["cron", "monitoring", "watchdog", "heartbeat", "healthcheck", "didnt.run"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://didnt.run"
+Source = "https://gitlab.com/robert.stetka/didnt-run-sdk-python"
+
+[project.scripts]
+didnt-run = "didntrun.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.3", "mypy>=1.13", "ruff>=0.8"]
+contract = ["psycopg[binary]>=3.2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/didntrun"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+# Ruff 0.16 formats Python code blocks inside Markdown. A README's snippets are illustrative and
+# hand-laid-out for reading — collapsing `def f():\n    ...` onto one line and exploding a call
+# across five is worse documentation, and ECS does not format the PHP SDK's README either.
+extend-exclude = ["*.md"]
+line-length = 110
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM", "RUF", "ANN", "PT", "S", "PTH"]
+ignore = [
+    # `meta` is caller-supplied JSON; Mapping[str, Any] is the honest type, not a weakness.
+    "ANN401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# S603 flags every subprocess call. Running the wrapped command IS this module's job, and it
+# deliberately runs it WITHOUT a shell — which is the thing S603 exists to encourage.
+"src/didntrun/cli.py" = ["S603"]
+# Tests assert, and pytest does not want return annotations on every test function. S105/S106 flag
+# every literal named like a credential, and a ping token fixture IS one — deliberately fake, and
+# the thing under test in the construction suite.
+"tests/**" = ["S101", "S105", "S106", "ANN"]
+# The four process-level CLI tests exist to observe what a REAL wrapper process does to its own
+# stderr, so spawning one is the method, not an oversight. S607's `sh` is deliberate too: `2>&-` is
+# how fd 2 gets closed, and a shell found on PATH is what a crontab line would use.
+"tests/unit/test_cli_process.py" = ["S101", "S105", "S106", "ANN", "S603", "S607"]
+# The last two contract tests call Watchdog._send on purpose: they assert on the SERVER's limits,
+# and going through the public ping() would hit the SDK's own guard first and never reach the wire.
+"tests/contract/test_ping_contract.py" = ["S101", "ANN", "SLF001"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests"]
+warn_unreachable = true
+
+# Tests are type-checked, but not required to annotate every test function: pytest calls them, not
+# us, so a missing `-> None` buys nothing. Everything else strict still applies — a test that
+# misuses a public type is still an error, which is the point of checking them at all.
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+# Follows from the two above rather than adding anything: unannotated helpers are allowed here, so
+# flagging every call to one would make the exemption self-cancelling. mypy 2.x reports those calls
+# from inside an unannotated test body as well, where 1.x did not.
+disallow_untyped_calls = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests/unit"]
+addopts = "-q"
+# A DeprecationWarning from the stdlib is a bug report against this package's 3.11 floor.
+# ResourceWarning is exempt: it fires at GC time, so with sockets in play it would make the suite
+# fail on collection timing rather than on anything a reader could act on.
+filterwarnings = ["error", "default::ResourceWarning"]