eones.core package

core.__init__.py

Submodules

eones.core.date module

core.date.py

class eones.core.date.Date(dt: datetime | None = None, tz: str | None = 'UTC', naive: Literal['utc', 'local', 'raise'] = 'raise')

Bases: object

Time manipulation wrapper for timezone-aware datetime operations.

property as_local: datetime

Return the datetime converted to the system’s local timezone.

as_utc() → datetime

Convert to UTC timezone.

Returns:

Datetime in UTC.

Return type:

datetime

as_zone(zone: str) → datetime

Convert to a specific timezone.

Parameters:

zone (str) – Target timezone name.

Returns:

Datetime in the new timezone.

Return type:

datetime

ceil(unit: str) → Date

Returns a new Date advanced to the end of the given unit.

property day: int

Day component of the date.

days_until(other: Date) → int

Return the number of days until other.

Positive if other is later; negative if earlier.

diff(other: Date, unit: Literal['days', 'weeks', 'months', 'years'] = 'days') → int

Return the absolute difference in the specified unit.

diff_for_humans(other: Date | None = None, locale: str = 'en') → str

Return a human-readable difference between two dates.

end_of(unit: Literal['year', 'month', 'week', 'day', 'hour', 'minute', 'second']) → Date

Returns the datetime aligned to the end of the given unit.

Parameters:

unit (Literal) – Temporal unit.

Returns:

Aligned datetime.

Return type:

Date

end_of_day() → Date

Return a new Date instance representing the end of the current day.

end_of_month() → Date

Return a new Date instance representing the last moment of the current month (23:59:59.999999 UTC).

end_of_year() → Date

Return a Date for the last moment of the current year.

floor(unit: Literal['year', 'month', 'week', 'day', 'hour', 'minute', 'second']) → Date

Return a new Date aligned to the start of the given unit.

format(fmt: str) → str

Return formatted datetime as a string.

classmethod from_iso(iso_str: str, tz: str | None = 'UTC') → Date

Create a Date from an ISO 8601 string.

classmethod from_timezone_aware_datetime(dt: datetime) → Date

Create a Date from a timezone-aware datetime, preserving the timezone.

This is an internal method to handle timezone-aware datetimes without accessing protected members directly.

Parameters:

dt – A timezone-aware datetime object

Returns:

A Date instance preserving the original timezone

Return type:

Date

classmethod from_unix(timestamp: float, tz: str | None = 'UTC') → Date

Create a Date from a Unix timestamp.

Parameters:

• timestamp (float) – Seconds since epoch.

• tz (str, optional) – Timezone. Defaults to “UTC”.

Returns:

Parsed Date.

Return type:

Date

property hour: int

Hour component of the date.

is_after(other: Date) → bool

Return True if the current date is after other.

is_before(other: Date) → bool

Return True if the current date is before other.

is_between(start: datetime, end: datetime, inclusive: bool = True) → bool

Check if date is between two datetime bounds.

Parameters:

• start (datetime) – Start datetime.

• end (datetime) – End datetime.

• inclusive (bool) – Include boundaries. Defaults to True.

Returns:

True if in range.

Return type:

bool

is_friday() → bool

Return True if the current date is a Friday.

Returns:

True if the date is Friday, False otherwise.

Return type:

bool

is_leap_year() → bool

Return True if the current year is a leap year.

Returns:

True if the year is a leap year, False otherwise.

Return type:

bool

is_monday() → bool

Return True if the current date is a Monday.

Returns:

True if the date is Monday, False otherwise.

Return type:

bool

is_same_day(other: Date) → bool

Return True if both dates fall on the same calendar day.

is_same_week(other: Date) → bool

Check if two dates fall in the same ISO calendar week.

Parameters:

other (Date) – Date to compare.

Returns:

True if both dates share the same ISO week.

Return type:

bool

is_saturday() → bool

Return True if the current date is a Saturday.

Returns:

True if the date is Saturday, False otherwise.

Return type:

bool

is_sunday() → bool

Return True if the current date is a Sunday.

Returns:

True if the date is Sunday, False otherwise.

Return type:

bool

is_thursday() → bool

Return True if the current date is a Thursday.

Returns:

True if the date is Thursday, False otherwise.

Return type:

bool

is_tuesday() → bool

Return True if the current date is a Tuesday.

Returns:

True if the date is Tuesday, False otherwise.

Return type:

