eones package

Eones: Navigate time with elegance.

This package provides a semantically rich interface for handling dates and temporal logic. From parsing and formatting to complex deltas and period framing, Eones offers tools to handling reason about time — not just measure it.

class eones.Eones(value: str | Dict[str, int] | datetime | None = None, tz: str = 'UTC', formats: List[str] | None = None, additional_formats: List[str] | None = None)

Bases: object

Central entrypoint for time manipulation, reasoning, and exploration. Acts as a façade for Date and its helpers — abstracting parsing, formatting, delta application, comparisons, and range boundaries. A natural interface for working with time as a concept, not just a datatype.

add(**kwargs: int) → Eones

Add a delta to the current date.

Accepts keyword arguments such as: years, months, days, hours, minutes, seconds. Updates the internal Date in place.

Parameters:

**kwargs – Components of the time delta.

Returns:

self, updated.

Return type:

Eones

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

Advance the current date to the end of the specified temporal unit.

Parameters:

unit (Literal) – The unit to ceil to. Valid options are: “year”, “month”, “week”, “day”, “hour”, “minute”, “second”.

Returns:

The same instance, updated to the ceiled date.

Return type:

Eones

clone() → Eones

Alias for copy().

copy() → Eones

Return a copy of the current Eones instance.

Returns:

A new instance with the same date and configuration.

Return type:

Eones

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

Return a human-readable difference between dates.

difference(other: str | datetime | Dict[str, int] | Date, unit: str | None = None) → int

Calculate the difference between this date and another.

Parameters:

• other – The other date to compare with.

• unit – The unit for the difference calculation. Options are ‘days’, ‘weeks’, ‘months’, or ‘years’.

Returns:

The time difference expressed in the specified unit.

Return type:

int

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

Set the datetime to the end of the specified unit.

Parameters:

unit (Literal) – Unit to align to.

Returns:

Self, updated.

Return type:

Eones

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

Truncate the current date down to the start of the unit.

format(fmt: str) → str

Return the current date formatted using the given format string.

is_between(start: str | datetime | Dict[str, int] | Date, end: str | datetime | Dict[str, int] | Date, inclusive: bool = True) → bool

Check if the current date is between two given dates.

Parameters:

• start – Start date (str, dict, datetime, or Date).

• end – End date (same formats as start).

• inclusive – Whether to include the endpoints.

Returns:

True if the current date is between start and end.

Return type:

bool

is_same_week(other: Any) → bool

Check if another date falls within the same ISO week as this one.

Parameters:

other (Any) – The date to compare with. Can be Eones, Date, datetime, dict, or str.

Returns:

True if both dates are in the same ISO week, False otherwise.

Return type:

bool

static is_valid_format(date_str: str, formats: List[str]) → bool

Check if a date string matches any of the provided formats.

Parameters:

• date_str – The date string to validate

• formats – List of accepted datetime format strings

Returns:

True if the string matches at least one format

Return type:

bool

is_within(compare: str | datetime | Dict[str, int] | Date, check_month: bool = True) → bool

Check if current date is within same month/year as ‘compare’.

Parameters:

• compare – The other date to compare against.

• check_month – Whether to compare month and year (True) or just year (False).

Returns:

True if in same period.

Return type:

bool

next_weekday(weekday: int) → Date

Get the next occurrence of a given weekday from the current date.

Parameters:

weekday – Integer (0=Monday, …, 6=Sunday).

Returns:

A new Date representing that next weekday.

Return type:

Date

now() → Date

Return the current internal Date.

Returns:

The current date object.

Return type:

Date

property parser: Parser

Lazy loader for the parser instance.

range(mode: str = 'month') → tuple[datetime, datetime]

Return the datetime range for the given period.

Parameters:

mode – One of “day”, “month”, or “year”.

Returns:

Start and end datetimes for the period.

Return type:

Tuple[datetime, datetime]

Raises:

ValueError – If the mode is invalid.

replace(**kwargs: Any) → Eones

Replace date parts and update internal Date instance.

Example: e.replace(day=1, month=1)

Parameters:

**kwargs – Components to replace (year, month, day, etc).

Returns:

self, updated with new internal date.

Return type:

Eones

round(unit: Literal['minute', 'hour', 'day']) → Eones

Round the datetime to the nearest unit (“minute”, “hour”, or “day”).

Returns:

self, updated.

Return type:

Eones

static sanitize_formats(formats: List[Any]) → List[str]

