Merge pull request #8 from wppbav:doc-updates

Updated docs

docs/endpoints/brandscape-data.md

@@ -94,7 +94,7 @@ As a result, you will see a set of columns, extracted from the `"brand"` include
 
 ## Metric keys
 
-`brandscape-data` provides a special filter to specify the data *columns* that the response should contain: `metric_keys`.
+`brandscape-data` functions and methods provide a parameter to specify the data *columns* that the response should contain: `metric_keys`.
 
 You can specify the metrics that your response should contain, and the API will include all score types for that metric.
 
@@ -107,3 +107,9 @@ You can specify the metrics that your response should contain, and the API will
     - `relevance_rank`
     - Brand information such as `id`, `brand_name`, and `category_name`
     - Any additional columns from the `include` parameter
+
+    ```py
+    bavapi.brandscape_data(studies=111, metric_keys="differentiation") # (1)
+    ```
+
+    1. Will only return `differentiation_c` and `differentiation_rank` data.

docs/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}"> 
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

docs/release-notes.md

@@ -2,6 +2,25 @@
 
 ## Version 0.6
 
+### Version 0.6.1 (July 19th, 2023)
+
+#### Fix
+
+- :bug: Fix `metric_keys` incorrectly categorized as a filter instead of a top-level parameter within the `Query` class.
+
+#### Internal
+
+- :wrench: Changed the custom `IntEnum` implementation to not override the standard lib's `IntEnum.__str__`.
+- :hammer: Added `nox` session for deploying docs.
+
+#### Tests
+
+- :test_tube: Added tests for checking that filters and parameters are assigned correctly in `Client` methods.
+
+#### Docs
+
+- :notebook: Added warning about potential SSL errors outside of `bavapi` when using the Fount API.
+
 ### Version 0.6.0 (July 13th, 2023)
 
 #### Internal

docs/roadmap.md