bool

is_wednesday() → bool

Return True if the current date is a Wednesday.

Returns:

True if the date is Wednesday, False otherwise.

Return type:

bool

is_weekend() → bool

Return True if the current date falls on a weekend (Saturday or Sunday).

Returns:

True if the date is Saturday (5) or Sunday (6), False otherwise.

Return type:

bool

is_within(other: Date, check_month: bool = True) → bool

Check if the current date is within the same year/month as another Date.

Parameters:

• other (Date) – Date to compare.

• check_month (bool) – If True, also check that months match.

Returns:

True if within the same period.

Return type:

bool

property microsecond: int

Microsecond component of the date.

property minute: int

Minute component of the date.

property month: int

Month component of the date.

month_span_to(other: Date) → int

Return the number of full calendar months between self and other. Positive if other is later. Negative if other is earlier.

next_weekday(weekday: int) → Date

Return the next date matching the specified weekday.

Parameters:

weekday (int) – Target weekday (0 = Monday).

Returns:

The next date matching the weekday.

Return type:

Date

classmethod now(tz: str = 'UTC', naive: Literal['utc', 'local', 'raise'] = 'raise') → Date

Create a Date for the current moment.

previous_weekday(weekday: int) → Date

Return the previous date matching the specified weekday.

Parameters:

weekday (int) – Target weekday (0 = Monday).

Returns:

The previous date matching the weekday.

Return type:

Date

replace(tz: str | None = None, naive: Literal['utc', 'local', 'raise'] | None = None, **kwargs: Any) → Date

Return a new Date with specific fields replaced.

round(unit: str) → Date

Round the Date to the nearest specified unit.

property second: int

Second component of the date.

shift(delta: timedelta) → Date

Return a new Date shifted by the given timedelta.

start_of(unit: Literal['year', 'month', 'week', 'day', 'hour', 'minute', 'second']) → Date

Returns the datetime aligned to the start of the given unit.

Parameters:

unit (Literal) – Temporal unit.

Returns:

Aligned datetime.

Return type:

Date

start_of_day() → Date

Return a new Date instance representing the start of the current day.

start_of_month() → Date

Return a new Date instance for the first moment of the current month.

start_of_year() → Date

Return a new Date instance for the first moment of the current year.

property timezone: str

Return the key of the timezone in use.

to_datetime() → datetime

Return the internal datetime object.

Returns:

The timezone-aware datetime.

Return type:

datetime

to_dict() → dict

Return a dictionary representation of the Date.

to_iso() → str

Return ISO 8601 formatted string of the datetime.

Returns:

ISO format datetime string.

Return type:

str

to_unix() → float

Return Unix timestamp of the datetime.

Returns:

Unix timestamp.

Return type:

float

truncate(unit: str) → Date

Truncate the Date to the specified unit (e.g., ‘day’, ‘hour’, etc.).

property year: int

Year component of the date.

year_span_to(other: Date) → int

Return the number of full calendar years between self and other. Positive if other is later. Negative if other is earlier.

Example

Date(“2020-05-20”).year_span_to(Date(“2024-05-19”)) == 3 Date(“2020-05-20”).year_span_to(Date(“2024-05-20”)) == 4

eones.core.delta module

core.delta.py

class eones.core.delta.Delta(**kwargs: int)

Bases: object

Represents a compound time delta composed of calendar (years, months) and duration (weeks, days, hours, minutes, seconds) components.

Calendar components are applied first, followed by duration components. This order preserves intuitive behavior when transitioning across irregular month lengths (e.g., Jan 31 + 1 month → Feb 28/29).

Examples

>>> Delta(years=1, days=3)
>>> Delta.from_iso("P1Y3D")

Notes

The original input dictionary is preserved for accurate inversion and scaling.

apply(date: Date, calendar: bool = True, duration: bool = True) → Date

Apply this delta to a Date instance.

Parameters:

• date (Date) – The reference date.

• calendar (bool) – Whether to apply calendar delta (years/months).

• duration (bool) – Whether to apply duration delta (weeks to seconds).

Returns:

A new shifted Date instance.

Return type:

Date

Raises:

TypeError – If input is not a Date.

apply_calendar(date: Date) → Date

Apply only the calendar part to a date.

Parameters:

date (Date) – The original date.

Returns:

Date with years/months applied.

Return type:

Date

apply_duration(date: Date) → Date

