mosaic-python-client 0.2.0__py3-none-any.whl

mosaic_client/gpas/client.py

@@ -0,0 +1,342 @@
+"""
+This module contains functions for interacting with the gPAS SOAP interface.
+"""
+
+from zeep import Client
+
+from mosaic_client.gpas.models import Domain, DomainResponse
+from mosaic_client.gpas.schemas import DomainResponseSchema, DomainSchema
+from mosaic_client.helpers import WSDLClient, _cast_client, _read_key_value_list, _serialize_dict
+
+KeyValueTuple = tuple[str, str]
+
+
+def delete_entry(client: Client, domain_name: str, value: str) -> None:
+    """
+    Deletes a value and its associated pseudonym from the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the value is present
+    :param value: value to remove
+    """
+    client.service.deleteEntry(domainName=domain_name, value=value)
+
+
+def delete_entries(client: Client, domain_name: str, values: list[str]) -> list[KeyValueTuple]:
+    """
+    Deletes a list of values and their associated pseudonyms from the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the value is present
+    :param values: list of values to remove
+    :return: list of key-value pairs where the key is the value that was requested to be deleted, and the value is
+    an indicator whether deletion was successful or not
+    """
+    response = client.service.deleteEntries(domainName=domain_name, values=values)
+    return _read_key_value_list(_serialize_dict(response))
+
+
+def get_or_create_pseudonym_for(client: Client, domain_name: str, value: str) -> str:
+    """
+    Requests a new pseudonym for a value in the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the value is supposed to be inserted
+    :param value: value to insert
+    :return: pseudonym that is assigned to the value
+    """
+    return client.service.getOrCreatePseudonymFor(domainName=domain_name, value=value)
+
+
+def get_or_create_pseudonym_for_list(client: Client, domain_name: str, values: list[str]) -> list[KeyValueTuple]:
+    """
+    Request new pseudonyms for a list of values in the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the value is supposed to be inserted
+    :param values: list of values to insert
+    :return: list of key-value pairs where the key is the original value that is supposed to be pseudonymized,
+    and the value is the assigned pseudonym
+    """
+    response = client.service.getOrCreatePseudonymForList(domainName=domain_name, values=values)
+    return _read_key_value_list(_serialize_dict(response))
+
+
+def get_value_for(client: Client, domain_name: str, pseudonym: str) -> str:
+    """
+    Gets the value for a pseudonym in the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the pseudonym is present
+    :param pseudonym: pseudonym to resolve
+    :return: value assigned to the pseudonym
+    """
+    return client.service.getValueFor(domainName=domain_name, psn=pseudonym)
+
+
+def get_value_for_list(client: Client, domain_name: str, pseudonyms: list[str]) -> list[KeyValueTuple]:
+    """
+    Gets the values for a list of pseudonyms in the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the pseudonyms are present
+    :param pseudonyms: pseudonyms to resolve
+    :return: list of key-value pairs, structured as { pseudonym => value }
+    """
+    response = client.service.getValueForList(domainName=domain_name, psnList=pseudonyms)
+    return _read_key_value_list(_serialize_dict(response))
+
+
+def get_pseudonym_for(client: Client, domain_name: str, value: str) -> str:
+    """
+    Gets the pseudonym for a value in the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the value is present
+    :param value: value to resolve
+    :return: pseudonym assigned to the value
+    """
+    return client.service.getPseudonymFor(domainName=domain_name, value=value)
+
+
+def get_pseudonym_for_list(client: Client, domain_name: str, values: list[str]) -> list[KeyValueTuple]:
+    """
+    Gets the pseudonyms for a list of values in the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain where the values are present
+    :param values: values to resolve
+    :return: list of key-value pairs, structured as { value => pseudonym }
+    """
+    response = client.service.getPseudonymForList(domainName=domain_name, values=values)
+    return _read_key_value_list(_serialize_dict(response))
+
+
+def insert_value_pseudonym_pair(client: Client, domain_name: str, value: str, pseudonym: str) -> None:
+    """
+    Manually inserts a value and a pseudonym into the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain to insert the pair into
+    :param value: value to add
+    :param pseudonym: pseudonym to assign to the value
+    """
+    client.service.insertValuePseudonymPair(domainName=domain_name, value=value, pseudonym=pseudonym)
+
+
+def insert_value_pseudonym_pairs(client: Client, domain_name: str, pairs: list[KeyValueTuple]) -> None:
+    """
+    Manually inserts a list of values and pseudonyms into the specified data domain.
+
+    :param client: Zeep client with gPAS service definitions
+    :param domain_name: name of the domain to insert the pairs into
+    :param pairs: list of key-value pairs, structured as { value => pseudonym }
+    """
+    # for some reason this is the only case where the "entry" key is mandatory. it is not returned by any other
+    # endpoints where there's supposedly an "entry" key, e.g. deleteEntries (???)
+    client.service.insertValuePseudonymPairs(
+        domainName=domain_name,
+        pairs={
+            "entry": [
+                {
+                    "key": kv_tuple[0],
+                    "value": kv_tuple[1],
+                }
+                for kv_tuple in pairs
+            ]
+        },
+    )
+
+
+def add_domain(client: Client, domain: Domain) -> None:
+    """
+    Adds a new domain.
+
+    :param client: Zeep client with gPAS domain service definitions
+    :param domain: domain data class to create
+    """
+    domain_soap = DomainSchema().dump(domain)
+    client.service.addDomain(domainDTO=domain_soap)
+
+
+def get_domain(client: Client, domain_name: str) -> DomainResponse:
+    """
+    Gets a domain that matches the specified name. Raises a Fault if there is no domain with such a name.
+
+    :param client: Zeep client with gPAS domain service definitions
+    :param domain_name: name of the domain to get
+    :return: domain response instance
+    """
+    domain_soap = client.service.getDomain(domainName=domain_name)
+    return DomainResponseSchema().load(_serialize_dict(domain_soap))
+
+
+def list_domains(client: Client) -> list[DomainResponse]:
+    """
+    Lists all available domains in the gPAS instance.
+
+    :param client: Zeep client with gPAS domain service definitions
+    :return: list of all available domains as domain response instances
+    """
+    domains = _serialize_dict(client.service.listDomains())
+    return [DomainResponseSchema().load(domain) for domain in domains]
+
+
+def delete_domain(client: Client, domain_name: str) -> None:
+    """
+    Deletes a domain that matches the specified name. Raises a Fault if there is no domain with such a name.
+
+    :param client: Zeep client with gPAS domain service definitions
+    :param domain_name: name of the domain to delete
+    """
+    client.service.deleteDomainWithPSNs(domainName=domain_name)
+
+
+class GPASClient(WSDLClient):
+    """
+    This class is a wrapper around the gPAS service functions.
+    """
+
+    def __init__(self, client: Client | str, domain_client: Client | str):
+        """
+        Constructs a new SOAP client for gPAS service definitions.
+
+        :param client: URL to WSDL endpoint or zeep instance with WSDL information for the gPAS service
+        :param domain_client: URL to WSDL endpoint or zeep instance with WSDL information for the gPAS management
+        service
+        """
+        super().__init__(client)
+        self._domain_client = _cast_client(domain_client)
+
+    def delete_entry(self, domain_name: str, value: str) -> None:
+        """
+        Deletes a value and its associated pseudonym from the specified data domain.
+
+        :param domain_name: name of the domain where the value is present
+        :param value: value to remove
+        """
+        delete_entry(self._client, domain_name, value)
+
+    def delete_entries(self, domain_name: str, values: list[str]) -> list[KeyValueTuple]:
+        """
+        Deletes a list of values and their associated pseudonyms from the specified data domain.
+
+        :param domain_name: name of the domain where the value is present
+        :param values: list of values to remove
+        :return: list of key-value pairs where the key is the value that was requested to be deleted, and the value is
+        an indicator whether deletion was successful or not
+        """
+        return delete_entries(self._client, domain_name, values)
+
+    def get_or_create_pseudonym_for(self, domain_name: str, value: str) -> str:
+        """
+        Requests a new pseudonym for a value in the specified data domain.
+
+        :param domain_name: name of the domain where the value is supposed to be inserted
+        :param value: value to insert
+        :return: pseudonym that is assigned to the value
+        """
+        return get_or_create_pseudonym_for(self._client, domain_name, value)
+
+    def get_or_create_pseudonym_for_list(self, domain_name: str, values: list[str]) -> list[KeyValueTuple]:
+        """
+        Request new pseudonyms for a list of values in the specified data domain.
+
+        :param domain_name: name of the domain where the value is supposed to be inserted
+        :param values: list of values to insert
+        :return: list of key-value pairs where the key is the original value that is supposed to be pseudonymized,
+        and the value is the assigned pseudonym
+        """
+        return get_or_create_pseudonym_for_list(self._client, domain_name, values)
+
+    def get_value_for(self, domain_name: str, pseudonym: str) -> str:
+        """
+        Gets the value for a pseudonym in the specified data domain.
+
+        :param domain_name: name of the domain where the pseudonym is present
+        :param pseudonym: pseudonym to resolve
+        :return: value assigned to the pseudonym
+        """
+        return get_value_for(self._client, domain_name, pseudonym)
+
+    def get_value_for_list(self, domain_name: str, pseudonyms: list[str]) -> list[KeyValueTuple]:
+        """
+        Gets the values for a list of pseudonyms in the specified data domain.
+
+        :param domain_name: name of the domain where the pseudonyms are present
+        :param pseudonyms: pseudonyms to resolve
+        :return: list of key-value pairs, structured as { pseudonym => value }
+        """
+        return get_value_for_list(self._client, domain_name, pseudonyms)
+
+    def get_pseudonym_for(self, domain_name: str, value: str) -> str:
+        """
+        Gets the pseudonym for a value in the specified data domain.
+
+        :param domain_name: name of the domain where the value is present
+        :param value: value to resolve
+        :return: pseudonym assigned to the value
+        """
+        return get_pseudonym_for(self._client, domain_name, value)
+
+    def get_pseudonym_for_list(self, domain_name: str, values: list[str]) -> list[KeyValueTuple]:
+        """
+        Gets the pseudonyms for a list of values in the specified data domain.
+
+        :param domain_name: name of the domain where the values are present
+        :param values: values to resolve
+        :return: list of key-value pairs, structured as { value => pseudonym }
+        """
+        return get_pseudonym_for_list(self._client, domain_name, values)
+
+    def insert_value_pseudonym_pair(self, domain_name: str, value: str, pseudonym: str) -> None:
+        """
+        Manually inserts a value and a pseudonym into the specified data domain.
+
+        :param domain_name: name of the domain to insert the pair into
+        :param value: value to add
+        :param pseudonym: pseudonym to assign to the value
+        """
+        insert_value_pseudonym_pair(self._client, domain_name, value, pseudonym)
+
+    def insert_value_pseudonym_pairs(self, domain_name: str, pairs: list[KeyValueTuple]) -> None:
+        """
+        Manually inserts a list of values and pseudonyms into the specified data domain.
+
+        :param domain_name: name of the domain to insert the pairs into
+        :param pairs: list of key-value pairs, structured as { value => pseudonym }
+        """
+        insert_value_pseudonym_pairs(self._client, domain_name, pairs)
+
+    def add_domain(self, domain: Domain) -> None:
+        """
+        Adds a new domain.
+
+        :param domain: domain data class to create
+        """
+        add_domain(self._domain_client, domain)
+
+    def get_domain(self, domain_name: str) -> DomainResponse:
+        """
+        Gets a domain that matches the specified name. Raises a Fault if there is no domain with such a name.
+
+        :param domain_name: name of the domain to get
+        :return: domain response instance
+        """
+        return get_domain(self._domain_client, domain_name)
+
+    def list_domains(self) -> list[DomainResponse]:
+        """
+        Lists all available domains in the gPAS instance.
+
+        :return: list of all available domains as domain response instances
+        """
+        return list_domains(self._domain_client)
+
+    def delete_domain(self, domain_name: str) -> None:
+        """
+        Deletes a domain that matches the specified name. Raises a Fault if there is no domain with such a name.
+
+        :param domain_name: name of the domain to delete
+        """
+        delete_domain(self._domain_client, domain_name)

