v1.1.0

1.1.0 (2024-05-20)

Feature

• ✨ Added new bavapi.tools module to support the Tools/TurboPitch endpoints in the BAV API.

Docs

• 🧹 Fixed minor typos in docstrings for bavapi.Client and sync methods.
• 📓 Blocked config module from appearing in API reference docs.
• ✨ Added documentation cross-linkage support for pydantic and pandas. References to pydantic and pandas functions or classes now link to their documentation page.

Internal

• 🧹 New config module to hold the user agent and URL to use with the package.

Typing

• 🐛 Fixed too-strict type definitions for parsing.params.list_to_str.

v1.0.4

1.0.4 (2024-04-09)

Feature

• ✨ Added new "audience-groups" endpoint to bavapi.

Docs

• 🚀 Added v2 roadmap to the documentation.
• 📓 Added documentation for Audience Groups.
• 🧹 Fixed various typos.

Test

• 🧪 Clean up testing of http and client modules through dependency injection.

Typing

• 🦆 Moved commonly used protocols to typing module.
• 🐛 Changed type of exc_type argument in the aretry function to correct Tuple instead of Iterable.

Internal

• 🧹 Removed old testing code for reproducing SSL issues in earlier versions of bavapi.

v1.0.3

1.0.3 (2024-02-09)

Fix

• 🐛 Fix bug in custom dtype conversion within the response parsing logic.

v1.0.2

1.0.2 (2024-02-08)

Fix

• ⚠️ Fix deprecation warning when parsing responses into dataframes with pandas>=2.2.

Docs

• ✨ Add ability to copy code blocks from the documentation.

Test

• 🧪 Added tests for correct dtype conversions.

Internal

• 🧹 Cleaned up unused and ignored logging for development scripts.

v1.0.1

v1.0.1 - (2024-01-19)

Fix

• 🐛 Fixed typo in sectors (previously spelled sector) parameter for categories endpoint queries.

v1.0.0

1.0.0 (2024-01-04)

Feature

• 🎉 Added five new endpoints to bavapi with accompanying FountFilters classes:
  • cities
  • companies
  • countries
  • regions
  • years

Changes

• ♻️ Initial handshake API request will now be retried on SSL errors.

Docs

• 🧹 Reordered some sections in the Basic usage and Advanced usage sections of the documentation.
• 🧹 Updated and standardized Jupyter notebook demo.
• 🧹 Clarified when a query is considered to be a single-page query in the bavapi.Query.is_single_page docstring.
• 🧹 Fixed some minor errors in bavapi.Client method docstrings.
• 🎉 Added examples of the batch logic in the Jupyter demo notebook.
• 🧹 Repurposed the getting started section on reference classes as the primary documentation page for the references functionality, rather than keeping a section in Basic usage.
• ✨ Changed Release notes dates to ISO-8601 format.

Internal

• ℹ️ Cleaned up and added comments to documentation scripts.
• ✨ Removed tqdm as a dependency from the batching logic.
• ℹ️ Added comments to nox session for deploying the docs.
• 🧹 Simplified some logic in Query.ensure.
• 🎉 Added support for specifying exceptions to retry on for aretry internal function.

CI

• ♻️ CI won't run unless a package or test file is changed, or the CI action file is changed.
• ✨ Added manual trigger to documentation so deploying fixes to the docs doesn't require a version change.

v0.13.0

0.13.0 (December 11th, 2023)

This version of bavapi is expected to be the last beta version before a release candidate.

Feature

• 🎉 bavapi will now retry page requests upon failure. You can control the number of retry attempts with the retries parameter in top-level functions and the Client interface.
• 🎉 It is now possible to control the behavior of errors in the request process. If on_errors is set to "warn" (default), successful requests will be returned and a warning will be issued detailing which pages resulted in errors and each exception associated with it. If on_errors is set to "raise" (old behavior) instead, an exception will be raised as soon as any request fails.
• 🎉 Added bav_study and released filters to studies endpoint function and method.

Changes

• 🚀 Reduced the size of the initial request to 1 item if a paginated request is detected for improved performance.
• 🚀 Paginated requests are now performed in batches instead of starting every request from the start. This should mitigate several issues (like SSL errors) with large queries and improve overall run times. You can control this behavior through the batch_size and n_workers parameters in top-level functions and the Client interface.
• 🔨 Instead of having failed requests immediately raise exceptions, bavapi will continue downloading pages, collect successful responses, and warn the user about the pages that failed to be collected. This can be controlled by the on_errors parameter in top-level functions and the Client interface.
• ✨ Using bavapi.Query instances in request functions and methods will now combine method parameters with parameters in the query object. Parameters specified in the query object will take precedence over parameters specified in the function or method. Filter values in the method parameters will be ignored if the query object contains filters.

Fix

• 🐛 Refactored the expanding step of the result parsing pipeline to fix undefined behavior when multiple expandable columns are found in the result.

Internal

• 🧹 Removed trailing whitespaces
• 🔨 New data fetching algorithm based on asynchronous workers.
• 🐛 Fixed unmatched checkout action versions in ci.
• 🔨 Refactored filter consolidation logic to avoid unnecessary copies of parameters.

Docs

• 📓 Added clarification about prefixed column names in brandscape-data endpoint results.
• ✨ Various improvements to documentation, focused on warnings/tips and code snippets.

Test

• 🧪 Added tests for new _batched and _fetcher modules.
• 🧪 Added new test case for parsing.responses to test correct behavior with multiple expandable columns in the response.
• 🧪 Added new tests for query consolidation logic.
• 🔧 Fixed HTTPClient tests to work with new architecture.
• ✨ Simplified integration tests thanks to the new retry functionality