Remove duplicates and invalid formats from a format list.

Parameters:

formats – List of format strings (may contain duplicates or invalid types)

Returns:

Clean list of unique format strings

Return type:

List[str]

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

Set the datetime to the start of the specified unit.

Parameters:

unit (Literal) – Unit to align to.

Returns:

Self, updated.

Return type:

Eones

exception eones.InvalidFormatError(message: str = 'Invalid or unsupported date format')

Bases: EonesError

Raised when an invalid or unsupported format string is used.

exception eones.InvalidTimezoneError(tz: str)

Bases: EonesError

Raised when an invalid timezone string is provided.

eones.add_days(date: Date, days: int) → Date

Add days to a date.

Parameters:

• date – Date object

• days – Number of days to add (can be negative)

Returns:

New date with days added

Return type:

Date

eones.date_diff_days(date1: Date, date2: Date) → int

Calculate the difference in days between two dates.

Parameters:

• date1 – First date

• date2 – Second date

Returns:

Difference in days (date2 - date1)

Return type:

int

eones.date_range(start: Date, end: Date, step_days: int = 1) → List[Date]

Generate a range of dates from start to end.

Parameters:

• start – Start date

• end – End date (inclusive)

• step_days – Step size in days

Returns:

List of dates in the range

Return type:

List[Date]

eones.format_date(date: Date | datetime, fmt: str) → str

Format a date using the given format string.

Parameters:

• date – Date object or datetime to format

• fmt – Format string

Returns:

Formatted date string

Return type:

str

eones.from_timestamp(timestamp: int | float, tz: str = 'UTC') → Date

Create a Date from Unix timestamp.

Parameters:

• timestamp – Unix timestamp (int or float)

• tz – Timezone (default: “UTC”)

Returns:

Date object

Return type:

Date

eones.parse_date(value: str | dict | datetime, tz: str = 'UTC', formats: List[str] | None = None) → Date

Parse a date from various input formats.

Parameters:

• value – Date input (string, dict, or datetime)

• tz – Timezone string

• formats – List of format strings for parsing

Returns:

Parsed date object

Return type:

Date

eones.to_timestamp(date: Date | datetime) → int

Convert a date to Unix timestamp.

Parameters:

date – Date object or datetime

Returns:

Unix timestamp

Return type:

int

Subpackages

• eones.core package
  • Submodules
  • eones.core.date module
    • Date
      • Date.as_local
      • Date.as_utc()
      • Date.as_zone()
      • Date.ceil()
      • Date.day
      • Date.days_until()
      • Date.diff()
      • Date.diff_for_humans()
      • Date.end_of()
      • Date.end_of_day()
      • Date.end_of_month()
      • Date.end_of_year()
      • Date.floor()
      • Date.format()
      • Date.from_iso()
      • Date.from_timezone_aware_datetime()
      • Date.from_unix()
      • Date.hour
      • Date.is_after()
      • Date.is_before()
      • Date.is_between()
      • Date.is_friday()
      • Date.is_leap_year()
      • Date.is_monday()
      • Date.is_same_day()
      • Date.is_same_week()
      • Date.is_saturday()
      • Date.is_sunday()
      • Date.is_thursday()
      • Date.is_tuesday()
      • Date.is_wednesday()
      • Date.is_weekend()
      • Date.is_within()
      • Date.microsecond
      • Date.minute
      • Date.month
      • Date.month_span_to()
      • Date.next_weekday()
      • Date.now()
      • Date.previous_weekday()
      • Date.replace()
      • Date.round()
      • Date.second
      • Date.shift()
      • Date.start_of()
      • Date.start_of_day()
      • Date.start_of_month()
      • Date.start_of_year()
      • Date.timezone
      • Date.to_datetime()
      • Date.to_dict()
      • Date.to_iso()
      • Date.to_unix()
      • Date.truncate()
      • Date.year
      • Date.year_span_to()
  • eones.core.delta module
    • Delta
      • Delta.apply()
      • Delta.apply_calendar()
      • Delta.apply_duration()
      • Delta.from_iso()
      • Delta.from_timedelta()
      • Delta.invert()
      • Delta.is_zero()
      • Delta.scale()
      • Delta.to_dict()
      • Delta.to_input_dict()
      • Delta.to_iso()
      • Delta.total_months
      • Delta.total_seconds
  • eones.core.delta_calendar module
    • DeltaCalendar
      • DeltaCalendar.apply()
      • DeltaCalendar.from_iso()
      • DeltaCalendar.invert()
      • DeltaCalendar.is_zero()
      • DeltaCalendar.months
      • DeltaCalendar.scale()
      • DeltaCalendar.to_dict()
      • DeltaCalendar.to_input_dict()
      • DeltaCalendar.to_iso()
      • DeltaCalendar.total_months
      • DeltaCalendar.years
  • eones.core.delta_duration module
    • DeltaDuration
      • DeltaDuration.apply()
      • DeltaDuration.from_iso()
      • DeltaDuration.from_timedelta()
      • DeltaDuration.invert()
      • DeltaDuration.is_zero()
      • DeltaDuration.scale()
      • DeltaDuration.timedelta
      • DeltaDuration.to_dict()
      • DeltaDuration.to_input_dict()
      • DeltaDuration.to_iso()
      • DeltaDuration.total_seconds
  • eones.core.parser module
    • Parser
      • Parser.parse()
      • Parser.to_eones_date()
  • eones.core.range module
    • Range
      • Range.custom_range()
      • Range.day_range()
      • Range.month_range()
      • Range.quarter_range()
      • Range.week_range()
      • Range.year_range()
