[Feat/documentation] Docs for federation package (#198)

* feat: added policy apply on metadata

* test: added intial tests for TrustEvaluationHelper

* fix: fixed validation issues

* feat: implemented method add_trust_attestation_metadata

* test: added test for add_trust_attestation_metadata

* fix: added metadata association by metadata_type field

* fix: minor fix to test for add_trust_attestation_metadata's data type

* chore: renamed test file

* chore: Removed comment

* fix: fixed x509 verification exception handling

* chore: fix typo

* fix: merged federation and metadata policy implementation

* test: adapted tests

* feat: added final_metadata property

* feat: added chain discovery plus refactoring

* docs: documented file class and functions

* fix: fixed trust_anchor_entity_conf handling

* docs: documented trust_chain_builder.py

* fix: moved implementation of get_http_url in utils.py

* fix: fixed response handling

* docs: documented file class and function plus refactoring

* docs: documented file __init__.py

* docs: added docs for http_client.py

---------

Co-authored-by: Giuseppe De Marco <giuseppe.demarco@teamdigitale.governo.it>

pyeudiw/federation/__init__.py

@@ -1,6 +1,16 @@
 from pyeudiw.federation.schemas.entity_configuration import EntityStatementPayload, EntityConfigurationPayload
 
 def is_es(payload: dict) -> bool:
+    """
+    Determines if payload dict is an Entity Statement
+
+    :param payload: the object to determine if is an Entity Statement
+    :type payload: dict
+
+    :returns: True if is an Entity Statement and False otherwise
+    :rtype: bool
+    """
+
     try:
         EntityStatementPayload(**payload)
         if payload["iss"] != payload["sub"]:
@@ -10,6 +20,16 @@ def is_es(payload: dict) -> bool:
 
 
 def is_ec(payload: dict) -> bool:
+    """
+    Determines if payload dict is an Entity Configuration
+
+    :param payload: the object to determine if is an Entity Configuration
+    :type payload: dict
+
+    :returns: True if is an Entity Configuration and False otherwise
+    :rtype: bool
+    """
+
     try:
         EntityConfigurationPayload(**payload)
         return True

pyeudiw/federation/http_client.py

@@ -3,15 +3,43 @@
 import requests
 
 
-async def fetch(session, url, httpc_params: dict):
+async def fetch(session: dict, url: str, httpc_params: dict) -> str:
+    """
+    Fetches the content of a URL.
+
+    :param session: a dict representing the current session
+    :type session: dict
+    :param url: the url where fetch the content
+    :type url: str
+    :param httpc_params: parameters to perform http requests.
+    :type httpc_params: dict
+
+    :returns: the response in string format
+    :rtype: str
+    """
+
     async with session.get(url, **httpc_params.get("connection", {})) as response:
         if response.status != 200:  # pragma: no cover
             # response.raise_for_status()
             return ""
         return await response.text()
 
 
-async def fetch_all(session, urls, httpc_params: dict):
+async def fetch_all(session: dict, urls: list[str], httpc_params: dict) -> list[str]:
+    """
+    Fetches the content of a list of URL.
+
+    :param session: a dict representing the current session
+    :type session: dict
+    :param urls: the url list where fetch the content
+    :type urls: list[str]
+    :param httpc_params: parameters to perform http requests.
+    :type httpc_params: dict
+
+    :returns: the list of responses in string format
+    :rtype: list[str]
+    """
+
     tasks = []
     for url in urls:
         task = asyncio.create_task(fetch(session, url, httpc_params))
@@ -21,7 +49,19 @@ async def fetch_all(session, urls, httpc_params: dict):
 
 
 async def http_get(urls, httpc_params: dict, sync=True):
+    """
+    Perform a GET http call.
+
+    :param session: a dict representing the current session
+    :type session: dict
+    :param urls: the url list where fetch the content
+    :type urls: list[str]
+    :param httpc_params: parameters to perform http requests.
+    :type httpc_params: dict
 
+    :returns: the list of responses in string format
+    :rtype: list[str]
+    """
     if sync:
         _conf = {
             'verify': httpc_params['connection']['ssl'],