sob.thesaurus

This module provides functionality for creating a data model from a set of example structures.

Synonyms

Synonyms(
    items: collections.abc.Iterable[
        sob.abc.Readable | sob.abc.MarshallableTypes
    ] = (),
)

This class is a set-like object containing deserialized data, implied to represent variations of one type of entity, and is used to infer a model for that entity.

Source code in src/sob/thesaurus.py

def __init__(
    self, items: Iterable[abc.Readable | abc.MarshallableTypes] = ()
) -> None:
    self._type: set[type] = set()
    self._nullable: bool = False
    self._set: set[abc.MarshallableTypes] = set()
    if items:
        self.__ior__(items)

add

add(
    item: sob.abc.Readable | sob.abc.MarshallableTypes,
) -> None

This method adds a synonymous item to the set. If the item is a file-like (input/output) object, that object is first read, deserialized, and unmarshalled.

Parameters:

• item (sob.abc.Readable | sob.abc.MarshallableTypes) –

  A file-like or a JSON-serializable python object.

Source code in src/sob/thesaurus.py

def add(  # noqa: C901
    self, item: abc.Readable | abc.MarshallableTypes
) -> None:
    """
    This method adds a synonymous item to the set. If the item is a
    file-like (input/output) object, that object is first read,
    deserialized, and unmarshalled.

    Parameters:
        item: A file-like or a JSON-serializable python object.
    """
    if not isinstance(item, (abc.Readable, *abc.MARSHALLABLE_TYPES)):
        raise TypeError(item)
    if isinstance(item, abc.Readable):
        # Deserialize and unmarshal file-like objects
        item = unmarshal(deserialize(_read(item))[0])
    elif isinstance(item, Iterable) and not isinstance(
        item, (str, abc.Model, Mapping)
    ):
        if isinstance(item, Iterable) and not isinstance(item, Sequence):
            item = tuple(item)
        # Unmarshal items which appear to not have been part of an
        # unmarshalled container
        item = unmarshal(item)
    if isinstance(item, Null):
        self._nullable = True
    elif item is not None:
        if not isinstance(item, MARSHALLABLE_TYPES):
            raise TypeError(item)
        item_type: type = (
            list
            if isinstance(item, abc.Array)
            else dict
            if isinstance(item, abc.Dictionary)
            else type(item)
        )
        if (item_type is int) and float in self._type:
            pass
        elif (item_type is float) and int in self._type:
            self._type.remove(int)
            self._type.add(item_type)
        else:
            self._type.add(item_type)
        if not isinstance(item, Hashable):
            if isinstance(item, Mapping):
                item = Dictionary(item)
            if isinstance(item, Sequence):
                item = Array(item)
        self._set.add(item)  # type: ignore

union

union(
    other: collections.abc.Iterable[
        sob.abc.Readable | sob.abc.MarshallableTypes
    ],
) -> sob.thesaurus.Synonyms

This method returns an instance of Synonyms which incorporates all (non-redundant) items from both self and other.

Source code in src/sob/thesaurus.py

def union(
    self, other: Iterable[abc.Readable | abc.MarshallableTypes]
) -> Synonyms:
    """
    This method returns an instance of `Synonyms` which incorporates
    all (non-redundant) items from both `self` and `other`.
    """
    new_synonyms: Synonyms = copy(self)
    new_synonyms |= other
    return new_synonyms

get_models

get_models(
    pointer: str,
    module: str = "__main__",
    name: typing.Callable[
        [str], str
    ] = sob.thesaurus.get_class_name_from_pointer,
) -> collections.abc.Iterable[type]

Retrieve a sequence of class definitions representing a data model capable of describing these synonyms.

Parameters:

• pointer (str): A JSON pointer for the top-level model class, used to infer class names.
• module (str): The name of the module in which model classes will be defined. This defaults to "main".
• name (str) = sob.thesaurus.get_class_name_from_pointer: A function which accepts one str argument—a synonym key concatenated with "#" and JSON pointer (for example: "key#/body/items/0") and which returns a str which will be the resulting class name (for example: "KeyBodyItemsItem").

Source code in src/sob/thesaurus.py

