macrotap 0.1.0__tar.gz

macrotap-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__
+.pytype
+
+.DS_Store
+.idea/
+dist/
+
+.ipynb*
+*.zip
+.obsidian
+sandbox
+session
+

macrotap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Iris Solutions Team
+
+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.

macrotap-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: macrotap
+Version: 0.1.0
+Summary: Quick and easy access to macroeconomic data from public providers
+Project-URL: Homepage, https://github.com/iris-solutions-team/macrotap
+Project-URL: Documentation, https://iris-solutions-team.github.io/macrotap-pages
+Project-URL: Bug Tracker, https://github.com/iris-solutions-team/macrotap/issues
+Author-email: Jaromir Benes <jaromir.benes@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: API,data,finance,macroeconomics,public
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: datapie>=0.3.0
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+
+# MacroTap
+
+

macrotap-0.1.0/README.md

@@ -0,0 +1,4 @@
+
+# MacroTap
+
+

macrotap-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = [ "hatchling",]
+build-backend = "hatchling.build"
+
+[project]
+name = "macrotap"
+version = "0.1.0"
+description = "Quick and easy access to macroeconomic data from public providers"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent",]
+keywords = [ "macroeconomics", "finance", "data", "API", "public",]
+dependencies = [ "datapie >= 0.3.0", "requests >= 2.32.5",]
+[[project.authors]]
+name = "Jaromir Benes"
+email = "jaromir.benes@gmail.com"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/iris-solutions-team/macrotap"
+Documentation = "https://iris-solutions-team.github.io/macrotap-pages"
+"Bug Tracker" = "https://github.com/iris-solutions-team/macrotap/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = [ "src/macrotap",]
+
+[tool.hatch.build.targets.sdist]
+include = [ "src/macrotap", "README.md", "LICENSE",]

macrotap-0.1.0/src/macrotap/__init__.py

@@ -0,0 +1,15 @@
+r"""
+"""
+
+
+from .fred import *
+from .fred import __all__ as all_fred
+
+from .imf import *
+from .imf import __all__ as all_imf
+
+__all__ = (
+    *all_fred,
+    *all_imf,
+)
+

macrotap-0.1.0/src/macrotap/fred/__init__.py

@@ -0,0 +1,5 @@
+
+from .main import from_fred
+
+__all__ = ("from_fred", )
+

macrotap-0.1.0/src/macrotap/fred/main.py

