contentgrid-hal-client 0.0.1__tar.gz

contentgrid_hal_client-0.0.1/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2024 Xenit Solutions
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

contentgrid_hal_client-0.0.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.1
+Name: contentgrid-hal-client
+Version: 0.0.1
+Summary: Python Client for interacting with HAL-forms application
+Author-email: Ranec Belpaire <ranec.belpaire@xenit.eu>
+License: Copyright 2024 Xenit Solutions
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+            http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.5
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests==2.31.0
+Requires-Dist: uri-template==1.3.0
+
+# HALFormsClient Library
+
+## Overview
+
+The `HALFormsClient` library provides a Python client for interacting with RESTful services that use the HAL (Hypertext Application Language) and HAL-Forms standards. This library simplifies the handling of HAL responses and their embedded resources, enabling easy navigation and interaction with APIs that follow the HAL and HAL-Forms specifications.
+
+## Features
+
+- Automatic token management for service accounts.
+- Robust retry mechanisms for HTTP requests.
+- Easy navigation of HAL links and embedded resources.
+- Support for CURIEs (Compact URIs) for compacting and expanding link relations.
+- Handling of common HTTP methods (`GET`, `POST`, `PATCH`, `DELETE`, `PUT`) with ease.
+- Validation and transformation of HAL links and URIs.
+- Customizable client configuration, including endpoint and authentication details.
+
+## Installation
+
+To install the library, use pip:
+
+```bash
+pip install contentgrid-hal-client
+```
+
+## Usage
+
+### Initialization
+
+To initialize the `HALFormsClient`, you need to provide the endpoint of the HAL service and optionally authentication details:
+
+```python
+from halformsclient import HALFormsClient
+
+# Initialize using service account
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+# Initialize using bearer token
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    token="your_token"
+)
+
+
+# Initialize using session cookie
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    session_cookie="your_session_cookie"
+)
+
+```
+
+### Fetching and Interacting with HAL Resources
+
+You can fetch a HAL resource and interact with it using the provided methods:
+
+```python
+# Fetch a resource by following a link
+resource = client.follow_link(HALLink(uri="/some/resource"))
+
+# Access metadata
+print(resource.metadata)
+
+# Access links
+links = resource.get_links("key")
+
+# Access embedded resources
+embedded_objects = resource.get_embedded_objects_by_key("embedded_key")
+
+# Update a resource with PUT or PATCH
+resource.put_data({"key": "value"})
+resource.patch_data({"key": "new_value"})
+
+# Delete a resource
+resource.delete()
+```
+
+### Handling CURIEs
+
+CURIEs (Compact URIs) are supported for compacting and expanding link relations:
+
+```python
+curie_registry = CurieRegistry(curies=[{"name": "ex", "href": "https://example.com/{rel}"}])
+expanded_uri = curie_registry.expand_curie("ex:some_relation")
+compact_uri = curie_registry.compact_curie("https://example.com/some_relation")
+```
+
+### Error Handling
+
+The library provides custom exceptions for common HTTP errors:
+
+```python
+from halformsclient.exceptions import BadRequest, Unauthorized
+
+try:
+    resource = client.follow_link(HALLink(uri="/some/invalid/resource"))
+except BadRequest as e:
+    print(f"Bad request: {str(e)}")
+except Unauthorized as e:
+    print(f"Unauthorized: {str(e)}")
+```

contentgrid_hal_client-0.0.1/README.md

