Skip to content

Home

Carbonic Logo

A modern Python datetime library with fluent API, immutable design, and comprehensive timezone support.

Overview

Carbonic is a datetime library designed for modern Python applications that need powerful, type-safe datetime manipulation. Built with dataclasses and Python's standard library zoneinfo, it provides an intuitive, fluent API for working with dates, times, durations, and intervals.

Key Features

✨ Fluent & Immutable

Chain operations naturally with a fluent API while maintaining immutability for safety:

from carbonic import DateTime, now

# Fluent chaining
result = now().add(days=7).end_of("month").to_date_string()

# All operations return new instances
dt = DateTime(2024, 1, 15, 14, 30)
new_dt = dt.add(hours=2)  # Original dt is unchanged

πŸ”’ Type Safe

Full type annotations and PEP 561 compliance for excellent IDE support:

from carbonic import DateTime, Duration

dt: DateTime = DateTime.now()
duration: Duration = Duration(hours=2, minutes=30)
future: DateTime = dt + duration  # Type checked!

πŸ”„ Standard Library Compatible

New in 1.0.2: Seamlessly work with Python's standard library datetime types:

import datetime
from carbonic import Date, DateTime, Duration

# Direct compatibility with stdlib types
carbonic_date = Date(2024, 1, 15)
native_date = datetime.date(2024, 1, 15)

# All stdlib properties and methods work
print(carbonic_date.year, carbonic_date.month, carbonic_date.day)
print(carbonic_date.weekday())    # 0 (Monday)
print(carbonic_date.isoformat())  # "2024-01-15"

# Direct comparison with stdlib objects
assert carbonic_date == native_date
assert carbonic_date < datetime.date(2024, 1, 16)

# Pass Carbonic objects to functions expecting stdlib types
def takes_date(d: datetime.date) -> str:
    return f"{d.year}-{d.month:02d}-{d.day:02d}"

result = takes_date(carbonic_date)  # Works seamlessly!

🌍 Timezone Aware

Built-in timezone support using Python's standard zoneinfo:

from carbonic import DateTime

# Create timezone-aware datetime
utc_time = DateTime.now()  # UTC by default
ny_time = DateTime.now("America/New_York")

# Convert between timezones
tokyo_time = utc_time.as_timezone("Asia/Tokyo")

πŸ“… Rich Date Operations

Comprehensive date and time manipulation:

from carbonic import DateTime, Period

dt = DateTime(2024, 1, 15)

# Date arithmetic
next_month = dt.add(months=1)
# Note: Additional methods like previous(), next_business_day() may need implementation

# Date boundaries
start_of_week = dt.start_of("week")
end_of_month = dt.end_of("month")

# Duration calculations
other_dt = DateTime(2024, 2, 15)
diff = dt.diff(other_dt)

🌐 Localization Support

Multi-language formatting and humanization with support for 6 languages:

from carbonic import DateTime, Duration

dt = DateTime(2024, 1, 15, 14, 30)
duration = Duration(hours=2, minutes=30)

# English (default)
formatted_en = dt.format("l, F j, Y")  # "Monday, January 15, 2024"
duration_en = duration.humanize()      # "2 hours 30 minutes"

# Polish localization
formatted_pl = dt.format("l, j F Y", locale="pl")  # "poniedziaΕ‚ek, 15 stycznia 2024"
duration_pl = duration.humanize(locale="pl")       # "2 godziny 30 minut"

# Spanish localization
formatted_es = dt.format("l, j {d}e F {d}e Y", locale="es")  # "lunes, 15 de enero de 2024"
duration_es = duration.humanize(locale="es")       # "2 horas 30 minutos"

# French localization
formatted_fr = dt.format("l j F Y", locale="fr")   # "lundi 15 janvier 2024"
duration_fr = duration.humanize(locale="fr")       # "2 heures 30 minutes"

# German localization
formatted_de = dt.format("l, j. F Y", locale="de") # "Montag, 15. Januar 2024"
duration_de = duration.humanize(locale="de")       # "2 Stunden 30 Minuten"

# Portuguese localization
formatted_pt = dt.format("l, j {d}e F {d}e Y", locale="pt")  # "segunda-feira, 15 de janeiro de 2024"
duration_pt = duration.humanize(locale="pt")       # "2 horas 30 minutos"

Supported Locales: English (en), Polish (pl), Spanish (es), French (fr), German (de), Portuguese (pt)

⚑ Performance Optimized

  • Zero-copy operations where possible
  • Lazy evaluation for expensive formatting
  • Memory-efficient immutable design with __slots__
  • Optional fast parsing with ciso8601

πŸ”— Framework Integration

  • Pydantic: Custom field types for validation and serialization
  • JSON Schema: Automatic schema generation for APIs
  • FastAPI: Seamless integration with modern web frameworks

Quick Start

Installation

# Install from PyPI
pip install carbonic

# With optional fast parsing
pip install carbonic[performance]

# With Pydantic integration for validation
pip install carbonic[pydantic]

# Development installation
pip install carbonic[dev]

Basic Usage

from carbonic import DateTime, Date, Duration, now, today

# Current time
current = now()                    # UTC by default
local = now("America/New_York")    # Specific timezone

# Create specific datetime
dt = DateTime(2024, 1, 15, 14, 30, 0, tz="UTC")

# Date-only operations
date = Date(2024, 1, 15)
today_date = today()

# Duration arithmetic
duration = Duration(hours=2, minutes=30)
future = dt + duration

# Formatting
iso_string = dt.to_iso_string()         # "2024-01-15T14:30:00+00:00"
readable = dt.format("Y-m-d H:i:s")    # "2024-01-15 14:30:00"

Pydantic Integration

Carbonic integrates with Pydantic for data validation (requires: pip install carbonic[pydantic]). See the Pydantic integration guide for full details.

from pydantic import BaseModel
from carbonic.integrations.pydantic import DateTimeField

class Event(BaseModel):
    name: str
    start_time: DateTimeField

event = Event(name="Meeting", start_time="2024-01-15T14:30:00Z")
# Result: DateTime(2024, 1, 15, 14, 30, 0, tz='UTC')

Core Classes

Class Purpose Example Usage
DateTime Full datetime with timezone DateTime(2024, 1, 15, 14, 30, tz="UTC")
Date Date-only operations Date(2024, 1, 15)
Duration Time differences Duration(hours=2, minutes=30)
Period Named time periods Period.MONTH, Period.FRIDAY
Interval Time ranges Interval(start_dt, end_dt)

Why Carbonic?

Designed for Modern Python

  • Python 3.12+: Leverages latest Python features
  • Type Safety: Full mypy compatibility
  • Immutability: Prevents bugs and enables safe concurrency
  • Standard Library: No external dependencies for core functionality

Developer Experience

  • Intuitive API: Natural, readable method names
  • Excellent IDE Support: Complete type annotations
  • Comprehensive Testing: 100% test coverage
  • Clear Documentation: Detailed guides and examples

Production Ready

  • Timezone Correct: Proper timezone handling with zoneinfo
  • Business Logic: Built-in business day calculations
  • Localization: Multi-language support architecture
  • Performance: Optimized for real-world usage patterns

Learn More

  • Getting Started

    New to Carbonic? Start here for installation and basic concepts.

    Quick Start

  • User Guide

    Comprehensive guides for each feature and class.

    Browse Guides

  • API Reference

    Complete API documentation with examples.

    API Docs

  • Examples

    Real-world examples and common use cases.

    See Examples

Community & Support

License

Carbonic is released under the MIT License. See the LICENSE file for details.