Apply only the duration part to a date.

Parameters:

date (Date) – The original date.

Returns:

Date with weeks to seconds applied.

Return type:

Date

classmethod from_iso(iso: str) → Delta

Parse ISO 8601 delta string.

Parameters:

iso (str) – ISO-compliant duration string.

Returns:

Parsed instance.

Return type:

Delta

Raises:

ValueError – If the format is invalid.

classmethod from_timedelta(td: timedelta) → Delta

Create a Delta instance from datetime.timedelta.

invert() → Delta

Return the inverse of this delta.

Returns:

Negated delta.

Return type:

Delta

is_zero() → bool

Check if the delta has no effect.

Returns:

True if delta is zero.

Return type:

bool

scale(factor: int) → Delta

Multiply the delta by a scalar.

Parameters:

factor (int) – Scaling multiplier.

Returns:

A new instance.

Return type:

Delta

to_dict() → Dict[str, int]

Return a normalized dict combining calendar and duration.

Returns:

Keys include ‘years’, ‘months’, ‘days’, ‘hours’, etc.

Return type:

Dict[str, int]

to_input_dict() → Dict[str, int]

Return the original input dictionary.

Returns:

User-specified delta components.

Return type:

Dict[str, int]

to_iso() → str

Return ISO 8601-compliant string representation.

Returns:

Serialized delta (e.g., ‘P1Y2M3DT4H30M’).

Return type:

str

property total_months: int

Return the calendar component expressed as total months.

property total_seconds: int

Return the duration component expressed as total seconds.

eones.core.delta_calendar module

core.calendar.py

class eones.core.delta_calendar.DeltaCalendar(years: int = 0, months: int = 0)

Bases: object

Represents calendar-based deltas using months and years.

Unlike timedelta-based durations, this class handles logical time shifts such as “add 1 month” or “add 2 years”, accounting for month boundaries and varying month lengths.

Internally, it normalizes the delta into absolute months and reconstructs years and months from that total.

Examples

>>> DeltaCalendar(years=1, months=2)
>>> DeltaCalendar.from_iso("P1Y2M")

Notes

The day component of the input datetime may be truncated if the target month has fewer days.

apply(base_datetime: datetime) → datetime

Apply the calendar delta to a datetime.

Shifts the month and year while preserving the day when possible. If the resulting month has fewer days, the day is truncated.

Parameters:

base_datetime (datetime) – The original datetime.

Returns:

A new datetime with the delta applied.

Return type:

datetime

classmethod from_iso(iso: str) → DeltaCalendar

Parse an ISO 8601 calendar delta string.

Parameters:

iso (str) – ISO string.

Returns:

Parsed instance.

Return type:

DeltaCalendar

Raises:

ValueError – If the string is not valid ISO format.

invert() → DeltaCalendar

Return a new DeltaCalendar with reversed direction.

Returns:

The inverse calendar delta.

Return type:

DeltaCalendar

is_zero() → bool

Check if the delta represents no change.

Returns:

True if both years and months are 0.

Return type:

bool

months

scale(factor: int) → DeltaCalendar

Multiply the delta by a scalar.

Parameters:

factor (int) – Multiplier.

Returns:

A new scaled instance.

Return type:

DeltaCalendar

to_dict() → Dict[str, int]

Return a normalized version of the delta.

This version reflects the internal normalized representation (e.g., years=1, months=13 → years=2, months=1).

Returns:

Keys are “years” and “months”.

Return type:

Dict[str, int]

to_input_dict() → Dict[str, int]

Return the original input as passed by the user.

Returns:

The original unnormalized dictionary.

Return type:

Dict[str, int]

to_iso() → str

Serialize to ISO 8601 calendar duration.

Returns:

ISO representation (e.g., ‘P1Y2M’).

Return type:

str

property total_months: int

Return the delta expressed as total months.

years

eones.core.delta_duration module

core.delta_duration.py

class eones.core.delta_duration.DeltaDuration(**kwargs: int)

Bases: object

Represents a duration-based delta using standard time components.

This class encapsulates time intervals expressed in weeks, days, hours, minutes, and seconds. Internally, it leverages Python’s timedelta but preserves original input granularity for semantic clarity.

Examples

>>> DeltaDuration(days=2, hours=4)
>>> DeltaDuration.from_iso("P1DT3H")

Notes

• Zero values are excluded from internal state.

