atomref.elements

Element identity is intentionally minimal: atomic number, symbol, and name. The module also contains the canonicalization helpers used throughout the package.

atomref.elements

Periodic-table access for stable element identity.

Element `dataclass`

Element(z: int, symbol: str, name: str)

Chemical element identity keyed by atomic number and symbol.

Attributes:

Name	Type	Description
`z`	`int`	Atomic number. Packaged elements span 1 (H) through 118 (Og).
`symbol`	`str`	Conventional case-sensitive element symbol.
`name`	`str`	English element name.

Examples:

>>> get_element("cl")
Element(z=17, symbol='Cl', name='Chlorine')

canonicalize_element_symbol

canonicalize_element_symbol(token: str | None) -> str | None

Canonicalize a free-form token to a conventional element symbol.

The function accepts strings such as "cl", " Cl " or "Cl12" and returns "Cl" when a leading element-like token can be identified. It normalizes spelling but does not validate that the result is a known element.

Parameters:

Name	Type	Description	Default
`token`	`str \| None`	Free-form token, or `None`. Empty strings and the missing-value markers `"?"` and `"."` are treated as missing.	required

Returns:

Type	Description
`str \| None`	A conventionally capitalized leading element-like token, or `None` if no such token is present.

Examples:

>>> canonicalize_element_symbol(" Cl12 ")
'Cl'
>>> canonicalize_element_symbol("?") is None
True

Notes

Call is_valid_element_symbol or get_element when membership in the packaged periodic table must also be checked.

is_valid_element_symbol

is_valid_element_symbol(symbol: str | None) -> bool

Check whether a canonical symbol is present in the periodic table.

Parameters:

Name	Type	Description	Default
`symbol`	`str \| None`	Case-sensitive canonical symbol, or `None`.	required

Returns:

Type	Description
`bool`	`True` only for an exact packaged symbol. This function does not trim or canonicalize its argument.

Examples:

>>> is_valid_element_symbol("Cl")
True
>>> is_valid_element_symbol("cl")
False

get_element

get_element(symbol: str | None) -> Element | None

Look up packaged element identity from a symbol-like token.

Parameters:

Name	Type	Description	Default
`symbol`	`str \| None`	Free-form symbol token accepted by canonicalize_element_symbol, or `None`.	required

Returns:

Type	Description
`Element \| None`	The matching immutable Element, or `None` if the token is missing or does not identify a packaged element.

Examples:

>>> get_element(" Cl12 ").z
17
>>> get_element("not-an-element") is None
True

iter_elements

iter_elements() -> tuple[Element, ...]

Return all packaged elements in increasing atomic-number order.

Returns:

Type	Description
`tuple[Element, ...]`	An immutable tuple containing H through Og, ordered by atomic number.

Examples:

>>> elements = iter_elements()
>>> elements[0].symbol, elements[-1].symbol
('H', 'Og')

atomref.elements