sqlite-fxmacrodata 0.1.0__tar.gz

sqlite_fxmacrodata-0.1.0/LICENSE

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

sqlite_fxmacrodata-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include PUBLIC_FILES.json
+include MANIFEST.in
+include src/fxmacrodata_sqlite/__init__.py
+include src/fxmacrodata_sqlite/py.typed
+include tests/test_loader.py
+include examples/event_study.sql
+global-exclude *.pyc *.pyo
+global-exclude __pycache__/*

sqlite_fxmacrodata-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: sqlite-fxmacrodata
+Version: 0.1.0
+Summary: Load public FXMacroData responses into SQLite
+License-Expression: MIT
+Project-URL: Documentation, https://fxmacrodata.com/documentation/reference?utm_source=pypi&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=package
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fxmacrodata-platform-core==0.1.0
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+Dynamic: license-file
+
+# FXMacroData for SQLite
+
+Load FXMacroData public responses into a SQLite database file with the Python
+standard library's `sqlite3` module. No third-party database driver is
+required, which makes this the simplest way to keep a local, queryable copy of
+macro announcements while retaining the source payload and revision metadata.
+
+[FXMacroData documentation](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=readme)
+
+## Install and connect
+
+Requires Python 3.10 or later. Install this package and its adjacent public
+client dependencies from the distribution supplied to you:
+
+```sh
+python -m pip install /path/to/fxmacrodata-public-client /path/to/fxmacrodata-platform-core /path/to/sqlite-fxmacrodata
+```
+
+Then load into a database file you own:
+
+```python
+import sqlite3
+from fxmacrodata_platform_core import read
+from fxmacrodata_sqlite import load
+
+with sqlite3.connect("fxmacrodata.db") as connection:
+    batch = read("indicator_history", {"currency": "usd", "indicator": "policy_rate"})
+    result = load(batch, connection, "fxmacrodata", batch_size=1000)
+```
+
+USD operations work without a key. For other currencies configure
+`FXMD_API_KEY` in your runtime secret store and pass
+`api_key_env="FXMD_API_KEY"` to `read` or `load_operation`.
+
+By default the loader creates the envelope table if absent. Set
+`create_table=False` to use a table you provisioned yourself;
+`create_table_sql(table)` returns the required DDL and `insert_sql(table)` the
+statement used for every block. Identifiers accept one or two simple names,
+such as `fxmacrodata` or `analytics.fxmacrodata` for an attached database, and
+are always double-quoted. Quoted names, SQL fragments and URL-like names are
+rejected.
+
+Every operation exposed by `fxmacrodata_platform_core.operations()` is available,
+including REST and MCP operations. The loader adds a tabular envelope without
+changing the original public response. `record_json` retains the original record;
+`response_json` retains the complete response, including pagination and metadata.
+An empty response produces one envelope with `record_json = 'null'`, so absence of
+data and the server's metadata remain inspectable. It is not an observation.
+
+Columns are `operation`, `source_url`, `record_id`, `currency`, `indicator`,
+`date`, `announcement_datetime`, `value`, `value_text`, `record_json`,
+`response_json`, and the loader's `content_hash`. Only `value` is numeric
+(`REAL`); everything else is `TEXT`. Dates and announcement times remain source
+strings. No publication time is inferred, and no missing value is filled.
+`value_text` and JSON preserve source numbers supplied as strings. JSON numeric
+tokens follow the public Python client parser, so original lexical precision is
+not guaranteed. SQLite's JSON functions (`json_extract`) work directly on the
+JSON columns.
+
+Select operations with the shared catalogue rather than constructing URLs:
+
+```python
+from fxmacrodata_platform_core import operations, schemas
+
+available = operations()
+input_schemas = schemas()
+```
+
+`load_operation` accepts `api_key_env`, `complete_history`, `max_pages`, and
+`client_factory` for the public source reader. `max_pages` bounds history
+pagination; an incomplete read raises an error before a destination load starts.
+`batch_size` bounds destination blocks to 1–10,000 rows. `max_batch_bytes` also
+bounds each block using a conservative JSON byte estimate (16 MiB by default,
+128 MiB maximum). An oversized individual envelope is rejected before destination
+changes; narrow the source date range to reduce the response size. The source
+response is materialized before loading; choose a source date range suitable for
+memory. Read the installed operation's schema for required arguments and date filters.
+
+Supply source credentials through your runtime secret store, exposing only the
+environment variable name to the adapter. The database file is opened by you;
+the adapter never chooses a path, saves or prints credentials.
+
+The package licence covers this adapter code. FXMacroData data access and onward
+redistribution remain subject to your subscription and applicable licence. Loading
+data into a database does not grant permission to publish or resell it.
+
+## Retries and querying
+
+The table's primary key is `(operation, record_id, content_hash)` and every
+block is inserted with `INSERT OR IGNORE` inside its own transaction. Retrying
+the same source batch is idempotent: identical envelopes are skipped, while
+changed record data or response metadata produces a distinct content hash and
+is retained alongside the earlier version.
+
+```sql
+SELECT currency, indicator, date, value,
+       json_extract(record_json, '$.publication_time_status') AS status
+FROM fxmacrodata
+WHERE record_json <> 'null';
+```
+
+Delivery is at-least-once with an idempotent key. Blocks are not retried
+automatically. On a failure the failing block is rolled back; earlier blocks
+are already committed, and retrying the same source batch is safe.
+`LoadResult.rows` counts envelopes submitted, rather than newly created rows.
+
+See [event_study.sql](examples/event_study.sql) for an announcement/price join.
+The example expects your own licensed market-price table and uses source
+announcement timestamps only. Timestamp presence alone is not evidence that a
+release had already been published; use source publication metadata when
+building a point-in-time backtest.
+
+## Development
+
+Tests are offline and use an in-memory database:
+
+```sh
+python -m pytest tests -q
+```
+
+Standard library reference:
+[sqlite3 documentation](https://docs.python.org/3/library/sqlite3.html?utm_source=pypi&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=upstream-reference).

sqlite_fxmacrodata-0.1.0/PUBLIC_FILES.json

@@ -0,0 +1,11 @@
+[
+  "LICENSE",
+  "README.md",
+  "pyproject.toml",
+  "PUBLIC_FILES.json",
+  "MANIFEST.in",
+  "src/fxmacrodata_sqlite/__init__.py",
+  "src/fxmacrodata_sqlite/py.typed",
+  "tests/test_loader.py",
+  "examples/event_study.sql"
+]

sqlite_fxmacrodata-0.1.0/README.md

@@ -0,0 +1,122 @@
+# FXMacroData for SQLite
+
+Load FXMacroData public responses into a SQLite database file with the Python
+standard library's `sqlite3` module. No third-party database driver is
+required, which makes this the simplest way to keep a local, queryable copy of
+macro announcements while retaining the source payload and revision metadata.
+
+[FXMacroData documentation](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=readme)
+
+## Install and connect
+
+Requires Python 3.10 or later. Install this package and its adjacent public
+client dependencies from the distribution supplied to you:
+
+```sh
+python -m pip install /path/to/fxmacrodata-public-client /path/to/fxmacrodata-platform-core /path/to/sqlite-fxmacrodata
+```
+
+Then load into a database file you own:
+
+```python
+import sqlite3
+from fxmacrodata_platform_core import read
+from fxmacrodata_sqlite import load
+
+with sqlite3.connect("fxmacrodata.db") as connection:
+    batch = read("indicator_history", {"currency": "usd", "indicator": "policy_rate"})
+    result = load(batch, connection, "fxmacrodata", batch_size=1000)
+```
+
+USD operations work without a key. For other currencies configure
+`FXMD_API_KEY` in your runtime secret store and pass
+`api_key_env="FXMD_API_KEY"` to `read` or `load_operation`.
+
+By default the loader creates the envelope table if absent. Set
+`create_table=False` to use a table you provisioned yourself;
+`create_table_sql(table)` returns the required DDL and `insert_sql(table)` the
+statement used for every block. Identifiers accept one or two simple names,
+such as `fxmacrodata` or `analytics.fxmacrodata` for an attached database, and
+are always double-quoted. Quoted names, SQL fragments and URL-like names are
+rejected.
+
+Every operation exposed by `fxmacrodata_platform_core.operations()` is available,
+including REST and MCP operations. The loader adds a tabular envelope without
+changing the original public response. `record_json` retains the original record;
+`response_json` retains the complete response, including pagination and metadata.
+An empty response produces one envelope with `record_json = 'null'`, so absence of
+data and the server's metadata remain inspectable. It is not an observation.
+
+Columns are `operation`, `source_url`, `record_id`, `currency`, `indicator`,
+`date`, `announcement_datetime`, `value`, `value_text`, `record_json`,
+`response_json`, and the loader's `content_hash`. Only `value` is numeric
+(`REAL`); everything else is `TEXT`. Dates and announcement times remain source
+strings. No publication time is inferred, and no missing value is filled.
+`value_text` and JSON preserve source numbers supplied as strings. JSON numeric
+tokens follow the public Python client parser, so original lexical precision is
+not guaranteed. SQLite's JSON functions (`json_extract`) work directly on the
+JSON columns.
+
+Select operations with the shared catalogue rather than constructing URLs:
+
+```python
+from fxmacrodata_platform_core import operations, schemas
+
+available = operations()
+input_schemas = schemas()
+```
+
+`load_operation` accepts `api_key_env`, `complete_history`, `max_pages`, and
+`client_factory` for the public source reader. `max_pages` bounds history
+pagination; an incomplete read raises an error before a destination load starts.
+`batch_size` bounds destination blocks to 1–10,000 rows. `max_batch_bytes` also
+bounds each block using a conservative JSON byte estimate (16 MiB by default,
+128 MiB maximum). An oversized individual envelope is rejected before destination
+changes; narrow the source date range to reduce the response size. The source
+response is materialized before loading; choose a source date range suitable for
+memory. Read the installed operation's schema for required arguments and date filters.
+
+Supply source credentials through your runtime secret store, exposing only the
+environment variable name to the adapter. The database file is opened by you;
+the adapter never chooses a path, saves or prints credentials.
+
+The package licence covers this adapter code. FXMacroData data access and onward
+redistribution remain subject to your subscription and applicable licence. Loading
+data into a database does not grant permission to publish or resell it.
+
+## Retries and querying
+
+The table's primary key is `(operation, record_id, content_hash)` and every
+block is inserted with `INSERT OR IGNORE` inside its own transaction. Retrying
+the same source batch is idempotent: identical envelopes are skipped, while
+changed record data or response metadata produces a distinct content hash and
+is retained alongside the earlier version.
+
+```sql
+SELECT currency, indicator, date, value,
+       json_extract(record_json, '$.publication_time_status') AS status
+FROM fxmacrodata
+WHERE record_json <> 'null';
+```
+
+Delivery is at-least-once with an idempotent key. Blocks are not retried
+automatically. On a failure the failing block is rolled back; earlier blocks
+are already committed, and retrying the same source batch is safe.
+`LoadResult.rows` counts envelopes submitted, rather than newly created rows.
+
+See [event_study.sql](examples/event_study.sql) for an announcement/price join.
+The example expects your own licensed market-price table and uses source
+announcement timestamps only. Timestamp presence alone is not evidence that a
+release had already been published; use source publication metadata when
+building a point-in-time backtest.
+
+## Development
+
+Tests are offline and use an in-memory database:
+
+```sh
+python -m pytest tests -q
+```
+
+Standard library reference:
+[sqlite3 documentation](https://docs.python.org/3/library/sqlite3.html?utm_source=pypi&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=upstream-reference).

sqlite_fxmacrodata-0.1.0/examples/event_study.sql

@@ -0,0 +1,26 @@
+-- Requires loaded announcement envelopes and your market_prices(currency, ts, close),
+-- where ts is an ISO-8601 UTC text timestamp comparable with announcement_datetime.
+-- This uses announcement times, not inferred publication times.
+-- Inspect publisher/publication metadata before using results in a point-in-time backtest.
+WITH events AS (
+    SELECT DISTINCT record_id, currency, announcement_datetime AS event_time
+    FROM fxmacrodata
+    WHERE announcement_datetime IS NOT NULL AND record_json <> 'null'
+), windows AS (
+    SELECT e.record_id, e.currency, e.event_time,
+           (SELECT p.close FROM market_prices p
+             WHERE p.currency = e.currency
+               AND p.ts <= e.event_time
+               AND p.ts >= datetime(e.event_time, '-5 minutes')
+             ORDER BY p.ts DESC LIMIT 1) AS pre_price,
+           (SELECT p.close FROM market_prices p
+             WHERE p.currency = e.currency
+               AND p.ts >= datetime(e.event_time, '+5 minutes')
+               AND p.ts <= datetime(e.event_time, '+10 minutes')
+             ORDER BY p.ts ASC LIMIT 1) AS post_price
+    FROM events e
+)
+SELECT record_id, currency, event_time, pre_price, post_price,
+       (post_price / NULLIF(pre_price, 0) - 1) * 100 AS return_pct
+FROM windows
+WHERE pre_price IS NOT NULL AND post_price IS NOT NULL;

sqlite_fxmacrodata-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlite-fxmacrodata"
+version = "0.1.0"
+description = "Load public FXMacroData responses into SQLite"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["fxmacrodata-platform-core==0.1.0"]
+
+[project.urls]
+Documentation = "https://fxmacrodata.com/documentation/reference?utm_source=pypi&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=package"
+
+[project.optional-dependencies]
+test = ["pytest>=8,<9"]
+
+[tool.setuptools]
+packages = ["fxmacrodata_sqlite"]
+package-dir = {"" = "src"}
+include-package-data = false
+
+[tool.setuptools.package-data]
+fxmacrodata_sqlite = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

sqlite_fxmacrodata-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sqlite_fxmacrodata-0.1.0/src/fxmacrodata_sqlite/__init__.py

@@ -0,0 +1,158 @@
+"""Load public FXMacroData responses into a customer-owned SQLite table."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+import math
+import re
+from typing import Any
+
+from fxmacrodata_platform_core import read
+
+__version__ = "0.1.0"
+
+COLUMNS = (
+    "operation", "source_url", "record_id", "currency", "indicator", "date",
+    "announcement_datetime", "value", "value_text", "record_json", "response_json",
+    "content_hash",
+)
+TYPES = tuple(
+    "REAL" if name == "value" else
+    "TEXT NOT NULL" if name in {"operation", "record_id", "content_hash"} else "TEXT"
+    for name in COLUMNS
+)
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]{0,127}\Z")
+
+
+class LoadError(RuntimeError):
+    """A destination operation failed; inspect the destination before retrying."""
+
+
+@dataclass(frozen=True)
+class LoadResult:
+    table: str
+    rows: int
+    batches: int
+
+
+def _table(table: str) -> tuple[str, str]:
+    if not isinstance(table, str):
+        raise ValueError("table must be a schema.table or table identifier")
+    parts = table.split(".")
+    if not 1 <= len(parts) <= 2 or any(not _IDENTIFIER.fullmatch(p) for p in parts):
+        raise ValueError("table must contain one or two simple SQL identifiers")
+    return ".".join(parts), ".".join(f'"{p}"' for p in parts)
+
+
+def _rows(batch: Any) -> list[dict[str, Any]]:
+    rows = []
+    for source in batch.rows():
+        row = {name: source.get(name) for name in COLUMNS[:-1]}
+        if not isinstance(row["operation"], str) or not isinstance(row["record_id"], str):
+            raise ValueError("every row requires string operation and record_id")
+        for name, value in row.items():
+            if name == "value":
+                if value is not None and (
+                    isinstance(value, bool) or not isinstance(value, (int, float)) or
+                    not math.isfinite(value)
+                ):
+                    raise ValueError("value must be a finite number or null")
+            elif value is not None and not isinstance(value, str):
+                raise ValueError(f"{name} must be a string or null")
+        encoded = json.dumps(row, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        row["content_hash"] = hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+        rows.append(row)
+    return rows
+
+
+def create_table_sql(table: str) -> str:
+    """Return DDL for a lossless envelope table keyed for idempotent retries."""
+    _, quoted = _table(table)
+    fields = ",\n    ".join(f'"{name}" {kind}' for name, kind in zip(COLUMNS, TYPES))
+    return (
+        f"CREATE TABLE IF NOT EXISTS {quoted} (\n    {fields},\n"
+        '    PRIMARY KEY ("operation", "record_id", "content_hash")\n)'
+    )
+
+
+def insert_sql(table: str) -> str:
+    """Return the idempotent INSERT statement used for every block."""
+    _, quoted = _table(table)
+    names = ", ".join(f'"{name}"' for name in COLUMNS)
+    placeholders = ", ".join("?" for _ in COLUMNS)
+    return f"INSERT OR IGNORE INTO {quoted} ({names}) VALUES ({placeholders})"
+
+
+def _blocks(rows: list[dict[str, Any]], batch_size: int, max_batch_bytes: int) -> list[list[dict[str, Any]]]:
+    if isinstance(batch_size, bool) or not isinstance(batch_size, int) or not 1 <= batch_size <= 10000:
+        raise ValueError("batch_size must be an integer between 1 and 10000")
+    if isinstance(max_batch_bytes, bool) or not isinstance(max_batch_bytes, int) or not 1 <= max_batch_bytes <= 128 * 1024 * 1024:
+        raise ValueError("max_batch_bytes must be an integer between 1 and 134217728")
+    output, block, size = [], [], 0
+    for row in rows:
+        length = len(json.dumps(row, ensure_ascii=True).encode("utf-8")) + 2
+        if length > max_batch_bytes:
+            raise ValueError("one envelope exceeds max_batch_bytes; narrow the source date range")
+        if block and (len(block) >= batch_size or size + length > max_batch_bytes):
+            output.append(block)
+            block, size = [], 0
+        block.append(row)
+        size += length
+    if block:
+        output.append(block)
+    return output
+
+
+def load(batch: Any, connection: Any, table: str, *, batch_size: int = 1000,
+         max_batch_bytes: int = 16 * 1024 * 1024, create_table: bool = True) -> LoadResult:
+    """Insert bounded blocks through a ``sqlite3.Connection``, one transaction per block.
+
+    Every block is an ``INSERT OR IGNORE`` on the envelope primary key, so
+    retrying the same source batch stores nothing twice. A failed block is
+    rolled back and never retried automatically.
+    """
+    table, _ = _table(table)
+    if isinstance(batch_size, bool) or not isinstance(batch_size, int) or not 1 <= batch_size <= 10000:
+        raise ValueError("batch_size must be an integer between 1 and 10000")
+    rows = _rows(batch)
+    blocks = _blocks(rows, batch_size, max_batch_bytes)
+    if create_table:
+        try:
+            with connection:
+                connection.execute(create_table_sql(table))
+        except Exception:
+            raise LoadError("SQLite table setup failed") from None
+    statement = insert_sql(table)
+    count = 0
+    for block in blocks:
+        try:
+            with connection:
+                connection.executemany(statement, [tuple(row[name] for name in COLUMNS) for row in block])
+        except Exception:
+            raise LoadError(
+                f"SQLite insert block {count + 1} failed and was rolled back; earlier blocks "
+                "are committed. Inspect the destination; retrying the same batch is idempotent."
+            ) from None
+        count += 1
+    return LoadResult(table, len(rows), count)
+
+
+def load_operation(operation: str, args: dict[str, Any] | None, connection: Any, table: str,
+                   *, api_key_env: str | None = None, complete_history: bool = True,
+                   max_pages: int = 10000, client_factory: Any = None,
+                   batch_size: int = 1000, max_batch_bytes: int = 16 * 1024 * 1024,
+                   create_table: bool = True) -> LoadResult:
+    """Read one public operation and load its complete response envelope."""
+    _table(table)
+    _blocks([], batch_size, max_batch_bytes)
+    batch = read(operation, args, api_key_env=api_key_env,
+                 complete_history=complete_history, max_pages=max_pages,
+                 client_factory=client_factory)
+    return load(batch, connection, table, batch_size=batch_size,
+                max_batch_bytes=max_batch_bytes, create_table=create_table)
+
+
+__all__ = ["COLUMNS", "TYPES", "LoadError", "LoadResult", "create_table_sql", "insert_sql",
+           "load", "load_operation"]

sqlite_fxmacrodata-0.1.0/src/sqlite_fxmacrodata.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: sqlite-fxmacrodata
+Version: 0.1.0
+Summary: Load public FXMacroData responses into SQLite
+License-Expression: MIT
+Project-URL: Documentation, https://fxmacrodata.com/documentation/reference?utm_source=pypi&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=package
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fxmacrodata-platform-core==0.1.0
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+Dynamic: license-file
+
+# FXMacroData for SQLite
+
+Load FXMacroData public responses into a SQLite database file with the Python
+standard library's `sqlite3` module. No third-party database driver is
+required, which makes this the simplest way to keep a local, queryable copy of
+macro announcements while retaining the source payload and revision metadata.
+
+[FXMacroData documentation](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=readme)
+
+## Install and connect
+
+Requires Python 3.10 or later. Install this package and its adjacent public
+client dependencies from the distribution supplied to you:
+
+```sh
+python -m pip install /path/to/fxmacrodata-public-client /path/to/fxmacrodata-platform-core /path/to/sqlite-fxmacrodata
+```
+
+Then load into a database file you own:
+
+```python
+import sqlite3
+from fxmacrodata_platform_core import read
+from fxmacrodata_sqlite import load
+
+with sqlite3.connect("fxmacrodata.db") as connection:
+    batch = read("indicator_history", {"currency": "usd", "indicator": "policy_rate"})
+    result = load(batch, connection, "fxmacrodata", batch_size=1000)
+```
+
+USD operations work without a key. For other currencies configure
+`FXMD_API_KEY` in your runtime secret store and pass
+`api_key_env="FXMD_API_KEY"` to `read` or `load_operation`.
+
+By default the loader creates the envelope table if absent. Set
+`create_table=False` to use a table you provisioned yourself;
+`create_table_sql(table)` returns the required DDL and `insert_sql(table)` the
+statement used for every block. Identifiers accept one or two simple names,
+such as `fxmacrodata` or `analytics.fxmacrodata` for an attached database, and
+are always double-quoted. Quoted names, SQL fragments and URL-like names are
+rejected.
+
+Every operation exposed by `fxmacrodata_platform_core.operations()` is available,
+including REST and MCP operations. The loader adds a tabular envelope without
+changing the original public response. `record_json` retains the original record;
+`response_json` retains the complete response, including pagination and metadata.
+An empty response produces one envelope with `record_json = 'null'`, so absence of
+data and the server's metadata remain inspectable. It is not an observation.
+
+Columns are `operation`, `source_url`, `record_id`, `currency`, `indicator`,
+`date`, `announcement_datetime`, `value`, `value_text`, `record_json`,
+`response_json`, and the loader's `content_hash`. Only `value` is numeric
+(`REAL`); everything else is `TEXT`. Dates and announcement times remain source
+strings. No publication time is inferred, and no missing value is filled.
+`value_text` and JSON preserve source numbers supplied as strings. JSON numeric
+tokens follow the public Python client parser, so original lexical precision is
+not guaranteed. SQLite's JSON functions (`json_extract`) work directly on the
+JSON columns.
+
+Select operations with the shared catalogue rather than constructing URLs:
+
+```python
+from fxmacrodata_platform_core import operations, schemas
+
+available = operations()
+input_schemas = schemas()
+```
+
+`load_operation` accepts `api_key_env`, `complete_history`, `max_pages`, and
+`client_factory` for the public source reader. `max_pages` bounds history
+pagination; an incomplete read raises an error before a destination load starts.
+`batch_size` bounds destination blocks to 1–10,000 rows. `max_batch_bytes` also
+bounds each block using a conservative JSON byte estimate (16 MiB by default,
+128 MiB maximum). An oversized individual envelope is rejected before destination
+changes; narrow the source date range to reduce the response size. The source
+response is materialized before loading; choose a source date range suitable for
+memory. Read the installed operation's schema for required arguments and date filters.
+
+Supply source credentials through your runtime secret store, exposing only the
+environment variable name to the adapter. The database file is opened by you;
+the adapter never chooses a path, saves or prints credentials.
+
+The package licence covers this adapter code. FXMacroData data access and onward
+redistribution remain subject to your subscription and applicable licence. Loading
+data into a database does not grant permission to publish or resell it.
+
+## Retries and querying
+
+The table's primary key is `(operation, record_id, content_hash)` and every
+block is inserted with `INSERT OR IGNORE` inside its own transaction. Retrying
+the same source batch is idempotent: identical envelopes are skipped, while
+changed record data or response metadata produces a distinct content hash and
+is retained alongside the earlier version.
+
+```sql
+SELECT currency, indicator, date, value,
+       json_extract(record_json, '$.publication_time_status') AS status
+FROM fxmacrodata
+WHERE record_json <> 'null';
+```
+
+Delivery is at-least-once with an idempotent key. Blocks are not retried
+automatically. On a failure the failing block is rolled back; earlier blocks
+are already committed, and retrying the same source batch is safe.
+`LoadResult.rows` counts envelopes submitted, rather than newly created rows.
+
+See [event_study.sql](examples/event_study.sql) for an announcement/price join.
+The example expects your own licensed market-price table and uses source
+announcement timestamps only. Timestamp presence alone is not evidence that a
+release had already been published; use source publication metadata when
+building a point-in-time backtest.
+
+## Development
+
+Tests are offline and use an in-memory database:
+
+```sh
+python -m pytest tests -q
+```
+
+Standard library reference:
+[sqlite3 documentation](https://docs.python.org/3/library/sqlite3.html?utm_source=pypi&utm_medium=referral&utm_campaign=sqlite-fxmacrodata&utm_content=upstream-reference).

sqlite_fxmacrodata-0.1.0/src/sqlite_fxmacrodata.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+PUBLIC_FILES.json
+README.md
+pyproject.toml
+examples/event_study.sql
+src/fxmacrodata_sqlite/__init__.py
+src/fxmacrodata_sqlite/py.typed
+src/sqlite_fxmacrodata.egg-info/PKG-INFO
+src/sqlite_fxmacrodata.egg-info/SOURCES.txt
+src/sqlite_fxmacrodata.egg-info/dependency_links.txt
+src/sqlite_fxmacrodata.egg-info/requires.txt
+src/sqlite_fxmacrodata.egg-info/top_level.txt
+tests/test_loader.py

sqlite_fxmacrodata-0.1.0/src/sqlite_fxmacrodata.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sqlite_fxmacrodata-0.1.0/src/sqlite_fxmacrodata.egg-info/requires.txt

@@ -0,0 +1,4 @@
+fxmacrodata-platform-core==0.1.0
+
+[test]
+pytest<9,>=8

sqlite_fxmacrodata-0.1.0/src/sqlite_fxmacrodata.egg-info/top_level.txt

@@ -0,0 +1 @@
+fxmacrodata_sqlite

sqlite_fxmacrodata-0.1.0/tests/test_loader.py

@@ -0,0 +1,170 @@
+import json
+import sqlite3
+
+import pytest
+
+from fxmacrodata_platform_core import Batch
+import fxmacrodata_sqlite as adapter
+
+
+def batch(count=3, metadata=None):
+    return Batch("indicator_history", {
+        "data": [{"currency": "USD", "indicator": "policy_rate", "value": str(i),
+                  "date": "2026-10-01", "publication_time_status": "unknown"}
+                 for i in range(count)],
+        "metadata": metadata or {"revision": 1},
+    })
+
+
+@pytest.fixture
+def connection():
+    with sqlite3.connect(":memory:") as db:
+        yield db
+
+
+def stored(connection, table="fxmacrodata"):
+    names = ", ".join(f'"{n}"' for n in adapter.COLUMNS)
+    cursor = connection.execute(f'SELECT {names} FROM "{table}" ORDER BY "value_text"')
+    return [dict(zip(adapter.COLUMNS, row)) for row in cursor.fetchall()]
+
+
+def test_rows_round_trip_through_a_real_connection(connection):
+    source = batch()
+    result = adapter.load(source, connection, "fxmacrodata", batch_size=2)
+    assert (result.rows, result.batches) == (3, 2)
+    rows = stored(connection)
+    assert len(rows) == 3
+    row = rows[0]
+    assert row["operation"] == "indicator_history"
+    assert row["date"] == "2026-10-01"
+    assert row["announcement_datetime"] is None
+    assert row["value"] == 0.0 and isinstance(row["value"], float)
+    assert row["value_text"] == "0"
+    assert json.loads(row["record_json"])["publication_time_status"] == "unknown"
+    assert json.loads(row["response_json"]) == source.payload
+    assert len(row["content_hash"]) == 64
+    columns = {c[1]: c for c in connection.execute('PRAGMA table_info("fxmacrodata")')}
+    assert columns["value"][2] == "REAL" and columns["record_id"][3] == 1
+    assert [c[1] for c in sorted(columns.values(), key=lambda c: c[5]) if c[5]] == ["operation", "record_id", "content_hash"]
+
+
+def test_empty_response_is_a_metadata_envelope_not_an_observation(connection):
+    source = batch(0)
+    result = adapter.load(source, connection, "fxmacrodata")
+    rows = stored(connection)
+    assert result.rows == 1 and len(rows) == 1
+    assert rows[0]["record_json"] == "null"
+    assert rows[0]["value"] is None and rows[0]["date"] is None
+    assert json.loads(rows[0]["response_json"]) == source.payload
+
+
+def test_retry_is_idempotent_and_changed_metadata_adds_a_row(connection):
+    adapter.load(batch(1), connection, "fxmacrodata")
+    adapter.load(batch(1), connection, "fxmacrodata")
+    assert len(stored(connection)) == 1
+    adapter.load(batch(1, {"revision": 2}), connection, "fxmacrodata")
+    rows = stored(connection)
+    assert len(rows) == 2
+    assert rows[0]["record_id"] == rows[1]["record_id"]
+    assert rows[0]["content_hash"] != rows[1]["content_hash"]
+
+
+def test_schema_qualified_table_is_quoted(connection):
+    connection.execute("ATTACH DATABASE ':memory:' AS analytics")
+    adapter.load(batch(2), connection, "analytics.fxmacrodata")
+    count = connection.execute('SELECT COUNT(*) FROM "analytics"."fxmacrodata"').fetchone()[0]
+    assert count == 2
+    assert 'CREATE TABLE IF NOT EXISTS "analytics"."fxmacrodata"' in adapter.create_table_sql("analytics.fxmacrodata")
+    assert adapter.insert_sql("fxmacrodata").startswith('INSERT OR IGNORE INTO "fxmacrodata" (')
+
+
+@pytest.mark.parametrize("table", ['t"; DROP TABLE t; --', "a.b.c", "https://host/table", 'a."b"', "a b", "", None])
+def test_bad_identifiers_never_execute(connection, table):
+    with pytest.raises(ValueError):
+        adapter.load(batch(), connection, table)
+    assert connection.execute("SELECT COUNT(*) FROM sqlite_master").fetchone()[0] == 0
+
+
+@pytest.mark.parametrize("size", [0, -1, 10001, True, 2.5])
+def test_batch_bounds(connection, size):
+    with pytest.raises(ValueError):
+        adapter.load(batch(), connection, "fxmacrodata", batch_size=size)
+    assert connection.execute("SELECT COUNT(*) FROM sqlite_master").fetchone()[0] == 0
+
+
+def test_failed_block_is_rolled_back_not_retried_or_exposed(connection):
+    class Failing:
+        def __init__(self, inner, fail_block):
+            self.inner, self.fail_block, self.blocks = inner, fail_block, 0
+
+        def __enter__(self):
+            return self.inner.__enter__()
+
+        def __exit__(self, *args):
+            return self.inner.__exit__(*args)
+
+        def execute(self, *args):
+            return self.inner.execute(*args)
+
+        def executemany(self, sql, params):
+            self.blocks += 1
+            self.inner.executemany(sql, params)
+            if self.blocks == self.fail_block:
+                raise RuntimeError("private destination diagnostic")
+
+    wrapped = Failing(connection, 2)
+    with pytest.raises(adapter.LoadError) as error:
+        adapter.load(batch(), wrapped, "fxmacrodata", batch_size=1)
+    assert "block 2" in str(error.value)
+    assert "private destination diagnostic" not in str(error.value)
+    assert wrapped.blocks == 2
+    assert len(stored(connection)) == 1
+
+
+def test_preprovisioned_table_skips_ddl(connection):
+    with pytest.raises(adapter.LoadError):
+        adapter.load(batch(1), connection, "fxmacrodata", create_table=False)
+    connection.execute(adapter.create_table_sql("fxmacrodata"))
+    adapter.load(batch(1), connection, "fxmacrodata", create_table=False)
+    assert len(stored(connection)) == 1
+
+
+def test_operation_forwards_public_reader_options(monkeypatch, connection):
+    calls = []
+    monkeypatch.setattr(adapter, "read", lambda *args, **kw: calls.append((args, kw)) or batch(1))
+    factory = object()
+    adapter.load_operation("indicator_history", {"currency": "usd", "indicator": "policy_rate"},
+                           connection, "fxmacrodata", api_key_env="FXMD_API_KEY",
+                           max_pages=12, client_factory=factory)
+    assert calls[0][1] == dict(api_key_env="FXMD_API_KEY", complete_history=True,
+                                max_pages=12, client_factory=factory)
+    assert len(stored(connection)) == 1
+
+
+def test_credential_arguments_are_rejected_by_the_reader(connection):
+    from fxmacrodata_platform_core import IntegrationError
+    with pytest.raises(IntegrationError):
+        adapter.load_operation("indicator_history",
+                               {"currency": "usd", "indicator": "policy_rate", "api_key": "x"},
+                               connection, "fxmacrodata")
+
+
+def test_byte_limit_splits_blocks_and_rejects_oversized_envelopes_before_ddl(connection):
+    source = batch()
+    budget = max(len(json.dumps(r, ensure_ascii=True).encode()) + 2 for r in adapter._rows(source))
+    result = adapter.load(source, connection, "fxmacrodata", batch_size=100, max_batch_bytes=budget)
+    assert result.batches == 3
+    with sqlite3.connect(":memory:") as untouched:
+        with pytest.raises(ValueError, match="narrow the source date range"):
+            adapter.load(source, untouched, "fxmacrodata", max_batch_bytes=1)
+        assert untouched.execute("SELECT COUNT(*) FROM sqlite_master").fetchone()[0] == 0
+
+
+def test_invalid_loader_configuration_never_reads_source(monkeypatch, connection):
+    def unexpected(*args, **kwargs):
+        pytest.fail("source must not be called for invalid loader configuration")
+    monkeypatch.setattr(adapter, "read", unexpected)
+    for options in ({"batch_size": 0}, {"max_batch_bytes": 0}, {"table": "a.b.c"}):
+        with pytest.raises(ValueError):
+            adapter.load_operation("release_calendar", {"currency": "usd"}, connection,
+                                   **{"table": "fxmacrodata", **options})