datapungi_fed 0.5.0__py3-none-any.whl

datapungi_fed/__init__.py

@@ -0,0 +1,71 @@
+"""Gets FRED and GeoFRED data from Federal Reserve (FED) by connecting to its API."""
+from typing import Any
+
+import pandas as pd
+
+import datapungi_fed.tests as tests
+from datapungi_fed.api import Client
+
+__version__ = '0.5.0'
+
+_default_client: Client | None = None
+
+_GROUP_NAMES = {
+    'datasetlist', 'category', 'release', 'series', 'source', 'tag', 'geo'
+}
+
+__all__ = ['Client', 'ts', 'tests', *_GROUP_NAMES]
+
+
+def __dir__() -> list[str]:
+    """Expose only the public, user-facing names for tab completion and help()."""
+    return sorted(set(__all__) | {'__version__'})
+
+
+def _get_data() -> Client:
+    """Return the lazily-initialized default module-level client."""
+    global _default_client
+    if _default_client is None:
+        _default_client = Client()
+    return _default_client
+
+
+def __getattr__(name: str) -> Any:
+    """Expose database group attributes at module level (e.g. ``dpf.series``)."""
+    if name in _GROUP_NAMES:
+        return getattr(_get_data(), name)
+    raise AttributeError(f"module 'datapungi_fed' has no attribute '{name}'")
+
+
+def ts(*args: Any, **kwargs: Any) -> Any:
+    """Quick time-series query — shortcut for ``dpf.series(...)``.
+
+    A list or tuple of series IDs can be passed to fetch multiple series and
+    merge them into a single ``DataFrame`` with one column per series.
+    """
+    # Support dpf.ts(['gdp', 'gnp']) by fetching each series individually and
+    # concatenating along columns.
+    if (
+        len(args) == 1
+        and isinstance(args[0], (list, tuple))
+        and all(isinstance(t, str) for t in args[0])
+    ):
+        tickers = list(args[0])
+        if not tickers:
+            return pd.DataFrame()
+
+        # verbose mode is per-series and not meaningful for a merged frame.
+        kwargs.pop('verbose', None)
+
+        frames: list[pd.DataFrame] = []
+        meta: dict[str, Any] = {}
+        for ticker in tickers:
+            df = getattr(_get_data(), 'series')(ticker, **kwargs)
+            frames.append(df)
+            meta[ticker] = df.attrs.get('meta', {})
+
+        combined = pd.concat(frames, axis=1, sort=True)
+        combined.attrs['meta'] = meta
+        return combined
+
+    return getattr(_get_data(), 'series')(*args, **kwargs)

datapungi_fed/api.py

@@ -0,0 +1,98 @@
+import logging
+from typing import Any
+
+import pandas as pd
+
+from datapungi_fed import connection as settings
+from datapungi_fed import drivers
+from datapungi_fed.core import _load_datasetlist, _make_group_functions, _QueryExecutor
+from datapungi_fed.groups import DriverGroup
+
+logger = logging.getLogger(__name__)
+
+# Singular user-facing attribute names for each database group.
+_GROUP_ALIASES = {
+    'Categories': 'category',
+    'Releases': 'release',
+    'Series': 'series',
+    'Sources': 'source',
+    'Tags': 'tag',
+    'Geo': 'geo',
+}
+
+
+class Client:
+    """
+    Explicit client for the FRED and GeoFRED APIs.
+
+    Parameters
+    ----------
+    api_key : str, dict, or None
+        FRED API key as a string, or a connection configuration dictionary,
+        or ``None`` to load the key from the ``API_KEY_FED`` environment
+        variable / package settings.
+    userSettings : dict, optional
+        Optional user settings dictionary.
+    """
+    def __init__(
+        self,
+        api_key: str | dict[str, Any] | None = None,
+        userSettings: dict[str, Any] | None = None,
+    ):
+        self.__connectInfo = settings._get_connection_config(
+            connectionParameters=api_key, userSettings=userSettings
+        )
+
+        #specific drivers
+        self.datasetlist  = drivers.datasetlist()
+
+        #core drivers: build one driver per YAML group, sharing a single query executor.
+        etdb = _QueryExecutor(
+            baseRequest = self.__connectInfo.baseRequest,
+            userSettings = self.__connectInfo.userSettings,
+        )
+        for dbGroupName in (entry['group'] for entry in _load_datasetlist()):
+            default_db_name, db_functions = _make_group_functions(dbGroupName, etdb)
+            default_db = db_functions[default_db_name]
+            attr_name = _GROUP_ALIASES.get(dbGroupName, dbGroupName.lower())
+            setattr(self, attr_name, DriverGroup(attr_name, default_db, db_functions))
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return getattr(self, 'series')(*args, **kwargs)
+
+    def ts(self, *args: Any, **kwargs: Any) -> Any:
+        """Quick time-series query — shortcut for ``self.series(...)``.
+
+        A list or tuple of series IDs can be passed to fetch multiple series
+        and merge them into a single ``DataFrame`` with one column per series.
+        """
+        if (
+            len(args) == 1
+            and isinstance(args[0], (list, tuple))
+            and all(isinstance(t, str) for t in args[0])
+        ):
+            tickers = list(args[0])
+            if not tickers:
+                return pd.DataFrame()
+
+            kwargs.pop('verbose', None)
+
+            frames: list[pd.DataFrame] = []
+            meta: dict[str, Any] = {}
+            for ticker in tickers:
+                df = self.series(ticker, **kwargs)  # type: ignore[attr-defined]
+                frames.append(df)
+                meta[ticker] = df.attrs.get('meta', {})
+
+            combined = pd.concat(frames, axis=1, sort=True)
+            combined.attrs['meta'] = meta
+            return combined
+
+        return self.series(*args, **kwargs)  # type: ignore[attr-defined]
+
+    def __str__(self) -> str:
+        return self.__doc__ or ''
+
+
+# Backward-compatible alias for internal code/tests.
+_data = Client