@@ -0,0 +1,154 @@
+"""
+"""
+
+
+#[
+
+from __future__ import annotations
+
+# Typing imports
+from typing import Iterable, Any
+
+# Third-party imports
+import requests as _rq
+import datapie as _ap
+
+#]
+
+
+_FRED_FREQ_MAP = {
+    "A".casefold(): _ap.Frequency.YEARLY,
+    "Q".casefold(): _ap.Frequency.QUARTERLY,
+    "M".casefold(): _ap.Frequency.MONTHLY,
+    "D".casefold(): _ap.Frequency.DAILY,
+}
+
+
+_BASE_URL = r"https://api.stlouisfed.org/fred/series"
+_OBSERVATIONS_URL = _BASE_URL + r"/observations"
+_API_KEY = r"951f01181da86ccb9045ce8716f82f43"
+_PARAMETERS = r"?series_id={series_id}&api_key={api_key}&file_type=json"
+_MISSING_VALUE = r"."
+
+
+def from_fred(
+    request_strings: str | Iterable[str],
+    return_info: bool = False,
+) -> _ap.Databox:
+    r"""
+................................................................................
+
+==Download time series from FRED (St Louis Fed Database)==
+
+This method downloads time series data from the FRED database. The data is
+downloaded using the FRED API. The method requires an API key, which is provided
+by the FRED website. The API key is stored in the `_API_KEY` variable in the
+`_fred.py` module. The method downloads the data for the specified series IDs
+and returns a `Databox` object with the downloaded series.
+
+db = Databox.from_fred(
+    request_strings,
+)
+
+
+### Input arguments ###
+
+???+ input "request_strings"
+    A list or dictionary of series IDs to download from FRED. If a dictionary is
+    provided, the keys are used as the FRED codes and the values are used for
+    the names of the time series in the Databox. If list of strings is provided,
+    the series IDs are used as the names of the series in the `Databox` object.
+
+
+### Returns ###
+
+???+ returns "db"
+    A `Databox` object containing the downloaded time series data.
+
+................................................................................
+    """
+    #[
+    if isinstance(request_strings, str):
+        request_strings = (request_strings, )
+    #
+    output_db = _ap.Databox()
+    info = []
+    for i in request_strings:
+        output_db[i], current_info, = _get_series(i, )
+        if return_info:
+            info.append(current_info)
+    #
+    if return_info:
+        return output_db, info,
+    #
+    return output_db
+    #}
+
+
+def _request_from_series_ids(series_ids: Iterable[str], ):
+    """
+    """
+    #[
+    return {
+        series_id.strip(): series_id.strip()
+        for series_id in series_ids
+    }
+    #]
+
+
+def _get_series(series_id: str, ) -> tuple[_ap.Series, dict[str, Any]]:
+    """
+    """
+    #[
+    urls = _get_series_urls(series_id, )
+    meta_response = _rq.get(urls["meta_url"], ).json()
+    data_response = _rq.get(urls["data_url"], ).json()
+    #
+    if "seriess" not in meta_response or "observations" not in data_response:
+        raise ValueError(f"Invalid response from FRED API for {series_id}", )
+    #
+    freq = _get_freq_from_meta_response(meta_response, )
+    iso_dates, str_values = _get_dates_and_values_from_data_response(data_response, )
+    values = tuple( (float(x) if x != _MISSING_VALUE else None) for x in str_values )
+    dates = _ap.periods_from_iso_strings(iso_dates, frequency=freq, )
+    info = {
+        "meta_url": urls["meta_url"],
+        "data_url": urls["data_url"],
+        "meta_response": meta_response,
+        "data_response": data_response,
+    }
+    return _ap.Series(periods=dates, values=values, ), info,
+    #]
+
+
+def _get_freq_from_meta_response(meta_response: dict, ):
+    """
+    """
+    #[
+    freq_letter = meta_response["seriess"][0]["frequency_short"].casefold()
+    return _FRED_FREQ_MAP[freq_letter]
+    #]
+
+
+def _get_dates_and_values_from_data_response(data_response: dict, ):
+    """
+    """
+    #[
+    date_value_pairs = (
+        (obs["date"], obs["value"], )
+        for obs in data_response["observations"]
+    )
+    return zip(*date_value_pairs, )
+    #]
+
+
+def _get_series_urls(series_id: str, ):
+    """
+    """
+    #[
+    parameters = _PARAMETERS.format(series_id=series_id, api_key=_API_KEY, )
+    meta_url = _BASE_URL + parameters
+    data_url = _OBSERVATIONS_URL + parameters
+    return {"meta_url": meta_url, "data_url": data_url, }
+    #]
+

macrotap-0.1.0/src/macrotap/imf/__init__.py

@@ -0,0 +1,4 @@
+
+from .main import from_imf
+
+__all__ = ("from_imf", )

macrotap-0.1.0/src/macrotap/imf/_imf_requests.py