mosaic_client/gpas/models.py

@@ -0,0 +1,70 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal
+
+Alphabet = (
+    Literal[
+        "org.emau.icmvc.ganimed.ttp.psn.alphabets.Hex",
+        "org.emau.icmvc.ganimed.ttp.psn.alphabets.Numbers",
+        "org.emau.icmvc.ganimed.ttp.psn.alphabets.NumbersWithoutZero",
+        "org.emau.icmvc.ganimed.ttp.psn.alphabets.NumbersX",
+        "org.emau.icmvc.ganimed.ttp.psn.alphabets.Symbol31",
+        "org.emau.icmvc.ganimed.ttp.psn.alphabets.Symbol32",
+    ]
+    | str
+)
+ForceCache = Literal["DEFAULT", "OFF", "ON"]
+ValidateViaParents = Literal["CASCADE_DELETE", "ENSURE_EXISTS", "OFF", "VALIDATE"]
+
+
+@dataclass(frozen=True)
+class DomainConfig:
+    """
+    Configuration settings for gPAS domains.
+    """
+
+    psn_prefix: str | None = None
+    psn_suffix: str | None = None
+    include_prefix_in_check_digit_calculation: bool = False
+    include_suffix_in_check_digit_calculation: bool = False
+    max_detected_errors: int = 2
+    multi_psn_domain: bool = False
+    psn_length: int = 8
+    psns_deletable: bool = False
+    send_notifications_web: bool = False
+    use_last_char_as_delimiter_after_x_chars: int = 0
+    force_cache: ForceCache = "DEFAULT"
+    validate_values_via_parents: ValidateViaParents = "OFF"
+
+
+@dataclass(frozen=True)
+class Domain:
+    """
+    Describes a gPAS domain.
+    """
+
+    label: str
+    name: str
+    config: DomainConfig = field(default_factory=DomainConfig)
+    alphabet: Alphabet = "org.emau.icmvc.ganimed.ttp.psn.alphabets.Numbers"
+    check_digit_class: str = "org.emau.icmvc.ganimed.ttp.psn.generator.Verhoeff"
+    comment: str | None = None
+    parent_domain_names: list[str] = field(default_factory=list)
+    expiration_properties: None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class DomainResponse(Domain):
+    """
+    Further information about a domain that are available after a domain was created.
+    """
+
+    child_domain_names: list[str]
+    number_of_pseudonyms: int
+    number_of_anonyms: int
+    cache_used: bool
+    percent_psns_used: float
+    create_date: datetime
+    update_date: datetime
+    create_date_string: str
+    update_date_string: str

