polars-fxmacrodata 0.1.0__py3-none-any.whl

polars_fxmacrodata/__init__.py

@@ -0,0 +1,6 @@
+"""FXMacroData's native Polars IO source."""
+
+from .io import operation_catalog, scan_fxmacrodata, source_schema
+
+__all__ = ["operation_catalog", "scan_fxmacrodata", "source_schema"]
+__version__ = "0.1.0"

polars_fxmacrodata/io.py

@@ -0,0 +1,127 @@
+"""Read public FXMacroData operations through the Polars scan interface."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Any, Iterator, Mapping
+
+import polars as pl
+from polars.io.plugins import register_io_source
+
+from fxmacrodata_platform_core import COLUMNS, operations, read, validate_request
+
+
+def source_schema() -> pl.Schema:
+    """Return the lossless, additive schema without fetching remote data."""
+    return pl.Schema({name: pl.Float64 if name == "value" else pl.String for name in COLUMNS})
+
+
+def operation_catalog() -> pl.DataFrame:
+    """Discover every supported REST operation and packaged MCP tool locally."""
+    rows = [
+        {
+            "name": operation.name,
+            "description": operation.description,
+            "method": operation.method,
+            "path": operation.path,
+            "input_schema_json": json.dumps(operation.input_schema, sort_keys=True),
+        }
+        for operation in operations()
+    ]
+    return pl.DataFrame(rows, schema={name: pl.String for name in (
+        "name", "description", "method", "path", "input_schema_json"
+    )})
+
+
+@dataclass(frozen=True)
+class _IOSource:
+    operation: str
+    arguments_json: str
+    api_key_env: str | None
+    complete_history: bool
+    max_pages: int
+
+    def __call__(
+        self,
+        with_columns: list[str] | None,
+        predicate: pl.Expr | None,
+        n_rows: int | None,
+        batch_size: int | None,
+    ) -> Iterator[pl.DataFrame]:
+        schema = source_schema()
+        columns = list(schema) if with_columns is None else with_columns
+        if n_rows == 0:
+            yield pl.DataFrame(schema=schema).select(columns)
+            return
+        batch = read(
+            self.operation,
+            json.loads(self.arguments_json),
+            api_key_env=self.api_key_env,
+            complete_history=self.complete_history,
+            max_pages=self.max_pages,
+        )
+        rows = iter(batch.rows())
+        size = batch_size if batch_size is not None and batch_size > 0 else 10_000
+        remaining = n_rows
+        emitted = False
+        while remaining is None or remaining > 0:
+            chunk = []
+            for _ in range(size):
+                try:
+                    chunk.append(next(rows))
+                except StopIteration:
+                    break
+            if not chunk:
+                break
+            frame = pl.DataFrame(chunk, schema=schema, strict=True)
+            # A pushed predicate may refer to a column excluded by the projection.
+            if predicate is not None:
+                frame = frame.filter(predicate)
+            if remaining is not None:
+                frame = frame.head(remaining)
+                remaining -= frame.height
+            frame = frame.select(columns)
+            if frame.height:
+                emitted = True
+                yield frame
+        if not emitted:
+            yield pl.DataFrame(schema=schema).select(columns)
+
+
+def scan_fxmacrodata(
+    operation: str,
+    arguments: Mapping[str, Any] | None = None,
+    *,
+    api_key_env: str | None = None,
+    complete_history: bool = True,
+    max_pages: int = 10_000,
+) -> pl.LazyFrame:
+    """Create a lazy scan; credentials are resolved only when it is collected.
+
+    ``api_key_env`` is an environment variable name, never an API key. Omitting
+    it explicitly uses anonymous access. Original records and response envelopes
+    remain available in ``record_json`` and ``response_json``.
+    """
+    if not isinstance(operation, str) or operation not in {item.name for item in operations()}:
+        raise ValueError("Unknown operation; inspect operation_catalog()['name']")
+    if not isinstance(max_pages, int) or isinstance(max_pages, bool) or max_pages < 1:
+        raise ValueError("max_pages must be a positive integer")
+    if api_key_env is not None and (
+        not isinstance(api_key_env, str)
+        or not api_key_env.isidentifier()
+        or not api_key_env.isascii()
+    ):
+        raise ValueError("api_key_env must be an environment variable name")
+    if arguments is not None and not isinstance(arguments, Mapping):
+        raise ValueError("arguments must be an object")
+    if not isinstance(complete_history, bool):
+        raise ValueError("complete_history must be a boolean")
+    source = _IOSource(
+        operation,
+        json.dumps(validate_request(operation, dict(arguments) if arguments is not None else None), allow_nan=False, sort_keys=True),
+        api_key_env,
+        complete_history,
+        max_pages,
+    )
+    return register_io_source(io_source=source, schema=source_schema())

polars_fxmacrodata-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: polars-fxmacrodata
+Version: 0.1.0
+Summary: Lazy Polars IO source for FXMacroData macroeconomic and market data
+Author-email: FXMacroData <info@fxmacrodata.com>
+License: MIT License
+        
+        Copyright (c) 2026 FXMacroData
+        
+        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.
+        
+Project-URL: Homepage, https://fxmacrodata.com/?utm_source=pypi&utm_medium=referral&utm_campaign=polars-fxmacrodata&utm_content=package
+Project-URL: Documentation, https://fxmacrodata.com/documentation/reference?utm_source=pypi&utm_medium=referral&utm_campaign=polars-fxmacrodata&utm_content=docs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: polars==1.38.1
+Requires-Dist: fxmacrodata-platform-core==0.1.0
+Dynamic: license-file
+
+# FXMacroData for Polars
+
+Query FXMacroData as a native Polars lazy IO source. Combine macroeconomic releases,
+FX, commodities, positioning and research data with your own datasets using the
+same expressions, joins and sinks as other Polars scans.
+
+[Explore FXMacroData](https://fxmacrodata.com/?utm_source=github&utm_medium=referral&utm_campaign=polars-fxmacrodata&utm_content=readme)
+
+## Install
+
+Install the `polars-fxmacrodata` wheel together with its
+`fxmacrodata-platform-core` and `fxmacrodata-public-client` dependencies. The Polars IO
+plugin API is unstable, so this package pins the supported Polars release.
+
+From the supplied packages directory:
+
+```sh
+python -m pip install ./fxmacrodata-public-client ./fxmacrodata-platform-core ./polars-fxmacrodata
+```
+
+```python
+import polars as pl
+from polars_fxmacrodata import operation_catalog, scan_fxmacrodata
+
+# Local discovery includes operation arguments and requires no remote request.
+print(operation_catalog().select("name", "description"))
+print(operation_catalog().filter(pl.col("name") == "indicator_history"))
+
+history = scan_fxmacrodata(
+    "indicator_history",
+    {"currency": "USD", "indicator": "policy_rate"},
+    api_key_env="FXMD_API_KEY",
+)
+result = (
+    history.filter(pl.col("value").is_not_null())
+    .select("date", "value", "record_json")
+    .collect()
+)
+```
+
+Set `FXMD_API_KEY` using your environment or secret manager. Pass its name through
+`api_key_env`; the source resolves its value when executing the query. Omitting
+`api_key_env` explicitly selects anonymous access. Credentials do not belong in
+arguments, notebooks, saved query plans or source control.
+
+`scan_fxmacrodata` builds a plan without making a request. `collect`, a sink, or
+another executing operation performs the read. Historical operations follow all
+pages by default; `complete_history=False` requests the supplied page only.
+`max_pages` defaults to 10,000 and raises on an incomplete history instead of
+silently truncating it. Normal API access and licence terms apply.
+
+## Add release context to portfolio positions
+
+Suppose `positions.parquet` contains `currency` and `position_usd` columns:
+
+```python
+calendar = scan_fxmacrodata(
+    "release_calendar", {"currency": "USD"}, api_key_env="FXMD_API_KEY"
+)
+positions = pl.scan_parquet("positions.parquet")
+exposure_by_event = (
+    calendar.filter(pl.col("announcement_datetime").is_not_null())
+    .select("currency", "indicator", "announcement_datetime", "record_json")
+    .join(positions, on="currency", how="inner")
+    .collect()
+)
+```
+
+Calendar times retain the API's original strings. Unknown publication times stay
+null. An observation's period date is not substituted for its release time.
+
+## Data and query semantics
+
+The fixed schema contains `operation`, `source_url`, `record_id`, `currency`,
+`indicator`, `date`, `announcement_datetime`, `value`, `value_text`, `record_json`
+and `response_json`. `value` is nullable Float64; other columns are nullable
+String. `record_json` preserves the original record and `response_json` preserves
+the complete response envelope, including metadata and revision information.
+Empty results retain an envelope row with a null record. Inspect `source_schema()`
+without fetching data.
+
+The scanner applies pushed predicates before column projection and honours the
+engine's row limit and batch-size hint. Predicates run in Polars and are not
+translated into different API filters. Supply documented operation arguments to
+reduce the remote dataset. The complete response is fetched before it is emitted
+in dataframe batches; a final `head()` limits the result, not the remote history
+request. Collecting the same plan again performs a fresh read.
+
+All public REST operations and packaged MCP tools are exposed through the
+operation catalog. MCP tool names have an `mcp_` prefix. Authentication and
+endpoint-specific access requirements remain those of the selected operation.
+
+## Development
+
+Run the offline source tests with `python -m pytest tests`. They exercise native
+Polars collection with fixture responses and never call the live service.

polars_fxmacrodata-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+polars_fxmacrodata/__init__.py,sha256=6efTQP5oH1BABm9I4MxsVXZFLZgH9YQIQdJki0dxen0,205
+polars_fxmacrodata/io.py,sha256=5W1un_yJ8WfHQxEsUCTWQbYkcMB2E58dC2FTiHUhuS0,4781
+polars_fxmacrodata/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+polars_fxmacrodata-0.1.0.dist-info/licenses/LICENSE,sha256=mLVV_vNUMbtObjBLP4s10Tc8K4m_5sbNJ96E169Td84,1089
+polars_fxmacrodata-0.1.0.dist-info/METADATA,sha256=2mGgGPOgfs9G9X63hRZh9URBfdFFinM81Clp1r-d-6g,6156
+polars_fxmacrodata-0.1.0.dist-info/WHEEL,sha256=16fc_9Rp854SLcdhaDEjr0u65p0e3FhZxihNgcnCE98,91
+polars_fxmacrodata-0.1.0.dist-info/top_level.txt,sha256=R-t9IQtKzdwpoJJBfsfXr5GLEkIGlD8iSsikjAM0Wxc,19
+polars_fxmacrodata-0.1.0.dist-info/RECORD,,

polars_fxmacrodata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

polars_fxmacrodata-0.1.0.dist-info/licenses/LICENSE

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

polars_fxmacrodata-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+polars_fxmacrodata