Delorean Python datetime manipulation library

Delorean's scope for timezone-aware datetime work

Delorean addresses the code that appears when an application has to shift, manipulate, or generate Python datetime values. Its intended users are Python developers working with time zones, date calculations, and abstractions around `datetime`. The library presents this as a cleaner alternative to constructing and converting values through several lower-level operations.

The README contrasts a conventional `zoneinfo` workflow with a shorter Delorean call. The standard-library example creates a UTC datetime with `datetime.now(timezone.utc)`, converts it to `US/Eastern` with `astimezone`, and uses `ZoneInfo`. Delorean wraps the practical shift in the following sequence:

from delorean import Delorean

d = Delorean()
d = d.shift('US/Eastern')
return d

That comparison establishes the library's main value proposition: reduce explicit timezone manipulation while retaining datetime behavior. It does not claim that Delorean creates time itself, stores scheduling state, or handles recurring events. Its responsibility is datetime manipulation, not a full scheduling or event-processing system.

The repository metadata identifies Delorean as a Python 3-only package and classifies it under date, datetime, time zone, and timedelta topics. Version 2.0.0 declares Python 3.10 as its minimum supported version and lists compatibility classifiers through Python 3.14. This makes the dependency and runtime boundary clear for a small library, but compatibility with an application still depends on the interpreter selected by that application.

Delorean's dependency model and package structure

Delorean is not presented as an isolated datetime implementation. Its `pyproject.toml` declares `babel>=2.10.3`, `humanize>=4.2.2`, `python-dateutil>=2.8.2`, and `tzlocal>=4.2` as runtime dependencies. The README also states that the project stands on the standard library's `zoneinfo` and `dateutil`. Those references point to a layered design in which timezone-aware behavior comes from established components rather than from a separate time database maintained by Delorean.

The repository includes the `delorean/` package, tests, documentation, `CHANGES.rst`, and a `changelog.d/` directory. The build configuration uses Hatchling and includes the `delorean` package in the wheel. The repository also contains `uv.lock`, so dependency resolution is represented as part of the development setup even though the package metadata remains based on version ranges.

This dependency model has a direct adoption cost. A project that already standardizes on `dateutil` or `zoneinfo` may find that Delorean requires additional packages, particularly `babel`, `humanize`, and `tzlocal`. Conversely, applications that need Delorean's abstraction can avoid implementing timezone conversion and related formatting behavior themselves. The README does not document a no-dependency mode, so dependency reduction should not be assumed.

The public API is exported from `delorean/__init__.py`, which the lint configuration treats as a re-export module. The README demonstrates `Delorean` and `shift`, but it does not provide a complete inventory of every class, function, supported format, or conversion rule.

Using Delorean for a first timezone shift

The README directs new users to the documentation after a short example. It does not provide an installation command, so there is no confirmed package-manager invocation to copy here. For developers working from the repository, the Makefile exposes a test task through `uv`, which can establish whether the local development environment is usable before trying the example in application code.

The documented first use is intentionally minimal. Import `Delorean`, construct an instance, and shift it to a named time zone. The README uses `US/Eastern`; the package metadata includes `tzlocal`, although the README does not explain how that package affects the constructor or shift operation.

The development test command is:

uv run pytest

The Makefile maps this command to the `test` target. It is a repository verification command, not an installation guide for consuming Delorean as a dependency. A reader who follows that target should expect it to invoke the repository's pytest suite under the `uv` environment. The documentation at `http://delorean.rtfd.org/` is the project-linked location for usage information beyond the README.

The example returns a value rather than printing a result. That detail matters when adapting it: application code must use the returned object, and the README does not state its exact string representation or show how to serialize it. The example also does not specify what happens when the time zone name is invalid, whether the object preserves naive datetime values, or how daylight-saving transitions are handled.

Delorean 2.0.0 maintenance and Python upgrade boundaries

