fathom-charts 0.2.0__tar.gz

fathom_charts-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

fathom_charts-0.2.0/LICENSE

@@ -0,0 +1,38 @@
+Fathom Charts SDK License
+
+Copyright (c) 2026 Adrien Insights. All rights reserved.
+
+The fathom-charts Python package (the "Software") is proprietary. It is licensed,
+not sold.
+
+1. Grant. Subject to these terms, Adrien Insights grants you a non-exclusive,
+   non-transferable, revocable, royalty-free license to install, use and copy
+   the Software, and to include it, in source or compiled, bundled or minified
+   form, in your own applications, solely to access the Fathom Charts service
+   (fathomcharts.com, its REST API and its WebSocket stream, the "Service")
+   under the Service's terms of use.
+
+2. Restrictions. You may not: (a) use the Software, or any part or derivative of
+   it, to access or build a client for any service other than the Service;
+   (b) distribute, sell, sublicense or publish the Software on its own, as a
+   package, library or SDK, other than as part of your own application;
+   (c) remove or alter this notice.
+
+3. Ownership. The Software and all rights in it remain the property of
+   Adrien Insights. No right is granted other than those expressly stated
+   above. Using the Service also requires an account and an API key, governed
+   by the Service's terms of use and terms of sale.
+
+4. Termination. This license ends automatically if you breach these terms or
+   when your right to use the Service ends. You must then stop using the
+   Software and remove it from your applications.
+
+5. No warranty. 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 NON-INFRINGEMENT. TO
+   THE EXTENT PERMITTED BY LAW, ADRIEN INSIGHTS SHALL NOT BE LIABLE FOR ANY
+   CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.
+
+6. Law. These terms are governed by French law.
+
+Contact: support@fathomcharts.com