• eones.integrations package
  • Submodules
  • eones.integrations.django module
    • DateTimeField
      • DateTimeField.from_db_value()
      • DateTimeField.get_prep_value()
  • eones.integrations.serializers module
    • eones_encoder()
  • eones.integrations.sqlalchemy module
    • EonesType
      • EonesType.process_bind_param()
      • EonesType.process_result_value()
• eones.locales package
  • get_messages()
  • Submodules
  • eones.locales.en module
  • eones.locales.es module

Submodules

eones.constants module

contants.py

eones.constants.is_weekend_day(weekday: int, first_day_of_week: int = 0) → bool

Check if a given weekday is a weekend day.

Parameters:

• weekday (int) – ISO weekday number (0=Monday, 6=Sunday)

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

Returns:

True if the weekday is a weekend day

Return type:

bool

eones.constants.iso_to_us_weekday(iso_weekday: int) → int

Convert ISO weekday (0=Monday) to US weekday (0=Sunday).

Parameters:

iso_weekday (int) – ISO weekday number (0=Monday, 6=Sunday)

Returns:

US weekday number (0=Sunday, 6=Saturday)

Return type:

int

eones.constants.us_to_iso_weekday(us_weekday: int) → int

Convert US weekday (0=Sunday) to ISO weekday (0=Monday).

Parameters:

us_weekday (int) – US weekday number (0=Sunday, 6=Saturday)

Returns:

ISO weekday number (0=Monday, 6=Sunday)

Return type:

int

eones.errors module

errors.py

exception eones.errors.EonesError

Bases: Exception

Base exception class for all Eones errors.

exception eones.errors.InvalidDateError(message: str = 'Invalid date format or value')

Bases: EonesError

Raised when a provided date is invalid or cannot be parsed.

exception eones.errors.InvalidFormatError(message: str = 'Invalid or unsupported date format')

Bases: EonesError

Raised when an invalid or unsupported format string is used.

exception eones.errors.InvalidTimezoneError(tz: str)

Bases: EonesError

Raised when an invalid timezone string is provided.

exception eones.errors.UnsupportedInputError(message: str = 'Unsupported input type for date parsing')

Bases: EonesError

Raised when the input type is not supported by the parser.

eones.formats module

formats.py

eones.formats.is_valid_format(date_str: str, formats: List[str]) → bool

Check if a date string matches any of the provided formats.

Parameters:

• date_str – The date string to validate.

• formats – A list of accepted datetime format strings.

Returns:

True if the string matches at least one format.

eones.formats.sanitize_formats(formats: List[str]) → List[str]

Remove duplicates and ensure all formats are strings.

Parameters:

formats – A list of format definitions.

Returns:

Cleaned list with unique and valid format strings.

eones.humanize module

Utility functions for human-friendly time differences.

eones.humanize.diff_for_humans(date: Date, other: 'Date' | None = None, locale: str = 'en') → str

Return a human-friendly representation of the difference.

Parameters:

• date – Base date to describe.

• other – Date to compare against. Defaults to Date.now in the same timezone as date.

• locale – Language key for messages.

eones.interface module

interface.py

class eones.interface.Eones(value: str | Dict[str, int] | datetime | None = None, tz: str = 'UTC', formats: List[str] | None = None, additional_formats: List[str] | None = None)

