Added new endpoints (#16)

* fixed local docs_deploy if versions not synced * version bump * added new supported endpoints * crossed out pending endpoints * documentation for new endpoints * added missing name param for function filters * added note about suppresing default includes * release notes for v0.10 * more info to alpha stage warning * added loading progress bar functionality * fixed site_url * added new endpoints to feature summary * cleaned up old patterns and links * more explicit examples * new convention to name Client instance as `bav` * added integration tests for new endpoints * Using `List` for 3.8 compatibility
wppbav · Oct 16, 2023 · 974d606 · 974d606
1 parent 6fed733
commit 974d606
Show file tree

Hide file tree

Showing 25 changed files with 1,561 additions and 122 deletions.
diff --git a/BAVAPI Jupyter Demo.ipynb b/BAVAPI Jupyter Demo.ipynb
@@ -9,7 +9,9 @@
     "\n",
     "In this notebook we will demo the functionality of `bavapi`, a python package to access BAV data from the WPPBAV [Fount](https:/fount.wppbav.com).\n",
     "\n",
-    "To learn more about `bavapi` and how to use it, please visit the [documentation](https://wppbav.github.io/bavapi-sdk-python/)."
+    "To learn more about `bavapi` and how to use it, please visit the [documentation](https://wppbav.github.io/bavapi-sdk-python/).\n",
+    "\n",
+    "To learn more about the `BAV API` and how to use it, please visit the [API documentation](https://developer.wppbav.com)."
    ]
   },
   {
@@ -46,7 +48,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "TOKEN = \"your_token\"  # paste your Fount API token here, or follow the instructions below"
+    "TOKEN = \"your_token\"  # paste your token here, or follow the instructions below"
    ]
   },
   {
@@ -271,13 +273,13 @@
     "For example, normally you would have to specify the audience by using its Fount ID. This can be retrieved from the `audiences` endpoint, and used like so:\n",
     "\n",
     "```py\n",
-    "fountapi.brandscape_data(TOKEN, country_code=\"GB\", audiences=12523)  # 12523 corresponds to All Adults.\n",
+    "bavapi.brandscape_data(TOKEN, country_code=\"GB\", audiences=12523)  # 12523 corresponds to All Adults.\n",
     "```\n",
     "\n",
     "Or alternatively, use the reference class:\n",
     "\n",
     "```py\n",
-    "fountapi.brandscape_data(TOKEN, country_code=\"GB\", audiences=Audiences.ALL_ADULTS)\n",
+    "bavapi.brandscape_data(TOKEN, country_code=\"GB\", audiences=Audiences.ALL_ADULTS)\n",
     "```\n",
     "\n",
     "To download these references, you must specify your Fount API key in a `.env` file at the top of your current working directory.\n",
@@ -296,7 +298,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    ">__**💡 Tip:**__ Uncomment the cell below to download reference files"
+    ">__**💡 Tip:**__ Uncomment the cell below to download reference files. Replace `TOKEN` with your API key."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# !bavapi-gen-refs --all -t \"TOKEN\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ">__**💡 Tip:**__ If you have set up a `.env` file with `FOUNT_API_KEY` as an environment variable, you can use the command below instead:"
    ]
   },
   {
@@ -325,7 +343,7 @@
     "The same can be done with countries. Use:\n",
     "\n",
     "```py\n",
-    "from bavapi_refs.countries import Country\n",
+    "from bavapi_refs.countries import Countries\n",
     "```"
    ]
   },
@@ -346,7 +364,9 @@
    "outputs": [],
    "source": [
     "# Get one single brand by ID\n",
-    "swatch = bavapi.brands(TOKEN, brand_id=2985)  # Note that this ID is the Fount ID, not the one in `bav_key`\n",
+    "swatch = bavapi.brands(\n",
+    "    TOKEN, brand_id=2985\n",
+    ")  # Note that this ID is the Fount ID, not the one in `bav_key`\n",
     "swatch"
    ]
   },
@@ -357,7 +377,9 @@
    "outputs": [],
    "source": [
     "# Get US studies that ended fielding after `2021-09-01`\n",
-    "us_studies = bavapi.studies(TOKEN, \"US\", filters={\"data_updated_since\":\"2021-09-01 00:00:00\"})\n",
+    "us_studies = bavapi.studies(\n",
+    "    TOKEN, \"US\", filters={\"data_updated_since\": \"2021-09-01 00:00:00\"}\n",
+    ")\n",
     "us_studies.head()"
    ]
   },
