Release/0.1.2 beta (#19)

* new custom return type for JsonOrXml, annotate all existing APIs

* bump lib to 0.1.2-beta

* use TypeVar instead of NewType

* include explicit package exports for api

* add new classifiers and badges to README and pyproject.toml

Author: zachspar

README.md

@@ -1,3 +1,5 @@
+[![PyPI version](https://badge.fury.io/py/fred-py-api.svg)](https://badge.fury.io/py/fred-py-api)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/fred-py-api?style=flat)](https://pypi.org/project/fred-py-api/)
 [![codecov](https://codecov.io/gh/zachspar/fred-py-api/branch/main/graph/badge.svg?token=BG1948D8Y7)](https://codecov.io/gh/zachspar/fred-py-api)
 
 # Fred Python API

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fred_py_api"
-version = "0.1.1"
+version = "0.1.2"
 authors = [
   { name="Zachary Spar", email="[email protected]" },
 ]
@@ -13,8 +13,14 @@ readme = "README.md"
 requires-python = ">=3.6"
 classifiers = [
     "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
     "Intended Audience :: Science/Research",
-    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]

src/fred/api/__init__.py

@@ -17,3 +17,15 @@ class FredAPI(FredAPISeries, FredAPIReleases, FredAPICategories, FredAPISources,
     """
 
     pass
+
+
+__all__ = [
+    "BaseFredAPIError",
+    "FredAPIRequestError",
+    "FredAPI",
+    "FredAPICategories",
+    "FredAPIReleases",
+    "FredAPISeries",
+    "FredAPISources",
+    "FredAPITags",
+]

src/fred/api/_fred_client.py

@@ -4,14 +4,17 @@
 """
 from http import HTTPStatus
 from os import environ
-from typing import Optional, Union, Dict
+from typing import Optional, Dict, TypeVar
 from xml.etree import ElementTree
 
 import requests
 
 from .exceptions import FredAPIRequestError
 
 
+JsonOrXml = TypeVar("JsonOrXml", Dict, ElementTree.Element)
+
+
 class FredClient(object):
     """Base Fred API."""
 
@@ -42,7 +45,7 @@ def get_api_key(self) -> str:
         """Get API key."""
         return self._api_key
 
-    def _get(self, endpoint: str = None, payload: dict = None) -> Union[Dict, ElementTree.Element]:
+    def _get(self, endpoint: str = None, payload: dict = None) -> JsonOrXml:
         """Invoke client get request."""
         if not payload:
             payload = {}

src/fred/api/categories.py

@@ -2,7 +2,7 @@
 """
 Fred API for Categories Namespace.
 """
-from ._fred_client import FredClient
+from ._fred_client import FredClient, JsonOrXml
 from .._util.decorators import validate_api_args
 
 
@@ -20,7 +20,7 @@ class FredAPICategories(FredClient):
     """
 
     @validate_api_args("api_key", "file_type", "category_id")
-    def get_category(self, category_id: int = None, **kwargs) -> dict:
+    def get_category(self, category_id: int = None, **kwargs) -> JsonOrXml:
         """Get category by ID. https://fred.stlouisfed.org/docs/api/fred/category.html"""
         return self._get(
             f"category",
@@ -45,7 +45,7 @@ def get_category(self, category_id: int = None, **kwargs) -> dict:
         "tag_names",
         "exclude_tag_names",
     )
-    def get_category_series(self, category_id: int, **kwargs) -> dict:
+    def get_category_series(self, category_id: int, **kwargs) -> JsonOrXml:
         """Get category series by category ID. https://fred.stlouisfed.org/docs/api/fred/category_series.html"""
         return self._get(
             f"category/series",
@@ -56,7 +56,7 @@ def get_category_series(self, category_id: int, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "file_type", "category_id", "realtime_start", "realtime_end")
-    def get_category_children(self, category_id: int = None, **kwargs) -> dict:
+    def get_category_children(self, category_id: int = None, **kwargs) -> JsonOrXml:
         """Get category children by category ID. https://fred.stlouisfed.org/docs/api/fred/category_children.html"""
         return self._get(
             f"category/children",
@@ -67,7 +67,7 @@ def get_category_children(self, category_id: int = None, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "file_type", "category_id", "realtime_start", "realtime_end")
-    def get_category_related(self, category_id: int, **kwargs) -> dict:
+    def get_category_related(self, category_id: int, **kwargs) -> JsonOrXml:
         """Get category related by category ID. https://fred.stlouisfed.org/docs/api/fred/category_related.html"""
         return self._get(
             f"category/related",
@@ -97,7 +97,7 @@ def get_category_related(self, category_id: int, **kwargs) -> dict:
         "order_by",
         "sort_order",
     )
-    def get_category_tags(self, category_id: int, **kwargs) -> dict:
+    def get_category_tags(self, category_id: int, **kwargs) -> JsonOrXml:
         """Get category tags by category ID. https://fred.stlouisfed.org/docs/api/fred/category_tags.html"""
         return self._get(
             f"category/tags",
@@ -128,7 +128,7 @@ def get_category_tags(self, category_id: int, **kwargs) -> dict:
         "order_by",
         "sort_order",
     )
-    def get_category_related_tags(self, category_id: int, tag_names: str, **kwargs) -> dict:
+    def get_category_related_tags(self, category_id: int, tag_names: str, **kwargs) -> JsonOrXml:
         """Get category related tags by category ID and tag names. https://fred.stlouisfed.org/docs/api/fred/category_related_tags.html"""
         return self._get(
             f"category/related_tags",

src/fred/api/releases.py

@@ -2,7 +2,7 @@
 """
 Fred API for Releases Namespace.
 """
-from ._fred_client import FredClient
+from ._fred_client import FredClient, JsonOrXml
 from .._util.decorators import validate_api_args
 
 
@@ -25,7 +25,7 @@ class FredAPIReleases(FredClient):
     @validate_api_args(
         "api_key", "file_type", "realtime_start", "realtime_end", "limit", "offset", "order_by", "sort_order"
     )
-    def get_releases(self, **kwargs) -> dict:
+    def get_releases(self, **kwargs) -> JsonOrXml:
         """Get releases. https://fred.stlouisfed.org/docs/api/fred/releases.html"""
         return self._get(
             f"releases",
@@ -45,7 +45,7 @@ def get_releases(self, **kwargs) -> dict:
         "sort_order",
         "include_release_dates_with_no_data",
     )
-    def get_releases_dates(self, **kwargs) -> dict:
+    def get_releases_dates(self, **kwargs) -> JsonOrXml:
         """Get releases dates. https://fred.stlouisfed.org/docs/api/fred/releases_dates.html"""
         return self._get(
             f"releases/dates",
@@ -55,7 +55,7 @@ def get_releases_dates(self, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "release_id", "file_type", "realtime_start", "realtime_end")
-    def get_release(self, release_id: int, **kwargs) -> dict:
+    def get_release(self, release_id: int, **kwargs) -> JsonOrXml:
         """Get release by ID. https://fred.stlouisfed.org/docs/api/fred/release.html"""
         return self._get(
             f"release",
@@ -76,7 +76,7 @@ def get_release(self, release_id: int, **kwargs) -> dict:
         "sort_order",
         "include_release_dates_with_no_data",
     )
-    def get_release_dates(self, release_id: int, **kwargs) -> dict:
+    def get_release_dates(self, release_id: int, **kwargs) -> JsonOrXml:
         """Get release dates by release ID. https://fred.stlouisfed.org/docs/api/fred/release_dates.html"""
         return self._get(
             f"release/dates",
@@ -101,7 +101,7 @@ def get_release_dates(self, release_id: int, **kwargs) -> dict:
         "tag_names",
         "exclude_tag_names",
     )
-    def get_release_series(self, release_id: int, **kwargs) -> dict:
+    def get_release_series(self, release_id: int, **kwargs) -> JsonOrXml:
         """Get release series by release ID. https://fred.stlouisfed.org/docs/api/fred/release_series.html"""
         return self._get(
             f"release/series",
@@ -112,7 +112,7 @@ def get_release_series(self, release_id: int, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "file_type", "release_id", "realtime_start", "realtime_end")
-    def get_release_sources(self, release_id: int, **kwargs) -> dict:
+    def get_release_sources(self, release_id: int, **kwargs) -> JsonOrXml:
         """Get release sources by release ID. https://fred.stlouisfed.org/docs/api/fred/release_sources.html"""
         return self._get(
             f"release/sources",
@@ -136,7 +136,7 @@ def get_release_sources(self, release_id: int, **kwargs) -> dict:
         "order_by",
         "sort_order",
     )
-    def get_release_tags(self, release_id: int, **kwargs) -> dict:
+    def get_release_tags(self, release_id: int, **kwargs) -> JsonOrXml:
         """Get release tags by release ID. https://fred.stlouisfed.org/docs/api/fred/release_tags.html"""
         return self._get(
             f"release/tags",
@@ -161,7 +161,7 @@ def get_release_tags(self, release_id: int, **kwargs) -> dict:
         "order_by",
         "sort_order",
     )
-    def get_release_related_tags(self, release_id: int, tag_names: str, **kwargs) -> dict:
+    def get_release_related_tags(self, release_id: int, tag_names: str, **kwargs) -> JsonOrXml:
         """Get release related tags by release ID and tag names.
         https://fred.stlouisfed.org/docs/api/fred/release_related_tags.html"""
         return self._get(
@@ -176,7 +176,7 @@ def get_release_related_tags(self, release_id: int, tag_names: str, **kwargs) ->
     @validate_api_args(
         "api_key", "file_type", "release_id", "element_id", "include_observation_values", "observation_date"
     )
-    def get_release_tables(self, release_id: int, element_id: int = None, **kwargs) -> dict:
+    def get_release_tables(self, release_id: int, element_id: int = None, **kwargs) -> JsonOrXml:
         """Get release tables by release ID and element ID.
         https://fred.stlouisfed.org/docs/api/fred/release_tables.html"""
         return self._get(

src/fred/api/series.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """
-Fred API Series Namespace Requests.
+Fred API Series Namespace.
 """
-from ._fred_client import FredClient
+from ._fred_client import FredClient, JsonOrXml
 from .._util.decorators import validate_api_args
 
 
@@ -24,7 +24,7 @@ class FredAPISeries(FredClient):
     """
 
     @validate_api_args("api_key", "file_type", "series_id", "realtime_start", "realtime_end")
-    def get_series_categories(self, series_id: str, **kwargs) -> dict:
+    def get_series_categories(self, series_id: str, **kwargs) -> JsonOrXml:
         """Get series categories by series ID. https://fred.stlouisfed.org/docs/api/fred/series_categories.html"""
         return self._get(
             f"series/categories",
@@ -35,7 +35,7 @@ def get_series_categories(self, series_id: str, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "file_type", "series_id", "realtime_start", "realtime_end", "order_by", "sort_order")
-    def get_series_tags(self, series_id: str, **kwargs) -> dict:
+    def get_series_tags(self, series_id: str, **kwargs) -> JsonOrXml:
         """Get series tags by series ID. https://fred.stlouisfed.org/docs/api/fred/series_tags.html"""
         return self._get(
             f"series/tags",
@@ -61,7 +61,7 @@ def get_series_tags(self, series_id: str, **kwargs) -> dict:
         "tag_names",
         "exclude_tag_names",
     )
-    def get_series_search(self, search_text: str, search_type: str = "full_text", **kwargs) -> dict:
+    def get_series_search(self, search_text: str, search_type: str = "full_text", **kwargs) -> JsonOrXml:
         """Get series search by text. https://fred.stlouisfed.org/docs/api/fred/series_search.html"""
         return self._get(
             f"series/search",
@@ -86,7 +86,7 @@ def get_series_search(self, search_text: str, search_type: str = "full_text", **
         "order_by",
         "sort_order",
     )
-    def get_series_search_tags(self, series_search_text: str, **kwargs) -> dict:
+    def get_series_search_tags(self, series_search_text: str, **kwargs) -> JsonOrXml:
         """Get series search tags by text. https://fred.stlouisfed.org/docs/api/fred/series_search_tags.html"""
         return self._get(
             f"series/search/tags",
@@ -111,7 +111,7 @@ def get_series_search_tags(self, series_search_text: str, **kwargs) -> dict:
         "order_by",
         "sort_order",
     )
-    def get_series_search_related_tags(self, series_search_text: str, tag_names: str, **kwargs) -> dict:
+    def get_series_search_related_tags(self, series_search_text: str, tag_names: str, **kwargs) -> JsonOrXml:
         """Get series related tags by text. https://fred.stlouisfed.org/docs/api/fred/series_search_related_tags.html"""
         return self._get(
             f"series/search/related_tags",
@@ -139,7 +139,7 @@ def get_series_search_related_tags(self, series_search_text: str, tag_names: str
         "output_type",
         "vintage_dates",
     )
-    def get_series_observations(self, series_id: str, **kwargs) -> dict:
+    def get_series_observations(self, series_id: str, **kwargs) -> JsonOrXml:
         """Get series observations by series ID. https://fred.stlouisfed.org/docs/api/fred/series_observations.html"""
         return self._get(
             f"series/observations",
@@ -160,7 +160,7 @@ def get_series_observations(self, series_id: str, **kwargs) -> dict:
         "start_time",
         "end_time",
     )
-    def get_series_updates(self, **kwargs) -> dict:
+    def get_series_updates(self, **kwargs) -> JsonOrXml:
         """Get series updates. https://fred.stlouisfed.org/docs/api/fred/series_updates.html"""
         # TODO FIXME: Validate start_time and end_time presence if applicable.
         return self._get(
@@ -173,7 +173,7 @@ def get_series_updates(self, **kwargs) -> dict:
     @validate_api_args(
         "api_key", "file_type", "series_id", "realtime_start", "realtime_end", "limit", "offset", "sort_order"
     )
-    def get_series_vintagedates(self, series_id: str, **kwargs) -> dict:
+    def get_series_vintagedates(self, series_id: str, **kwargs) -> JsonOrXml:
         """Get series vintagedates by series ID. https://fred.stlouisfed.org/docs/api/fred/series_vintage_dates.html"""
         return self._get(
             f"series/vintagedates",
@@ -184,7 +184,7 @@ def get_series_vintagedates(self, series_id: str, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "file_type", "series_id", "realtime_start", "realtime_end")
-    def get_series_release(self, series_id: str, **kwargs) -> dict:
+    def get_series_release(self, series_id: str, **kwargs) -> JsonOrXml:
         """Get series release by series ID. https://fred.stlouisfed.org/docs/api/fred/series_release.html"""
         return self._get(
             f"series/release",
@@ -195,7 +195,7 @@ def get_series_release(self, series_id: str, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "file_type", "series_id", "realtime_start", "realtime_end")
-    def get_series(self, series_id: str, **kwargs) -> dict:
+    def get_series(self, series_id: str, **kwargs) -> JsonOrXml:
         """Get series by ID. https://fred.stlouisfed.org/docs/api/fred/series.html"""
         return self._get(
             f"series",

src/fred/api/sources.py

@@ -2,7 +2,7 @@
 """
 Fred API Sources Namespace.
 """
-from ._fred_client import FredClient
+from ._fred_client import FredClient, JsonOrXml
 from .._util.decorators import validate_api_args
 
 
@@ -19,7 +19,7 @@ class FredAPISources(FredClient):
     @validate_api_args(
         "api_key", "file_type", "realtime_start", "realtime_end", "limit", "offset", "order_by", "sort_order"
     )
-    def get_sources(self, **kwargs) -> dict:
+    def get_sources(self, **kwargs) -> JsonOrXml:
         """Get sources. https://fred.stlouisfed.org/docs/api/fred/sources.html"""
         return self._get(
             f"sources",
@@ -29,7 +29,7 @@ def get_sources(self, **kwargs) -> dict:
         )
 
     @validate_api_args("api_key", "file_type", "source_id", "realtime_start", "realtime_end")
-    def get_source(self, source_id: int, **kwargs) -> dict:
+    def get_source(self, source_id: int, **kwargs) -> JsonOrXml:
         """Get source by ID. https://fred.stlouisfed.org/docs/api/fred/source.html"""
         return self._get(
             f"source",
@@ -50,7 +50,7 @@ def get_source(self, source_id: int, **kwargs) -> dict:
         "order_by",
         "sort_order",
     )
-    def get_source_releases(self, source_id: int, **kwargs) -> dict:
+    def get_source_releases(self, source_id: int, **kwargs) -> JsonOrXml:
         """Get source releases by source ID. https://fred.stlouisfed.org/docs/api/fred/source_releases.html"""
         return self._get(
             f"source/releases",