mosaic_client/gpas/schemas.py

@@ -0,0 +1,53 @@
+from marshmallow import Schema, fields, post_load
+
+from mosaic_client.gpas.models import Domain, DomainConfig, DomainResponse
+
+
+class DomainConfigSchema(Schema):
+    psn_prefix = fields.Str(data_key="psnPrefix", allow_none=True)
+    psn_suffix = fields.Str(data_key="psnSuffix", allow_none=True)
+    include_prefix_in_check_digit_calculation = fields.Bool(data_key="includePrefixInCheckDigitCalculation")
+    include_suffix_in_check_digit_calculation = fields.Bool(data_key="includeSuffixInCheckDigitCalculation")
+    max_detected_errors = fields.Int(data_key="maxDetectedErrors")
+    multi_psn_domain = fields.Bool(data_key="multiPsnDomain")
+    psn_length = fields.Int(data_key="psnLength")
+    psns_deletable = fields.Bool(data_key="psnsDeletable")
+    send_notifications_web = fields.Bool(data_key="sendNotificationsWeb")
+    use_last_char_as_delimiter_after_x_chars = fields.Int(data_key="useLastCharAsDelimiterAfterXChars")
+    validate_values_via_parents = fields.Str(data_key="validateValuesViaParents")
+    force_cache = fields.Str(data_key="forceCache")
+
+    @post_load
+    def make_domain_config(self, data, **kwargs) -> DomainConfig:
+        return DomainConfig(**data)
+
+
+class DomainSchema(Schema):
+    label = fields.Str(required=True)
+    name = fields.Str(required=True)
+    config = fields.Nested(DomainConfigSchema())
+    alphabet = fields.Str()
+    check_digit_class = fields.Str(data_key="checkDigitClass")
+    comment = fields.Str(allow_none=True)
+    parent_domain_names = fields.List(fields.Str(), data_key="parentDomainNames")
+    expiration_properties = fields.Constant(None, data_key="expirationProperties")
+
+    @post_load
+    def make_domain(self, data, **kwargs) -> Domain:
+        return Domain(**data)
+
+
+class DomainResponseSchema(DomainSchema):
+    child_domain_names = fields.List(fields.Str(), data_key="childDomainNames")
+    number_of_pseudonyms = fields.Int(data_key="numberOfPseudonyms")
+    number_of_anonyms = fields.Int(data_key="numberOfAnonyms")
+    cache_used = fields.Bool(data_key="cacheUsed")
+    percent_psns_used = fields.Float(data_key="percentPsnsUsed")
+    create_date = fields.DateTime(data_key="createDate")
+    update_date = fields.DateTime(data_key="updateDate")
+    create_date_string = fields.Str(data_key="createDateString")
+    update_date_string = fields.Str(data_key="updateDateString")
+
+    @post_load
+    def make_domain(self, data, **kwargs) -> DomainResponse:
+        return DomainResponse(**data)