@@ -0,0 +1,107 @@
+# HALFormsClient Library
+
+## Overview
+
+The `HALFormsClient` library provides a Python client for interacting with RESTful services that use the HAL (Hypertext Application Language) and HAL-Forms standards. This library simplifies the handling of HAL responses and their embedded resources, enabling easy navigation and interaction with APIs that follow the HAL and HAL-Forms specifications.
+
+## Features
+
+- Automatic token management for service accounts.
+- Robust retry mechanisms for HTTP requests.
+- Easy navigation of HAL links and embedded resources.
+- Support for CURIEs (Compact URIs) for compacting and expanding link relations.
+- Handling of common HTTP methods (`GET`, `POST`, `PATCH`, `DELETE`, `PUT`) with ease.
+- Validation and transformation of HAL links and URIs.
+- Customizable client configuration, including endpoint and authentication details.
+
+## Installation
+
+To install the library, use pip:
+
+```bash
+pip install contentgrid-hal-client
+```
+
+## Usage
+
+### Initialization
+
+To initialize the `HALFormsClient`, you need to provide the endpoint of the HAL service and optionally authentication details:
+
+```python
+from halformsclient import HALFormsClient
+
+# Initialize using service account
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+# Initialize using bearer token
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    token="your_token"
+)
+
+
+# Initialize using session cookie
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    session_cookie="your_session_cookie"
+)
+
+```
+
+### Fetching and Interacting with HAL Resources
+
+You can fetch a HAL resource and interact with it using the provided methods:
+
+```python
+# Fetch a resource by following a link
+resource = client.follow_link(HALLink(uri="/some/resource"))
+
+# Access metadata
+print(resource.metadata)
+
+# Access links
+links = resource.get_links("key")
+
+# Access embedded resources
+embedded_objects = resource.get_embedded_objects_by_key("embedded_key")
+
+# Update a resource with PUT or PATCH
+resource.put_data({"key": "value"})
+resource.patch_data({"key": "new_value"})
+
+# Delete a resource
+resource.delete()
+```
+
+### Handling CURIEs
+
+CURIEs (Compact URIs) are supported for compacting and expanding link relations:
+
+```python
+curie_registry = CurieRegistry(curies=[{"name": "ex", "href": "https://example.com/{rel}"}])
+expanded_uri = curie_registry.expand_curie("ex:some_relation")
+compact_uri = curie_registry.compact_curie("https://example.com/some_relation")
+```
+
+### Error Handling
+
+The library provides custom exceptions for common HTTP errors:
+
+```python
+from halformsclient.exceptions import BadRequest, Unauthorized
+
+try:
+    resource = client.follow_link(HALLink(uri="/some/invalid/resource"))
+except BadRequest as e:
+    print(f"Bad request: {str(e)}")
+except Unauthorized as e:
+    print(f"Unauthorized: {str(e)}")
+```

contentgrid_hal_client-0.0.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contentgrid-hal-client"
+dynamic = ["version"]
+description = "Python Client for interacting with HAL-forms application"
+readme = "README.md"
+authors = [{ name = "Ranec Belpaire", email = "ranec.belpaire@xenit.eu" }]
+license = { file = "LICENSE" }
+ 
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+]
+
+dependencies = [
+    "requests==2.31.0",
+    "uri-template==1.3.0",
+]
+
+requires-python = ">=3.5"
+
+[tool.setuptools_scm]
+write_to = "_version.txt"                                                                                                                                                                                                  
+root = "../"                                                                                                                                                                                                                   

contentgrid_hal_client-0.0.1/requirements.txt

@@ -0,0 +1,2 @@
+Requests==2.31.0
+uri-template==1.3.0

contentgrid_hal_client-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

contentgrid_hal_client-0.0.1/setup.py

@@ -0,0 +1,3 @@
+import setuptools 
+if __name__ == "__main__": 
+   setuptools.setup()

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client/__init__.py

@@ -0,0 +1 @@
+from .hal import HALLink, CurieRegistry, Curie, HALResponse, InteractiveHALResponse, HALFormsClient

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client/exceptions.py

@@ -0,0 +1,25 @@
+from requests.exceptions import HTTPError
+
+class NotFound(HTTPError):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
+class Unauthorized(HTTPError):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
+class BadRequest(HTTPError):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
+class IncorrectAttributeType(Exception):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
+class NonExistantAttribute(Exception):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
+class MissingRequiredAttribute(Exception):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client/hal.py