@@ -0,0 +1,178 @@
+
+#[
+
+from __future__ import annotations
+
+# Typing imports
+from typing import Any, Callable
+
+# Standard library imports
+import itertools as _it
+import dataclasses as _dc
+import time as _ti
+
+# Typing imports
+from collections.abc import Iterable
+
+#]
+
+
+DATA_FLOW_SEPARATOR = "/"
+
+DIM_SEPARATOR = "."
+
+URL_TEMPLATE = (
+    r"https://api.imf.org/external/sdmx/2.1/data/"
+    r"{data_flow}"
+    r"{data_flow_separator}"
+    r"{series_key}"
+    r"?TIME_PERIOD&dataonly"
+)
+
+
+def build_request_urls(
+    request_strings: Iterable[str],
+    **kwargs,
+) -> tuple[str, ...]:
+    r"""
+    """
+    requests = _get_requests_from_strings(request_strings, )
+    return tuple(
+        i.url
+        for i in requests
+    )
+
+
+def build_grouped_request_urls(
+    request_strings: Iterable[str],
+    group_by: Callable | None = None,
+) -> tuple[str, ...]:
+    r"""
+    """
+    requests = _get_requests_from_strings(request_strings, )
+    grouped_requests = _group_requests(
+        requests,
+        group_by=group_by,
+    )
+    return tuple(
+        _build_url_for_grouped_requests(i)
+        for i in grouped_requests
+    )
+
+
+def _get_requests_from_strings(
+    request_strings: str | Iterable[str], 
+) -> tuple[_Request, ...]:
+    r"""
+    """
+    #[
+    if isinstance(request_strings, str):
+        request_strings = (request_strings, )
+    requests = tuple(
+        _Request.from_request_string(n, )
+        for n in request_strings
+    )
+    return requests
+    #]
+
+
+def _group_requests(
+    requests: tuple[_Request],
+    group_by: Callable | None = None,
+) -> tuple[tuple[_Request, ...], ...]:
+
+    if group_by is None:
+        group_by = _group_by
+
+    invalid = next((i for i in requests if "+" in i.series_key), None)
+    if invalid:
+        raise ValueError(
+            f"Invalid series key '{invalid}' found in individual requests. "
+            "Use 'build_request_urls' with 'group_requests=False'."
+        )
+    requests = sorted(requests, key=group_by, )
+    grouped_requests = tuple(
+        tuple(group)
+        for _, group in _it.groupby(requests, key=group_by, )
+    )
+    return grouped_requests
+
+
+def _group_by(request: _Request, ) -> Any:
+    return request.data_flow
+
+
+def _build_url_for_grouped_requests(
+    grouped_requests: tuple[_Request, ...],
+) -> str:
+    r"""
+    """
+    #[
+    data_flow = grouped_requests[0].data_flow
+    dim_lists = tuple(
+        request.series_key_dims
+        for request in grouped_requests
+    )
+    combined_dims = (
+        "+".join(set(dim_group))
+        for dim_group in zip(*dim_lists)
+    )
+    series_key = _Request._DIM_SEPARATOR.join(combined_dims, )
+    url = _Request._URL_TEMPLATE.format(
+        data_flow=data_flow,
+        data_flow_separator=_Request._DATA_FLOW_SEPARATOR,
+        series_key=series_key,
+    )
+    return url
+    #]
+
+
+class _Request:
+    #[
+
+    __slots__ = (
+        "data_flow",
+        "series_key_dims",
+    )
+
+    _DATA_FLOW_SEPARATOR = DATA_FLOW_SEPARATOR
+
+    _DIM_SEPARATOR = DIM_SEPARATOR
+
+    _URL_TEMPLATE = URL_TEMPLATE
+
+    def __init__(
+        self,
+        data_flow: str = "",
+        series_key_dims: Iterable[str] = (),
+    ) -> None:
+        self.data_flow = data_flow
+        self.series_key_dims = tuple(series_key_dims)
+
+    @classmethod
+    def from_request_string(klass, request_string: str) -> _Request:
+        data_flow, series_key, = request_string.split(klass._DATA_FLOW_SEPARATOR, )
+        series_key_dims = tuple(series_key.split(klass._DIM_SEPARATOR, ))
+        return klass(
+            data_flow=data_flow,
+            series_key_dims=series_key_dims,
+        )
+
+    @property
+    def series_key(self, ) -> str:
+        return self._DIM_SEPARATOR.join(self.series_key_dims, )
+
+    @property
+    def url(self, ) -> str:
+        return self._URL_TEMPLATE.format(
+            data_flow=self.data_flow,
+            data_flow_separator=self._DATA_FLOW_SEPARATOR,
+            series_key=self.series_key,
+        )
+
+    @property
+    def num_dims(self, ) -> int:
+        return len(self.series_key_dims)
+
+    #]
+

macrotap-0.1.0/src/macrotap/imf/_imf_response.py

