Date

The Date class provides date-only operations without time components.

carbonic.core.date.Date dataclass

Date(year: int, month: int, day: int)

Immutable date object with fluent API and comprehensive date operations.

The Date class provides a modern, type-safe wrapper around Python's date with additional functionality for date manipulation and formatting. All operations return new instances, maintaining immutability.

Attributes:

Name	Type	Description
_date	date	Internal datetime.date object storing the actual date value

Examples:

>>> date = Date(2024, 1, 15)
>>> date.add(days=10).format("Y-m-d")
'2024-01-25'

>>> today = Date.today()
>>> today.start_of("month").format("F j, Y")
'January 1, 2024'

Initialize a new Date instance.

Parameters:

Name	Type	Description	Default
year	int	Year (e.g., 2024)	required
month	int	Month (1-12)	required
day	int	Day of month (1-31)	required

Raises:

Type	Description
ValueError	If any date component is invalid

Attributes

iso_week property

iso_week: tuple[int, int]

Return (year, week) tuple.

Functions

today classmethod

today(tz: str | None = None) -> Date

Create a Date instance for today.

tomorrow classmethod

tomorrow() -> Date

Get tomorrow's date.

Returns:

Type	Description
Date	Date object representing tomorrow

yesterday classmethod

yesterday() -> Date

Get yesterday's date.

Returns:

Type	Description
Date	Date object representing yesterday

next classmethod

next(unit: str, count: int = 1) -> Date

Get a date in the future relative to today.

Parameters:

Name	Type	Description	Default
unit	str	Time unit ("day", "week", "month", "quarter", "year")	required
count	int	Number of units to add (default: 1)	1

Returns:

Type	Description
Date	Date object in the future

Examples:

>>> Date.next("day")      # Tomorrow
>>> Date.next("week", 2)  # 2 weeks from today
>>> Date.next("month")    # Next month

previous classmethod

previous(unit: str, count: int = 1) -> Date

Get a date in the past relative to today.

Parameters:

Name	Type	Description	Default
unit	str	Time unit ("day", "week", "month", "quarter", "year")	required
count	int	Number of units to subtract (default: 1)	1

Returns:

Type	Description
Date	Date object in the past

Examples:

>>> Date.previous("day")      # Yesterday
>>> Date.previous("week", 2)  # 2 weeks ago
>>> Date.previous("month")    # Last month

parse classmethod

parse(s: str, fmt: str | None = None) -> Date

Parse a date string into a Date object.

Parameters:

Name	Type	Description	Default
s	str	The date string to parse. Supports: - ISO date formats (2024-01-15) - Custom formats when fmt is provided	required
fmt	str | None	Optional format string. If None, auto-detect format. Supports both strftime (%Y-%m-%d) and Carbon (Y-m-d) formats.	None

Returns:

Type	Description
Date	Date object

Raises:

Type	Description
ParseError	If the string cannot be parsed

Examples:

>>> Date.parse("2024-01-15")

from_date classmethod

from_date(d: date) -> Date

Create a Date instance from datetime.date.

weekday

weekday() -> int

Return day of week where Monday=0, Sunday=6 (datetime.date compatibility).

isoweekday

isoweekday() -> int

ISO weekday where Monday=1, Sunday=7 (datetime.date compatibility).

isoformat

isoformat() -> str

Return ISO 8601 format string (YYYY-MM-DD) for datetime.date compatibility.

isocalendar

isocalendar() -> tuple[int, int, int]

Return (year, week, weekday) tuple for datetime.date compatibility.

timetuple

timetuple()

Return time.struct_time for datetime.date compatibility.

toordinal

toordinal() -> int

Return proleptic Gregorian ordinal for datetime.date compatibility.

replace

replace(
    year: int | None = None, month: int | None = None, day: int | None = None
) -> Date

Return a Date with one or more components replaced (datetime.date compatibility).

add

add(*, years: int = 0, months: int = 0, days: int = 0) -> Date

Add years, months, and/or days to this date.

subtract

subtract(*, years: int = 0, months: int = 0, days: int = 0) -> Date

