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.