TurboPitch Tools Support (#38)

* small changes to prepare for tools

* Implemented tools-turbopitch endpoints

* added pandas and pydantic inventories

* added isort to the list of tools

* change copyright year?

* added missing `audience-groups` to the list of supported endpoints

* fixed some docstring typos

* prepare for deprecations

* add config to refuse-list for doc generation

* integration tests for tools endpoints

* added documentation for tools endpoints

* added isort to list of tools

* checked off tools item in v2 roadmap

* minor styling changes

* added release notes for 1.1

* version bump

* mention new tools functionality

* make raise_if_fails context manager private

* improve tools

* update release notes

* remove v2 roadmap

* fixed dtype for test comparisons

* fixed another dtype for comparisons

CONTRIBUTING.md

@@ -52,6 +52,7 @@ In order to run integration tests and the `bavapi-gen-refs` [command](https://wp
 - Full test coverage using [`coverage`](https://coverage.readthedocs.io/en/).
 - Run development scripts in multiple Python versions with [`nox`](https://nox.thea.codes/en/stable/).
 - Documentation using [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/).
+- Import sorting with [`isort`](https://pycqa.github.io/isort/).
 - Code auto-formatting with [`black`](https://black.readthedocs.io/en/stable/).
 - Linting with [`pylint`](https://docs.pylint.org/).
 

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [2023] [WPPBAV]
+   Copyright [2024] [WPPBAV]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -77,6 +77,7 @@ Once you have acquired a token, you can start using this library directly in pyt
 - Support for all endpoints in the WPPBAV Fount API.
   - Extended support for the following endpoints:
     - `audiences`
+    - `audience-groups`
     - `brand-metrics`
     - `brand-metric-groups`
     - `brands`
@@ -90,6 +91,7 @@ Once you have acquired a token, you can start using this library directly in pyt
     - `studies`
     - `years`
   - Other endpoints are available via the `raw_query` functions and methods.
+  - Extended support for Fount API Tools/TurboPitch endpoints.
 - Validates query parameters are of the correct types and provides type hints for better IDE support.
 - Retrieve multiple pages of data simultaneously, monitoring and preventing exceeding API rate limit.
 - Both synchronous and asynchronous APIs for accessing BAV data.

bavapi/__init__.py

@@ -28,11 +28,13 @@
 # pylint: disable=R0801
 
 from bavapi import filters
+from bavapi import tools
 from bavapi.client import Client
 from bavapi.exceptions import APIError, DataNotFoundError, RateLimitExceededError
 from bavapi.query import Query
 from bavapi.sync import (
     audiences,
+    audience_groups,
     brand_metric_groups,
     brand_metrics,
     brands,
@@ -51,6 +53,7 @@
 
 __all__ = (
     "audiences",
+    "audience_groups",
     "brand_metrics",
     "brand_metric_groups",
     "brands",
@@ -68,6 +71,7 @@
     "Client",
     "Query",
     "filters",
+    "tools",
     "APIError",
     "DataNotFoundError",
     "RateLimitExceededError",

bavapi/client.py

@@ -49,6 +49,7 @@
 )
 
 from bavapi import filters as _filters
+from bavapi.config import BASE_URL, USER_AGENT
 from bavapi.http import HTTPClient
 from bavapi.parsing.responses import parse_response
 from bavapi.query import Query
@@ -67,9 +68,6 @@
 
 __all__ = ("Client",)
 
-BASE_URL: Final[str] = "https://fount.wppbav.com/api/v2/"
-USER_AGENT: Final[str] = "BAVAPI SDK Python"
-
 BRANDSCAPE_DEFAULTS: Final[List[str]] = ["study", "brand", "category", "audience"]
 CATEGORIES_DEFAULTS: Final[List[str]] = ["sector"]
 
@@ -798,7 +796,7 @@ async def brandscape_data(
         - Brand + Audience + Country + Year
 
         You should read these from left to right. A combination of "Study + Audience"
-        worksjust as well as "Study + Audience + Brand".
+        works just as well as "Study + Audience + Brand".
         However, "Category + Audience" will not.
 
         If you use Country or Year filters, you must use both filters together.

bavapi/config.py

@@ -0,0 +1,6 @@
+"""Constants for the API connection"""
+
+from typing import Final
+
+BASE_URL: Final[str] = "https://fount.wppbav.com/api/v2/"
+USER_AGENT: Final[str] = "BAVAPI SDK Python"

bavapi/filters.py

@@ -26,6 +26,7 @@
 
 # pylint: disable=no-name-in-module, too-few-public-methods
 
+# import warnings
 from typing import Dict, Literal, Optional, Type, TypeVar, Union
 
 from pydantic import BaseModel, field_validator, model_validator
@@ -55,6 +56,8 @@
 
 FiltersOrMapping = Union[F, InputParamsMapping]
 
+# warnings.filterwarnings("default", category=DeprecationWarning, module="bavapi")
+
 
 class FountFilters(BaseModel):
     """Base class for Fount API Filters.
@@ -109,6 +112,14 @@ def ensure(
             k: v for k, v in addl_filters.items() if v
         }
 
+        # if addl_filters:
+        #     warnings.warn(
+        #         f"Using the {list(new_filters.keys())} function parameter(s) is deprecated. "
+        #         f"Use the `filters` parameter with a {cls.__name__} instance instead.",
+        #         DeprecationWarning,
+        #         2,
+        #     )
+
         if filters is None:
             if not new_filters:
                 return None

bavapi/parsing/params.py

@@ -3,7 +3,7 @@
 import datetime as dt
 from typing import Dict, Mapping, Sequence, TypeVar, Union, cast
 
-from bavapi.typing import BaseMutableParamsMapping, BaseMutableParamsMappingValues
+from bavapi.typing import MutableParamsMapping, SequenceOrValues
 
 T = TypeVar("T")
 
@@ -56,7 +56,9 @@ def to_fount_params(data: Mapping[str, T], param: str) -> Dict[str, T]:
     return {f"{param}[{k}]": v for k, v in data.items()}
 
 
-def list_to_str(mapping: BaseMutableParamsMapping) -> BaseMutableParamsMappingValues:
+def list_to_str(
+    mapping: MutableParamsMapping[SequenceOrValues[Union[T, str]]]
+) -> MutableParamsMapping[Union[T, str]]:
     """Convert any lists in a dictionary to a string with comma-separated elements.
 
     Parameters
@@ -73,4 +75,4 @@ def list_to_str(mapping: BaseMutableParamsMapping) -> BaseMutableParamsMappingVa
         if not isinstance(value, str) and isinstance(value, Sequence):
             mapping[key] = ",".join(str(i) for i in value)
 
-    return cast(BaseMutableParamsMappingValues, mapping)
+    return cast(MutableParamsMapping[Union[T, str]], mapping)

bavapi/sync.py

@@ -753,7 +753,7 @@ async def brandscape_data(
     - Brand + Audience + Country + Year
 
     You should read these from left to right. A combination of "Study + Audience"
-    worksjust as well as "Study + Audience + Brand".
+    works just as well as "Study + Audience + Brand".
     However, "Category + Audience" will not.
 
     If you use Country or Year filters, you must use both filters together.