def get_models(
    self,
    pointer: str,
    module: str = "__main__",
    name: Callable[[str], str] = get_class_name_from_pointer,
) -> Iterable[type]:
    """
    Retrieve a sequence of class definitions representing a data model
    capable of describing these synonyms.

    Parameters:

    - pointer (str): A JSON pointer for the top-level model class, used to
      infer class names.
    - module (str): The name of the module in which model classes will be
      defined. This defaults to "__main__".
    - name (str) = sob.thesaurus.get_class_name_from_pointer:
      A function which accepts one `str` argument—a synonym key
      concatenated with "#" and JSON pointer (for example:
      "key#/body/items/0") and which returns a `str` which will be the
      resulting class name (for example: "KeyBodyItemsItem").
    """
    if not callable(name):
        raise TypeError(name)
    # This assertion ensures `self` contains data which can be described by
    # a model class.
    message: str
    if not self._type:
        message = "No type could be identified"
        raise RuntimeError(message)
    quoted_pointer: str = "{}#".format(quote_plus(pointer, safe="/+"))
    for model_class in self._iter_types(
        pointer=quoted_pointer,
        module=module,
        name=name,
    ):
        if not issubclass(model_class, abc.Model):
            raise TypeError((quoted_pointer, model_class))
        yield model_class

Thesaurus

Thesaurus(
    _items: (
        collections.abc.Mapping[
            str,
            collections.abc.Iterable[
                sob.abc.Readable | sob.abc.MarshallableTypes
            ]
            | sob.thesaurus.Synonyms,
        ]
        | collections.abc.Iterable[
            tuple[
                str,
                collections.abc.Iterable[
                    sob.abc.Readable
                    | sob.abc.MarshallableTypes
                ]
                | sob.thesaurus.Synonyms,
            ]
        ]
        | sob.thesaurus.Thesaurus
        | None
    ) = None,
    **kwargs: collections.abc.Iterable[
        sob.abc.Readable | sob.abc.MarshallableTypes
    ]
)

An instance of sob.Thesaurus is a dictionary-like object wherein each value is an instance of sob.Synonyms.

For example, if you have an API with several GET endpoints, the endpoint paths relative to the API base URL would make ideal keys for your sob.Thesaurus instance. After adding a representative sample of responses from each endpoint to the corresponding sob.Synonyms instance in your sob.Thesaurus instance, your thesaurus will be able to generate a python module with an sob based data model for all of your endpoints, including polymorphism where encountered.

The keys of an sob.Thesaurus dictionary are meaningful in that they contribute to the naming of classes (which are formatted to comply with PEP-8, and to avoid collision with builtins, language keywords, etc.).

For background: The sob library was designed for authoring a data model representing schemas defined by an OpenAPI specification. Although OpenAPI specifications are increasingly ubiquitous, there are scenarios where you might need to interact with an API which does not have an OpenAPI specification, or for which the OpenAPI specification is simply not available to you. In these cases, you can generate an sob model to validate your API responses using sob.Thesaurus.

Parameters:

• _items (collections.abc.Mapping[str, collections.abc.Iterable[sob.abc.Readable | sob.abc.MarshallableTypes] | sob.thesaurus.Synonyms] | collections.abc.Iterable[tuple[str, collections.abc.Iterable[sob.abc.Readable | sob.abc.MarshallableTypes] | sob.thesaurus.Synonyms]] | sob.thesaurus.Thesaurus | None, default: None ) –

  A mapping of keys to values, where each value is an iterable of items which are synonymous with the key. This can either be an iterable of key/value pair tuples, or a dictionary-like object.

Source code in src/sob/thesaurus.py

def __init__(
    self,
    _items: Mapping[
        str, Iterable[abc.Readable | abc.MarshallableTypes] | Synonyms
    ]
    | Iterable[
        tuple[
            str, Iterable[abc.Readable | abc.MarshallableTypes] | Synonyms
        ]
    ]
    | Thesaurus
    | None = None,
    **kwargs: Iterable[abc.Readable | abc.MarshallableTypes],
) -> None:
    """
    Parameters:
        _items: A mapping of keys to values, where each value is
            an iterable of items which are synonymous with the key.
            This can either be an iterable of key/value pair tuples,
            or a dictionary-like object.
    """
    self._dict: dict[str, Synonyms] = {}
    key: str
    value: Iterable[abc.Readable | abc.MarshallableTypes]
    for key, value in dict(
        *((_items,) if _items else ()), **kwargs
    ).items():
        self[key] = value

