or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

date-time-components.mddatetime-operations.mdduration-intervals.mdformatting-localization.mdindex.mdtesting-utilities.mdtimezone-management.md
tile.json

tessl/pypi-pendulum

Python datetimes made easy with timezone-aware datetime manipulation and human-readable formatting

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pendulum@3.1.x

To install, run

npx @tessl/cli install tessl/pypi-pendulum@3.1.0

index.mddocs/

Pendulum

A comprehensive Python datetime library that provides timezone-aware datetime manipulation with an intuitive API. Pendulum serves as a drop-in replacement for Python's native datetime class while offering enhanced functionality including seamless timezone handling, natural language formatting, precise duration calculations, and proper handling of daylight saving time transitions.

Package Information

  • Package Name: pendulum
  • Package Type: Library
  • Language: Python
  • Installation: pip install pendulum

Core Imports

import pendulum

For specific classes:

from pendulum import DateTime, Date, Time, Duration, Interval

Basic Usage

import pendulum

# Create timezone-aware datetime (defaults to UTC)
dt = pendulum.now()
print(dt)  # 2024-03-15T14:30:00+00:00

# Create datetime in specific timezone
paris_dt = pendulum.now('Europe/Paris')
print(paris_dt)  # 2024-03-15T15:30:00+01:00

# Create datetime from components
dt = pendulum.datetime(2024, 3, 15, 14, 30, 0)

# Parse datetime strings
dt = pendulum.parse('2024-03-15T14:30:00')
dt = pendulum.from_format('2024-03-15 14:30', 'YYYY-MM-DD HH:mm')

# Date arithmetic with timezone awareness
tomorrow = dt.add(days=1)
last_week = dt.subtract(weeks=1)

# Human-readable differences
diff = dt.diff_for_humans()  # "2 hours ago"

# Duration with years and months support
duration = pendulum.duration(years=1, months=2, days=3)
print(duration.in_words())  # "1 year 2 months 3 days"

# Timezone conversion
utc_dt = paris_dt.in_timezone('UTC')
local_dt = dt.in_timezone('local')

Architecture

Pendulum's design centers around timezone-aware datetime objects with comprehensive manipulation capabilities:

  • DateTime/Date/Time Classes: Core temporal objects with extensive manipulation methods
  • Duration/Interval: Time spans with support for years/months (unlike standard timedelta)
  • Timezone Handling: IANA timezone database integration with DST support
  • Parsing/Formatting: Flexible string parsing and multiple output formats
  • Localization: 200+ locales for human-readable formatting
  • Testing Utilities: Time freezing and travel for deterministic testing

All datetime objects are timezone-aware by default (UTC if not specified), eliminating naive datetime issues while maintaining full compatibility with Python's datetime module.

Capabilities

DateTime Operations

Core datetime creation, manipulation, and timezone handling. Includes creating DateTime objects, timezone conversion, date arithmetic, and comparison operations.

def now(tz: str | Timezone | FixedTimezone | None = None) -> DateTime: ...
def datetime(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, tz: str | float | Timezone | FixedTimezone | datetime.tzinfo | None = UTC, fold: int = 1, raise_on_unknown_times: bool = False) -> DateTime: ...
def local(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0) -> DateTime: ...
def naive(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, fold: int = 1) -> DateTime: ...
def today(tz: str | Timezone = 'local') -> DateTime: ...
def tomorrow(tz: str | Timezone = 'local') -> DateTime: ...
def yesterday(tz: str | Timezone = 'local') -> DateTime: ...
def instance(obj: datetime.datetime | datetime.date | datetime.time, tz: str | None = None) -> DateTime | Date | Time: ...
def parse(string: str, **options) -> DateTime | Date | Time | Duration: ...
def from_format(string: str, fmt: str, tz: str | Timezone = UTC, locale: str | None = None) -> DateTime: ...
def from_timestamp(timestamp: int | float, tz: str = 'UTC') -> DateTime: ...

DateTime Operations

Date and Time Components

Specialized classes for working with date-only and time-only values, providing targeted functionality for applications that don't need full datetime capabilities.

def date(year: int, month: int, day: int) -> Date: ...
def time(hour: int, minute: int = 0, second: int = 0, microsecond: int = 0) -> Time: ...

Date and Time Components

Duration and Intervals

Time span calculations with support for years and months. Includes duration creation, interval operations, and human-readable formatting of time differences.

def duration(days: float = 0, seconds: float = 0, microseconds: float = 0, milliseconds: float = 0, minutes: float = 0, hours: float = 0, weeks: float = 0, years: float = 0, months: float = 0) -> Duration: ...
def interval(start: DateTime, end: DateTime, absolute: bool = False) -> Interval: ...

Duration and Intervals

Timezone Management

Comprehensive timezone handling with IANA database support, including timezone creation, conversion, and local timezone management for testing.

def timezone(name: str | int) -> Timezone | FixedTimezone: ...
def local_timezone() -> Timezone: ...
def set_local_timezone(tz: str | Timezone) -> None: ...
def test_local_timezone(tz: str | Timezone): ...
def timezones() -> set[str]: ...

Timezone Management

Formatting and Localization

Multiple output formats and localization support for human-readable datetime representation across different cultures and languages.

def format_diff(diff: Duration, is_now: bool = True, absolute: bool = False, locale: str | None = None) -> str: ...
def set_locale(name: str) -> None: ...
def get_locale() -> str: ...
def locale(name: str): ...
def week_starts_at(wday: WeekDay) -> None: ...
def week_ends_at(wday: WeekDay) -> None: ...

Formatting and Localization

Testing Utilities

Time manipulation utilities for deterministic testing, including freezing time and traveling to specific moments.

def freeze() -> None: ...
def travel(years: int = 0, months: int = 0, weeks: int = 0, days: int = 0, hours: int = 0, minutes: int = 0, seconds: int = 0, microseconds: int = 0) -> None: ...
def travel_to(dt: DateTime, freeze: bool = False) -> None: ...
def travel_back() -> None: ...

Testing Utilities

Types

class DateTime:
    """Timezone-aware datetime with extensive manipulation capabilities"""
    
class Date:
    """Date without time component"""
    
class Time:
    """Time without date component"""
    
class Duration:
    """Time duration with years/months support"""
    
class Interval:
    """Time interval between two DateTime objects"""
    
class Timezone:
    """IANA timezone representation"""
    
class FixedTimezone:
    """Fixed offset timezone representation"""
    
class WeekDay:
    """Weekday enumeration (MONDAY=0 through SUNDAY=6)"""

Constants

# Version information
__version__: str  # Package version string

# Time unit constants
YEARS_PER_CENTURY: int = 100
YEARS_PER_DECADE: int = 10
MONTHS_PER_YEAR: int = 12
WEEKS_PER_YEAR: int = 52
DAYS_PER_WEEK: int = 7
HOURS_PER_DAY: int = 24
MINUTES_PER_HOUR: int = 60
SECONDS_PER_MINUTE: int = 60
SECONDS_PER_HOUR: int = 3600
SECONDS_PER_DAY: int = 86400

# Weekday constants
MONDAY: WeekDay
TUESDAY: WeekDay
WEDNESDAY: WeekDay
THURSDAY: WeekDay
FRIDAY: WeekDay
SATURDAY: WeekDay
SUNDAY: WeekDay

# Special timezone
UTC: Timezone