Refactor type hints

[ofek]

This PR uses from __future__ import annotations to allow for:

• Lazily computed types (no more strings)
• Direct subscripting of built-in types e.g. Dict[str, List[str]] -> dict[str, list[str]]
• Removal of Optional in favor of | None e.g. str | None
• Removal of Union in favor of | e.g. str | int

Notes:

• The VersionComparisonMethod type alias in src/packaging/version.py was unused so I removed it
• All types are now stored in a dedicated file src/packaging/_types.py but type definitions must use the old-style type classes because it is ambiguous that they are type aliases for use in annotations rather than assignments and typing.TypeAlias was introduced only very recently in 3.10
• After this is merged I plan to do one or two more PRs that will drastically reduce the cost of importing packaging modules

[pradyunsg]

After this is merged I plan to do one or two more PRs that will drastically reduce the cost of importing packaging modules

Could you please mention what these changes / PRs would be doing, and how they'd reduce the import overhead?

[ofek]

The majority of the improvement will be lazily loading imports such as subprocess and logging, and I may defer regular expression compilation in a second PR however I don't see that being a huge improvement.

[ofek]

ofek#1

❯ docker run --rm python:3.13-rc bash -c "python -m pip install -qqq 'packaging @ git+https://github.com/pypa/packaging@main' && python -c 'from packaging.requirements import Requirement' && sleep 2 && for i in {1..10}; do python -m timeit -n 1 -r 1 'from packaging.requirements import Requirement'; done"
1 loop, best of 1: 32.3 msec per loop
1 loop, best of 1: 32.1 msec per loop
1 loop, best of 1: 32.2 msec per loop
1 loop, best of 1: 31.5 msec per loop
1 loop, best of 1: 31.3 msec per loop
1 loop, best of 1: 31.5 msec per loop
1 loop, best of 1: 31.5 msec per loop
1 loop, best of 1: 31.4 msec per loop
1 loop, best of 1: 31.3 msec per loop
1 loop, best of 1: 32.1 msec per loop

❯ docker run --rm python:3.13-rc bash -c "python -m pip install -qqq 'packaging @ git+https://github.com/ofek/packaging@import-time-1' && python -c 'from packaging.requirements import Requirement' && sleep 2 && for i in {1..10}; do python -m timeit -n 1 -r 1 'from packaging.requirements import Requirement'; done"
1 loop, best of 1: 16.5 msec per loop
1 loop, best of 1: 16.9 msec per loop
1 loop, best of 1: 17.1 msec per loop
1 loop, best of 1: 16.9 msec per loop
1 loop, best of 1: 17 msec per loop
1 loop, best of 1: 16.8 msec per loop
1 loop, best of 1: 16.9 msec per loop
1 loop, best of 1: 16.9 msec per loop
1 loop, best of 1: 16.9 msec per loop
1 loop, best of 1: 16.9 msec per loop

[ofek]

This PR is ready for review!

[zanieb]

Why are these changes needed for ofek#1?

[ofek]

I thought I would do a refactor first since I saw a performance benefit to separating type definitions into a separate module. The benefit turned out to be nonexistent because the annotations import has an equivalent cost (it will go away eventually) but I figured this is useful anyway since there is no benefit to defining runtime types.

I think the changes here are useful as the typing people are encouraging the more built-in approaches and heavily discouraging (I can't find where at the moment) the use of Optional and Union.

[ofek]

Found it: https://discuss.python.org/t/clarification-for-pep-604-is-foo-int-none-to-replace-all-use-of-foo-optional-int/26945/6

[Secrus]

I don't think this is valid anymore. The issue is closed in the mypy repo, maybe you could check? WOuld be nice to avoid hauling around the tech debt.

[ofek]

I thought the same thing and tried but encountered errors.

[pradyunsg]

I came here to merge this and realised that the codebase has evolved meaningfully since this PR was filed, so filed an updated #785.

[ofek]

After that is merged I will do the lazy import performance improvement in a separate PR!