__setitem__

__setitem__(
    key: str,
    value: (
        sob.thesaurus.Synonyms
        | collections.abc.Iterable[
            sob.abc.Readable | sob.abc.MarshallableTypes
        ]
    ),
) -> None

This method adds/overwrites the synonyms for the specified key. If the value is not an instance of sob.Synonyms, a new instance of sob.Synonyms is created and JSON data items from value are added to it.

Parameters:

• key (str) –

  A string to utilize when attributing a unique name to the class representing these synonyms.

• value (sob.thesaurus.Synonyms | collections.abc.Iterable[sob.abc.Readable | sob.abc.MarshallableTypes]) –

  An iterable of JSON data which should be considered synonymous.

Source code in src/sob/thesaurus.py

def __setitem__(
    self,
    key: str,
    value: Synonyms | Iterable[abc.Readable | abc.MarshallableTypes],
) -> None:
    """
    This method adds/overwrites the synonyms for the specified `key`.
    If the `value` is not an instance of `sob.Synonyms`, a new instance
    of `sob.Synonyms` is created and JSON data items from `value` are
    added to it.

    Parameters:
        key: A string to utilize when attributing a unique name to the
            class representing these synonyms.
        value: An iterable of JSON data which should be considered
            synonymous.
    """
    if not isinstance(value, Synonyms):
        value = Synonyms(value)
    return self._dict.__setitem__(key, value)

__delitem__

__delitem__(key: str) -> None

This method deletes the synonyms assigned the specified key.

Parameters:

• key (str) –

Source code in src/sob/thesaurus.py

def __delitem__(self, key: str) -> None:
    """
    This method deletes the synonyms assigned the specified `key`.

    Parameters:
        key:
    """
    self._dict.__delitem__(key)

pop

pop(
    key: str,
    default: (
        sob.thesaurus.Synonyms | sob._types.Undefined
    ) = sob._types.UNDEFINED,
) -> sob.thesaurus.Synonyms

This method removes and returns the synonyms assigned to the specified key.

Parameters:

• key (str) –
• default (sob.thesaurus.Synonyms | sob._types.Undefined, default: sob._types.UNDEFINED ) –

  A value to return if the specified key does not exist. If no default is provided, a KeyError will be raised if the key is not found.

Source code in src/sob/thesaurus.py

def pop(
    self, key: str, default: Synonyms | Undefined = UNDEFINED
) -> Synonyms:
    """
    This method removes and returns the synonyms assigned to the specified
    `key`.

    Parameters:
        key:
        default: A value to return if the specified `key` does not exist.
            If no default is provided, a `KeyError` will be raised if the
            key is not found.
    """
    return self._dict.pop(
        key,
        **({} if isinstance(default, Undefined) else {"default": default}),
    )

popitem

popitem() -> tuple[str, sob.thesaurus.Synonyms]

This method removes and returns a tuple of the most recently added key/synonyms pair (by default), or the first added key/synonyms pair if last is set to False.

Source code in src/sob/thesaurus.py

def popitem(self) -> tuple[str, Synonyms]:
    """
    This method removes and returns a tuple of the most recently added
    key/synonyms pair (by default), or the first added key/synonyms pair
    if `last` is set to `False`.
    """
    return self._dict.popitem()

clear

clear() -> None

This method clears the thesaurus, removing all synonyms.

Source code in src/sob/thesaurus.py

def clear(self) -> None:
    """
    This method clears the thesaurus, removing all synonyms.
    """
    self._dict.clear()

update

update(
    **kwargs: (
        sob.thesaurus.Synonyms
        | collections.abc.Iterable[
            sob.abc.Readable | sob.abc.MarshallableTypes
        ]
    ),
) -> None

This method updates the thesaurus with one or more specified synonyms.

Parameters:

• kwargs (sob.thesaurus.Synonyms | collections.abc.Iterable[sob.abc.Readable | sob.abc.MarshallableTypes], default: {} ) –

  A mapping of keys to values, where each value is an iterable of items which are synonymous with the key, or is an instance of sob.Synonyms.

Source code in src/sob/thesaurus.py