• Input validation ensures only integers are accepted (not bools).

apply(base_datetime: datetime) → datetime

Apply the duration delta to a given datetime.

Parameters:

base_datetime (datetime) – The base datetime to shift.

Returns:

A new datetime offset by this delta.

Return type:

datetime

classmethod from_iso(iso: str) → DeltaDuration

Parse an ISO 8601 duration string.

Supports optional weeks (e.g., ‘P2W’) as per extended ISO 8601.

Parameters:

iso (str) – Duration in ISO 8601 format.

Returns:

Parsed delta instance.

Return type:

DeltaDuration

Raises:

ValueError – If the format is invalid.

classmethod from_timedelta(td: timedelta) → DeltaDuration

Create a DeltaDuration from a datetime.timedelta.

invert() → DeltaDuration

Return a new DeltaDuration with negated values.

Returns:

The inverse duration.

Return type:

DeltaDuration

is_zero() → bool

Check if the duration is equivalent to zero.

Returns:

True if total time is 0 seconds.

Return type:

bool

scale(factor: int) → DeltaDuration

Multiply the duration by a scalar factor.

Parameters:

factor (int) – The scaling multiplier.

Returns:

A new instance with scaled values.

Return type:

DeltaDuration

timedelta

to_dict() → Dict[str, int]

Return a normalized breakdown of the duration into explicit units.

Returns:

Keys are days, hours, minutes, and seconds.

Return type:

Dict[str, int]

to_input_dict() → Dict[str, int]

Return the original dictionary passed to the constructor.

Returns:

User-provided keyword arguments (filtered and non-zero).

Return type:

Dict[str, int]

to_iso() → str

Serialize the duration to ISO 8601 format.

Returns:

ISO 8601-compliant duration string (e.g., ‘P1DT2H30M’).

Return type:

str

property total_seconds: int

Return the duration expressed in total seconds.

eones.core.parser module

core.parser.py

class eones.core.parser.Parser(tz: str = 'UTC', formats: List[str] | None = None)

Bases: object

Converts unshaped temporal input into meaningful Date form.

Accepts strings, dictionaries, datetimes, or Date instances, and interprets them based on provided format patterns. Useful for transforming loose or user-provided values into structured time representations.

parse(value: str | Dict[str, int] | datetime | Date | None) → Date

Parse an input into a Date.

Parameters:

value – Input value (string, dict, datetime, Date, or None).

Returns:

Parsed Date instance.

Return type:

Date

Raises:

ValueError – If input type or content is not valid.

to_eones_date(value: str | datetime | Dict[str, int] | Date) → Date

Convert various types to a Date instance.

Parameters:

value (EonesLike) – A value of type Eones, Date, or input parseable to Date.

Returns:

Parsed or extracted Date.

Return type:

Date

eones.core.range module

core.range.py

class eones.core.range.Range(date: Date)

Bases: object

Generates the start and end bounds of a temporal window.

Based on a given Date, this class exposes methods to calculate the exact datetime boundaries of days, months, and years — including edge-aligned timestamps suitable for querying, slicing, and framing temporal datasets.

custom_range(start_delta: Delta, end_delta: Delta) → Tuple[datetime, datetime]

Return a range defined by applying deltas to the base date.

Parameters:

• start_delta (Delta) – Delta applied to generate the start.

• end_delta (Delta) – Delta applied to generate the end.

Returns:

Resulting start and end datetimes.

Return type:

Tuple[datetime, datetime]

day_range() → Tuple[datetime, datetime]

Return the start and end of the current day.

Returns:

Start and end of the day.

Return type:

Tuple[datetime, datetime]

month_range() → Tuple[datetime, datetime]

Return the start and end of the current month.

Returns:

Start and end of the month.

Return type:

Tuple[datetime, datetime]

quarter_range() → Tuple[datetime, datetime]

Return the start and end of the current quarter.

Returns:

Start and end of the quarter.

Return type:

Tuple[datetime, datetime]

week_range(first_day_of_week: int = 0) → Tuple[datetime, datetime]

Return the start and end of the current week.

Parameters:

first_day_of_week (int) – First day of week (0=Monday, 6=Sunday)

Returns:

Start and end of the week.

Return type:

Tuple[datetime, datetime]

year_range() → Tuple[datetime, datetime]

Return the start and end of the current year.

Returns:

Start and end of the year.

Return type:

Tuple[datetime, datetime]