mosaic_client/helpers.py

@@ -0,0 +1,115 @@
+"""
+This module contains helper functions that are used all throughout the mosaic_client library.
+"""
+
+from typing import Any
+
+import zeep.helpers
+from zeep import Client
+
+
+def _serialize_dict(obj: Any) -> Any:
+    """
+    Converts a zeep response object into a dict or list, depending on the structure of the
+    response data.
+
+    :param obj: object to convert
+    :return: object as dict or list
+    """
+    return zeep.helpers.serialize_object(obj, dict)
+
+
+def _malformed_key_value_response(reason: str) -> ValueError:
+    """
+    Returns a ValueError informing about an incorrectly structured key-value response.
+
+    :param reason: reason for error
+    :return: ValueError with specified reason
+    """
+    return ValueError(f"key-value response is malformed: {reason}")
+
+
+def _read_key_value_list(entry_list: list) -> list[tuple[Any, Any]]:
+    """
+    Reads a list of objects structured as [{ "key", "value" }] into a list of tuples
+    where the first value of the tuple is the key and the second is the value. This function
+    will throw a ValueError if the list passed into this function is malformed.
+
+    :param entry_list: list of objects to parse
+    :return: list of key-value tuples
+    """
+    key_value_lst: list[tuple[Any, Any]] = []
+
+    for i in range(len(entry_list)):
+        entry = entry_list[i]
+
+        # check for "key" key
+        if "key" not in entry:
+            raise _malformed_key_value_response(f"'entry[{i}]' is missing 'key' attribute")
+
+        # check for "value" key
+        if "value" not in entry:
+            raise _malformed_key_value_response(f"'entry[{i}]' is missing 'value' attribute")
+
+        key_value_lst.append((entry["key"], entry["value"]))
+
+    return key_value_lst
+
+
+def _read_key_value_entry_response(response: Any) -> list[tuple[Any, Any]]:
+    """
+    Reads an object structured as { "entry": [{ "key", "value" }] } into a list of tuples
+    where the first value of the tuple is the key and the second is the value. This function
+    will throw a ValueError if the object passed into this function is malformed.
+
+    :param response: object to parse
+    :return: list of key-value tuples
+    """
+    # check that it's actually a dict
+    if type(response) != dict:
+        raise _malformed_key_value_response("not an object")
+
+    # check for "entry" key
+    if "entry" not in response:
+        raise _malformed_key_value_response("'entry' attribute is missing")
+
+    # "entry" key should hold list of key-value entries
+    response_entry_lst = response["entry"]
+
+    # check that it's actually a list
+    if type(response_entry_lst) != list:
+        raise _malformed_key_value_response("'entry' value is not a list")
+
+    return _read_key_value_list(response_entry_lst)
+
+
+def _cast_client(client: Client | str) -> Client:
+    """
+    Takes zeep client instances or wsdl urls as strings and either just returns the given client instance or creates
+    one if a string was given. Raises a TypeError if the given client is neither a zeep client nor a string.
+
+    :param client: client instance or wsdl url as a string
+    :return: zeep client instance
+    """
+    if isinstance(client, Client):
+        pass
+    elif isinstance(client, str):
+        client = Client(client)
+    else:
+        raise TypeError(f"unsupported constructor argument type: {type(client)}")
+
+    return client
+
+
+class WSDLClient:
+    """
+    Generic SOAP client base.
+    """
+
+    def __init__(self, client: Client | str):
+        """
+        Constructs a new SOAP client.
+
+        :param client: URL to WSDL endpoint or zeep instance with WSDL information
+        """
+        self._client = _cast_client(client)