@@ -0,0 +1,362 @@
+from http import HTTPStatus
+from json import JSONDecodeError
+import json
+import logging
+import re
+from typing import List, Optional
+from urllib.parse import urljoin
+import uri_template
+import requests
+from requests.adapters import Retry, HTTPAdapter
+from .exceptions import BadRequest, Unauthorized
+from .token_utils import get_application_token
+
+class HALLink:
+    def __init__(self, uri: str, name: Optional[str] = None, title: Optional[str] = None, link_relation: Optional[str] = None) -> None:
+        self.name: Optional[str] = name
+        self.title: Optional[str] = title
+        self.uri: str = uri
+        self.link_relation = link_relation
+
+class CurieRegistry:
+    def __init__(self, curies: List[dict]) -> None:
+        self.curies = {
+            curie["name"]: Curie(curie["name"], curie["href"]) for curie in curies
+        }
+
+    def expand_curie(self, rel):
+        if ":" in rel:
+            prefix, suffix = rel.split(":", 1)
+            if prefix in self.curies.keys():
+                return uri_template.URITemplate(self.curies[prefix].url_template).expand(
+                    rel=suffix
+                )
+        return rel
+
+    def compact_curie(self, link: str):
+        for curie in self.curies.values():
+            variable_names = re.findall(r'{(.*?)}', curie.url_template)
+            pattern = re.sub(r'{(.*?)}', r'(?P<\g<1>>.+)',  curie.url_template)
+            match = re.match(pattern, link)
+            if match:
+                extracted_values = match.groupdict()
+                variable_map = {variable_names[i]: extracted_values[variable_names[i]] for i in range(len(variable_names))}
+                if "rel" in variable_map.keys():
+                    return f"{curie.prefix}:{variable_map['rel']}"
+        return link
+    
+class Curie:
+    def __init__(self, prefix: str, url_template: str) -> None:
+        assert uri_template.validate(template=url_template)
+        self.url_template = url_template
+        self.url_prefix = str(uri_template.URITemplate(url_template).expand(rel=''))
+        self.prefix = prefix
+
+class HALResponse:
+    def __init__(self, data: dict, curie_registry: CurieRegistry = None) -> None:
+        self.data: dict = data
+        self.links: dict = data.get("_links", None)
+        if self.links == None:
+            logging.warning(f"HALresponse [type {type(self)}] did not have a _links field.")
+        if self.links and "curies" in self.links.keys():
+            self.curie_registry: CurieRegistry = CurieRegistry(self.links["curies"])
+        elif curie_registry != None:
+            self.curie_registry: CurieRegistry = curie_registry
+        else:
+            self.curie_registry = CurieRegistry(curies=[])
+        
+        self.embedded: dict = data.get("_embedded", None)
+        self.templates: dict = data.get("_templates", None)
+        self.metadata = {
+            key: value
+            for key, value in data.items()
+            if not key.startswith("_")
+        }
+
+    def has_link(self, linkrel : str) -> bool:
+        return len(self.get_links(linkrel=linkrel)) > 0
+    
+    def get_link(self, linkrel: str) -> HALLink:
+        if self.has_link(linkrel=linkrel):
+            if linkrel in self.links.keys():
+                value = self.links[linkrel]
+                if type(value) == list:
+                    raise Exception(f"Linkrel {linkrel} was multivalued. Use get_links instead.")
+            return self.get_links(linkrel=linkrel)[0]
+        else:
+            return None
+
+    def get_links(self, linkrel: str) -> List[HALLink]:
+        full_linkrel = linkrel
+        # compact linkrel if curie registry is available.
+        if self.curie_registry:
+            linkrel = self.curie_registry.compact_curie(linkrel)
+
+        if linkrel in self.links.keys():
+            value = self.links[linkrel]
+            if type(value) == list:
+                return [
+                    HALLink(
+                        name=v.get("name", None),
+                        title=v.get("title", None),
+                        uri=v["href"],
+                        link_relation=full_linkrel
+                    )
+                    for v in value
+                ]
+            elif type(value) == dict:
+                return [ 
+                    HALLink(
+                        name=value.get("name", None),
+                        title=value.get("title", None),
+                        uri=value["href"],
+                        link_relation=full_linkrel
+                    )
+                ]
+                
+            else:
+                raise Exception(f"Unkown HALLINK type {type(value)}")
+        else:
+            return []
+    
+    def get_embedded_objects_by_key(self, key : str, infer_type:type = None) -> Optional[List["HALResponse"]]:
+        if self.embedded:
+            if not infer_type:
+                infer_type = HALResponse
+            return [
+                infer_type(data=v, curie_registry=self.curie_registry)
+                for v in self.embedded[self.curie_registry.compact_curie(key)]
+            ]
+        else:
+            return []
+
+    def get_self_link(self) -> HALLink:
+        return self.get_link("self")
+    
+    def __str__(self) -> str:
+        return json.dumps(self.data, indent=4)
+    
+class InteractiveHALResponse(HALResponse):
+    def __init__(self, data: dict, client: "HALFormsClient", curie_registry: CurieRegistry = None) -> None:
+        super().__init__(data, curie_registry)
+        self.client : "HALFormsClient" = client
+
+    def get_embedded_objects_by_key(self, key, infer_type:type = None) -> Optional[List[HALResponse]]:
+        if self.embedded:
+            if not infer_type:
+                infer_type = InteractiveHALResponse
+
+            if issubclass(infer_type, InteractiveHALResponse):
+                return [
+                    infer_type(data=v, client=self.client, curie_registry=self.curie_registry)
+                    for v in self.embedded[self.curie_registry.compact_curie(key)]
+                ]
+            else:
+                return [
+                    infer_type(data=v, curie_registry=self.curie_registry)
+                    for v in self.embedded[self.curie_registry.compact_curie(key)]
+                ]
+        else:
+            return []
+        
+    # Common operations
+    def refetch(self):
+        response = self.client.follow_link(self.get_self_link())
+        self.__init__(data=response.data, client=self.client, curie_registry=self.curie_registry)
+
+    def delete(self):
+        response = self.client.delete(self.get_self_link().uri)
+        self.client._validate_non_json_response(response)
+
+    def put_data(self, data : dict) -> None:
+        response = self.client.put(self.get_self_link().uri, json=data, headers={"Content-Type" : "application/json"})
+        data = self.client._validate_json_response(response)
+        # Reintialize class based on response data
+        self.__init__(data=data, client=self.client, curie_registry=self.curie_registry)
+
+    def patch_data(self, data : dict) -> None:
+        response = self.client.patch(self.get_self_link().uri, json=data, headers={"Content-Type" : "application/json"})
+        data = self.client._validate_json_response(response)
+        # Reintialize class based on response data
+        self.__init__(data=data, client=self.client, curie_registry=self.curie_registry)
+
+
+class HALFormsClient(requests.Session):
+    def __init__(self,
+        client_endpoint: str,
+        auth_uri: str = None,
+        client_id: str = None,
+        client_secret: str = None,
+        token: str = None,
+        session_cookie : str = None,
+        pool_maxsize : int = 10,
+    ) -> None:
+        super().__init__()
+        self.token = token
+        self.session_cookie = session_cookie.replace("SESSION=","") if session_cookie else None
+
+        self.client_endpoint = client_endpoint
+        self.auth_uri = auth_uri
+
+        # Retries requests for status_forcelist response codes with backoff factor increasing wait time between each request
+        retries = Retry(total=5,
+                backoff_factor=0.2,
+                status_forcelist=[ 500, 502, 503, 504 ])
+        
+        self.mount('http://', HTTPAdapter(max_retries=retries, pool_maxsize=pool_maxsize))
+
+        # Service account
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+        self.has_service_account = self.client_id and self.client_secret
+
+        logging.info(f"ContentGrid deployment endpoint: {self.client_endpoint}")
+        logging.info(f"ContentGrid Auth URI: {self.auth_uri}")
+        if self.has_service_account:
+            logging.info(f"ContentGrid service account used...")
+            logging.info(
+                f"\t - Client id: {self.client_id}, Client secret: {self.client_secret[:4]}****..."
+            )
+            if not self.auth_uri:
+                raise Exception("Auth URI is required when using a service account")
+            logging.info("Fetching session token...")
+            self.headers["Authorization"] = (
+                f"Bearer {get_application_token(auth_uri=self.auth_uri, client_id=self.client_id, client_secret=self.client_secret)}"
+            )
+        elif self.token:
+            self.headers["Authorization"] = f"Bearer {self.token}"
+        elif self.session_cookie:
+            self.cookies.set(name="SESSION", value=self.session_cookie)
+        else:
+            raise Exception("Token or Service account (client_id & client_secret) is required.")
+        
+        self.headers["Accept"] = "application/prs.hal-forms+json"
+        logging.info(f"Client Cookies : {self.cookies.items()}")
+
+    def _transform_hal_links_to_uris(self, attributes : dict) -> None:
+        for attribute, value in attributes.items():
+            if isinstance(value, list):
+                for i, v in enumerate(value):
+                    if isinstance(v, HALLink):
+                        attributes[attribute][i] = v.uri
+            else:
+                if isinstance(value, HALLink):
+                    attributes[attribute] = value.uri
+
+    def _create_text_uri_list_payload(self, links : List[str | HALLink | HALResponse]) -> str:
+        uri_list = []
+        for link in links:
+            if isinstance(link, HALLink):
+                uri_list.append(link.uri)
+            elif isinstance(link, HALResponse):
+                uri_list.append(link.get_self_link().uri)
+            elif isinstance(link, str):
+                uri_list.append(link)
+            else:
+                raise BadRequest(f"Incorrect Link type {type(link)} in uri list payload, allowed types: HALLink, HALResponse or str")
+        return "\n".join(uri_list)
+
+    def _validate_non_json_response(self, response: requests.Response) -> requests.Response:
+        self._raise_for_status(response)
+        return response
+    
+    def _validate_json_response(self, response: requests.Response) -> dict | str:
+        self._raise_for_status(response)
+        if response.status_code < 300:
+            try:
+                return response.json()
+            except JSONDecodeError as e:
+                logging.error(f"Failed to parse JSON, error: {str(e)}")
+                return response.content
+    
+    def _raise_for_status(self, response: requests.Response):
+        """Raises :class:`HTTPError`, if one occurred."""
+
+        http_error_msg = ""
+        if hasattr(response, "reason") and isinstance(response.reason, bytes):
+            # We attempt to decode utf-8 first because some servers
+            # choose to localize their reason strings. If the string
+            # isn't utf-8, we fall back to iso-8859-1 for all other
+            # encodings. (See PR #3538)
+            try:
+                reason = response.reason.decode("utf-8")
+            except UnicodeDecodeError:
+                reason = response.reason.decode("iso-8859-1")
+        else:
+            if hasattr(response, "reason"):
+                reason = response.reason
+            else:
+                reason = "reason unknown"
+
+        if 400 <= response.status_code < 500:
+            http_error_msg = (
+                f"{response.status_code} Client Error: {reason} for url: {response.url}. response: {response.text}"
+            )
+
+        elif 500 <= response.status_code < 600:
+            http_error_msg = (
+                f"{response.status_code} Server Error: {reason} for url: {response.url}. response: {response.text}"
+            )
+
+        if http_error_msg:
+            raise requests.HTTPError(http_error_msg, response=self)
+        
+
+    def _add_page_and_size_to_params(self, page, size , params):
+        # Check if params does not contain page or size, if not set it to page and size (or defaults)
+        # params dict has precendence over page and size variables
+        if not "page" in params.keys():
+            params["page"] = page
+        if not "size" in params.keys():
+            params["size"] = size
+        return params
+
+    def request(self, method, url, *args, **kwargs) -> requests.Response:
+        logging.debug(f"{method} - {urljoin(self.client_endpoint, url)}")
+        if "params" in kwargs:
+            logging.debug(f"params: {kwargs['params']}")
+        if "json" in kwargs:
+            logging.debug(f"Json payload: {json.dumps(kwargs['json'], indent=4)}")
+        response = super().request(
+            method, urljoin(self.client_endpoint, url), *args, **kwargs
+        )
+        if response.status_code == 401:
+            if (
+                "WWW-Authenticate" in response.headers.keys()
+                and "invalid_token" in response.headers["WWW-Authenticate"]
+            ):
+                logging.warning("ContentGrid authorization token expired.")
+                if self.has_service_account:
+                    logging.debug("Refreshing token...")
+                    self.headers["Authorization"] = (
+                        f"Bearer {get_application_token(auth_uri=self.auth_uri, client_id=self.client_id, client_secret=self.client_secret)}"
+                    )
+                    response = super().request(
+                        method, urljoin(self.client_endpoint, url), *args, **kwargs
+                    )
+                else:
+                    raise Unauthorized("Token invalid!")
+        return response
+    
+    def follow_link(self, link: "HALLink", expect_json: bool = True, infer_type: type=HALResponse, params={}) -> HALResponse | str:
+        response = self.get(link.uri, params=params)
+        if expect_json:
+            if issubclass(infer_type, InteractiveHALResponse):
+                return infer_type(self._validate_json_response(response=response), client=self)
+            return infer_type(self._validate_json_response(response=response))
+        else:
+            self._validate_non_json_response(response=response)
+            return response.content
+        
+    def get_method_from_string(self, http_method:str):
+        method_dict = {
+            "GET" : self.get,
+            "POST" : self.post,
+            "PATCH" : self.patch,
+            "DELETE" : self.delete,
+            "PUT" : self.put
+        }
+        if http_method not in method_dict.keys():
+            raise Exception(f"Unkown method from HAL-forms: {http_method}")
+        return method_dict[http_method]

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client/token_utils.py

