DateType

2025.11.30 verified Mon Apr 27 auth: no python

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. Current version: 2025.11.30. Released roughly monthly.

pip install datetype

Common errors

error TypeError: NaiveDateTime instance is not aware ↓

cause Trying to pass a NaiveDateTime where an AwareDateTime (or DateTime) is expected.

fix

Either make the datetime aware by adding a tzinfo, or use NaiveDateTime explicitly in the type annotation.

error AttributeError: 'Date' object has no attribute 'hour' ↓

cause Date objects do not have time components. Attempted to access time attribute on a Date.

fix

Use DateTime or NaiveDateTime if you need time components.

error TypeError: cannot compare datetime.date with datetype.Date ↓

cause Mixing stdlib and DateType types in comparisons.

fix

Convert one type to the other using .to_stdlib() or .from_stdlib() before comparing.

Warnings

breaking DateType types (Date, DateTime, etc.) are NOT interchangeable with stdlib datetime types. Passing a datetype.Date to a function expecting datetime.date will fail type checks and may raise errors at runtime if the function relies on datetime.date methods. ↓

fix Always use datetype types throughout your codebase, or convert using .to_stdlib() and .from_stdlib() methods.

gotcha DateTime is an alias for AwareDateTime, not NaiveDateTime. A naive datetime (without tzinfo) will not be accepted as DateTime; you must use NaiveDateTime explicitly. ↓

fix Use `NaiveDateTime` for naive datetimes and `AwareDateTime` (or `DateTime`) for aware datetimes.

deprecated The `date` and `datetime` names from `datetype` were previously exported but now prefer `Date` and `DateTime` (capitalized). The old lowercase aliases may be removed in future versions. ↓

fix Use `Date`, `DateTime`, `NaiveDateTime`, `AwareDateTime` with capital first letter.

Imports

Date
wrong
```
from datetime import date (DateType wraps but is incompatible)
```
correct
```
from datetype import Date
```
datetype.Date is not the same as datetime.date; they are incompatible by design.
DateTime
wrong
```
from datetime import datetime
```
correct
```
from datetype import DateTime
```
datetype.DateTime is not substitutable for datetime.datetime.

NaiveDateTime

wrong

from datetype import DateTime (NaiveDateTime is distinct from DateTime)

correct

from datetype import NaiveDateTime

DateTime requires aware (tz-aware) instances; use NaiveDateTime for naive.

AwareDateTime
wrong
```
from datetype import DateTime
```
correct
```
from datetype import AwareDateTime
```
AwareDateTime is an alias for DateTime; both require tz-aware.

Quickstart

Create strict date and datetime objects that are not interchangeable with stdlib types.

from datetype import Date, DateTime, NaiveDateTime, AwareDateTime
from datetime import timezone, timedelta

# Date: no time, no timezone
d = Date(2024, 12, 25)
print(d)  # 2024-12-25

# NaiveDateTime: no timezone
ndt = NaiveDateTime(2024, 12, 25, 10, 30)
print(ndt)  # 2024-12-25 10:30:00

# AwareDateTime: requires tzinfo
tz = timezone(timedelta(hours=5))
adt = AwareDateTime(2024, 12, 25, 10, 30, tzinfo=tz)
print(adt)  # 2024-12-25 10:30:00+05:00

# Note: DateTime is same as AwareDateTime
from datetype import DateTime as DT
assert DT is AwareDateTime