def update(
    self,
    **kwargs: Synonyms | Iterable[abc.Readable | abc.MarshallableTypes],
) -> None:
    """
    This method updates the thesaurus with one or more specified synonyms.

    Parameters:
        kwargs: A mapping of keys to values, where each value is
            an iterable of items which are synonymous with the key,
            or is an instance of `sob.Synonyms`.
    """
    key: str
    value: Iterable[abc.Readable | abc.MarshallableTypes]
    for key, value in kwargs.items():
        self[key] = value

setdefault

setdefault(
    key: str,
    default: collections.abc.Iterable[
        sob.abc.Readable | sob.abc.MarshallableTypes
    ],
) -> sob.thesaurus.Synonyms

This method assigns default synonyms to the specified key if no synonyms have previously been assigned to the key, and returns either the existing or newly assigned synonyms.

Source code in src/sob/thesaurus.py

def setdefault(
    self,
    key: str,
    default: Iterable[abc.Readable | abc.MarshallableTypes],
) -> Synonyms:
    """
    This method assigns `default` synonyms to the specified `key` if
    no synonyms have previously been assigned to the key, and returns
    either the existing or newly assigned synonyms.
    """
    if not isinstance(default, Synonyms):
        default = Synonyms(default)
    return self._dict.setdefault(key, default)

get_module_source

get_module_source(
    name: typing.Callable[
        [str], str
    ] = sob.thesaurus.get_class_name_from_pointer,
) -> str

This method generates and returns the source code for a module defining data models applicable to the data contained in this thesaurus.

Parameters:

• name (str) = sob.thesaurus.get_class_name_from_pointer: A function which accepts one str argument—a synonym key concatenated with "#" and JSON pointer (for example: "key#/body/items/0") and which returns a str which will be the resulting class name (for example: "KeyBodyItemsItem").

Source code in src/sob/thesaurus.py

def get_module_source(
    self, name: Callable[[str], str] = get_class_name_from_pointer
) -> str:
    """
    This method generates and returns the source code for a module
    defining data models applicable to the data contained in this
    thesaurus.

    Parameters:

    - name (str) = sob.thesaurus.get_class_name_from_pointer:
      A function which accepts one `str` argument—a synonym key
      concatenated with "#" and JSON pointer (for example:
      "key#/body/items/0") and which returns a `str` which will be the
      resulting class name (for example: "KeyBodyItemsItem").
    """
    return get_models_source(
        *self.get_models(module="__main__", name=name)
    )

get_module

get_module(
    name: typing.Callable[
        [str], str
    ] = sob.thesaurus.get_class_name_from_pointer,
) -> types.ModuleType

This method generates and returns a module defining data models applicable to the data contained in this thesaurus. This module is not suitable for writing out for static use--use Thesaurus.save_module to generate and write a model suitable for static use.

Parameters:

• name (str) = sob.thesaurus.get_class_name_from_pointer: A function which accepts one str argument—a synonym key concatenated with "#" and JSON pointer (for example: "key#/body/items/0") and which returns a str which will be the resulting class name (for example: "KeyBodyItemsItem").

Source code in src/sob/thesaurus.py

def get_module(
    self, name: Callable[[str], str] = get_class_name_from_pointer
) -> ModuleType:
    """
    This method generates and returns a module defining data models
    applicable to the data contained in this thesaurus. This module is not
    suitable for writing out for static use--use `Thesaurus.save_module`
    to generate and write a model suitable for static use.

    Parameters:

    - name (str) = sob.thesaurus.get_class_name_from_pointer:
      A function which accepts one `str` argument—a synonym key
      concatenated with "#" and JSON pointer (for example:
      "key#/body/items/0") and which returns a `str` which will be the
      resulting class name (for example: "KeyBodyItemsItem").
    """
    # For pickling to work, the `__module__` variable needs to be set to
    # the calling module.
    module_name: str = get_calling_module_name(2)
    module: ModuleType = ModuleType(module_name)
    exec(  # noqa: S102
        self._get_module_source(module_name, name=name), module.__dict__
    )
    return module

save_module

save_module(
    path: str | pathlib.Path,
    name: typing.Callable[
        [str], str
    ] = sob.thesaurus.get_class_name_from_pointer,
) -> None

