Update deprecated typing imports to collections.abc

[brockdyer03]

Description

A number of imports from the typing module have been deprecated since Python 3.9 or 3.10, and were removed/updated in this PR.

Some examples include:

1. typing.Callable -> collections.abc.Callable
2. typing.Sequence -> collections.abc.Sequence
3. typing.Tuple -> tuple
4. typing.Set -> set
5. typing.Union[Any, Any] -> Any | Any
6. typing.Optional[Any] -> Any | None

Tests

I ran nox -s type_check to test the changes.

nox > Running session type_check
nox > Reusing existing virtual environment at .nox/type_check.
nox > uv sync --group type_check --all-extras
Audited 37 packages in 0.36ms
nox > mypy 
Success: no issues found in 176 source files
nox > Session type_check was successful.

OS: Fedora 43 KDE Plasma
Python: 3.14.3
ORCA: 6.1.1
OpenMPI: 4.1.8

---

Release Notes

Fixed

• Updated deprecated typing types to be compliant with Python >=3.11 guidelines (Update deprecated typing imports to collections.abc #216)

[CLAassistant]

All committers have signed the CLA.

[haneug]

Thank you for making a contribution. Please also run the other nox sessions simply with calling uv run nox to perform the import sorting and code formatting.

[timmyte]

@brockdyer03
Good catch! Thanks for updating the outdated annotations.

There is still a Tuple left here in the docstring:
https://github.com/brockdyer03/opi/blob/641a7245e57e477cf637f8ce16c41137bc6ef575/src/opi/output/ir_mode.py#L19

@haneug
We should probably refrain from re-stating the type annotation in the docstrings to avoid these kind of pitfalls.

[brockdyer03]

I've run nox, and additionally fixed the Tuple in ir_modes.py.

One other thing I changed is the use of typing.Union in src/opi/output/models/base/get_item.py, which I've replaced with types.UnionType, which is a recommended alternative since it looks like typing.Union has fallen out of fashion with the typing community.

[brockdyer03]

We should probably refrain from re-stating the type annotation in the docstrings to avoid these kind of pitfalls.

While this isn't my project, I would caution against this as it means that when a user looks at the API documentation they will have to look at the function signature in addition to the docstring, which could become quite laborious for functions with many arguments (scrolling up and down constantly).

Additionally, it should probably be discouraged to write docstrings in that manner in general in my opnion (e.g. writing tuple[float, float, float] in a docstring). A (perhaps) more readable alternative, which seems to be the preference in Numpy, is to use more common language in docstrings as opposed to the actual type hints. This would mean that instead of writing

"""
Attributes
----------
dipole : tuple[float, float, float]
    Dipole derivatives TX TY TZ in atomic units
"""

one would write

"""
Attributes
----------
dipole : tuple of float
    Dipole derivatives TX TY TZ in atomic units
"""

or perhaps even

"""
Attributes
----------
dipole : tuple of float with length 3
    Dipole derivatives TX TY TZ in atomic units
"""

This would result in API documentation that is generally more human-readable, whereas the explicit type syntax is generally considered more machine-readable.

In the end it's a matter of personal preference, but I think that making documentation that is generally in line with Numpy is a good idea since there are a considerable number of Python users that use Numpy and read their documentation, and thus are familiar with their format.

[timmyte]

We should probably refrain from re-stating the type annotation in the docstrings to avoid these kind of pitfalls.

While this isn't my project, I would caution against this as it means that when a user looks at the API documentation they will have to look at the function signature in addition to the docstring, which could become quite laborious for functions with many arguments (scrolling up and down constantly).

Additionally, it should probably be discouraged to write docstrings in that manner in general in my opnion (e.g. writing tuple[float, float, float] in a docstring). A (perhaps) more readable alternative, which seems to be the preference in Numpy, is to use more common language in docstrings as opposed to the actual type hints. This would mean that instead of writing

"""
Attributes
----------
dipole : tuple[float, float, float]
    Dipole derivatives TX TY TZ in atomic units
"""

one would write

"""
Attributes
----------
dipole : tuple of float
    Dipole derivatives TX TY TZ in atomic units
"""

or perhaps even

"""
Attributes
----------
dipole : tuple of float with length 3
    Dipole derivatives TX TY TZ in atomic units
"""

This would result in API documentation that is generally more human-readable, whereas the explicit type syntax is generally considered more machine-readable.

In the end it's a matter of personal preference, but I think that making documentation that is generally in line with Numpy is a good idea since there are a considerable number of Python users that use Numpy and read their documentation, and thus are familiar with their format.

@brockdyer03
Thanks for these points. They are indeed worth considering. I will discuss this with @haneug

[haneug]

Thank you for contributing to OPI!