Subtract years, months, and/or days from this date.

diff

diff(other: Date, *, absolute: bool = False) -> Duration

Calculate difference between this date and another date.

Parameters:

Name	Type	Description	Default
other	Date	The other date to compare with	required
absolute	bool	If True, return absolute difference (always positive)	False

Returns:

Type	Description
Duration	Duration representing the difference

add_duration

add_duration(duration: Duration) -> Date

Add a Duration to this Date.

Parameters:

Name	Type	Description	Default
duration	Duration	The Duration to add	required

Returns:

Type	Description
Date	New Date with the duration added

subtract_duration

subtract_duration(duration: Duration) -> Date

Subtract a Duration from this Date.

Parameters:

Name	Type	Description	Default
duration	Duration	The Duration to subtract	required

Returns:

Type	Description
Date	New Date with the duration subtracted

start_of

start_of(unit: Literal['day', 'month', 'year', 'quarter', 'week']) -> Date

Return the start of the specified time period.

end_of

end_of(unit: Literal['day', 'month', 'year', 'quarter', 'week']) -> Date

Return the end of the specified time period.

is_weekday

is_weekday() -> bool

Return True if this date is a weekday (Monday-Friday).

is_weekend

is_weekend() -> bool

Return True if this date is a weekend (Saturday-Sunday).

add_business_days

add_business_days(days: int) -> Date

Add business days to this date, skipping weekends.

Parameters:

Name	Type	Description	Default
days	int	Number of business days to add (can be negative)	required

Returns:

Type	Description
Date	New Date with business days added

Examples:

Date(2023, 12, 25).add_business_days(1) # Monday -> Tuesday Date(2023, 12, 29).add_business_days(1) # Friday -> Monday (skip weekend)

subtract_business_days

subtract_business_days(days: int) -> Date

Subtract business days from this date, skipping weekends.

Parameters:

Name	Type	Description	Default
days	int	Number of business days to subtract (can be negative)	required

Returns:

Type	Description
Date	New Date with business days subtracted

Examples:

Date(2023, 12, 26).subtract_business_days(1) # Tuesday -> Monday Date(2024, 1, 1).subtract_business_days(1) # Monday -> Friday (skip weekend)

to_datetime

to_datetime(tz: str | None = 'UTC') -> datetime.datetime

Convert to datetime.datetime with timezone (default UTC).

to_date

to_date() -> datetime.date

Return a copy of the underlying datetime.date object.

strftime

strftime(fmt: str) -> str

Format date using strftime format string.

format

format(fmt: str, *, locale: str | None = None) -> str

Format date using Carbon-style format string.

Uses Carbon-style tokens for flexible date formatting. Escape characters with backslash () to include them literally.

Format Tokens

Token	Description	Example
Y	4-digit year	2024
y	2-digit year	24
m	Month with leading zero	01, 12
n	Month without leading zero	1, 12
d	Day with leading zero	01, 31
j	Day without leading zero	1, 31
S	Ordinal suffix	st, nd, rd, th
F	Full month name (localized)	January, enero
M	Short month name (localized)	Jan, ene
l	Full day name (localized)	Monday, lunes
D	Short day name (localized)	Mon, lun

Parameters:

Name	Type	Description	Default
fmt	str	Carbon-style format string with tokens above	required
locale	str | None	Locale code for localized month/day names (default: English) Supported: en, pl, es, fr, de, pt	None

Returns:

Type	Description
str	Formatted date string

Examples:

>>> date = Date(2024, 1, 15)
>>> date.format("Y-m-d")
'2024-01-15'
>>> date.format("l, F j, Y")
'Monday, January 15, 2024'
>>> date.format("l, F j, Y", locale="es")
'lunes, enero 15, 2024'
>>> date.format("jS \\o\\f F Y")
'15th of January 2024'

to_iso_string

to_iso_string() -> str

Return ISO date string (YYYY-MM-DD).

to_datetime_string

to_datetime_string() -> str

Return date with default time (YYYY-MM-DD 00:00:00).