This method generates and saves the source code for a module defining data models applicable to the data contained in this thesaurus.

Parameters:

• path (str): The file path where the data will be written.
• name (str) = sob.thesaurus.get_class_name_from_pointer: A function which accepts one str argument—a synonym key concatenated with "#" and JSON pointer (for example: "key#/body/items/0") and which returns a str which will be the resulting class name (for example: "KeyBodyItemsItem").

Source code in src/sob/thesaurus.py

def save_module(
    self,
    path: str | Path,
    name: Callable[[str], str] = get_class_name_from_pointer,
) -> None:
    """
    This method generates and saves the source code for a module
    defining data models applicable to the data contained in this
    thesaurus.

    Parameters:

    - path (str): The file path where the data will be written.
    - name (str) = sob.thesaurus.get_class_name_from_pointer:
      A function which accepts one `str` argument—a synonym key
      concatenated with "#" and JSON pointer (for example:
      "key#/body/items/0") and which returns a `str` which will be the
      resulting class name (for example: "KeyBodyItemsItem").
    """
    if isinstance(path, str):
        path = Path(path)
    os.makedirs(path.parent, exist_ok=True)
    module_source: str = self.get_module_source(name=name)
    with open(path, "w") as module_io:
        module_io.write(f"{module_source}\n")

get_class_name_from_pointer

get_class_name_from_pointer(pointer: str) -> str

This function creates a class name based on the sob.Thesaurus key of the sob.Synonyms instance to which an element belongs, combined with the JSON pointer of the applicable element. This function can be substituted for another, when generating a module from a thesaurus, by passing a function to the name parameter of sob.Thesaurus.get_module_source, sob.Thesaurus.get_module, or sob.Thesaurus.save_module.

Parameters:

• pointer (str): The synonyms key + JSON pointer of the element for which the class is being generated.

Source code in src/sob/thesaurus.py

def get_class_name_from_pointer(pointer: str) -> str:
    """
    This function creates a class name based on the `sob.Thesaurus` key of the
    `sob.Synonyms` instance to which an element belongs,
    combined with the *JSON pointer* of the applicable element. This function
    can be substituted for another, when generating a module from a thesaurus,
    by passing a function to the `name` parameter of
    `sob.Thesaurus.get_module_source`, `sob.Thesaurus.get_module`, or
    `sob.Thesaurus.save_module`.

    Parameters:

    - pointer (str): The synonyms key + JSON pointer of the element for which
      the class is being generated.
    """
    return get_class_name(
        f"{pointer[:-2]}/item"
        if pointer.endswith("/0")
        else pointer.replace("/0/", "/item/")
    )

get_class_meta_attribute_assignment_source

get_class_meta_attribute_assignment_source(
    class_name_: str,
    attribute_name: str,
    metadata: sob.abc.Meta,
) -> str

This function generates source code for setting a metadata attribute on a class.

Parameters:

• class_name (str): The name of the class to which we want to assign a metadata attribute.
• attribute_name (str): The name of the attribute we want to assign.
• metadata (sob.abc.Meta): The metadata from which to take the assigned value.

Source code in src/sob/thesaurus.py

def get_class_meta_attribute_assignment_source(
    class_name_: str,
    attribute_name: str,
    metadata: abc.Meta,
) -> str:
    """
    This function generates source code for setting a metadata attribute on
    a class.

    Parameters:

    - class_name (str): The name of the class to which we want to assign a
      metadata attribute.
    - attribute_name (str): The name of the attribute we want to assign.
    - metadata (sob.abc.Meta): The metadata from which to take the assigned
      value.
    """
    writable_function_name: str = "sob.get_writable_{}_meta".format(
        "object"
        if isinstance(metadata, abc.ObjectMeta)
        else ("array" if isinstance(metadata, abc.ArrayMeta) else "dictionary")
    )
    # We insert "  # type: ignore" at the end of the first line where the value
    # is assigned due to mypy issues with properties having getters and setters
    return suffix_long_lines(
        (
            f"{writable_function_name}(  # type: ignore\n"
            f"    {suffix_long_lines(class_name_, -4)}\n"
            f").{attribute_name} = {getattr(metadata, attribute_name)!r}"
        ),
        -4,
    )