schedule-bit 0.1.0__tar.gz

schedule_bit-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.live-sandbox.json

schedule_bit-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0
+
+The first release.
+
+- One method per API operation (sync `Client`, async `AsyncClient`), typed with
+  models generated from the OpenAPI contract.
+- 429 and 503 are retried, and network failures and other 5xx where it is safe,
+  with jittered back-off that honours `Retry-After` and `RateLimit-Reset`.
+- The writes that take an `Idempotency-Key` get one automatically, the same
+  across a call's retries.
+- `RateLimit-*` headers are read on every answer; an optional client-side pacer
+  keeps you under a rate.
+- Typed errors: `Refusal` (409), `LocalTimeError` (422), `RateLimited`,
+  `NetworkError`, `TimeoutError`. `try_claim` returns a refusal instead of raising.
+- `Slots` for hex masks; `local_day`, `local_hour` and `local_slot` for local time.
+- `watch()` is a resuming WebSocket iterator (`schedule-bit[watch]`); `assist()`
+  streams the Director's events.

schedule_bit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ontology.io
+
+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.

schedule_bit-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: schedule-bit
+Version: 0.1.0
+Summary: Python SDK for the schedule-bit API: read and write time as bitmasks, with retries, rate limits and live watches handled.
+Project-URL: Homepage, https://schedule-bit.io
+Project-URL: Documentation, https://api.schedule-bit.io/v1/docs
+Project-URL: Source, https://github.com/ontology-io/schedule-bit/tree/main/sdks/python
+Project-URL: Changelog, https://github.com/ontology-io/schedule-bit/blob/main/sdks/python/CHANGELOG.md
+Author: Ontology.io
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bitmask,booking,calendar,schedule,scheduling,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: watch
+Requires-Dist: websockets<16,>=13; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# schedule-bit for Python
+
+The [schedule-bit](https://schedule-bit.io) API from Python. It keeps time as bitmasks, so claiming a resource never double-books it. This SDK covers every operation, sync and async. Retries, rate limits, idempotency and live updates are handled for you.
+
+```sh
+pip install schedule-bit            # or: uv add schedule-bit
+pip install "schedule-bit[watch]"   # adds live watching over WebSocket
+```
+
+Python 3.10 or newer.
+
+## Quick start
+
+```python
+from schedule_bit import Client, Refusal, Slots
+
+with Client() as api:                       # key from SCHEDULE_BIT_API_KEY
+    api.create_world(name="room-1", preset="temporal-hour")
+    api.declare_occupier("room-1", name="omar")
+    api.declare_occupier("room-1", name="sara")
+
+    receipt = api.claim("room-1", who="omar", date="2026-11-12", slots=Slots.range(9, 11))
+    print(receipt.slots)                    # [9, 10]
+
+    outcome = api.try_claim("room-1", who="sara", date="2026-11-12", slots=[10])
+    if isinstance(outcome, Refusal):
+        print(outcome.by, outcome.detail)   # held, "slot 10 is held by omar"
+```
+
+Async is the same, with `await`:
+
+```python
+from schedule_bit import AsyncClient
+
+async with AsyncClient() as api:
+    free = await api.offered("room-1", date="2026-11-12")
+    print(free.slots)
+```
+
+Every operation in the [API reference](https://api.schedule-bit.io/v1/docs) is a method here in `snake_case`, for example `explainClaim` is `explain_claim`. Body fields are keyword arguments, in Python or API spelling. Answers are typed models in `schedule_bit.models`.
+
+## What the client does for you
+
+| | |
+|---|---|
+| **Retries** | 429 and 503 always, and network failures or other 5xx when the call is safe to repeat (a read, `explain_claim`, or a write with an idempotency key). Waits use jittered back-off that honours `Retry-After` and `RateLimit-Reset`. The default is 4 retries; set `max_retries=0` to turn them off. |
+| **Idempotency** | Writes that accept an `Idempotency-Key` get one, the same across that call's retries, so a retried claim never claims twice. To pass your own, use `options=RequestOptions(idempotency_key=…)`. |
+| **Rate limits** | `api.rate_limit` holds the latest `RateLimit-*` headers, `on_rate_limit=` is called with each one, and `rate_limit_per_minute=` paces requests on the client side. |
+| **Timeouts** | 30 s per attempt, which you can change per client (`timeout=`) or per call (`RequestOptions(timeout=…)`). A sync call can be cancelled with `RequestOptions(cancel=threading.Event())`; an async call is cancelled by cancelling its task. |
+| **Errors** | `Refusal` (409, the engine said no, `.by` names why), `LocalTimeError` (422, with `.candidates`), `RateLimited`, `ApiError` for any other problem, and `NetworkError` / `TimeoutError` with the last cause attached. |
+| **Secrets** | Keys never appear in errors, reprs or logs. |
+
+## Masks and local time
+
+```python
+from datetime import datetime
+from zoneinfo import ZoneInfo
+from schedule_bit import Slots, local_slot
+
+Slots.from_hex("0x600").list()       # [9, 10]
+(Slots.range(9, 12) - [10]).hex      # "0xa00"
+
+at = datetime(2026, 10, 25, 1, 30, tzinfo=ZoneInfo("Europe/London"), fold=1)
+api.claim("room-1", who="omar", **local_slot(at))   # the second 01:30 that night
+```
+
+At a clock change, Python's `fold` says which of a repeated time you mean, and `local_slot` sends it as `occurrence`. Without it, the API answers with a `LocalTimeError` that lists the candidates.
+
+## Watching a World
+
+```python
+with api.watch("room-1") as frames:
+    for frame in frames:
+        print(frame.type)            # hello, claim.made, claim.released, …
+```
+
+If the connection drops, the watch reconnects with the same back-off. It catches up from the journal, so no commit is missed, and it yields each event once.
+
+## Development
+
+```sh
+uv sync
+uv run python scripts/generate.py          # after the contract changes
+uv run pytest                              # unit tests (a fake server, no sleeping)
+SCHEDULE_BIT_LIVE=1 uv run pytest -m live  # the shared scenarios against the dev API
+uv run ruff check && uv run mypy
+```
+
+`src/schedule_bit/_generated/` is generated from `sdks/spec/openapi.json`, so don't edit it by hand. A unit test fails when it is stale. The behaviour every SDK shares is in [`sdks/POLICY.md`](../POLICY.md).
+
+MIT licensed.

schedule_bit-0.1.0/README.md

@@ -0,0 +1,91 @@
+# schedule-bit for Python
+
+The [schedule-bit](https://schedule-bit.io) API from Python. It keeps time as bitmasks, so claiming a resource never double-books it. This SDK covers every operation, sync and async. Retries, rate limits, idempotency and live updates are handled for you.
+
+```sh
+pip install schedule-bit            # or: uv add schedule-bit
+pip install "schedule-bit[watch]"   # adds live watching over WebSocket
+```
+
+Python 3.10 or newer.
+
+## Quick start
+
+```python
+from schedule_bit import Client, Refusal, Slots
+
+with Client() as api:                       # key from SCHEDULE_BIT_API_KEY
+    api.create_world(name="room-1", preset="temporal-hour")
+    api.declare_occupier("room-1", name="omar")
+    api.declare_occupier("room-1", name="sara")
+
+    receipt = api.claim("room-1", who="omar", date="2026-11-12", slots=Slots.range(9, 11))
+    print(receipt.slots)                    # [9, 10]
+
+    outcome = api.try_claim("room-1", who="sara", date="2026-11-12", slots=[10])
+    if isinstance(outcome, Refusal):
+        print(outcome.by, outcome.detail)   # held, "slot 10 is held by omar"
+```
+
+Async is the same, with `await`:
+
+```python
+from schedule_bit import AsyncClient
+
+async with AsyncClient() as api:
+    free = await api.offered("room-1", date="2026-11-12")
+    print(free.slots)
+```
+
+Every operation in the [API reference](https://api.schedule-bit.io/v1/docs) is a method here in `snake_case`, for example `explainClaim` is `explain_claim`. Body fields are keyword arguments, in Python or API spelling. Answers are typed models in `schedule_bit.models`.
+
+## What the client does for you
+
+| | |
+|---|---|
+| **Retries** | 429 and 503 always, and network failures or other 5xx when the call is safe to repeat (a read, `explain_claim`, or a write with an idempotency key). Waits use jittered back-off that honours `Retry-After` and `RateLimit-Reset`. The default is 4 retries; set `max_retries=0` to turn them off. |
+| **Idempotency** | Writes that accept an `Idempotency-Key` get one, the same across that call's retries, so a retried claim never claims twice. To pass your own, use `options=RequestOptions(idempotency_key=…)`. |
+| **Rate limits** | `api.rate_limit` holds the latest `RateLimit-*` headers, `on_rate_limit=` is called with each one, and `rate_limit_per_minute=` paces requests on the client side. |
+| **Timeouts** | 30 s per attempt, which you can change per client (`timeout=`) or per call (`RequestOptions(timeout=…)`). A sync call can be cancelled with `RequestOptions(cancel=threading.Event())`; an async call is cancelled by cancelling its task. |
+| **Errors** | `Refusal` (409, the engine said no, `.by` names why), `LocalTimeError` (422, with `.candidates`), `RateLimited`, `ApiError` for any other problem, and `NetworkError` / `TimeoutError` with the last cause attached. |
+| **Secrets** | Keys never appear in errors, reprs or logs. |
+
+## Masks and local time
+
+```python
+from datetime import datetime
+from zoneinfo import ZoneInfo
+from schedule_bit import Slots, local_slot
+
+Slots.from_hex("0x600").list()       # [9, 10]
+(Slots.range(9, 12) - [10]).hex      # "0xa00"
+
+at = datetime(2026, 10, 25, 1, 30, tzinfo=ZoneInfo("Europe/London"), fold=1)
+api.claim("room-1", who="omar", **local_slot(at))   # the second 01:30 that night
+```
+
+At a clock change, Python's `fold` says which of a repeated time you mean, and `local_slot` sends it as `occurrence`. Without it, the API answers with a `LocalTimeError` that lists the candidates.
+
+## Watching a World
+
+```python
+with api.watch("room-1") as frames:
+    for frame in frames:
+        print(frame.type)            # hello, claim.made, claim.released, …
+```
+
+If the connection drops, the watch reconnects with the same back-off. It catches up from the journal, so no commit is missed, and it yields each event once.
+
+## Development
+
+```sh
+uv sync
+uv run python scripts/generate.py          # after the contract changes
+uv run pytest                              # unit tests (a fake server, no sleeping)
+SCHEDULE_BIT_LIVE=1 uv run pytest -m live  # the shared scenarios against the dev API
+uv run ruff check && uv run mypy
+```
+
+`src/schedule_bit/_generated/` is generated from `sdks/spec/openapi.json`, so don't edit it by hand. A unit test fails when it is stale. The behaviour every SDK shares is in [`sdks/POLICY.md`](../POLICY.md).
+
+MIT licensed.

schedule_bit-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "schedule-bit"
+version = "0.1.0"
+description = "Python SDK for the schedule-bit API: read and write time as bitmasks, with retries, rate limits and live watches handled."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ontology.io" }]
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+]
+keywords = ["schedule", "scheduling", "bitmask", "calendar", "booking", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+watch = ["websockets>=13,<16"]
+
+[project.urls]
+Homepage = "https://schedule-bit.io"
+Documentation = "https://api.schedule-bit.io/v1/docs"
+Source = "https://github.com/ontology-io/schedule-bit/tree/main/sdks/python"
+Changelog = "https://github.com/ontology-io/schedule-bit/blob/main/sdks/python/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.6",
+  "mypy>=1.11",
+  "websockets>=13,<16",
+  "datamodel-code-generator==0.83.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/schedule_bit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = ["live: runs against the deployed dev API (needs an operator key)"]
+addopts = "-m 'not live'"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+extend-exclude = ["src/schedule_bit/_generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+plugins = ["pydantic.mypy"]
+files = ["src/schedule_bit"]
+exclude = ["src/schedule_bit/_generated/"]
+
+[[tool.mypy.overrides]]
+module = ["schedule_bit._generated.*"]
+ignore_errors = true

schedule_bit-0.1.0/src/schedule_bit/__init__.py

@@ -0,0 +1,57 @@
+"""The schedule-bit API from Python.
+
+    from schedule_bit import Client, Slots
+
+    with Client() as api:                      # key from SCHEDULE_BIT_API_KEY
+        api.create_world(name="room-1", preset="temporal-hour")
+        api.declare_occupier("room-1", name="omar")
+        receipt = api.claim("room-1", who="omar", date="2026-10-15", slots=Slots.range(9, 11))
+
+See https://api.schedule-bit.io/v1/docs for every operation; each one is a method
+here, in ``snake_case`` (``explainClaim`` is ``explain_claim``).
+"""
+
+from ._client import DEFAULT_BASE_URL, AsyncClient, Client
+from ._generated import models
+from ._options import RequestOptions
+from ._redact import redact
+from ._version import __version__
+from .errors import (
+    ApiError,
+    Cancelled,
+    LocalTimeError,
+    NetworkError,
+    RateLimited,
+    Refusal,
+    ScheduleBitError,
+    TimeoutError,
+)
+from .local_time import local_day, local_hour, local_slot
+from .masks import Slots
+from .rate_limit import RateLimit, TokenBucket
+from .retry import RetryPolicy
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "ApiError",
+    "AsyncClient",
+    "Cancelled",
+    "Client",
+    "LocalTimeError",
+    "NetworkError",
+    "RateLimit",
+    "RateLimited",
+    "Refusal",
+    "RequestOptions",
+    "RetryPolicy",
+    "ScheduleBitError",
+    "Slots",
+    "TimeoutError",
+    "TokenBucket",
+    "__version__",
+    "local_day",
+    "local_hour",
+    "local_slot",
+    "models",
+    "redact",
+]