datetype

library2025.11.30pypypi✓ verified 85d ago

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.

type-stubs serialization

pip install datetype

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · DATETYPE

datetype

type-stubspythonv2025.11.30

Install

1.6s avg

Import

15ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2025.11.30 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.014s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.016s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Date

✓ from datetype import Date

✗ from datetime import date (DateType wraps but is incompatible)

datetype.Date is not the same as datetime.date; they are incompatible by design.

DateTime

✓ from datetype import DateTime

✗ from datetime import datetime

datetype.DateTime is not substitutable for datetime.datetime.

NaiveDateTime

✓ from datetype import NaiveDateTime

✗ from datetype import DateTime (NaiveDateTime is distinct from DateTime)

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

AwareDateTime

✓ from datetype import AwareDateTime

✗ from datetype import DateTime

AwareDateTime is an alias for DateTime; both require tz-aware.

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

Debug

Known issues

breakingDateType 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.

affects: all

gotchaDateTime 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.

affects: all

deprecatedThe `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.

affects: >=2024.0.0

Errors

Common errors & fixes

TypeError: NaiveDateTime instance is not aware

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.

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

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.

TypeError: cannot compare datetime.date with datetype.Date

Mixing stdlib and DateType types in comparisons.

fix

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

Upgrade

Version history

2025.11.30latest on PyPI · released Dec 1, 2025

Audit

Dependencies

typing-extensionsoptionalUsed for type hints like Literal on older Python versions

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/glyph/DateType ↗

packagehttps://pypi.org/project/datetype/ ↗

docshttps://datetype.readthedocs.io/en/latest/ ↗