v0.12.1

Fix

• 🐛 Incorrect datetime format used when formatting string values.
• 🐛 Removed unused testing helper code that could lead to recursion errors.

Internal

• 🧪 Add tests for all arguments in bavapi-gen-refs argument parser.
• 🧹 Removed unnecessary development flags for coverage and typing.

Typing

• ✨ Improved typing of generate_references and sync modules.

Docs

• 🧹 Fixed incorrect warning about mixing filters and endpoints.
• ✅ Normalized docstring default definitions to follow numpydoc spec.

v0.12.0

0.12.0 (November 15th, 2023)

Feature

• 🎉 Added support for metric_group_keys, for use with the brandscape-data endpoint.
• 🎉 It is now possible to use page as the start page of a paginated request. Use per_page and/or max_pages to change the behavior of the pagination. More info in the Basic Usage section of the documentation.
• ✨ As a result of the new paginated behavior, it is now possible to chunk requests by setting the start and end of the request with page and per_page, respectively. See more info in the Project tips section of the documentation.

Changes

• ⚠️ Exceptions DataNotFoundError and RateLimitExceededError are now subclasses of APIError.
• 🔨 Refactored pagination logic to allow for control over the start and end of the paginated request to the Fount. Shouldn't break existing uses of page unless per_page and/or max_pages were also in use. More info in the Basic Usage section of the documentation.
• ⚙️ Query.with_page parameters are now optional and default to None.
• 🔧 Query attributes page, per_page, and max_pages must be greater than 0.
• 🛑 (BREAKING) Query.paginated parameter order has changed to make per_page optional.

Fix

• ⚙️ Various issues and inconsistencies with pagination logic.
• 🐛 Fixed per_page not applying to single page results.

Docs

• ✨ Added instructions for performing batched requests in the Project Tips section of the documentation.

v0.11.0

0.11.0 (October 27th, 2023)

In preparation for a stable release of bavapi, some aspects of the endpoint function/method interface have been normalized across the library.

This means that all endpoints now support a query parameter directly, to allow for better reproducibility and parametrization of queries. raw_query now also uses query instead of params, with query being required unlike with other endpoints.

Another change is that the order of parameters has been altered. The main reason for this is that parameters like brand_id were positional parameters before, when they are exclusive with almost all othe r parameters. This was also the case for parameters like studies, which are exclusive with country_codes and year_numbers. Now {endpoint}_id parameters and other exclusive or niche filters have been turned to keyword-only parameters. Filters like inactive and not_in_most_influential have been removed from endpoint functions. Use the filters parameter instead. See each endpoint documentation page for more information.

Feature

• 🎉 It is now possible to pass a bavapi.Query object to all endpoint functions and methods with the query parameter. If query is used, all the parameters that would be used in the query (listed before query in each endpoint documentation) will be ignored.
• 🎉 It is now possible to specify a destination folder for the bavapi-gen-refs command with the -d/--dest-folder argument.
• 🎉 Reference classes generated via bavapi-gen-refs can now be imported with from bavapi_refs import Countries for example.

Changes

• 🛑 (BREAKING) Changed raw_query params parameter name to query to match all other endpoints.
• 🛑 (BREAKING) Changed the order of several endpoint parameters for more effective queries. Now, each endpoint function has a set of parameters that can be set as positional arguments for exploratory filtering, while niche filters and IDs have become keyword only parameters.
  • audiences:
    • Positional filters: name, active, public
    • Keyword filters: audience_id, private, groups
  • brand_metrics:
    • Positional filters: name, active, public
    • Keyword filters: metric_id, private, groups
  • brand_metric_groups:
    • Positional filters: name, active
    • Keyword filters: group_id
  • brands:
    • Positional filters: name, country_codes, year_numbers
    • Keyword filters: brand_id, studies
  • brandscape_data:
    • Positional filters: country_code, year_number, audiences, brand_name
    • Keyword filters: studies
  • categories:
    • Positional filters: name, sector
    • Keyword filters: category_id
  • collections:
    • Positional filters: name, public
    • Keyword filters: collection_id, shared_with_me, mine
  • sectors:
    • Positional filters: name, in_most_influential
    • Keyword filters: sector_id
  • studies:
    • Positional filters: country_codes, year_numbers, full_year
    • Keyword filters: study_id

Error Messages

• ⚠️ Improved error message for bavapi-gen-refs command when neither -a/--all nor -n/--name arguments aren't used.

Fix

• 🐛 Fixed that requests with item_id would ignore other query parameters.
• 🐛 Addressed undefined behavior when max_pages is larger than the total number of pages as reported by the API. Now the max number of pages is always capped by the reported total.

Internal

• 🐛 Fixed typing of tuple internal docs_deploy function annotations not being compatible with Python <3.9.
• 🚀 Removed slow and unnecessary test for the verbose parameter in HTTPClient.
• 🚀 Refactored tests that instantiate httpx.AsyncClient instances for a 20x reduction in test run time.

Docs

• ✨ Filter classes table in Basic usage page now points to each endpoint function docs.
• ✨ Automatically add comment to docs/contributing.md to edit ./CONTRIBUTING.md instead.
• 📓 Updated Jupyter notebook demo with latest features and conventions.
• 📓 Documented the use of bavapi.Query object in functions and methods.
• 📓 Improved code example for the Using reference classes section of the Basic usage page.
• 📓 Clarified which endpoint filters are positional and keyword-only in respective endpoint documentation pages
• 🐛 Fixed incorrect rendering of tabs in the Suppressing progess bar section of the Basic usage page.
• ❌ Removed datetime formatting section from the Basic usage page.