Bases: object

Central entrypoint for time manipulation, reasoning, and exploration. Acts as a façade for Date and its helpers — abstracting parsing, formatting, delta application, comparisons, and range boundaries. A natural interface for working with time as a concept, not just a datatype.

add(**kwargs: int) → Eones

Add a delta to the current date.

Accepts keyword arguments such as: years, months, days, hours, minutes, seconds. Updates the internal Date in place.

Parameters:

**kwargs – Components of the time delta.

Returns:

self, updated.

Return type:

Eones

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

Advance the current date to the end of the specified temporal unit.

Parameters:

unit (Literal) – The unit to ceil to. Valid options are: “year”, “month”, “week”, “day”, “hour”, “minute”, “second”.

Returns:

The same instance, updated to the ceiled date.

Return type:

Eones

clone() → Eones

Alias for copy().

copy() → Eones

Return a copy of the current Eones instance.

Returns:

A new instance with the same date and configuration.

Return type:

Eones

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

Return a human-readable difference between dates.

difference(other: str | datetime | Dict[str, int] | Date, unit: str | None = None) → int

Calculate the difference between this date and another.

Parameters:

• other – The other date to compare with.

• unit – The unit for the difference calculation. Options are ‘days’, ‘weeks’, ‘months’, or ‘years’.

Returns:

The time difference expressed in the specified unit.

Return type:

int

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

Set the datetime to the end of the specified unit.

Parameters:

unit (Literal) – Unit to align to.

Returns:

Self, updated.

Return type:

Eones

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

Truncate the current date down to the start of the unit.

format(fmt: str) → str

Return the current date formatted using the given format string.

is_between(start: str | datetime | Dict[str, int] | Date, end: str | datetime | Dict[str, int] | Date, inclusive: bool = True) → bool

Check if the current date is between two given dates.

Parameters:

• start – Start date (str, dict, datetime, or Date).

• end – End date (same formats as start).

• inclusive – Whether to include the endpoints.

Returns:

True if the current date is between start and end.

Return type:

bool

is_same_week(other: Any) → bool

Check if another date falls within the same ISO week as this one.

Parameters:

other (Any) – The date to compare with. Can be Eones, Date, datetime, dict, or str.

Returns:

True if both dates are in the same ISO week, False otherwise.

Return type:

bool

static is_valid_format(date_str: str, formats: List[str]) → bool

Check if a date string matches any of the provided formats.

Parameters:

• date_str – The date string to validate

• formats – List of accepted datetime format strings

Returns:

True if the string matches at least one format

Return type:

bool

is_within(compare: str | datetime | Dict[str, int] | Date, check_month: bool = True) → bool

Check if current date is within same month/year as ‘compare’.

Parameters:

• compare – The other date to compare against.

• check_month – Whether to compare month and year (True) or just year (False).

Returns:

True if in same period.

Return type:

bool

next_weekday(weekday: int) → Date

Get the next occurrence of a given weekday from the current date.

Parameters:

weekday – Integer (0=Monday, …, 6=Sunday).

Returns:

A new Date representing that next weekday.

Return type:

Date

now() → Date

Return the current internal Date.

Returns:

The current date object.

Return type:

Date

property parser: Parser

Lazy loader for the parser instance.

range(mode: str = 'month') → tuple[datetime, datetime]

Return the datetime range for the given period.

Parameters:

mode – One of “day”, “month”, or “year”.

Returns:

Start and end datetimes for the period.

Return type:

Tuple[datetime, datetime]

Raises:

ValueError – If the mode is invalid.

replace(**kwargs: Any) → Eones

Replace date parts and update internal Date instance.

Example: e.replace(day=1, month=1)

Parameters:

**kwargs – Components to replace (year, month, day, etc).

Returns:

self, updated with new internal date.

Return type:

Eones

round(unit: Literal['minute', 'hour', 'day']) → Eones

Round the datetime to the nearest unit (“minute”, “hour”, or “day”).

Returns:

self, updated.

Return type:

Eones

static sanitize_formats(formats: List[Any]) → List[str]

Remove duplicates and invalid formats from a format list.

Parameters:

formats – List of format strings (may contain duplicates or invalid types)

Returns:

Clean list of unique format strings

Return type:

List[str]

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

Set the datetime to the start of the specified unit.

Parameters:

unit (Literal) – Unit to align to.

Returns:

Self, updated.

Return type:

Eones