feat: add rudimentary support for folksonomy tags

This adds initial basic CRUD methods for folksonomy tags centered
around products.

Author: Freso

openfoodfacts/api.py

@@ -2,7 +2,7 @@
 import logging
 import warnings
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional, Tuple, Union
+from typing import Any, Dict, List, Literal, Optional, Sequence, Tuple, Union
 
 import requests
 
@@ -214,6 +214,131 @@ def get_products(
         ).json()
 
 
+class FolksonomyResource:
+    def __init__(self, api_config: APIConfig):
+        self.api_config: APIConfig = api_config
+        self.base_url = URLBuilder.folksonomy(environment=self.api_config.environment)
+
+    def get(
+        self,
+        code: str,
+        owner: str | None = None,
+        keys: Sequence | str | None = None,
+    ) -> requests.Response:
+        """Retrieve folksonomy tags for a product.
+
+        :param code: the product barcode
+        :param owner: the tag owner; requires authentication as that user.
+            Case-sensitive. Leave empty for public tags (default).
+        :param keys: List of keys to filter by. Can be provided as either
+            a Python sequence (list, set, tuple, ...) or as
+            a comma-separated string.
+            If None (the default), all keys are returned.
+        :return: the API response"""
+        params: dict[str, str] = dict()
+        if owner:
+            params["owner"] = owner
+        if keys:
+            if not isinstance(keys, str):
+                keys = ",".join(keys)
+            params["keys"] = keys
+        return send_request(
+            url=f"{self.base_url}/product/{code}",
+            api_config=self.api_config,
+            method="get",
+            params=params,
+        )
+
+    def add(
+        self,
+        code: str,
+        key: str,
+        value: str,
+        version: Literal[1, None] = None,
+        owner: str | None = None,
+    ) -> requests.Response:
+        """Add a folksonomy tag to a product.
+
+        :param code: the product barcode
+        :param key: the key for the tag
+        :param value: the value to set for the tag
+        :param version: version of the tag. Should be None or 1.
+        :param owner: the tag owner; requires authentication as that user.
+            Case-sensitive. Leave empty for public tags (default).
+        :return: the API response"""
+        params: dict[str, str | int] = dict()
+        params["code"] = code
+        params["k"] = key
+        params["v"] = value
+        if version:
+            params["version"] = version
+        if owner:
+            params["owner"] = owner
+        return send_request(
+            url=f"{self.base_url}/product",
+            api_config=self.api_config,
+            method="post",
+            json=params,
+        )
+
+    def update(
+        self,
+        code: str,
+        key: str,
+        value: str,
+        version: int,
+        owner: str | None = None,
+    ) -> requests.Response:
+        """Update a folksonomy tag on a product.
+
+        :param code: the product barcode
+        :param key: the key for the tag
+        :param value: the value to set for the tag
+        :param version: must be equal to previous version + 1
+        :param owner: the tag owner; requires authentication as that user.
+            Case-sensitive. Leave empty for public tags (default).
+        :return: the API response"""
+        params: dict[str, str | int] = dict()
+        params["code"] = code
+        params["k"] = key
+        params["v"] = value
+        params["version"] = version
+        if owner:
+            params["owner"] = owner
+        return send_request(
+            url=f"{self.base_url}/product",
+            api_config=self.api_config,
+            method="put",
+            json=params,
+        )
+
+    def delete(
+        self,
+        code: str,
+        key: str,
+        version: int,
+        owner: str | None = None,
+    ) -> requests.Response:
+        """Delete a folksonomy tag on a product.
+
+        :param code: the product barcode
+        :param key: the key to delete
+        :param version: the version the tag is at
+        :param owner: the tag owner; requires authentication as that user.
+            Case-sensitive. Leave empty for public tags (default).
+        :return: the API response"""
+        params: dict[str, str | int] = dict()
+        params["version"] = version
+        if owner:
+            params["owner"] = owner
+        return send_request(
+            url=f"{self.base_url}/product/{code}/{key}",
+            api_config=self.api_config,
+            method="delete",
+            params=params,
+        )
+
+
 class ProductResource:
     def __init__(self, api_config: APIConfig):
         self.api_config = api_config
@@ -636,6 +761,7 @@ def __init__(
         self.country = country
         self.product = ProductResource(self.api_config)
         self.facet = FacetResource(self.api_config)
+        self.folksonomy = FolksonomyResource(self.api_config)
         self.robotoff = RobotoffResource(self.api_config)
 
 

openfoodfacts/utils/__init__.py

@@ -126,6 +126,28 @@ def country(flavor: Flavor, environment: Environment, country_code: str) -> str:
             base_domain=flavor.get_base_domain(),
         )
 
+    @staticmethod
+    def folksonomy(environment: Environment) -> str:
+        """Get API endpoint URL for the Folksonomy Engine.
+
+        Note that this method will always return the "openfoodfacts.org" top domain as
+            SDK users don't need to worry about cookie domains for authentication.
+            This endpoint is project agnostic and will work for all the projects.
+
+        Example use:
+        >>> print(URLBuilder.folksonomy(Environment.net))
+        "https://api.folksonomy.openfoodfacts.net"
+
+        :param environment: Whether to use the production (Environment.org)
+            or staging (Environment.net) environment.
+        :return: The Folksonomy Engine's API endpoint URL as a string.
+        """
+        return URLBuilder._get_url(
+            prefix="api.folksonomy",
+            tld=environment.value,
+            base_domain=Flavor.off.get_base_domain(),
+        )
+
 
 def jsonl_iter(jsonl_path: Union[str, Path]) -> Iterable[Dict]:
     """Iterate over elements of a JSONL file.