@@ -0,0 +1,102 @@
+
+#[
+
+from __future__ import annotations
+
+# Standard library imports
+import json
+
+# Third-party imports
+import datapie as ap
+
+#]
+
+
+SERIES_KEY_DELIMITER = "."
+DESCRIPTION_DELIMITER = " | "
+
+
+def parse_response_json(response_json: dict, ) -> ap.Databox:
+
+    observation_dims = response_json["structure"]["dimensions"]["observation"]
+    series_key_dims = response_json["structure"]["dimensions"]["series"]
+    series_data = response_json["dataSets"][0]["series"]
+
+    if len(observation_dims) != 1 or observation_dims[0]["id"] != "TIME_PERIOD":
+        raise ValueError("Unexpected observation dimensions structure")
+
+    time_periods_info = observation_dims[0]["values"]
+    time_periods_sdmx = tuple(i["id"] for i in time_periods_info)
+    time_periods_sdmx = tuple(_clean_sdmx_string(i) for i in time_periods_sdmx)
+    time_periods = {
+        str(i): ap.Period.from_sdmx_string(j)
+        for i, j in enumerate(time_periods_sdmx, )
+    }
+
+    def _extract_series_key_dim_value(dim:int, pointer:int) -> str:
+        return series_key_dims[dim]["values"][pointer]["id"]
+
+    def _extract_series_key_dim_info(dim:int, pointer:int) -> str:
+        return series_key_dims[dim]["values"][pointer]["name"]
+
+    def _series_key_from_pointer(pointers: tuple[int, ...], ) -> tuple[str, str]:
+        r"""
+        """
+        series_key_parts = tuple(
+            _extract_series_key_dim_value(i, p, )
+            for i, p, in enumerate(pointers)
+        )
+        return SERIES_KEY_DELIMITER.join(series_key_parts, )
+
+    def _description_from_pointer(pointers: tuple[int, ...], ) -> str:
+        description_parts = tuple(
+            _extract_series_key_dim_info(i, p, )
+            for i, p, in enumerate(pointers)
+        )
+        return DESCRIPTION_DELIMITER.join(description_parts, )
+
+    output_db = ap.Databox()
+
+    for series_key, series_record, in series_data.items():
+        pointers = _pointers_from_numeric_series_key(series_key, )
+        series_key = _series_key_from_pointer(pointers, )
+        description = _description_from_pointer(pointers, )
+        #
+        series_periods = tuple(
+            time_periods[i]
+            for i in series_record["observations"].keys()
+        )
+        #
+        series_values = tuple(
+            float(i[0]) if i[0] is not None else None
+            for i in series_record["observations"].values()
+        )
+        #
+        time_series = ap.Series(
+            periods=series_periods,
+            values=series_values,
+            description=description,
+        )
+        output_db[series_key] = time_series
+
+    return output_db
+
+
+def _clean_sdmx_string(s: str, ) -> str:
+    r"""
+    Dates in response do not conform to ISO 8601 due to use of "-M" for months
+    """
+    s = s.replace("-M", "-")
+    return s
+
+
+def _pointers_from_numeric_series_key(numeric_series_key: str) -> tuple[str, str]:
+    r"""
+    Convert '0:1:2' to (0, 1, 2, ) where each number is an int pointer to
+    the dimension value in the series key dimension structure
+    """
+    return tuple(
+        int(i)
+        for i in numeric_series_key.split(":")
+    )
+

macrotap-0.1.0/src/macrotap/imf/main.py

@@ -0,0 +1,63 @@
+
+#[
+
+from __future__ import annotations
+
+# Third-party imports
+import datapie as _ap
+import requests as _rq
+
+# Local imports
+from ._imf_requests import build_request_urls, build_grouped_request_urls
+from ._imf_response import parse_response_json
+
+#]
+
+
+REQUEST_DISPATCH = {
+    True: build_grouped_request_urls,
+    False: build_request_urls,
+}
+
+_HEADERS = {"accept": "application/json", }
+
+
+def from_imf(
+    request_strings: str | Iterable[str],
+    group_requests: bool = True,
+    group_by: Callable | None = None,
+    merge_strategy: str = "error",
+    return_info: bool = False,
+) -> _ap.Databox:
+    r"""
+    """
+    if isinstance(request_strings, str):
+        request_strings = (request_strings, )
+    request_strings = tuple(set(request_strings, ))
+
+    build_request_urls = REQUEST_DISPATCH[group_requests]
+    urls = build_request_urls(request_strings, group_by=group_by, )
+    responses = []
+
+    output_db = _ap.Databox()
+    info = []
+
+    for url in urls:
+        response = _rq.get(url, headers=_HEADERS, )
+        response_json = response.json()
+        response_db = parse_response_json(response_json, )
+        output_db.merge(
+            response_db,
+            strategy=merge_strategy,
+        )
+        if return_info:
+            info.append({
+                "url": url,
+                "response": response.json(),
+            })
+
+    if return_info:
+        return output_db, info,
+
+    return output_db
+