@@ -0,0 +1,81 @@
+'''
+Utilities for requesting and handling access tokens.
+'''
+import requests as re
+
+class TokenData():
+    '''
+    Token data for requesting an access token.
+
+    - scope: The scope of the token.
+    - grant_type: The grant type of the token.
+    - client_id: The client ID of the application.
+    - client_secret: The client secret of the application.
+    '''
+    def __init__(self, scope: str, grant_type: str, client_id: str, client_secret: str) -> None:
+        '''
+        Initialize a TokenData with the following parameters:
+
+        - scope: The scope of the token.
+        - grant_type: The grant type of the token.
+        - client_id: The client ID of the application.
+        - client_secret: The client secret of the application.
+        '''
+        self.scope = scope
+        self.grant_type = grant_type
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+    def to_dict(self) -> dict:
+        '''
+        Get the token data as a dictionary.
+
+        Returns the token data as a dictionary.
+        '''
+        return {
+            "scope": self.scope,
+            "grant_type": self.grant_type,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret
+        }
+
+
+def request_token(uri: str, data: TokenData) -> str:
+    '''
+    Given a URI and token data, request an access token.
+
+    - uri: The URI to request the access token from.
+    - data: The token data to use for the request.
+
+    Returns the access token.
+    '''
+    headers = {
+        'Content-Type': 'application/x-www-form-urlencoded'
+    }
+    data = data.to_dict()
+    res = re.post(uri, headers=headers, data=data)
+    
+    if res.status_code != 200:
+        raise Exception(f'Failed to request token. Status code: {res.status_code}. Reason: {res.reason}')
+    else:
+        return res.json()['access_token']
+
+
+def get_application_token(auth_uri: str, client_id: str, client_secret: str) -> str:
+    '''
+    Get an application token for the given client ID and client secret.
+
+    - auth_uri: The authorization URI of the application.
+    - client_id: The client ID of the application.
+    - client_secret: The client secret of the application.
+
+    Returns the application token.
+    '''
+    token_data = TokenData(
+        scope='email',
+        grant_type='client_credentials',
+        client_id=client_id,
+        client_secret=client_secret
+    )
+    acces_token = request_token(auth_uri, token_data)
+    return acces_token

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.1
+Name: contentgrid-hal-client
+Version: 0.0.1
+Summary: Python Client for interacting with HAL-forms application
+Author-email: Ranec Belpaire <ranec.belpaire@xenit.eu>
+License: Copyright 2024 Xenit Solutions
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+            http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.5
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests==2.31.0
+Requires-Dist: uri-template==1.3.0
+
+# HALFormsClient Library
+
+## Overview
+
+The `HALFormsClient` library provides a Python client for interacting with RESTful services that use the HAL (Hypertext Application Language) and HAL-Forms standards. This library simplifies the handling of HAL responses and their embedded resources, enabling easy navigation and interaction with APIs that follow the HAL and HAL-Forms specifications.
+
+## Features
+
+- Automatic token management for service accounts.
+- Robust retry mechanisms for HTTP requests.
+- Easy navigation of HAL links and embedded resources.
+- Support for CURIEs (Compact URIs) for compacting and expanding link relations.
+- Handling of common HTTP methods (`GET`, `POST`, `PATCH`, `DELETE`, `PUT`) with ease.
+- Validation and transformation of HAL links and URIs.
+- Customizable client configuration, including endpoint and authentication details.
+
+## Installation
+
+To install the library, use pip:
+
+```bash
+pip install contentgrid-hal-client
+```
+
+## Usage
+
+### Initialization
+
+To initialize the `HALFormsClient`, you need to provide the endpoint of the HAL service and optionally authentication details:
+
+```python
+from halformsclient import HALFormsClient
+
+# Initialize using service account
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+# Initialize using bearer token
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    token="your_token"
+)
+
+
+# Initialize using session cookie
+client = HALFormsClient(
+    client_endpoint="https://api.example.com",
+    auth_uri="https://auth.example.com",
+    session_cookie="your_session_cookie"
+)
+
+```
+
+### Fetching and Interacting with HAL Resources
+
+You can fetch a HAL resource and interact with it using the provided methods:
+
+```python
+# Fetch a resource by following a link
+resource = client.follow_link(HALLink(uri="/some/resource"))
+
+# Access metadata
+print(resource.metadata)
+
+# Access links
+links = resource.get_links("key")
+
+# Access embedded resources
+embedded_objects = resource.get_embedded_objects_by_key("embedded_key")
+
+# Update a resource with PUT or PATCH
+resource.put_data({"key": "value"})
+resource.patch_data({"key": "new_value"})
+
+# Delete a resource
+resource.delete()
+```
+
+### Handling CURIEs
+
+CURIEs (Compact URIs) are supported for compacting and expanding link relations:
+
+```python
+curie_registry = CurieRegistry(curies=[{"name": "ex", "href": "https://example.com/{rel}"}])
+expanded_uri = curie_registry.expand_curie("ex:some_relation")
+compact_uri = curie_registry.compact_curie("https://example.com/some_relation")
+```
+
+### Error Handling
+
+The library provides custom exceptions for common HTTP errors:
+
+```python
+from halformsclient.exceptions import BadRequest, Unauthorized
+
+try:
+    resource = client.follow_link(HALLink(uri="/some/invalid/resource"))
+except BadRequest as e:
+    print(f"Bad request: {str(e)}")
+except Unauthorized as e:
+    print(f"Unauthorized: {str(e)}")
+```

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+requirements.txt
+setup.py
+src/contentgrid_hal_client/__init__.py
+src/contentgrid_hal_client/exceptions.py
+src/contentgrid_hal_client/hal.py
+src/contentgrid_hal_client/token_utils.py
+src/contentgrid_hal_client.egg-info/PKG-INFO
+src/contentgrid_hal_client.egg-info/SOURCES.txt
+src/contentgrid_hal_client.egg-info/dependency_links.txt
+src/contentgrid_hal_client.egg-info/requires.txt
+src/contentgrid_hal_client.egg-info/top_level.txt
+tests/test_hal.py

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests==2.31.0
+uri-template==1.3.0