datapungi_fed/codegen.py

@@ -0,0 +1,109 @@
+r'''
+   Code snippet generation for reproducing queries with requests directly.
+'''
+
+import json
+import logging
+from textwrap import dedent
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class _CodeSnippetBuilder:
+    def build(
+        self,
+        query: dict[str, Any],
+        baseRequest: dict[str, Any],
+        userSettings: dict[str, Any] | None = None,
+        pandasCode: str = "",
+    ) -> str:
+        if userSettings is None:
+            userSettings = {}
+        #load code header - get keys
+        apiCode = self._api_code(query,userSettings)
+
+        #load request's code
+        queryCode = self._query_code(query,baseRequest,pandasCode)
+
+        return(apiCode + queryCode)
+
+    def _query_code(self, query: dict[str, Any], baseRequest: dict[str, Any], pandasCode: str = "") -> str:
+        queryClean = {'url':query['url'],'params':query['params']}  #passing only these two entries of query; params_dict is dropped.
+        queryClean['url'] = 'url'
+        queryClean['params']=queryClean['params'].replace(baseRequest['params']['api_key'],'{}')+'.format(key)'  #replace explicit api key by the var "key" poiting to it.
+
+        queryCode = '''\
+            query = {}
+            retrivedData = requests.get(**query)
+
+            {} #replace json by xml if this is the request format
+        '''
+
+        queryCode = dedent(queryCode).format(json.dumps(queryClean),pandasCode)
+        queryCode = queryCode.replace('"url": "url"', '"url": url')
+        queryCode = queryCode.replace('.format(key)"', '".format(key)')
+        queryCode = queryCode.replace('"UserID": "key"', '"UserID": key')  #TODO: need to handle generic case, UserID, api_key...
+        return(queryCode)
+
+    def _api_code(self, query: dict[str, Any], userSettings: dict[str, Any]) -> str:
+        r'''
+          The base format of a code that can be used to replicate a driver using Requests directly.
+        '''
+        try:
+            url = query['url']
+            apiKeyPath  = userSettings['ApiKeysPath']
+            apiKeyLabel = userSettings["ApiKeyLabel"]
+        except (KeyError, AttributeError, TypeError) as e:
+            logger.debug('Incomplete connection information for code snippet: %s', e)
+            url        = " incomplete connection information "
+            apiKeyPath = " incomplete connection information "
+            apiKeyLabel = ""
+
+        storagePref  = apiKeyPath.split('.')[-1]
+
+        passToCode = {'ApiKeyLabel': apiKeyLabel, "url":url, 'ApiKeysPath':apiKeyPath}
+
+        code = self._api_code_options(storagePref)
+        code = code.format(**passToCode)
+
+        return(code)
+
+    def _api_code_options(self, storagePref: str) -> str:
+        r''''
+          storagePref: yaml, json, env
+        '''
+        if storagePref == 'yaml':
+            code = '''\
+                import requests
+                import yaml
+                import pandas as pd
+
+                apiKeysFile = '{ApiKeysPath}'
+                with open(apiKeysFile, 'r') as stream:
+                    apiInfo= yaml.safe_load(stream)
+                    url,key = apiInfo['{ApiKeyLabel}']['url'], apiInfo['{ApiKeyLabel}']['key']
+            '''
+        elif storagePref == 'json':
+            code = '''\
+                import requests
+                import json
+                import pandas as pd
+
+                # json file should contain: {"BEA":{"key":"YOUR KEY","url": "{url}" }
+
+                apiKeysFile = '{ApiKeysPath}'
+                with open(apiKeysFile) as jsonFile:
+                   apiInfo = json.load(jsonFile)
+                   url,key = apiInfo['{ApiKeyLabel}']['url'], apiInfo['{ApiKeyLabel}']['key']
+            '''
+        else: #default to env
+            code = '''\
+                import requests
+                import os
+                import pandas as pd
+
+                url = "{url}"
+                key = os.getenv("{ApiKeyLabel}")
+            '''
+        return(dedent(code))