The repository is not archived, and its last push was on 2026-08-01. It also has a recent release, `2.0.0`, dated 2026-08-01. Those facts indicate current project activity in the repository record, but they do not prove that every API is stable or that the project will preserve compatibility across future Python releases.

The package requires Python `>=3.10`. The project metadata lists Python 3.10 through 3.14, and its development group includes `pytest`, `ruff`, `black`, and `towncrier`, while the documentation group includes `Sphinx`. The Makefile uses `uv` for tests, formatting, linting, and documentation commands. This gives maintainers several project-specific maintenance paths, but it does not document a support policy for older Python versions or a long-term-support branch.

The license is MIT, and the package declares `LICENSE.txt` as its license file. That identifies the repository's stated licensing model. It does not, by itself, settle whether a particular application satisfies its legal or policy requirements. The main upgrade consideration visible in `pyproject.toml` is technical: moving to Python 3.10 or newer is mandatory for version 2.0.0, and dependency versions are expressed as minimum constraints rather than fixed runtime pins. The `uv.lock` file may support reproducible repository development, but the README does not say whether it is intended for downstream applications.

Before upgrading an existing integration, the most concrete checks are the Python version, the behavior of timezone shifts, and the handling of values at timezone boundaries. Those checks matter because the README does not document migration steps from version 1.0.0 to 2.0.0.

Where Delorean differs from direct zoneinfo and dateutil use

The clearest alternative is to use Python's `datetime`, `timezone`, and `zoneinfo` directly, as shown in the README's opening example. That approach keeps timezone conversion close to the standard library and exposes each operation explicitly. It also avoids introducing Delorean's additional runtime dependencies, including `babel`, `humanize`, and `tzlocal`.

The trade-off is verbosity. Direct `zoneinfo` code requires the application to construct the current datetime, select the target zone, and call `astimezone`. Delorean reduces that sequence to construction followed by `shift('US/Eastern')`. That is useful when the application performs this pattern repeatedly and does not need to expose every intermediate operation.

`python-dateutil` is another stated foundation and dependency. `python-dateutil` is another stated foundation and dependency of Delorean. The README does not provide a feature matrix comparing Delorean with `dateutil`, so the exact division between parsing, shifting, formatting, and generation cannot be inferred from the repository.

Delorean is the wrong choice when minimizing dependencies is a hard requirement, when an application needs a narrowly specified operation that is easier to audit in direct standard-library code, or when undocumented edge-case behavior would be unacceptable. The library's convenience comes with an additional API layer, and the README does not explain all of that layer's semantics.

Delorean's operational limits for production datetime code

The first limitation is documentation depth in the README. It gives only a small timezone-shift example and refers readers to the external documentation for other features. It does not specify supported date formats, timezone database behavior, naive datetime handling, daylight-saving transition behavior, or serialization rules. Those omissions make direct adoption risky for code that makes correctness decisions around ambiguous local times.

A second limitation is the small set of concrete API examples. The repository metadata and README confirm the `Delorean` class and a `shift` call, but the README does not document whether Delorean accepts dates, strings, epochs, or other input types, nor does it define the full result contract. The phrase about generating datetimes indicates that generation is within the project's stated scope, but the README contains no generation example.

The runtime dependency list is also relevant when evaluating installation requirements. The repository files do not expose configuration for selecting a timezone database or controlling formatting, so applications should not assume that behavior can be tuned through Delorean without consulting the full documentation.

The project is best treated as a convenience layer for application code, not as a replacement for a scheduling engine, persistence model, or time synchronization service. The repository layout supports library development and testing, but it does not describe distributed behavior, background jobs, or operational monitoring.

Editorial conclusion

Python developers who want a higher-level interface for shifting datetimes between named time zones should inspect Delorean, especially its supported operations and timezone behavior. Projects that need a small dependency surface or prefer direct control through the standard library and dateutil should first verify that the convenience layer does not hide requirements their code must handle explicitly.

Frequently asked questions

Official sources

1. License: MIT
2. myusuf3/delorean on GitHub
3. Project website
4. README
5. Releases