@@ -7,6 +7,10 @@ This is a non-exhaustive list of potential features & changes to `bavapi` before
 - ~~`pydantic` V2 support~~ :white_check_mark:
 - Strict `mypy` support with [PEP 692](https://docs.python.org/3.12/whatsnew/3.12.html#whatsnew312-pep692) `Unpack` and `TypedDict`
 
+## Known issues
+
+- Fix sporadic `SSL: CERTIFICATE_VERIFY_FAILED` errors when making requests to the Fount API.
+
 ## New fully-supported endpoints
 
 Eventually, the plan is to support all endpoints. This is the current priority list:

docs/usage/basic.md

@@ -8,6 +8,13 @@ import bavapi
 
 ## Using bavapi
 
+!!! info "SSL Issues"
+    It's possible that you get `SSL: CERTIFICATE_VERIFY_FAILED` errors when performing requests with `bavapi`. At the moment, it is not clear to what might be the source of the issue; as it only happens sometimes, and the error doesn't appear to happen with other tested URLs.
+
+    Usually, making the request again solves the issue, but you might have to do so a couple of times if the issue persists.
+
+    :bulb: If you have any thoughts on how to solve this, please open an [issue](https://github.com/wppbav/bavapi-sdk-python/issues/) on GitHub.
+
 You can query the available [endpoints](../endpoints/index.md) with their corresponding methods:
 
 ```py
@@ -75,7 +82,7 @@ However, less commonly used filters, as well as [value filters](#value-filters)
 
 Filters can be specified using a Python dictionary (if you know the name of the filters you need), or directly creating a Filters instance:
 
-=== "Filters class (recommended)"
+=== "Filters instances (recommended)"
 
     ```py
     result = bavapi.brands(
@@ -203,6 +210,17 @@ result = bavapi.brands(name="Swatch", per_page=1000)
 
 You can also set a custom number of `max_pages` for the request, or directly specify the `page` parameter to get a single page of results.
 
+### Metric keys
+
+`metric_keys` is a special filter to specify the data *columns* that the response should contain.
+
+The API response will include all score types for that metric.
+
+!!! note
+    Currently, only the `brandscape-data` endpoint supports the use of metric keys. All other endpoints will ignore this parameter.
+
+    More info in the [`brandscape-data`](../endpoints/brandscape-data.md) endpoint section.
+
 ## Formatting output
 
 It is possible that some of the data retrieved from the Fount includes multiple items.

mkdocs.yml

@@ -8,6 +8,7 @@ copyright: Copyright © 2023 WPPBAV
 
 theme:
   name: material
+  custom_dir: docs/overrides
   logo: assets/wpp-bav-logo.svg
   favicon: assets/favicon.svg
   icon:

noxfile.py

@@ -3,7 +3,7 @@
 import json
 import os
 import pathlib
-from typing import Dict, List
+from typing import Dict, List, cast
 
 import nox
 
@@ -63,7 +63,7 @@ def tests_e2e_nocov(session: nox.Session) -> None:
 @nox.session(python=python_versions, venv_backend="mamba", reuse_venv=True)
 def tests_mamba(session: nox.Session) -> None:
     """Run tests locally with `mamba` as the backend."""
-    session.conda_install("--file", "requirements.txt")
+    session.conda_install("--file", "requirements.txt", channel="conda-forge")
     session.install("-e", ".[test]")
 
     session.run(
@@ -82,7 +82,7 @@ def tests_mamba(session: nox.Session) -> None:
 @nox.session(python=python_versions, venv_backend="mamba", reuse_venv=True)
 def tests_mamba_nocov(session: nox.Session) -> None:
     """Run tests locally with `mamba` as the backend with no coverage."""
-    session.conda_install("--file", "requirements.txt")
+    session.conda_install("--file", "requirements.txt", channel="conda-forge")
     session.install("-e", ".[test]")
 
     session.run("pytest", "-m", "not e2e", *session.posargs, external=True)
@@ -91,7 +91,7 @@ def tests_mamba_nocov(session: nox.Session) -> None:
 @nox.session(python="3.11", venv_backend="mamba", reuse_venv=True)
 def tests_mamba_e2e(session: nox.Session) -> None:
     """Run end to end tests locally with `mamba` as the backend."""
-    session.conda_install("--file", "requirements.txt")
+    session.conda_install("--file", "requirements.txt", channel="conda-forge")
     session.install("-e", ".[test]")
 
     session.run(
@@ -110,7 +110,7 @@ def tests_mamba_e2e(session: nox.Session) -> None:
 @nox.session(python="3.11", venv_backend="mamba", reuse_venv=True)
 def tests_mamba_e2e_nocov(session: nox.Session) -> None:
     """Run end to end tests locally with `mamba` as the backend with no coverage."""
-    session.conda_install("--file", "requirements.txt")
+    session.conda_install("--file", "requirements.txt", channel="conda-forge")
     session.install("-e", ".[test]")
 
     session.run("pytest", "-m", "e2e", *session.posargs, external=True)
@@ -146,11 +146,13 @@ def coverage(session: nox.Session) -> None:
 @nox.session(python="3.11")
 def lint(session: nox.Session) -> None:
     """Lint package."""
-    session.install("pylint", "mypy")
-    session.install("-e", ".")
+    session.install("-e", ".[lint]")
 
-    session.run("pylint", "bavapi")
     session.run("mypy", "bavapi")
+    session.run("pylint", "bavapi")
+    session.run("pylint", "tests")
+    session.run("isort", "-l", "100", ".")
+    session.run("black", ".")
 
 
 @nox.session(python=None)
@@ -192,9 +194,77 @@ def build(session: nox.Session) -> None:
     session.run("python", "-m", "build")
 
 
-@nox.session(python=None)
-def publish(session: nox.Session) -> None:
-    """Publish package wheel and source distribution to PyPI."""
-    session.install("twine")
+@nox.session(python=False)
+def docs_deploy(session: nox.Session) -> None:
+    """Build and deploy documentation with version handling.
+
+    If package minor version is latest, deploy docs version and assign to `latest`.
+    If package minor version is not latest, deploy docs version.
+    If package minor version exists, update docs version.
+
+    Arguments
+    ---------
+    --push: flag
+        Check versions from GitHub branch and deploy to branch.
+    --version: str
+        Override version from package
+
+    Examples
+    --------
+    Run docs_deploy locally
+
+    `nox -s docs_deploy`
+
+    Run docs_deploy for remote branch
+
+    `nox -s docs_deploy -- --push`
+
+    Override package version
+
+    `nox -s docs_deploy -- --version=2.0.0`
+    """
+
+    # Get current package version
+
+    try:
+        import tomllib
+    except ImportError:
+        session.install("tomli")
+        import tomli as tomllib
+
+    def version_tuple(string: str) -> tuple[int, ...]:
+        return tuple(int(i) for i in string.split("."))
+
+    if not any(
+        version_args := [i for i in session.posargs if i.startswith("--version=")]
+    ):
+        with open("pyproject.toml", "rb") as file:
+            version = version_tuple(tomllib.load(file)["project"]["version"])
+    else:
+        version = version_tuple(version_args[0].rpartition("=")[-1])
+
+    minor_str = ".".join(str(i) for i in version[:2])
+
+    remote = "--push" in session.posargs
+    remote_str = "remotely " if remote else ""
+    list_args = ("-b", "gh-pages") if remote else ()
+    deploy_args = ["--push", minor_str] if remote else [minor_str]
+
+    # Get deployed versions from branch
+    out = cast(str, session.run("mike", "list", *list_args, silent=True))
+    versions = [
+        tuple(int(i) for i in v.partition(" ")[0].split(".")) for v in out.splitlines()
+    ]
+
+    if version[:2] in versions:
+        print(f"Updating docs {remote_str}for version {minor_str}...")
+
+    elif all(version[:2] > v for v in versions):
+        print(f"Deploying docs {remote_str}for version {minor_str} as latest...")
+        deploy_args.extend(("--update-aliases", "latest"))
+    else:
+        print(f"Deploying docs {remote_str}for version {minor_str} as latest...")
+        deploy_args.append("latest")
 
-    session.run("twine", "upload", "dist/*")
+    print(f"Calling deploy with args: {deploy_args}")
+    # session.run("mike", "deploy", *deploy_args)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wpp-bavapi"
-version = "0.6.0"
+version = "0.6.1"
 authors = [
     { name = "Ignacio Maiz Vilches", email = "[email protected]" },
 ]
@@ -51,7 +51,7 @@ dependencies = [
 homepage = "https://github.com/wppbav/bavapi-sdk-python"
 
 [project.optional-dependencies]
-dev = ["black", "nox", "pip-tools", "pylint"]
+dev = ["black", "nox", "pip-tools"]
 doc = [
     "mkdocs",
     "mkdocs-material",
@@ -61,7 +61,7 @@ doc = [
     "mkdocs-section-index",
 ]
 test = ["coverage", "pytest", "pytest-asyncio", "python-dotenv"]
-lint = ["pylint", "mypy", "pandas-stubs"]
+lint = ["isort", "mypy", "pylint", "pandas-stubs"]
 
 [project.scripts]
 bavapi-gen-refs = "bavapi.reference.generate_reference:main"