@@ -368,7 +390,13 @@
    "outputs": [],
    "source": [
     "# Get Spanish data for 2022 for the `Adults with kids` base sorted by Differentiation in descending order (highest first)\n",
-    "es_bss = bavapi.brandscape_data(TOKEN, \"ES\", 2022, audiences=[Audiences.ADULTS_WITH_KIDS, Audiences.ADULTS_WITH_KIDS_0_11], sort=\"-differentiation_rank\")\n",
+    "es_bss = bavapi.brandscape_data(\n",
+    "    TOKEN,\n",
+    "    \"ES\",\n",
+    "    2022,\n",
+    "    audiences=[Audiences.ADULTS_WITH_KIDS, Audiences.ADULTS_WITH_KIDS_0_11],\n",
+    "    sort=\"-differentiation_rank\",\n",
+    ")\n",
     "es_bss.head()"
    ]
   },
@@ -379,7 +407,9 @@
    "outputs": [],
    "source": [
     "# Get Spanish data for 2020 and 2022\n",
-    "es_bss = bavapi.brandscape_data(TOKEN, \"ES\", [2019, 2022], audiences=Audiences.ALL_ADULTS)\n",
+    "es_bss = bavapi.brandscape_data(\n",
+    "    TOKEN, \"ES\", [2019, 2022], audiences=Audiences.ALL_ADULTS\n",
+    ")\n",
     "es_bss.head()"
    ]
   },
@@ -390,7 +420,9 @@
    "outputs": [],
    "source": [
     "# Get French and Spanish data for 2022\n",
-    "es_fr_bss = bavapi.brandscape_data(TOKEN, [\"ES\", \"FR\"], 2022, audiences=Audiences.ALL_ADULTS)\n",
+    "es_fr_bss = bavapi.brandscape_data(\n",
+    "    TOKEN, [\"ES\", \"FR\"], 2022, audiences=Audiences.ALL_ADULTS\n",
+    ")\n",
     "es_fr_bss.head()"
    ]
   },
@@ -412,7 +444,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "raw_res = bavapi.raw_query(TOKEN, \"companies\", bavapi.Query(filters={\"name\":\"Facebook\"}))\n",
+    "raw_res = bavapi.raw_query(\n",
+    "    TOKEN,\n",
+    "    \"companies\",\n",
+    "    bavapi.Query(filters=bavapi.filters.FountFilters(name=\"Facebook\")),  # type: ignore\n",
+    ")\n",
     "raw_res"
    ]
   },
@@ -468,7 +504,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.12.0"
   },
   "orig_nbformat": 4,
   "vscode": {

diff --git a/bavapi/__init__.py b/bavapi/__init__.py
@@ -11,27 +11,47 @@
 
 For more information, go to the WPPBAV Fount website at <https:/fount.wppbav.com>.
 
-Example usage
--------------
+Examples
+--------
+Use top-level endpoint functions for quickly downloading BAV data:
 
 >>> import bavapi
->>> async with bavapi.Client("API_TOKEN") as client:
-...     result = await client.brands(name="Facebook")
-"""
+>>> res = bavapi.brands("TOKEN", name="Facebook")
+
+For more advanced (and async compatibility), use the `Client` pattern:
 
-from importlib.metadata import PackageNotFoundError, version
+>>> import bavapi
+>>> async with bavapi.Client("API_TOKEN") as bav:
+...     result = await bav.brands(name="Facebook")
+"""
 
 from bavapi import filters
 from bavapi.client import Client
 from bavapi.exceptions import APIError, DataNotFoundError, RateLimitExceededError
 from bavapi.query import Query
-from bavapi.sync import audiences, brands, brandscape_data, raw_query, studies
+from bavapi.sync import (
+    audiences,
+    brand_metrics,
+    brand_metric_groups,
+    brands,
+    brandscape_data,
+    categories,
+    collections,
+    sectors,
+    raw_query,
+    studies,
+)
 
 __all__ = (
     "audiences",
+    "brand_metrics",
+    "brand_metric_groups",
     "brands",
     "brandscape_data",
+    "categories",
+    "collections",
     "raw_query",
+    "sectors",
     "studies",
     "Client",
     "Query",
@@ -40,8 +60,3 @@
     "DataNotFoundError",
     "RateLimitExceededError",
 )
-
-try:
-    __version__ = version(__package__ or __name__)
-except PackageNotFoundError:  # pragma: no cover
-    __version__ = "not_found"