datetype

What it is and what it does

DateType is a type-checking wrapper for Python's `datetime` module designed to address limitations in how the standard library's datetime types interact with static type checkers. The core issue it solves is that `datetime` objects inherit from `date` at runtime but should not be treated as interchangeable with `date` in type-checked code—a distinction that standard type stubs don't enforce. Additionally, it separates naive (timezone-unaware) and aware (timezone-aware) datetimes into distinct, mutually-incompatible types at the type-checking level, preventing accidental mixing of these fundamentally different datetime representations.

The implementation preserves the runtime behavior of stdlib datetime (instances still inherit as before) while providing separate `Naive` and `Aware` type wrappers and construction methods. It depends only on typing_extensions and supports Python versions from 3.7 through 3.14, making it suitable for projects that need stricter datetime type safety without major runtime overhead or compatibility concerns.

Use it for:

• Enforce type-checker rejection of code that passes a datetime where a date is expected, catching a common source of type errors
• Prevent mixing of naive and aware datetimes in the same codebase by making them incompatible at type-check time
• Migrate a large codebase to stricter datetime typing without rewriting datetime construction logic
• Build libraries that need to document and enforce whether they accept only naive or only aware datetimes

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

DateType provides type-checking-time wrapper types for Python's standard `datetime` module that enforce stricter type distinctions: preventing `datetime` from type-checking as `date`, and separating naive and aware datetimes into mutually-incompatible types.

Yes, if you use a type checker (mypy, pyright) and want stricter datetime type safety. The package is actively maintained, has no known vulnerabilities, and adds minimal friction. It's most valuable in codebases where datetime/date confusion or naive/aware mixing has been a source of bugs. If you don't use static type checking or haven't encountered these issues, it offers no runtime benefit.

Install

datetype on PyPI

pip install datetype

uv add datetype

poetry add datetype

Installing datetype

Before you install

Low install friction with a single lightweight dependency (typing_extensions). The package is actively maintained with recent commits and has been in production status since its first release.

License in practice

Licensed under Apache 2.0 with portions under MIT (inherited from typeshed). Both are permissive licenses suitable for most use cases, though the dual-license structure should be reviewed if you have specific compliance requirements.

Quickstart

pip install datetype

from datetype import Naive, Aware
from datetime import timezone

naive_dt = Naive.now()
aware_dt = Aware.now(timezone.utc)

Verify before relying

• Whether the type-checking fixes apply to all major type checkers (mypy, pyright, etc.) or only mypy
• Runtime performance impact of the wrapper compared to stdlib datetime
• Compatibility with third-party libraries that expect stdlib datetime instances

Package facts

Evidence: datetype-2025.11.30-py3-none-any.whl

Tags

More Software Development packages