---
id: datetype
version: "2025.11.30"
license: The "typeshed" project is licensed under the terms of the Apache license, as reproduced below. = = = = = Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS… (full text in the JSON record)
license_treatment: unclear
maintenance: active
---

# datetype — A type wrapper for the standard library `datetime` that supplies stricter checks, such as making 'datetime' not substitutable for 'date', and separating out Naive and Aware datetimes into separate, mutually-incompatible types.

License: unclear · Maintenance: active · Downloads: 89.5K/mo

## 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 above — 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

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

- License: The "typeshed" project is licensed under the terms of the Apache license, as reproduced below. = = = = = Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS… (full text in the JSON record) (unclear)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 89.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

datetime type checking, strict datetime types, naive aware datetime, type-safe datetime, mypy datetime, datetime type wrapper, type-checking, datetime

[View on SkillFed](https://skillfed.io/packages/datetype) · [View on PyPI](https://pypi.org/project/datetype/)