adapter

Reference

Bases: EntryAdapter

Lazy reference resource converter.

Go to EntryAdapter to see the full list of methods and properties.

Attributes:

Name	Type	Description
ENTRY_RESOURCE	ReferenceResource	This adapter stores entry resources as ReferenceResources.
_type_converters	Dict[str, Callable]	Dictionary of valid conversion types for entry. There are currently no available types.
as_<_type_converters>	Dict[str, Callable]	Convert entry to a type listed in _type_converters.

Source code in optimade/adapters/references/adapter.py

class Reference(EntryAdapter):
    """
    Lazy reference resource converter.

    Go to [`EntryAdapter`][optimade.adapters.base.EntryAdapter] to see the full list of methods
    and properties.

    Attributes:
        ENTRY_RESOURCE (ReferenceResource): This adapter stores entry resources as
            [`ReferenceResource`][optimade.models.references.ReferenceResource]s.
        _type_converters (Dict[str, Callable]): Dictionary of valid conversion types for entry.

            There are currently no available types.
        as_<_type_converters>: Convert entry to a type listed in `_type_converters`.

    """

    ENTRY_RESOURCE: type[ReferenceResource] = ReferenceResource

entry property

Get OPTIMADE entry.

Returns:

Type	Description
EntryResource	The entry resource.

__getattr__(name)

Get converted entry or attribute from OPTIMADE entry.

Support any level of "."-nested OPTIMADE ENTRY_RESOURCE attributes, e.g., attributes.species for StuctureResource.

Note

All nested attributes must individually be subclasses of pydantic.BaseModel, i.e., one can not access nested attributes in lists by passing a "."-nested name to this method, e.g., attributes.species.name or attributes.species[0].name will not work for variable name.

Order:

• Try to return converted entry if using as_<_type_converters key>.
• Try to return OPTIMADE ENTRY_RESOURCE (nested) attribute.
• Try to return OPTIMADE ENTRY_RESOURCE.attributes (nested) attribute.
• Raise AttributeError.

Parameters:

Name	Type	Description	Default
name	str	Requested attribute.	required

Raises:

Type	Description
AttributeError	If the requested attribute is not recognized. See above for the description of the order in which an attribute is tested for validity.

Source code in optimade/adapters/base.py

def __getattr__(self, name: str) -> Any:
    """Get converted entry or attribute from OPTIMADE entry.

    Support any level of "."-nested OPTIMADE `ENTRY_RESOURCE` attributes, e.g.,
    `attributes.species` for [`StuctureResource`][optimade.models.structures.StructureResource].

    Note:
        All nested attributes must individually be subclasses of `pydantic.BaseModel`,
        i.e., one can not access nested attributes in lists by passing a "."-nested `name` to this method,
        e.g., `attributes.species.name` or `attributes.species[0].name` will not work for variable `name`.

    Order:

    - Try to return converted entry if using `as_<_type_converters key>`.
    - Try to return OPTIMADE `ENTRY_RESOURCE` (nested) attribute.
    - Try to return OPTIMADE `ENTRY_RESOURCE.attributes` (nested) attribute.
    - Raise `AttributeError`.

    Parameters:
        name (str): Requested attribute.

    Raises:
        AttributeError: If the requested attribute is not recognized.
            See above for the description of the order in which an attribute is tested for validity.

    """
    # as_<entry_type>
    if name.startswith("as_"):
        entry_type = "_".join(name.split("_")[1:])
        return self.convert(entry_type)

    # Try returning ENTRY_RESOURCE attribute
    try:
        res = self._get_model_attributes((self.entry, self.entry.attributes), name)
    except AttributeError:
        pass
    else:
        return res

    # Non-valid attribute
    _entry_resource_name = re.match(
        r"(<class ')([a-zA-Z_]+\.)*([a-zA-Z_]+)('>)", str(self.ENTRY_RESOURCE)
    )
    entry_resource_name = (
        _entry_resource_name.group(3)
        if _entry_resource_name is not None
        else "UNKNOWN RESOURCE"
    )
    raise AttributeError(
        f"Unknown attribute: {name}\n"
        "If you want to get a converted entry as <entry_type> use `as_<entry_type>`, "
        f"where `<entry_type>` is one of {tuple(self._type_converters.keys()) + tuple(self._common_converters.keys())}\n"
        f"Otherwise, you can try to retrieve an OPTIMADE {entry_resource_name} attribute or property."
    )

__init__(entry)

Parameters:

Name	Type	Description	Default
entry	dict	A JSON OPTIMADE single resource entry.	required

Source code in optimade/adapters/base.py

def __init__(self, entry: dict[str, Any]) -> None:
    """
    Parameters:
        entry (dict): A JSON OPTIMADE single resource entry.
    """
    self._converted: dict[str, Any] = {}

    self._entry = self.ENTRY_RESOURCE(**entry)

    # Note that these return also the default values for otherwise non-provided properties.
    self._common_converters = {
        # Return JSON serialized string, see https://pydantic-docs.helpmanual.io/usage/exporting_models/#modeljson
        "json": self.entry.model_dump_json,
        # Return Python dict, see https://pydantic-docs.helpmanual.io/usage/exporting_models/#modeldict
        "dict": self.entry.model_dump,
    }

convert(format)

Convert OPTIMADE entry to desired format.

Parameters:

Name	Type	Description	Default
format	str	Type or format to which the entry should be converted.	required

Raises:

Type	Description
AttributeError	If format can not be found in _type_converters or _common_converters.

Returns:

Type	Description
Any	The converted entry according to the desired format or type.

Source code in optimade/adapters/base.py

def convert(self, format: str) -> Any:
    """Convert OPTIMADE entry to desired format.

    Parameters:
        format (str): Type or format to which the entry should be converted.

    Raises:
        AttributeError: If `format` can not be found in `_type_converters` or `_common_converters`.

    Returns:
        The converted entry according to the desired format or type.

    """
    if (
        format not in self._type_converters
        and format not in self._common_converters
    ):
        raise AttributeError(
            f"Non-valid entry type to convert to: {format}\nValid entry types: "
            f"{tuple(self._type_converters.keys()) + tuple(self._common_converters.keys())}"
        )

    if self._converted.get(format, None) is None:
        if format in self._type_converters:
            self._converted[format] = self._type_converters[format](self.entry)
        else:
            self._converted[format] = self._common_converters[format]()

    return self._converted[format]

from_url(url) classmethod

Convert OPTIMADE URL into the target entry type.

Parameters:

Name	Type	Description	Default
url	str	The OPTIMADE URL to convert.	required

Returns:

Type	Description
Any	The converted URL.

Source code in optimade/adapters/base.py

@classmethod
def from_url(cls, url: str) -> Any:
    """Convert OPTIMADE URL into the target entry type.

    Parameters:
        url (str): The OPTIMADE URL to convert.

    Returns:
        The converted URL.

    """
    import requests

    response = requests.get(url, timeout=100)
    if response.status_code != 200:
        raise RuntimeError(
            f"Could not retrieve OPTIMADE entry from URL {url} returned {response.status_code}"
        )

    try:
        json_response = response.json()

    except JSONDecodeError as exc:
        raise RuntimeError(
            f"Could not retrieve OPTIMADE entry from URL {url}: did not contain valid JSON response."
        ) from exc

    data: dict = json_response.get("data", {})
    if isinstance(data, list):
        raise RuntimeError(f"returned a list of {len(data)} entries.")

    return cls(data)

ingest_from(data, format=None) classmethod

Convert desired format to OPTIMADE format.

Parameters:

Name	Type	Description	Default
data	Any	The data to convert.	required
format	str	Type or format to which the entry should be converted.	None

Raises:

Type	Description
AttributeError	If format can not be found in _type_ingesters.

Returns:

Type	Description
Any	The ingested Structure.

Source code in optimade/adapters/base.py

@classmethod
def ingest_from(cls, data: Any, format: str | None = None) -> Any:
    """Convert desired format to OPTIMADE format.

    Parameters:
        data (Any): The data to convert.
        format (str): Type or format to which the entry should be converted.

    Raises:
        AttributeError: If `format` can not be found in `_type_ingesters`.

    Returns:
        The ingested Structure.

    """

    if format is None:
        for key, instance_type in cls._type_ingesters_by_type.items():
            if isinstance(data, instance_type):
                format = key
                break

        else:
            raise AttributeError(
                f"Non entry type to data of type {type(data)} from.\n"
                f"Valid entry types: {tuple(cls._type_ingesters.keys())}"
            )

    if format not in cls._type_ingesters:
        raise AttributeError(
            f"Non-valid entry type to ingest from: {format}\n"
            f"Valid entry types: {tuple(cls._type_ingesters.keys())}"
        )

    return cls(
        {
            "attributes": cls._type_ingesters[format](data).model_dump(),
            "id": "",
            "type": "structures",
        }
    )