contentgrid_hal_client-0.0.1/src/contentgrid_hal_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+contentgrid_hal_client

contentgrid_hal_client-0.0.1/tests/test_hal.py

@@ -0,0 +1,163 @@
+import os
+from dotenv import load_dotenv
+import pytest
+from contentgrid_hal_client import HALFormsClient, HALResponse, InteractiveHALResponse, HALLink, CurieRegistry
+from unittest.mock import patch, MagicMock
+
+load_dotenv(override=True)
+load_dotenv(".env.secret", override=True)
+
+CONTENTGRID_CLIENT_ENDPOINT = os.getenv("CONTENTGRID_CLIENT_ENDPOINT")
+CONTENTGRID_AUTH_URI = os.getenv("CONTENTGRID_AUTH_URI")
+
+# Service account
+CONTENTGRID_CLIENT_ID = os.getenv("CONTENTGRID_CLIENT_ID")
+CONTENTGRID_CLIENT_SECRET = os.getenv("CONTENTGRID_CLIENT_SECRET")
+
+
+@pytest.fixture
+def hal_client():
+    return HALFormsClient(
+        client_endpoint=CONTENTGRID_CLIENT_ENDPOINT,
+        auth_uri=CONTENTGRID_AUTH_URI,
+        client_id=CONTENTGRID_CLIENT_ID,
+        client_secret=CONTENTGRID_CLIENT_SECRET,
+    )
+
+
+def test_hal_client_initialization(hal_client: HALFormsClient):
+    assert hal_client.client_endpoint == CONTENTGRID_CLIENT_ENDPOINT
+    assert hal_client.auth_uri == CONTENTGRID_AUTH_URI
+    assert hal_client.client_id == CONTENTGRID_CLIENT_ID
+    assert hal_client.client_secret == CONTENTGRID_CLIENT_SECRET
+    assert hal_client.headers["Accept"] == "application/prs.hal-forms+json"
+
+
+def test_hal_link():
+    link = HALLink(uri="https://api.example.com/resource", name="resource", title="Resource")
+    assert link.uri == "https://api.example.com/resource"
+    assert link.name == "resource"
+    assert link.title == "Resource"
+
+
+def test_curie_registry():
+    curies = [{"name": "ex", "href": "https://api.example.com/rels/{rel}"}]
+    registry = CurieRegistry(curies)
+    expanded = registry.expand_curie("ex:resource")
+    assert expanded == "https://api.example.com/rels/resource"
+    compacted = registry.compact_curie("https://api.example.com/rels/resource")
+    assert compacted == "ex:resource"
+
+
+def test_hal_response_initialization():
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"},
+            "curies": [{"name": "ex", "href": "https://api.example.com/rels/{rel}"}]
+        },
+        "_embedded": {},
+        "_templates": {},
+        "metadata": "value"
+    }
+    response = HALResponse(data)
+    assert response.data == data
+    assert response.links == data["_links"]
+    assert response.embedded == data["_embedded"]
+    assert response.templates == data["_templates"]
+    assert response.metadata == {"metadata": "value"}
+
+
+def test_hal_response_has_link():
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"}
+        }
+    }
+    response = HALResponse(data)
+    assert response.has_link("self") is True
+    assert response.has_link("nonexistent") is False
+
+
+def test_hal_response_get_link():
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"}
+        }
+    }
+    response = HALResponse(data)
+    link = response.get_link("self")
+    assert link.uri == "https://api.example.com/resource"
+    assert response.get_link("nonexistent") is None
+
+
+def test_hal_response_get_links():
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"},
+            "multiple": [
+                {"href": "https://api.example.com/resource1"},
+                {"href": "https://api.example.com/resource2"}
+            ]
+        }
+    }
+    response = HALResponse(data)
+    links = response.get_links("multiple")
+    assert len(links) == 2
+    assert links[0].uri == "https://api.example.com/resource1"
+    assert links[1].uri == "https://api.example.com/resource2"
+
+
+@patch.object(HALFormsClient, 'request', return_value=MagicMock(status_code=200, json=lambda: {}))
+def test_interactive_hal_response_refetch(mock_request, hal_client: HALFormsClient):
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"}
+        }
+    }
+    response = InteractiveHALResponse(data, hal_client)
+    response.refetch()
+    assert mock_request.called
+    assert mock_request.call_args[0] == ('GET', 'https://api.example.com/resource')
+
+
+@patch.object(HALFormsClient, 'request', return_value=MagicMock(status_code=204))
+def test_interactive_hal_response_delete(mock_request, hal_client: HALFormsClient):
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"}
+        }
+    }
+    response = InteractiveHALResponse(data, hal_client)
+    response.delete()
+    assert mock_request.called
+    assert mock_request.call_args[0] == ('DELETE', 'https://api.example.com/resource')
+
+
+@patch.object(HALFormsClient, 'request', return_value=MagicMock(status_code=200, json=lambda: {}))
+def test_interactive_hal_response_put_data(mock_request, hal_client: HALFormsClient):
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"}
+        }
+    }
+    response = InteractiveHALResponse(data, hal_client)
+    new_data = {"key": "value"}
+    response.put_data(new_data)
+    assert mock_request.called
+    assert mock_request.call_args[0] == ('PUT', 'https://api.example.com/resource')
+    assert mock_request.call_args[1]['json'] == new_data
+
+
+@patch.object(HALFormsClient, 'request', return_value=MagicMock(status_code=200, json=lambda: {}))
+def test_interactive_hal_response_patch_data(mock_request, hal_client: HALFormsClient):
+    data = {
+        "_links": {
+            "self": {"href": "https://api.example.com/resource"}
+        }
+    }
+    response = InteractiveHALResponse(data, hal_client)
+    new_data = {"key": "value"}
+    response.patch_data(new_data)
+    assert mock_request.called
+    assert mock_request.call_args[0] == ('PATCH', 'https://api.example.com/resource')
+    assert mock_request.call_args[1]['json'] == new_data