fathom_charts-0.2.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: fathom-charts
+Version: 0.2.0
+Summary: Fathom Charts client: real-time order-flow indicator streams (WebSocket) and history (REST), for Python 3.11+ (asyncio).
+Project-URL: Homepage, https://fathomcharts.com/docs/sdk/python
+Project-URL: Documentation, https://fathomcharts.com/docs/sdk/python
+Author-email: Adrien Insights <support@fathomcharts.com>
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Keywords: fathom-charts,footprint,indicators,market-data,order-flow,trading,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: websockets>=15
+Requires-Dist: zstandard>=0.23
+Description-Content-Type: text/markdown
+
+# fathom-charts
+
+Python client for [Fathom Charts](https://fathomcharts.com): real-time order-flow indicator streams (WebSocket) and history (REST), for Python 3.11+ (asyncio).
+
+The SDK handles authentication, the initial snapshot, resuming after a disconnect, duplicates, history pagination and rate-limit retries.
+
+Documentation: [fathomcharts.com/docs/sdk/python](https://fathomcharts.com/docs/sdk/python)
+
+## Install
+
+```bash
+pip install fathom-charts
+# or
+uv add fathom-charts
+```
+
+Generate the types of each indicator's parameters and data from the catalog (`GET /v1/indicators`, no authentication):
+
+```bash
+curl https://api.fathomcharts.com/v1/indicators -o catalog.json
+fathom-charts-types catalog.json fathom_charts_types.py
+```
+
+The command also takes the catalog URL instead of a file. Each indicator gets `<Name>Params` and `<Name>Data` (`TypedDict`), named after its id (`big-trades` → `BigTradesParams`), with the catalog's descriptions as docstrings; `IndicatorParams`, `IndicatorData` and `IndicatorId` cover them all. A tuple whose last elements are optional is the union of its allowed lengths (`tuple[int, int, int] | tuple[int, int, int, int]`); JSON arrays still arrive as lists.
+
+## Real time
+
+```python
+import asyncio
+import os
+
+from fathom_charts import FathomChartsStream, Subscription, Upsert
+from fathom_charts_types import BigTradesData
+
+
+async def main() -> None:
+    async with FathomChartsStream(url="wss://stream.fathomcharts.com/v1", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as stream:
+        big_trades: Subscription[BigTradesData]
+        async with stream.subscribe(
+            instrument="NQ.front",
+            indicator="big-trades",
+            params={"minimum": 30},
+            mode="confirmed",
+        ) as big_trades:
+            async for event in big_trades:
+                if isinstance(event, Upsert):
+                    print(event.data["side"], event.data["volume"], event.data["price"])
+
+
+asyncio.run(main())
+```
+
+The events are frozen dataclasses: `Subscribed`, `Snapshot` (its `items` are `Item`), `Upsert`, `Remove`, `Status`, `Reset` and `Notice`, each with its `type` (`'upsert'`…), to test with `isinstance` or `match`. Heartbeats and pongs are handled by the SDK; notices (a restart, a maintenance window announced or cancelled) reach every subscription and `on_notice`; an `error` on the subscription is raised by the loop as a `FathomChartsError`. Leaving the `async with` block of a subscription unsubscribes (leaving an `async for` loop alone does not, in Python: use `async with`, or `await sub.close()`); the connection closes when no subscription is left. See [Real time](https://fathomcharts.com/docs/websocket).
+
+An application distributed to end users must not hold the API key: give `stream_token` instead of `api_key`, an async function returning a fresh single-use token that your backend gets from `POST /v1/stream-tokens` (`FathomChartsRest.stream_token()`), called for every connection.
+
+## History
+
+```python
+from fathom_charts import FathomChartsRest
+
+async with FathomChartsRest(base_url="https://api.fathomcharts.com", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as rest:
+    async for m in rest.history({
+        "instrument": "NQZ6",
+        "indicator": "big-trades",
+        "params": {"minimum": 30},
+        "from": "1790256600000000000",
+        "to": "1790258100000000000",
+    }):
+        if m["t"] == "upsert" and m["final"] and "data" in m:
+            print(m["cursor"], m["data"]["side"], m["data"]["volume"])
+```
+
+Queries are dictionaries with the fields of the API (`instrument`, `indicator`, `params`, `from`, `to`, `mode`, `limit`, `cursor`, `untilCursor`, `snapshot`); with `"snapshot": True`, `history()` yields the state at `from` first, as a `{"t": "snapshot", "cursor": …, "items": […]}` element. `page()` and `pages()` give the pages themselves, `estimate()` the cost of a query without running it. On error, the SDK raises a `FathomChartsError` carrying the error `code`. See [History](https://fathomcharts.com/docs/history).
+
+## Export to a file
+
+`export_ndjson()` decompresses an export as NDJSON (one mutation per line), in chunks of whole lines, and resumes it by itself after a cut, without gap or duplicate:
+
+```python
+from contextlib import aclosing
+
+from fathom_charts import RangeQuery
+
+query: RangeQuery = {"instrument": "NQZ6", "indicator": "big-trades", "params": {"minimum": 30}, "from": "1790256600000000000", "to": "1790258100000000000"}
+async with FathomChartsRest(base_url="https://api.fathomcharts.com", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as rest:
+    with open("big-trades.ndjson", "wb") as file:
+        async with aclosing(rest.export_ndjson(query)) as chunks:
+            async for chunk in chunks:
+                file.write(chunk)
+```
+
+`max_resumes` (default 5) bounds the consecutive resumptions without a new line, `resume_delay` (1 s, doubled up to 30 s) spaces them. `export()` gives the zstd-compressed file as sent (`body`, `content_type`, `filename`, and the `token` that resumes it).
+
+## Connection, resume and flow control
+
+`FathomChartsStream` multiplexes its subscriptions on one connection and reopens it after a cut (backoff with jitter), resuming each subscription after its last cursor received, with the engine build its state comes from; events already received are never delivered twice. During an update of the service the stream pauses and resumes by itself; when the computation of an indicator changed, the subscription receives `reset` (`engine_change`), `subscribed` and a new snapshot. See [Updates and maintenance](https://fathomcharts.com/docs/maintenance).
+
+Durations are in seconds.
+
+- A resume within the server's memory of recent messages continues where it stopped. An older one (a long cut, or a long `from_={"time": …}` replay interrupted) is caught up from history when your offer includes it and its depth reaches the cursor's UTC day: the rest of the replay follows, then real time, without `reset` nor snapshot (the historical part is charged like the `from_={"time": …}`). Otherwise the subscription receives `reset` (`cursor_expired`) followed by a fresh snapshot.
+- `high_water_mark` (default 10 000 queued events): above it, the SDK stops reading the socket (TCP backpressure up to the server) and queued provisional upserts of the same object are merged. While paused, the SDK sends `ping` messages so that the server keeps the connection.
+- `max_buffered` (default 4 × `high_water_mark`): a socket given by a `web_socket` factory that cannot be paused (`pausable` false) stops being read there: the SDK closes the connection (close code 4000, `client buffer full`) and reopens it from the last queued cursor once the consumer has read half the high-water mark. Nothing queued is lost, and the resume rules above apply.
+- `heartbeat_timeout` (default 15 s): without any message for this long (the server sends `hb` every 5 s), the connection is dropped and reopened.
+- `reconnect=Reconnect(...)`: `initial_delay` (0.25 s), `max_delay` (30 s), `quota_retry` (how long close code 4029 is retried, 120 s), `quota_delay` (5 s).
+- `random`: source of the reconnection jitter, in [0, 1) (default `random.random`; for tests).
+- `on_notice` receives the server notices (`reconnect`; `maintenance` with `id`, `effective_at`, `ends_at`, `message`; `maintenance-cancelled` with `id`; `breaking-change` with `effective_at`), also given to every subscription as `Notice` events; `stream.maintenance` lists the maintenance windows announced and not over; `on_state_change` the connection state (`idle`, `connecting`, `open`, `reconnecting`, `closed`), also readable as `stream.connection_state`.
+
+A `Subscription` is an async iterator of events, with:
+
+- `id`: its `sub` on the connection (`s1`, `s2`…), as in the protocol messages;
+- `request`: the subscription as requested, defaults filled in (`params={}`, `mode='live'`, `from_='live'`);
+- `cursor`: cursor of the last event handed to your loop, the resume point; a heartbeat also advances it while every received event is consumed, so it moves even when nothing is published;
+- `topic`: topic key from the latest `subscribed`;
+- `engine`: engine build from the latest `subscribed`; save it with `cursor` and resume a later process with `from_={"cursor": cursor, "engine": engine}`;
+- `close()`: unsubscribes (as leaving its `async with` block does).
+
+`CloseCode` lists the gateway's WebSocket close codes; `compare_cursors(a, b)` orders two cursors (negative, zero, positive).
+
+## Errors
+
+Every error the SDK raises, or ends an iteration with, is a `FathomChartsError` (`ERROR_CODES` lists the codes):
+
+- `code`: the API's code (`INVALID_PARAMETERS`, `FORBIDDEN`, `QUOTA_EXCEEDED`…), or one of the SDK's own: `CONFIGURATION` (invalid options: missing or empty `api_key`, both `api_key` and `stream_token`…), `CLOSED`, `KEY_REVOKED`, `ENTITLEMENTS_CHANGED`, `TOO_MANY_CONNECTIONS`, `PROTOCOL_ERROR`, `BINARY_NOT_SUPPORTED`, `INVALID_UTF8`, `MESSAGE_TOO_BIG`, `NETWORK_ERROR` (the API could not be reached, or the connection was lost during an answer), or `HTTP_<status>` for an HTTP error answer that is not a problem document;
+- `status`, `close_code`, `retry_after` when known;
+- `problem`: the RFC 9457 problem document of an HTTP error, with its `errors` (invalid fields); `None` when the answer is not a problem document;
+- `__cause__`: the original error (the error of httpx…), when there is one.
+
+A call is stopped by cancelling its task (`asyncio.timeout()`, `Task.cancel()`), a wait for a retry included: the `asyncio.CancelledError` goes through untouched, as asyncio requires.
+
+## License
+
+Proprietary: you may use this package and include it in your own applications only to access the Fathom Charts service. See [LICENSE](./LICENSE).

fathom_charts-0.2.0/README.md

@@ -0,0 +1,133 @@
+# fathom-charts
+
+Python client for [Fathom Charts](https://fathomcharts.com): real-time order-flow indicator streams (WebSocket) and history (REST), for Python 3.11+ (asyncio).
+
+The SDK handles authentication, the initial snapshot, resuming after a disconnect, duplicates, history pagination and rate-limit retries.
+
+Documentation: [fathomcharts.com/docs/sdk/python](https://fathomcharts.com/docs/sdk/python)
+
+## Install
+
+```bash
+pip install fathom-charts
+# or
+uv add fathom-charts
+```
+
+Generate the types of each indicator's parameters and data from the catalog (`GET /v1/indicators`, no authentication):
+
+```bash
+curl https://api.fathomcharts.com/v1/indicators -o catalog.json
+fathom-charts-types catalog.json fathom_charts_types.py
+```
+
+The command also takes the catalog URL instead of a file. Each indicator gets `<Name>Params` and `<Name>Data` (`TypedDict`), named after its id (`big-trades` → `BigTradesParams`), with the catalog's descriptions as docstrings; `IndicatorParams`, `IndicatorData` and `IndicatorId` cover them all. A tuple whose last elements are optional is the union of its allowed lengths (`tuple[int, int, int] | tuple[int, int, int, int]`); JSON arrays still arrive as lists.
+
+## Real time
+
+```python
+import asyncio
+import os
+
+from fathom_charts import FathomChartsStream, Subscription, Upsert
+from fathom_charts_types import BigTradesData
+
+
+async def main() -> None:
+    async with FathomChartsStream(url="wss://stream.fathomcharts.com/v1", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as stream:
+        big_trades: Subscription[BigTradesData]
+        async with stream.subscribe(
+            instrument="NQ.front",
+            indicator="big-trades",
+            params={"minimum": 30},
+            mode="confirmed",
+        ) as big_trades:
+            async for event in big_trades:
+                if isinstance(event, Upsert):
+                    print(event.data["side"], event.data["volume"], event.data["price"])
+
+
+asyncio.run(main())
+```
+
+The events are frozen dataclasses: `Subscribed`, `Snapshot` (its `items` are `Item`), `Upsert`, `Remove`, `Status`, `Reset` and `Notice`, each with its `type` (`'upsert'`…), to test with `isinstance` or `match`. Heartbeats and pongs are handled by the SDK; notices (a restart, a maintenance window announced or cancelled) reach every subscription and `on_notice`; an `error` on the subscription is raised by the loop as a `FathomChartsError`. Leaving the `async with` block of a subscription unsubscribes (leaving an `async for` loop alone does not, in Python: use `async with`, or `await sub.close()`); the connection closes when no subscription is left. See [Real time](https://fathomcharts.com/docs/websocket).
+
+An application distributed to end users must not hold the API key: give `stream_token` instead of `api_key`, an async function returning a fresh single-use token that your backend gets from `POST /v1/stream-tokens` (`FathomChartsRest.stream_token()`), called for every connection.
+
+## History
+
+```python
+from fathom_charts import FathomChartsRest
+
+async with FathomChartsRest(base_url="https://api.fathomcharts.com", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as rest:
+    async for m in rest.history({
+        "instrument": "NQZ6",
+        "indicator": "big-trades",
+        "params": {"minimum": 30},
+        "from": "1790256600000000000",
+        "to": "1790258100000000000",
+    }):
+        if m["t"] == "upsert" and m["final"] and "data" in m:
+            print(m["cursor"], m["data"]["side"], m["data"]["volume"])
+```
+
+Queries are dictionaries with the fields of the API (`instrument`, `indicator`, `params`, `from`, `to`, `mode`, `limit`, `cursor`, `untilCursor`, `snapshot`); with `"snapshot": True`, `history()` yields the state at `from` first, as a `{"t": "snapshot", "cursor": …, "items": […]}` element. `page()` and `pages()` give the pages themselves, `estimate()` the cost of a query without running it. On error, the SDK raises a `FathomChartsError` carrying the error `code`. See [History](https://fathomcharts.com/docs/history).
+
+## Export to a file
+
+`export_ndjson()` decompresses an export as NDJSON (one mutation per line), in chunks of whole lines, and resumes it by itself after a cut, without gap or duplicate:
+
+```python
+from contextlib import aclosing
+
+from fathom_charts import RangeQuery
+
+query: RangeQuery = {"instrument": "NQZ6", "indicator": "big-trades", "params": {"minimum": 30}, "from": "1790256600000000000", "to": "1790258100000000000"}
+async with FathomChartsRest(base_url="https://api.fathomcharts.com", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as rest:
+    with open("big-trades.ndjson", "wb") as file:
+        async with aclosing(rest.export_ndjson(query)) as chunks:
+            async for chunk in chunks:
+                file.write(chunk)
+```
+
+`max_resumes` (default 5) bounds the consecutive resumptions without a new line, `resume_delay` (1 s, doubled up to 30 s) spaces them. `export()` gives the zstd-compressed file as sent (`body`, `content_type`, `filename`, and the `token` that resumes it).
+
+## Connection, resume and flow control
+
+`FathomChartsStream` multiplexes its subscriptions on one connection and reopens it after a cut (backoff with jitter), resuming each subscription after its last cursor received, with the engine build its state comes from; events already received are never delivered twice. During an update of the service the stream pauses and resumes by itself; when the computation of an indicator changed, the subscription receives `reset` (`engine_change`), `subscribed` and a new snapshot. See [Updates and maintenance](https://fathomcharts.com/docs/maintenance).
+
+Durations are in seconds.
+
+- A resume within the server's memory of recent messages continues where it stopped. An older one (a long cut, or a long `from_={"time": …}` replay interrupted) is caught up from history when your offer includes it and its depth reaches the cursor's UTC day: the rest of the replay follows, then real time, without `reset` nor snapshot (the historical part is charged like the `from_={"time": …}`). Otherwise the subscription receives `reset` (`cursor_expired`) followed by a fresh snapshot.
+- `high_water_mark` (default 10 000 queued events): above it, the SDK stops reading the socket (TCP backpressure up to the server) and queued provisional upserts of the same object are merged. While paused, the SDK sends `ping` messages so that the server keeps the connection.
+- `max_buffered` (default 4 × `high_water_mark`): a socket given by a `web_socket` factory that cannot be paused (`pausable` false) stops being read there: the SDK closes the connection (close code 4000, `client buffer full`) and reopens it from the last queued cursor once the consumer has read half the high-water mark. Nothing queued is lost, and the resume rules above apply.
+- `heartbeat_timeout` (default 15 s): without any message for this long (the server sends `hb` every 5 s), the connection is dropped and reopened.
+- `reconnect=Reconnect(...)`: `initial_delay` (0.25 s), `max_delay` (30 s), `quota_retry` (how long close code 4029 is retried, 120 s), `quota_delay` (5 s).
+- `random`: source of the reconnection jitter, in [0, 1) (default `random.random`; for tests).
+- `on_notice` receives the server notices (`reconnect`; `maintenance` with `id`, `effective_at`, `ends_at`, `message`; `maintenance-cancelled` with `id`; `breaking-change` with `effective_at`), also given to every subscription as `Notice` events; `stream.maintenance` lists the maintenance windows announced and not over; `on_state_change` the connection state (`idle`, `connecting`, `open`, `reconnecting`, `closed`), also readable as `stream.connection_state`.
+
+A `Subscription` is an async iterator of events, with:
+
+- `id`: its `sub` on the connection (`s1`, `s2`…), as in the protocol messages;
+- `request`: the subscription as requested, defaults filled in (`params={}`, `mode='live'`, `from_='live'`);
+- `cursor`: cursor of the last event handed to your loop, the resume point; a heartbeat also advances it while every received event is consumed, so it moves even when nothing is published;
+- `topic`: topic key from the latest `subscribed`;
+- `engine`: engine build from the latest `subscribed`; save it with `cursor` and resume a later process with `from_={"cursor": cursor, "engine": engine}`;
+- `close()`: unsubscribes (as leaving its `async with` block does).
+
+`CloseCode` lists the gateway's WebSocket close codes; `compare_cursors(a, b)` orders two cursors (negative, zero, positive).
+
+## Errors
+
+Every error the SDK raises, or ends an iteration with, is a `FathomChartsError` (`ERROR_CODES` lists the codes):
+
+- `code`: the API's code (`INVALID_PARAMETERS`, `FORBIDDEN`, `QUOTA_EXCEEDED`…), or one of the SDK's own: `CONFIGURATION` (invalid options: missing or empty `api_key`, both `api_key` and `stream_token`…), `CLOSED`, `KEY_REVOKED`, `ENTITLEMENTS_CHANGED`, `TOO_MANY_CONNECTIONS`, `PROTOCOL_ERROR`, `BINARY_NOT_SUPPORTED`, `INVALID_UTF8`, `MESSAGE_TOO_BIG`, `NETWORK_ERROR` (the API could not be reached, or the connection was lost during an answer), or `HTTP_<status>` for an HTTP error answer that is not a problem document;
+- `status`, `close_code`, `retry_after` when known;
+- `problem`: the RFC 9457 problem document of an HTTP error, with its `errors` (invalid fields); `None` when the answer is not a problem document;
+- `__cause__`: the original error (the error of httpx…), when there is one.
+
+A call is stopped by cancelling its task (`asyncio.timeout()`, `Task.cancel()`), a wait for a retry included: the `asyncio.CancelledError` goes through untouched, as asyncio requires.
+
+## License
+
+Proprietary: you may use this package and include it in your own applications only to access the Fathom Charts service. See [LICENSE](./LICENSE).

fathom_charts-0.2.0/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "fathom-charts"
+version = "0.2.0"
+description = "Fathom Charts client: real-time order-flow indicator streams (WebSocket) and history (REST), for Python 3.11+ (asyncio)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "Adrien Insights", email = "support@fathomcharts.com" }]
+keywords = ["fathom-charts", "order-flow", "footprint", "indicators", "market-data", "websocket", "trading"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28",
+    "websockets>=15",
+    "zstandard>=0.23",
+]
+
+[project.urls]
+Homepage = "https://fathomcharts.com/docs/sdk/python"
+Documentation = "https://fathomcharts.com/docs/sdk/python"
+
+[project.scripts]
+fathom-charts-types = "fathom_charts.generate_types:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.15",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fathom_charts"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/fathom_charts", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src", "tests"]
+
+[tool.ruff]
+line-length = 140
+target-version = "py311"

fathom_charts-0.2.0/src/fathom_charts/__init__.py

@@ -0,0 +1,154 @@
+"""Fathom Charts client: real-time order-flow indicator streams (WebSocket) and history (REST)."""
+
+from .errors import ERROR_CODES, ErrorCode, FathomChartsError, ProblemFieldError
+from .protocol import (
+    AuthMessage,
+    ClientMessage,
+    CloseCode,
+    CursorFrom,
+    ErrorMessage,
+    From,
+    HeartbeatMessage,
+    MaintenanceWindow,
+    Mode,
+    NoticeKind,
+    NoticeMessage,
+    PingMessage,
+    PongMessage,
+    RemoveMessage,
+    ResetMessage,
+    ResetReason,
+    ServerMessage,
+    SnapshotItem,
+    SnapshotMessage,
+    SourceState,
+    StatusMessage,
+    SubscribedMessage,
+    SubscribeMessage,
+    TimeFrom,
+    UnsubscribeMessage,
+    UpsertMessage,
+    compare_cursors,
+)
+from .rest import (
+    Catalog,
+    CatalogField,
+    CatalogIndicator,
+    CatalogObject,
+    CatalogParam,
+    Estimate,
+    ExportResume,
+    ExportStream,
+    FathomChartsRest,
+    HistorySnapshot,
+    Instrument,
+    Instruments,
+    Limits,
+    Mutation,
+    OfferCode,
+    Offers,
+    Page,
+    PageQuery,
+    PageSnapshot,
+    PlanCode,
+    RangeQuery,
+    Resolved,
+    ServiceStatus,
+    StatusMaintenance,
+    StreamToken,
+    Usage,
+)
+from .stream import (
+    ConnectionState,
+    FathomChartsStream,
+    Item,
+    Notice,
+    Reconnect,
+    Remove,
+    Reset,
+    Snapshot,
+    Status,
+    StreamEvent,
+    Subscribed,
+    SubscribeRequest,
+    Subscription,
+    Upsert,
+    WebSocketFactory,
+    WebSocketLike,
+)
+
+__all__ = [
+    "ERROR_CODES",
+    "AuthMessage",
+    "Catalog",
+    "CatalogField",
+    "CatalogIndicator",
+    "CatalogObject",
+    "CatalogParam",
+    "ClientMessage",
+    "CloseCode",
+    "ConnectionState",
+    "CursorFrom",
+    "ErrorCode",
+    "ErrorMessage",
+    "Estimate",
+    "ExportResume",
+    "ExportStream",
+    "FathomChartsError",
+    "FathomChartsRest",
+    "FathomChartsStream",
+    "From",
+    "HeartbeatMessage",
+    "HistorySnapshot",
+    "Instrument",
+    "Instruments",
+    "Item",
+    "Limits",
+    "MaintenanceWindow",
+    "Mode",
+    "Mutation",
+    "Notice",
+    "NoticeKind",
+    "NoticeMessage",
+    "OfferCode",
+    "Offers",
+    "Page",
+    "PageQuery",
+    "PageSnapshot",
+    "PingMessage",
+    "PlanCode",
+    "PongMessage",
+    "ProblemFieldError",
+    "RangeQuery",
+    "Reconnect",
+    "Remove",
+    "RemoveMessage",
+    "Reset",
+    "ResetMessage",
+    "ResetReason",
+    "Resolved",
+    "ServerMessage",
+    "ServiceStatus",
+    "Snapshot",
+    "SnapshotItem",
+    "SnapshotMessage",
+    "SourceState",
+    "Status",
+    "StatusMaintenance",
+    "StatusMessage",
+    "StreamEvent",
+    "StreamToken",
+    "SubscribeMessage",
+    "SubscribeRequest",
+    "Subscribed",
+    "SubscribedMessage",
+    "Subscription",
+    "TimeFrom",
+    "UnsubscribeMessage",
+    "Upsert",
+    "UpsertMessage",
+    "Usage",
+    "WebSocketFactory",
+    "WebSocketLike",
+    "compare_cursors",
+]

fathom_charts-0.2.0/src/fathom_charts/errors.py

@@ -0,0 +1,91 @@
+"""Stable error codes and the error the SDK raises."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+ErrorCode = Literal[
+    "INVALID_PARAMETERS", "UNKNOWN_INDICATOR", "UNKNOWN_INSTRUMENT", "NOT_COVERED", "WARMING", "QUOTA_EXCEEDED",
+    "RATE_LIMITED", "CAPACITY", "CURSOR_EXPIRED", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "CONFLICT",
+    "WITHDRAWAL_WAIVER_REQUIRED", "SOURCE_DOWN", "UPSTREAM_ERROR", "INTERNAL",
+    "CONFIGURATION", "CLOSED", "KEY_REVOKED", "ENTITLEMENTS_CHANGED", "TOO_MANY_CONNECTIONS", "PROTOCOL_ERROR", "BINARY_NOT_SUPPORTED",
+    "INVALID_UTF8", "MESSAGE_TOO_BIG", "ABORTED", "NETWORK_ERROR",
+]
+"""A code of `ERROR_CODES`. An HTTP error answer without a problem document has the code `HTTP_<status>` (e.g. `HTTP_502`)."""
+
+ERROR_CODES: tuple[ErrorCode, ...] = (
+    "INVALID_PARAMETERS", "UNKNOWN_INDICATOR", "UNKNOWN_INSTRUMENT", "NOT_COVERED", "WARMING", "QUOTA_EXCEEDED",
+    "RATE_LIMITED", "CAPACITY", "CURSOR_EXPIRED", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "CONFLICT",
+    "WITHDRAWAL_WAIVER_REQUIRED", "SOURCE_DOWN", "UPSTREAM_ERROR", "INTERNAL",
+    "CONFIGURATION", "CLOSED", "KEY_REVOKED", "ENTITLEMENTS_CHANGED", "TOO_MANY_CONNECTIONS", "PROTOCOL_ERROR", "BINARY_NOT_SUPPORTED",
+    "INVALID_UTF8", "MESSAGE_TOO_BIG", "ABORTED", "NETWORK_ERROR",
+)
+"""
+Stable error codes.
+
+Codes of the API (RFC 9457 `code`) and of the WebSocket `error` messages: INVALID_PARAMETERS to INTERNAL. FORBIDDEN covers
+the rights of the offers: historical data (queries, estimates, exports, `from:{time}`) needs the Historical offer, real time
+the Live offer. WITHDRAWAL_WAIVER_REQUIRED: a checkout without the waiver of the right of withdrawal.
+
+Codes raised by the SDK itself:
+- CONFIGURATION: invalid client options.
+- CLOSED: `subscribe()` on a stream closed by `close()`.
+- KEY_REVOKED: the gateway closed the connection (4003) because the API key was revoked.
+- ENTITLEMENTS_CHANGED: the gateway closed the connection (4003) because the account's rights no longer cover it (offer
+  ended, account suspended, subscription quota exceeded).
+- TOO_MANY_CONNECTIONS: the connection quota of the plan stayed reached (4029) for `Reconnect.quota_retry`.
+- PROTOCOL_ERROR, BINARY_NOT_SUPPORTED, INVALID_UTF8, MESSAGE_TOO_BIG: the gateway refused a message (close 1002, 1003,
+  1007, 1009); it would refuse it again, so the stream fails.
+- ABORTED: kept for the other SDKs (a call stopped by its signal); in Python a call is stopped by cancelling its task
+  (`asyncio.timeout()`, `Task.cancel()`), and the `asyncio.CancelledError` goes through untouched, as asyncio requires.
+- NETWORK_ERROR: the API could not be reached, or the connection was lost during an answer (DNS, refused or reset
+  connection, TLS); the error of httpx is the `__cause__`.
+- `HTTP_<status>` (e.g. `HTTP_502`): an HTTP error answer without a problem document.
+
+Every error the SDK raises or ends an iteration with is a `FathomChartsError`; the error it stems from, if any, is its `__cause__`.
+"""
+
+
+class ProblemFieldError(TypedDict):
+    """One invalid field of a request: JSON Pointer from the root of the body, and what is wrong with it."""
+
+    path: str
+    message: str
+
+
+class FathomChartsError(Exception):
+    """Error raised by the SDK: a stable code (`ErrorCode`), the HTTP status or WebSocket close code when known."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status: int | None = None,
+        close_code: int | None = None,
+        retry_after: float | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.close_code = close_code
+        self.retry_after = retry_after
+        self.problem = problem
+        """The RFC 9457 problem document of an HTTP error, with its `errors` (invalid fields, `ProblemFieldError`) when the API
+        gives them; None when the answer is not a problem document."""
+
+    def __repr__(self) -> str:
+        return f"FathomChartsError({self.code!r}, {self.message!r})"
+
+
+def api_key_problem(api_key: object) -> str | None:
+    """Why `api_key` cannot be used (an unset or empty environment variable, typically), or None."""
+    if api_key is None:
+        return "api_key is missing: is the variable holding the API key set?"
+    if not isinstance(api_key, str):
+        return f"api_key must be a string, not {type(api_key).__name__}"
+    if api_key.strip() == "":
+        return "api_key is an empty string: is the variable holding the API key set and not empty?"
+    return None