Skip to content

Substances

albert.collections.substance.SubstanceCollection 

SubstanceCollection(*, session: AlbertSession)

Bases: BaseCollection

SubstanceCollection is a collection class for managing Substance entities in the Albert platform.

Parameters:

Name Type Description Default
session AlbertSession

An instance of the Albert session used for API interactions.

 required

Attributes:

Name Type Description
base_path str

The base URL for making API requests related to substances.

Methods:

Name Description
get_by_ids

Retrieves a list of substances by their CAS IDs and optional region.
get_by_id

Retrieves a single substance by its CAS ID and optional region, or None if not found.
Source code in src/albert/collections/substance.py 
32
33
34
def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)
    self.base_path = f"/api/{SubstanceCollection._api_version}/substances"

base_path 

base_path = (
    f"/api/{SubstanceCollection._api_version}/substances"
)

get_by_ids 

get_by_ids(
    *,
    cas_ids: list[str],
    region: str = "US",
    catch_errors: bool | None = None,
) -> list[SubstanceInfo]

Get substances by their CAS IDs.

If catch_errors is set to False, the number of substances returned may be less than the number of CAS IDs provided if any of the CAS IDs result in an error.

Parameters:

Name Type Description Default
cas_ids list[str]

A list of CAS IDs to retrieve substances for.

 required
region str

The region to filter the subastance by, by default "US"

 'US'
catch_errors bool

Whether to catch errors for unknown CAS, by default True.

 None

Returns:

Type Description
list[SubstanceInfo]

A list of substances with the given CAS IDs.
Source code in src/albert/collections/substance.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def get_by_ids(
    self,
    *,
    cas_ids: list[str],
    region: str = "US",
    catch_errors: bool | None = None,
) -> list[SubstanceInfo]:
    """Get substances by their CAS IDs.

    If `catch_errors` is set to False, the number of substances returned
    may be less than the number of CAS IDs provided if any of the CAS IDs result in an error.

    Parameters
    ----------
    cas_ids : list[str]
        A list of CAS IDs to retrieve substances for.
    region : str, optional
        The region to filter the subastance by, by default "US"
    catch_errors : bool, optional
        Whether to catch errors for unknown CAS, by default True.

    Returns
    -------
    list[SubstanceInfo]
        A list of substances with the given CAS IDs.
    """
    params = {
        "casIDs": ",".join(cas_ids),
        "region": region,
        "catchErrors": json.dumps(catch_errors) if catch_errors is not None else None,
    }
    params = {k: v for k, v in params.items() if v is not None}
    response = self.session.get(self.base_path, params=params)
    return SubstanceResponse.model_validate(response.json()).substances

get_by_id 

get_by_id(
    *,
    cas_id: str,
    region: str = "US",
    catch_errors: bool | None = None,
) -> SubstanceInfo | None

Get a substance by its CAS ID.

Parameters:

Name Type Description Default
cas_id str

The CAS ID of the substance to retrieve.

 required
region str

The region to filter the substance by, by default "US".

 'US'
catch_errors bool

Whether to suppress errors for unknown CAS IDs, by default None.

 None

Returns:

Type Description
SubstanceInfo | None

The retrieved substance, or None if the CAS ID is not found.
Source code in src/albert/collections/substance.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def get_by_id(
    self,
    *,
    cas_id: str,
    region: str = "US",
    catch_errors: bool | None = None,
) -> SubstanceInfo | None:
    """Get a substance by its CAS ID.

    Parameters
    ----------
    cas_id : str
        The CAS ID of the substance to retrieve.
    region : str, optional
        The region to filter the substance by, by default "US".
    catch_errors : bool, optional
        Whether to suppress errors for unknown CAS IDs, by default None.

    Returns
    -------
    SubstanceInfo | None
        The retrieved substance, or None if the CAS ID is not found.
    """
    results = self.get_by_ids(cas_ids=[cas_id], region=region, catch_errors=catch_errors)
    return results[0] if results else None