Add inline type annotations and a typing CI check - #1647

These annotations were compared with the typeshed stubs distributed in
types-python-dateutil==2.9.0.20261021. The implementation is the source of
truth where they differ:

• utils.default_tzinfo accepts objects with tzinfo and an appropriate
  replace method, including datetime.time, preserves their type, and
  accepts None as the replacement zone.
• utils.within_delta accepts compatible
  subtraction and comparison operations, including numbers and dates, rather
  than requiring datetimes and timedeltas.
• parser.parse accepts bytearrays and streams whose read method requires
  a size argument. Parser configuration and time zone lookups use structural
  interfaces. Time zone mappings may return strings or None, as well as
  integer offsets and tzinfo instances.
• ISO parsing accepts bytearrays and streams returning them. Typeshed's annotation
  permits a bytes separator for isoparser, but the implementation requires
  a string when a separator is specified. parse_tzstr returns a tzutc or
  tzoffset instance.
• Relative units in relativedelta accept floats, and weekday arguments may
  provide weekday and n attributes without inheriting from dateutil's
  weekday class. Scaling a relativedelta accepts strings, bytes,
  bytearrays and objects providing __float__ or __index__, because it
  converts the operand with float.
• Arithmetic with a relativedelta does not promise to preserve an arbitrary
  date subclass: adding a time component can promote a date to a datetime.
• Recurrence slicing returns a sequence of datetimes, rather than the single
  datetime specified in typeshed. count exhausts the recurrence and returns
  an integer. replace constructs an rrule, rather than preserving an
  arbitrary subclass.
• Weekday iterables can mix integers and structural weekday objects.
  Recurrence sets accept any iterable of datetimes as a rule.
  Frequencies accept integer variables, while invalid values remain runtime
  errors. Nonzero integer until values are not supported.
• tzfile accepts read-only binary streams without seeking, exposes its
  key, and accepts the constructor's key argument. Its ambiguity method
  does not accept the old idx argument. These differences also reflect
  changes since the version covered by the stubs.
• Fixed offsets and ranges accept objects providing total_seconds.
  Range transitions accept objects supporting addition to a datetime, and
  fixed ranges return None from transitions. Fixed-offset names may be
  None; fixed-zone offset methods always return a timedelta.
• tzstr.instance takes a TZ string and posix_offset, and returns a
  tzstr. The typeshed signature instead describes tzoffset.instance.
• tz.enfold accepts objects supporting replace(fold=...) and preserves
  their type.
• zoneinfo.rebuild ignores its arguments, so its annotations
  do not impose the restrictions of its former implementation.

These measurements compare master (27ecba297e3e33d2e46c0f34f06452d2284bf029), the rebased PR (8bf5f7ac), and the annotation revision before cast removal (7cf76f2e). All three source snapshots are on the same filesystem and use the same _version.py generated by the current Hatchling build. The comparison with the pre-removal revision therefore isolates source changes under the current version-file format; it does not reproduce its former packaging environment. This replaces the earlier table, which compared snapshots on different filesystems.

Each measurement uses a fresh process on CPython 3.11.17 or 3.15.0, with 60 samples and two warm-up rounds. Revision and module order are randomized, the process is pinned to one CPU, and bytecode caches are warm. Processes use -S and PYTHONHASHSEED=0. The timer surrounds importlib.import_module, including dependencies but excluding interpreter startup. Times below are medians in milliseconds; positive changes mean slower imports.

Python 3.11

Python 3.15

The earlier comparison against 64914d9b used the old setuptools-generated version file. There, importing __future__ accounted for most of the root-package overhead. Master's new Hatchling build generates a _version.py that already imports __future__, so that cost is shared by the baseline and PR in this comparison. Preloading __future__ before starting the timer gives the following root-package measurements:

Larger modules also load more bytecode and construct annotation metadata and additional helper definitions. An isolated experiment stripping signature annotations from compiled code reduced some of that overhead, but doesn't establish an exact breakdown. Small differences vary between runs; the percentages for the root package should be read alongside their absolute cost.

The library now contains 13 typing casts, down from 80 in 6ccb96cb and 133 in the initial annotation commit. These use the shared runtime fallback in dateutil._common. The separate ctypes.cast in the Windows module performs a pointer conversion and is not a typing cast.

Other casts were removed through narrower signatures, constrained type variables, a stream capability guard, explicit state invariants, and control flow that carries narrowed values to their uses. No new type-checker suppressions were added.

The tzical parser initializes component state and variables together, then uses that state to guard later access. Pyrefly does not establish that relationship across loop iterations, so seven uses have local unbound-name suppressions. A reduced example also produces a possibly-unbound diagnostic in pyright, while mypy accepts it.

One other suppression preserves an existing component-indexing error in the fallback for dates before the onset of an all-DST zone. This PR does not change that behavior.