pyoda_time package¶

Subpackages¶

Module contents¶

exception pyoda_time.AmbiguousTimeError¶

Bases: ValueError

Exception thrown to indicate that the specified local date/time occurs twice in a particular time zone due to daylight saving time changes.

This occurs for transitions where the clock goes backward (usually by an hour). For example, suppose the time zone goes backward at 2am, so the second after 01:59:59 becomes 01:00:00. In that case, times such as 01:30:00 occur twice.

This exception is used to indicate such problems, as they’re usually not the same as other <see cref=”ArgumentOutOfRangeException” /> causes, such as entering “15” for a month number.

In theory this isn’t calendar-specific; the local value will be ambiguous in this time zone regardless of the calendar used. However, this exception is always created in conjunction with a specific calendar, which leads to a more natural way of examining its information and constructing an error message.

__init__(earlier_mapping: ZonedDateTime, later_mapping: ZonedDateTime) → None¶

Constructs an instance from the given information.

User code is unlikely to need to deliberately call this constructor except possibly for testing.

The two mappings must have the same local time and time zone.

Parameters:

earlier_mapping – The earlier possible mapping
later_mapping – The later possible mapping

property earlier_mapping: ZonedDateTime¶

Gets the earlier of the two occurrences of the local date and time within the time zone.

Returns:: The earlier of the two occurrences of the local date and time within the time zone.

property later_mapping: ZonedDateTime¶

Gets the later of the two occurrences of the local date and time within the time zone.

Returns:: The later of the two occurrences of the local date and time within the time zone.

property local_date_time: LocalDateTime¶

Get the local date and time which is ambiguous in the time zone.

Returns:: The local date and time which is ambiguous in the time zone.

property zone: DateTimeZone¶

The time zone in which the local date and time is ambiguous.

Returns:: The time zone in which the local date and time is ambiguous.

class pyoda_time.AnnualDate¶

Bases: object

Represents an annual date (month and day) in the ISO calendar but without a specific year, typically for recurrent events such as birthdays, anniversaries, and deadlines.

Equality and comparison order are defined in the natural way. Two values are equal if they represent the same month and the same day-of-month. One value is earlier than another if it has a smaller month, or the same month but an earlier day-of-month.

In the future, this class may be expanded to support other calendar systems, but this does not generalize terribly cleanly, particularly to the Hebrew calendar system with its leap month.

The default value of this type is January 1st.

__eq__(other: object) → bool¶

Compares two AnnualDate values for equality.

See the type documentation for a description of equality semantics.

Parameters:: other – The other annual date to compare this one with
Returns:: True if the two dates are the same; false otherwise

__ge__(other: AnnualDate) → bool¶

Compares two annual dates to see if this one is later than or equal to the other one.

See the type documentation for a description of ordering semantics.

Parameters:: other – The other annual date to compare this one with
Returns:: true if this is strictly later than or equal to other, false otherwise.

__gt__(other: AnnualDate) → bool¶

Compares two annual dates to see if this one is strictly later than the other one.

See the type documentation for a description of ordering semantics.

Parameters:: other – The other annual date to compare this one with
Returns:: true if this is strictly later than other, false otherwise.

__init__(month: int = 1, day: int = 1) → None¶

Constructs an instance for the given month and day in the ISO calendar.

Parameters:

month – The month of year.
day – The day of month.

Raises:

ValueError – The parameters do not form a valid date. (February 29th is considered valid.)

__le__(other: AnnualDate) → bool¶

Compares two annual dates to see if this one is earlier than or equal to the other one.

See the type documentation for a description of ordering semantics.

Parameters:: other – The other annual date to compare this one with
Returns:: true if this is strictly earlier than or equal to other, false otherwise.

__lt__(other: AnnualDate) → bool¶

Compares two annual dates to see if this one is strictly earlier than the other one.

See the type documentation for a description of ordering semantics.

Parameters:: other – The other annual date to compare this one with
Returns:: true if this is strictly earlier than other, false otherwise.

compare_to(other: AnnualDate | None) → int¶

Indicates whether this annual date is earlier, later or the same as another one.

See the type documentation for a description of ordering semantics.

Parameters:: other – The other annual date to compare this one with
Returns:: A value less than zero if this annual date is earlier than other; zero if this time is the same as other; a value greater than zero if this annual date is later than other.

property day: int¶

Gets the day of month.

Returns:: The day of month.

equals(other: AnnualDate) → bool¶

Compares this annual date with the specified one for equality.

See the type documentation for a description of equality semantics.

Parameters:: other – The other annual date to compare this one with
Returns:: True if the specified annual date is equal to this one; false otherwise

in_year(year: int) → LocalDate¶

Returns this annual date in a particular year, as a LocalDate.

If this value represents February 29th, and the specified year is not a leap year, the returned value will be February 28th of that year. To see whether the original month and day is valid without truncation in a particular year, use is_valid_year.

Parameters:: year – The year component of the required date.
Returns:: A date in the given year, suitable for this annual date.

is_valid_year(year: int) → bool¶

Checks whether the specified year forms a valid date with the month/day in this value, without any truncation.

This will always return True except for values representing February 29th, where the specified year is a non leap year.

Parameters:: year – The year to test for validity
Returns:: True if the current value occurs within the given year; False otherwise.

property month: int¶

Gets the month of year.

Returns:: The month of year.

class pyoda_time.CalendarSystem¶

Bases: object

Maps the non-calendar-specific “local timeline” to human concepts such as years, months and days.

Many developers will never need to touch this class, other than to potentially ask a calendar how many days are in a particular year/month and the like. Pyoda Time defaults to using the ISO-8601 calendar anywhere that a calendar system is required but hasn’t been explicitly specified.

If you need to obtain a CalendarSystem instance, use one of the static properties or methods in this class, such as the iso() classmethod or the get_hebrew_calendar(HebrewMonthNumbering)” method.

Although this class is currently sealed, in the future this decision may be reversed. In any case, there is no current intention for third-party developers to be able to implement their own calendar systems (for various reasons). If you require a calendar system which is not currently supported, please file a feature request and we’ll see what we can do.

class property badi: CalendarSystem¶

Returns the Badíʿ (meaning “wondrous” or “unique”) calendar, as described at https://en.wikipedia.org/wiki/Badi_calendar.

This is a purely solar calendar with years starting at the vernal equinox.

The Badíʿ calendar was developed and defined by the founders of the Bahá’í Faith in the mid to late 1800’s A.D. The first year in the calendar coincides with 1844 A.D. Years are labeled “B.E.” for Bahá’í Era.

A year consists of 19 months, each with 19 days. Each day starts at sunset. Years are grouped into sets of 19 “Unities” (Váḥid) and 19 Unities make up 1 “All Things” (Kull-i-Shay’).

A period of days (usually 4 or 5, called Ayyám-i-Há) occurs between the 18th and 19th months. The length of this period of intercalary days is solely determined by the date of the following vernal equinox. The vernal equinox is a momentary point in time, so the “date” of the equinox is determined by the date (beginning at sunset) in effect in Tehran, Iran at the moment of the equinox.

In this Pyoda Time implementation, days start at midnight and lookup tables are used to determine vernal equinox dates. Ayyám-i-Há is internally modelled as extra days added to the 18th month. As a result, a few functions will not work as expected for Ayyám-i-Há, such as EndOfMonth.

Returns:: The Badíʿ calendar system.

class property coptic: CalendarSystem¶

Returns a Coptic calendar system, which defines every fourth year as leap, much like the Julian calendar.

The year is broken down into 12 months, each 30 days in length. An extra period at the end of the year is either 5 or 6 days in length. In this implementation, it is considered a 13th month.

Year 1 in the Coptic calendar began on August 29, 284 CE (Julian), thus Coptic years do not begin at the same time as Julian years. This calendar is not proleptic, as it does not allow dates before the first Coptic year.

This implementation defines a day as midnight to midnight exactly as per the ISO calendar. Some references indicate that a Coptic day starts at sunset on the previous ISO day, but this has not been confirmed and is not implemented.

Returns:: The Coptic calendar system.

class property gregorian: CalendarSystem¶

The Gregorian calendar system defines every fourth year as leap, unless the year is divisible by 100 and not by 400. This improves upon the Julian calendar leap year rule.

Although the Gregorian calendar did not exist before 1582 CE, this calendar system assumes it did, thus it is proleptic. This implementation also fixes the start of the year at January 1.

Returns:: The Gregorian calendar system.

class property hebrew_civil: CalendarSystem¶

Returns a Hebrew calendar system using the civil month numbering, equivalent to the one used by the BCL HebrewCalendar.

Returns:: A Hebrew calendar system using the civil month numbering, equivalent to the one used by the BCL.

class property hebrew_scriptural: CalendarSystem¶

Returns a Hebrew calendar system using the scriptural month numbering.

Returns:: A Hebrew calendar system using the scriptural month numbering.

class property ids: Iterable[str]¶

Returns the IDs of all calendar systems available within Pyoda Time.

The order of the keys is not guaranteed.

class property islamic_bcl: CalendarSystem¶

Returns an Islamic calendar system equivalent to the one used by the BCL HijriCalendar.

This uses the IslamicLeapYearPattern.Base16 leap year pattern and the IslamicEpoch.Astronomical epoch. This is equivalent to HijriCalendar when the HijriCalendar.HijriAdjustment is 0.

Returns:: An Islamic calendar system equivalent to the one used by the BCL.

class property iso: CalendarSystem¶

Returns a calendar system that follows the rules of the ISO-8601 standard, which is compatible with Gregorian for all modern dates.

This calendar system is effectively equivalent to CalendarSystem.gregorian.

Returns:: The ISO calendar system.

class property julian: CalendarSystem¶

Returns a pure proleptic Julian calendar system, which defines every fourth year as a leap year. This implementation follows the leap year rule strictly, even for dates before 8 CE, where leap years were actually irregular.

Although the Julian calendar did not exist before 45 BCE, this calendar assumes it did, thus it is proleptic. This implementation also fixes the start of the year at January 1.

Returns:: The Julian calendar system.

class property persian_arithmetic: CalendarSystem¶

Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour proposed by Ahmad Birashk with nested cycles of years determining which years are leap years.

This calendar is also known as the algorithmic Solar Hijri calendar.

Returns:: A Persian calendar system using cycles-within-cycles of years to determine leap years.

class property persian_astronomical: CalendarSystem¶

Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour of the BCL PersianCalendar from .NET 4.6 onwards (and Windows 10), and the astronomical system described in Wikipedia and Calendrical Calculations.

This implementation uses data derived from the .NET 4.6 implementation (with the data built into Pyoda Time, so there’s no BCL dependency) for simplicity; the actual implementation involves computing the time of noon in Iran, and is complex.

Returns:: A Persian calendar system using astronomical calculations to determine leap years.

class property persian_simple: CalendarSystem¶

Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour of the BCL PersianCalendar before .NET 4.6, and the sole Persian calendar in Noda Time 1.3.

This implementation uses a simple 33-year leap cycle, where years 1, 5, 9, 13, 17, 22, 26, and 30 in each cycle are leap years.

Returns:: A Persian calendar system using a simple 33-year leap cycle.

class property um_al_qura: CalendarSystem¶

Returns an Um Al Qura calendar system - an Islamic calendar system primarily used by Saudi Arabia.

This is a tabular calendar, relying on pregenerated data.

Returns:: A calendar system for the Um Al Qura calendar.

__init__() → None¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

__new__() → T¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

eras() → Iterable[Era]¶: Gets a read-only iterable of eras used in this calendar system.

classmethod for_id(id_: str) → CalendarSystem¶

Fetches a calendar system by its unique identifier. This provides full round-tripping of a calendar system. This method will always return the same reference for the same ID.

Parameters:: id – The ID of the calendar system. This is case-sensitive.
Returns:: The calendar system with the given ID.
Raises:: KeyError – No calendar system for the specified ID can be found.

get_absolute_year(year_of_era: int, era: Era) → int¶

Returns the “absolute year” (the one used throughout most of the API, without respect to eras) from a year- of-era and an era.

For example, in the Gregorian and Julian calendar systems, the BCE era starts at year 1, which is equivalent to an “absolute year” of 0 (then BCE year 2 has an absolute year of -1, and so on). The absolute year is the year that is used throughout the API; year-of-era is typically used primarily when formatting and parsing date values to and from text.

Parameters:

year_of_era – The year within the era.
era – The era in which to consider the year.

Returns:

The absolute year represented by the specified year of era.

get_days_in_month(year: int, month: int) → int¶

Returns the number of days in the given month within the given year.

Parameters:

year – The year in which to consider the month.
month – The month to determine the number of days in.

Returns:

The number of days in the given month and year.

get_days_in_year(year: int) → int¶

Returns the number of days in the given year.

Parameters:: year – The year to determine the number of days in.
Returns:: The number of days in the given year.

classmethod get_hebrew_calendar(month_numbering: HebrewMonthNumbering) → CalendarSystem¶

classmethod get_islamic_calendar(leap_year_pattern: IslamicLeapYearPattern, epoch: IslamicEpoch) → CalendarSystem¶

get_max_year_of_era(era: Era) → int¶

Returns the maximum valid year-of-era in the given era.

Note that depending on the calendar system, it’s possible that only part of the returned year falls within the given era. It is also possible that the returned value represents the earliest year of the era rather than the latest year. (See the BC era in the Gregorian calendar, for example.)

Parameters:: era – The era in which to find the greatest year
Returns:: The maximum valid year in the given era.
Raises:: ValueError – era is not an era used in this calendar.

get_min_year_of_era(era: Era) → int¶

Returns the minimum valid year-of-era in the given era.

Note that depending on the calendar system, it’s possible that only part of the returned year falls within the given era. It is also possible that the returned value represents the latest year of the era rather than the earliest year. (See the BC era in the Gregorian calendar, for example.)

Parameters:: era – The era in which to find the greatest year
Returns:: The minimum valid year in the given era.
Raises:: ValueError – era is not an era used in this calendar.

get_months_in_year(year: int) → int¶

Returns the maximum valid month (inclusive) within this calendar in the given year.

It is assumed that in all calendars, every month between 1 and this month number is valid for the given year. This does not necessarily mean that the first month of the year is 1, however. (See the Hebrew calendar system using the scriptural month numbering system for example.)

Parameters:: year – The year to consider.
Returns:: The maximum month number within the given year.

property id: str¶

Returns the unique identifier for this calendar system.

This provides full round-trip capability using for_id() to retrieve the calendar system from the identifier.

is_leap_year(year: int) → bool¶: Returns True if the given year is a leap year in this calendar.

property max_year: int¶

property min_year: int¶

property name: str¶

The name of this calendar system.

Each kind of calendar system has a unique name, but this does not usually provide enough information for round- tripping. (For example, the name of an Islamic calendar system does not indicate which kind of leap cycle it uses.)

class pyoda_time.DateAdjusters¶

Bases: object

Factory class for date adjusters: functions from LocalDate to LocalDate, which can be applied to LocalDate, LocalDateTime, and OffsetDateTime.

class property end_of_month: Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the last day of the current month.

Returns:: A date adjuster to move to the last day of the current month.

class property start_of_month: Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the first day of the current month.

Returns:: A date adjuster to move to the first day of the current month.

__init__() → None¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

__new__() → T¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

static add_period(period: Period) → Callable[[LocalDate], LocalDate]¶

Creates a date adjuster to add the specified period to the date.

This is the adjuster equivalent of LocalDate.plus(Period).

Parameters:: period – The period to add when the adjuster is invoked. Must not contain any (non-zero) time units.
Returns:: An adjuster which adds the specified period.

static day_of_month(day: int) → Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the specified day of the current month.

The returned adjuster will throw an exception if it is applied to a date that would create an invalid result.

Parameters:: day – The day of month to adjust dates to.
Returns:: An adjuster which changes the day to day retaining the same year and month.

static month(month: int) → Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the same day of the specified month.

The returned adjuster will throw an exception if it is applied to a date that would create an invalid result.

Parameters:: month – The month to adjust dates to.
Returns:: An adjuster which changes the month to month retaining the same year and day of month.

static next(day_of_week: IsoDayOfWeek) → Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the next specified day-of-week, adding a week if the day is already correct.

This is the adjuster equivalent of LocalDate.next.

Parameters:: day_of_week – The day-of-week to adjust dates to.
Returns:: An adjuster which advances a date to the next occurrence of the specified day-of-week.

static next_or_same(day_of_week: IsoDayOfWeek) → Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the next specified day-of-week, but return the original date if the day is already correct.

Parameters:: day_of_week – The day-of-week to adjust dates to.
Returns:: An adjuster which advances a date to the next occurrence of the specified day-of-week, or the original date if the day is already correct.

static previous(day_of_week: IsoDayOfWeek) → Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the previous specified day-of-week, subtracting a week if the day is already correct.

This is the adjuster equivalent of LocalDate.previous.

Parameters:: day_of_week – The day-of-week to adjust dates to.
Returns:: An adjuster which advances a date to the previous occurrence of the specified day-of-week.

static previous_or_same(day_of_week: IsoDayOfWeek) → Callable[[LocalDate], LocalDate]¶

A date adjuster to move to the previous specified day-of-week, but return the original date if the day is already correct.

Parameters:: day_of_week – The day-of-week to adjust dates to.
Returns:: An adjuster which advances a date to the previous occurrence of the specified day-of-week, or the original date if the day is already correct.

class pyoda_time.DateInterval¶

Bases: object

An interval between two dates.

Equality is defined in a component-wise fashion: two date intervals are considered equal if their start dates are equal to each other and their end dates are equal to each other. Ordering between date intervals is not defined.

The two dates must be in the same calendar, and the end date must not be earlier than the start date.

The end date is deemed to be part of the range, as this matches many real life uses of date ranges. For example, if someone says “I’m going to be on holiday from Monday to Friday,” they usually mean that Friday is part of their holiday.

__contains__(item: LocalDate | DateInterval) → bool¶

__eq__(other: object) → bool¶: Return self==value.

__init__(start: LocalDate, end: LocalDate) → None¶

Constructs a date interval from a start date and an end date, both of which are included in the interval.

Parameters:

start – Start date of the interval
end – End date of the interval

__iter__() → Iterator[LocalDate]¶

Returns an iterator for the dates in the interval, including both start and end.

Returns:: An iterator for the interval.

property calendar: CalendarSystem¶: The calendar system of the dates in this interval.

contains(date_or_interval: LocalDate | DateInterval, /) → bool¶

property end: LocalDate¶: The end date of the interval.

equals(other: DateInterval) → bool¶

intersection(interval: DateInterval) → DateInterval | None¶

Return the intersection between the given interval and this interval.

Friendly alternative to __and__().

Parameters:: interval – The specified interval to intersect with this one.
Returns:: A DateInterval corresponding to the intersection between the given interval and the current instance. If there is no intersection, None is returned.
Raises:: ValueError – interval uses a different calendar to this date interval.

property start: LocalDate¶: The start date of the interval.

union(interval: DateInterval) → DateInterval | None¶

Return the union between the given interval and this interval, as long as they’re overlapping or contiguous.

Friendly alternative to __or__().

Parameters:: interval – The specified interval from which to generate the union interval.
Returns:: A DateInterval corresponding to the union between the given interval and the current instance, in the case the intervals overlap or are contiguous; None otherwise.
Raises:: ValueError – interval uses a different calendar to this date interval.

class pyoda_time.DateTimeZone¶

Bases: ABC, _IZoneIntervalMap

Represents a time zone - a mapping between UTC and local time. A time zone maps UTC instants to local times - or, equivalently, to the offset from UTC at any particular instant.

class property utc: DateTimeZone¶

Gets the UTC (Coordinated Universal Time) time zone.

This is a single instance which is not provider-specific; it is guaranteed to have the ID “UTC”, and to compare equal to an instance returned by calling for_offset with an offset of zero, but it may or may not compare equal to an instance returned by e.g. DateTimeZoneProviders.Tzdb["UTC"].

Returns:: The UTC DateTimeZone.

__init__(id_: str, is_fixed: bool, min_offset: Offset, max_offset: Offset) → None¶

Initializes a new instance of the DateTimeZone class.

Parameters:

id – The unique id of this time zone.
is_fixed – Set to True is this time zone has no transitions.
min_offset – Minimum offset applied with this zone
max_offset – Maximum offset applied with this zone

at_leniently(local_date_time: LocalDateTime) → ZonedDateTime¶

Maps the given LocalDateTime to the corresponding ZonedDateTime in a lenient manner.

Ambiguous values map to the earlier of the alternatives, and “skipped” values are shifted forward by the duration of the “gap”.

See at_strictly and resolve_local(LocalDateTime, ZoneLocalMappingResolver) for alternative ways to map a local time to a specific instant.

Parameters:: local_date_time – The local date/time to map.
Returns:: The unambiguous mapping if there is one, the earlier result if the mapping is ambiguous, or the forward-shifted value if the given local date/time is skipped.

at_start_of_day(date: LocalDate) → ZonedDateTime¶

Returns the earliest valid ZonedDateTime with the given local date.

If midnight exists unambiguously on the given date, it is returned. If the given date has an ambiguous start time (e.g. the clocks go back from 1am to midnight) then the earlier ZonedDateTime is returned. If the given date has no midnight (e.g. the clocks go forward from midnight to 1am) then the earliest valid value is returned; this will be the instant of the transition.

Parameters:: date – The local date to map in this time zone.
Raises:: SkippedTimeError – The entire day was skipped due to a very large time zone transition. (This is extremely rare.)
Returns:: The ZonedDateTime representing the earliest time in the given date, in this time zone.

at_strictly(local_date_time: LocalDateTime) → ZonedDateTime¶

Maps the given LocalDateTime to the corresponding ZonedDateTime, if and only if that mapping is unambiguous in this time zone. Otherwise, SkippedTimeError or AmbiguousTimeException is thrown, depending on whether the mapping is ambiguous or the local date/time is skipped entirely.

See at_leniently and resolve_local(LocalDateTime, ZoneLocalMappingResolver) for alternative ways to map a local time to a specific instant.

Parameters:

local_date_time – The local date and time to map into this time zone.

Raises:

SkippedTimeError – The given local date/time is skipped in this time zone.
AmbiguousTimeError – The given local date/time is ambiguous in this time zone.

Returns:

The unambiguous matching ZonedDateTime if it exists.

classmethod for_offset(offset: Offset) → DateTimeZone¶

Returns a fixed time zone with the given offset.

The returned time zone will have an ID of “UTC” if the offset is zero, or “UTC+/-Offset” otherwise. In the former case, the returned instance will be equal to DateTimeZone.utc.

Note also that this method is not required to return the same DateTimeZone instance for successive requests for the same offset; however, all instances returned for a given offset will compare as equal.

Parameters:: offset – The offset for the returned time zone
Returns:: A fixed time zone with the given offset.

get_utc_offset(instant: Instant) → Offset¶

Returns the offset from UTC, where a positive duration indicates that local time is later than UTC. In other words, local time = UTC + offset.

This is mostly a convenience method for calling <c>GetZoneInterval(instant).WallOffset</c>, although it can also be overridden for more efficiency.

Parameters:: instant – The instant for which to calculate the offset.
Returns:: The offset from UTC at the specified instant.

abstractmethod get_zone_interval(instant: Instant) → ZoneInterval¶

get_zone_intervals(*, interval: Interval | None = None, start: Instant | None = None, end: Instant | None = None) → Generator[ZoneInterval]¶

property id: str¶

The provider’s ID for the time zone.

This identifies the time zone within the current time zone provider; a different provider may provide a different time zone with the same ID, or may not provide a time zone with that ID at all.

map_local(local_date_time: LocalDateTime) → ZoneLocalMapping¶

Returns complete information about how the given LocalDateTime is mapped in this time zone.

Mapping a local date/time to a time zone can give an unambiguous, ambiguous or impossible result, depending on time zone transitions. Use the return value of this method to handle these cases in an appropriate way for your use case.

As an alternative, consider resolve_local, which uses a caller-provided strategy to convert the ZoneLocalMapping returned here to a ZonedDateTime.

Parameters:: local_date_time – The local date and time to map in this time zone.
Returns:: A mapping of the given local date and time to zero, one or two zoned date/time values.

property max_offset: Offset¶: The greatest (most positive) offset within this time zone, over all time.

property min_offset: Offset¶: The least (most negative) offset within this time zone, over all time.

resolve_local(local_date_time: LocalDateTime, resolver: ZoneLocalMappingResolver) → ZonedDateTime¶

Maps the given LocalDateTime to the corresponding ZonedDateTime, following the given ZoneLocalMappingResolver to handle ambiguity and skipped times.

This is a convenience method for calling map_local and passing the result to the resolver. Common options for resolvers are provided in the static Resolvers class.

See at_strictly and at_leniently for alternative ways to map a local time to a specific instant.

Parameters:

local_date_time – The local date and time to map in this time zone.
resolver – The resolver to apply to the mapping.

Returns:

The result of resolving the mapping.

class pyoda_time.DateTimeZoneProviders¶

Bases: object

Static access to date/time zone providers built into Pyoda Time and for global configuration where this is unavoidable.

All properties are thread-safe, and the providers returned by the read-only properties cache their results.

class property tzdb: <class 'pyoda_time._i_date_time_zone_provider.IDateTimeZoneProvider'>¶

Gets a time zone provider which uses a TzdbTimeZoneSource. The underlying source is TzdbDateTimeZoneSource.default, which is initialized from resources within the pyoda_time package.

Returns:: A time zone provider using a TzdbDateTimeZoneSource`.

__init__() → None¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

__new__() → T¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

class pyoda_time.Duration¶

Bases: object

Represents a fixed (and calendar-independent) length of time.

class property epsilon: Duration¶

Return a Duration representing 1 nanosecond.

This is the smallest amount by which an instant can vary.

class property max_value: Duration¶: The maximum value supported by Duration.

class property min_value: Duration¶: The minimum value supported by Duration.

class property one_day: Duration¶

Represents the Duration value equal to the number of nanoseconds in 1 day.

The value of this property is 86.4 trillion nanoseconds; that is, 86,400,000,000,000 nanoseconds.

class property one_week: Duration¶

Return a Duration equal to the number of nanoseconds in 1 standard week (7 days).

equal to the number of nanoseconds in 1 standard week (7 days).

class property zero: Duration¶: Gets a zero Duration of 0 nanoseconds.

__add__(other: Duration) → Duration¶

__eq__(other: object) → bool¶: Return self==value.

__ge__(other: Duration) → bool¶: Return self>=value.

__gt__(other: Duration) → bool¶: Return self>value.

__init__() → None¶

__le__(other: Duration) → bool¶: Return self<=value.

__lt__(other: Duration) → bool¶: Return self<value.

__neg__() → Duration¶

__sub__(other: Duration) → Duration¶

static add(left: Duration, right: Duration) → Duration¶

Adds one duration to another. Friendly alternative to __add__.

Parameters:

left – The left hand side of the operator.
right – The right hand side of the operator.

Returns:

A new Duration representing the sum of the given values.

property bcl_compatible_ticks: int¶

The total number of ticks in the duration, truncated towards zero where necessary.

Within the constraints specified below, this property is intended to be equivalent to .NET’s TimeSpan.Ticks.

If the number of nanoseconds in a duration is not a whole number of ticks, it is truncated towards zero. For example, durations in the range [-99ns, 99ns] would all count as 0 ticks.

See also: total_ticks()

compare_to(other: Duration | None) → int¶

Compares the current object with another object of the same type. See the type documentation for a description of ordering semantics.

Parameters:: other – An object to compare with this object.
Returns:: An integer that indicates the relative order of the objects being compared.
Raises:: TypeError – An object of an incompatible type was passed to this method.

The return value has the following meanings:

Value	Meaning
< 0	This object is less than the `other` parameter.
0	This object is equal to `other`.
> 0	This object is greater than `other`.

property days: int¶

The whole number of standard (24 hour) days within the duration.

This is truncated towards zero; For example, “-1.75 days” and “1.75 days” would have results of -1 and 1 respectively.

static divide(left: Duration, right: float | Duration) → Duration | float¶

equals(other: Duration) → bool¶

Indicates whether the current object is equal to another object of the same type. See the type documentation for a description of equality semantics.

Parameters:: other – An object to compare with this object.
Returns:: true if the current object is equal to the other parameter; otherwise, false.

classmethod from_days(days: float) → Duration¶

Returns a Duration that represents the given number of days, assuming a ‘standard’ 24-hour day.

Parameters:: days – The number of days.
Returns:: A Duration representing the given number of days.

classmethod from_hours(hours: float) → Duration¶

Returns a Duration that represents the given number of hours.

Parameters:: hours – The number of hours.
Returns:: A Duration representing the number of hours.

classmethod from_microseconds(microseconds: float) → Duration¶

Returns a Duration that represents the given number of microseconds.

Parameters:: microseconds – The number of microseconds.
Returns:: A Duration representing the given number of microseconds.

classmethod from_milliseconds(milliseconds: float) → Duration¶

Returns a Duration that represents the given number of milliseconds.

Parameters:: milliseconds – The number of milliseconds.
Returns:: A Duration representing the given number of milliseconds.

classmethod from_minutes(minutes: float) → Duration¶

Returns a Duration that represents the given number of minutes.

Parameters:: minutes – The number of minutes.
Returns:: A Duration representing the given number of minutes.

classmethod from_nanoseconds(nanoseconds: float) → Duration¶

Returns a Duration that represents the given number of nanoseconds.

When nanoseconds is a float, any fractional parts of the value are truncated towards zero.

Parameters:: nanoseconds – The number of nanoseconds.
Returns:: A Duration representing the given number of nanoseconds.

classmethod from_seconds(seconds: float) → Duration¶

Returns a Duration that represents the given number of seconds.

Parameters:: seconds – The number of seconds.
Returns:: A Duration representing the given number of seconds.

classmethod from_ticks(ticks: float) → Duration¶

Returns a Duration that represents the given number of ticks.

Parameters:: ticks – The number of ticks.
Returns:: A Duration representing the given number of ticks.

classmethod from_timedelta(timedelta: timedelta) → Duration¶

Returns a Duration that represents the same number of microseconds as the given datetime.timedelta.

Parameters:: timedelta – The datetime.timedelta to convert.
Returns:: A new Duration with the same number of microseconds as the given datetime.timedelta.

property hours: int¶: The hour component of this duration, in the range [-23, 23], truncated towards zero.

static max(x: Duration, y: Duration) → Duration¶

Returns the larger duration of the given two.

A “larger” duration is one that advances time by more than a “smaller” one. This means that a positive duration is always larger than a negative one, for example. (This is the same comparison used by the binary comparison operators.)

Parameters:

x – The first duration to compare.
y – The second duration to compare.

Returns:

The larger duration of x or y.

property microseconds: int¶: The subsecond component of this duration, expressed in microseconds, in the range [-999999, 999999] and truncated towards zero.

property milliseconds: int¶: The subsecond component of this duration, expressed in milliseconds, in the range [-999, 999] and truncated towards zero.

static min(x: Duration, y: Duration) → Duration¶

Returns the smaller duration of the given two.

Parameters:

x – The first duration to compare.
y – The second duration to compare.

Returns:

The smaller duration of x or y.

minus(other: Duration) → Duration¶

Returns the result of subtracting another duration from this one, for a fluent alternative to __sub__.

Parameters:: other – The duration to subtract
Returns:: A new Duration representing the result of the subtraction.

property minutes: int¶: The minute component of this duration, in the range [-59, 59], truncated towards zero.

static multiply(left: Duration | float, right: Duration | float) → Duration¶

property nanosecond_of_day: int¶

The number of nanoseconds within the day of this duration.

For negative durations, this will be negative (or zero).

static negate(duration: Duration) → Duration¶

Implements a friendly alternative to the unary negation operator.

Parameters:: duration – Duration to negate
Returns:: The negative value of this duration

plus(other: Duration) → Duration¶

Returns the result of adding another duration to this one, for a fluent alternative to __add__.

Parameters:: other – The duration to add
Returns:: A new Duration representing the result of the addition.

property seconds: int¶: The second component of this duration, in the range [-59, 59], truncated towards zero.

property subsecond_nanoseconds: int¶: The subsecond component of this duration, expressed in nanoseconds, in the range [-999999999, 999999999].

property subsecond_ticks: int¶: The subsecond component of this duration, expressed in ticks, in the range [-9999999, 9999999] and truncated towards zero.

static subtract(left: Duration, right: Duration) → Duration¶

Subtracts one duration from another. Friendly alternative to __add__.

Parameters:

left – The left hand side of the operator.
right – The right hand side of the operator.

Returns:

A new Duration representing the difference of the given values.

to_nanoseconds() → int¶

to_timedelta() → timedelta¶

Returns a datetime.timedelta that represents the same number of microseconds as this Duration.

If the number of nanoseconds in a duration is not a whole number of microseconds, it will be truncated towards zero. For instance, durations in the range [-999, 999] would all count as 0 microseconds.

Returns:: A new TimeSpan with the same number of ticks as this Duration.

property total_days: float¶

The total number of days in this duration, as a float.

This property is the Duration equivalent of TimeSpan.TotalDays. It represents the complete duration in days, rather than only the whole number of days. For example, for a duration of 36 hours, this property would return 1.5.

property total_hours: float¶

The total number of hours in this duration, as a float.

This property is the Duration equivalent of TimeSpan.TotalHours. Unlike hours, it represents the complete duration in hours rather than the whole number of hours as part of the day. So for a duration of 1 day, 2 hours and 30 minutes, the hours property will return 2, but total_hours will return 26.5.

property total_microseconds: float¶

property total_milliseconds: float¶

The total number of milliseconds in this duration, as a float.

This property is the Duration equivalent of TimeSpan.TotalMilliseconds. Unlike milliseconds, it represents the complete duration in milliseconds rather than the whole number of milliseconds within the second. So for a duration of 10 minutes, 20 seconds and 250 milliseconds, the milliseconds property will return 250, but total_milliseconds will return 620250.

property total_minutes: float¶

The total number of minutes in this duration, as a float.

This property is the Duration equivalent of TimeSpan.TotalMinutes. Unlike minutes, it represents the complete duration in minutes rather than the whole number of minutes within the hour. So for a duration of 2 hours, 30 minutes and 45 seconds, the minutes property will return 30, but total_minutes will return 150.75.

property total_nanoseconds: float¶

The total number of nanoseconds in this duration, as a float.

The result is always an integer, but may not be precise due to the limitations of the float type. In other words, Duration.from_nanoseconds(duration.total_nanoseconds) is not guaranteed to round-trip. To guarantee precision and round-tripping, use to_nanoseconds() and from_nanoseconds().

property total_seconds: float¶

The total number of seconds in this duration, as a float.

This property is the <c>Duration</c> equivalent of <see cref=”TimeSpan.TotalSeconds”/>. Unlike seconds, it represents the complete duration in seconds rather than the whole number of seconds within the minute. So for a duration of 10 minutes, 20 seconds and 250 milliseconds, the seconds property will return 20, but total_seconds will return 620.25.

property total_ticks: float¶

The total number of ticks in this duration, as a float.

This property is the Duration equivalent of TimeSpan.Ticks.

class pyoda_time.IClock¶

Bases: Protocol

Represents a clock which can return the current time as an Instant.

IClock is intended for use anywhere you need to have access to the current time.

Although it’s not strictly incorrect to call SystemClock.instance.get_current_instant() directly, in the same way as you might call datetime.now(tz=UTC), it’s strongly discouraged as a matter of style for production code. We recommend providing an instance of IClock to anything that needs it, which allows you to write tests using the fake clock in the pyoda_time.testing package (or your own implementation).

__init__(*args, **kwargs)¶

abstractmethod get_current_instant() → Instant¶

Gets the current Instant on the timeline according to this clock.

Returns:: The current instant on the timeline according to this clock.

in_tzdb_system_default_zone() → ZonedClock¶

Constructs a ZonedClock from this clock, in the TZDB mapping for the system default time zone and the ISO calendar system.

Returns:

in_utc() → ZonedClock¶

Constructs a ZonedClock from this clock, using the UTC time zone and ISO calendar system.

Returns:: A ZonedClock with the given clock, in the UTC time zone and ISO calendar system.

in_zone(zone: DateTimeZone, calendar: CalendarSystem = ISO) → ZonedClock¶

Constructs a ZonedClock from this clock, a time zone, and a calendar system.

Parameters:

zone – Time zone to use in the returned object.
calendar – Calendar to use in the returned object.

Returns:

A ZonedClock with the given clock, time zone and calendar system.

class pyoda_time.IDateTimeZoneProvider¶

Bases: Protocol

Provides stable, performant time zone data.

Consumers should be able to treat an IDateTimeZoneProvider like a cache: lookups should be quick (after at most one lookup of a given ID), and multiple calls for a given ID must always return references to equal instances, even if they are not references to a single instance. Consumers should not feel the need to cache data accessed through this interface.

Implementations designed to work with any IDateTimeZoneSource implementation (such as DateTimeZoneCache) should not attempt to handle exceptions thrown by the source. A source-specific provider may do so, as it has more detailed knowledge of what can go wrong and how it can best be handled.

__init__(*args, **kwargs)¶

abstractmethod get_system_default() → DateTimeZone¶

Gets the time zone from this provider that matches the system default time zone, if a matching time zone is available.

Callers should be aware that this method will throw DateTimeZoneNotFoundError if no matching time zone is found. For the built-in Pyoda Time providers, this is unlikely to occur in practice (assuming the system is using a standard Windows time zone), but can occur even then, if no mapping is found. The TZDB source contains mappings for almost all Windows system time zones, but a few (such as “Mid-Atlantic Standard Time”) are unmappable.

Returns:: The provider-specific representation of the system default time zone.
Raises:: DateTimeZoneNotFoundError – The system default time zone is not mapped by this provider.

abstractmethod get_zone_or_none(zone_id: str) → DateTimeZone | None¶

Returns the time zone for the given ID, if it’s available.

Note that this may return a DateTimeZone that has a different ID to that requested, if the ID provided is an alias.

Note also that this method is not required to return the same DateTimeZone instance for successive requests for the same ID; however, all instances returned for a given ID must compare as equal.

The fixed-offset timezones with IDs “UTC” and “UTC+/-Offset” are always available.

Parameters:: zone_id – The time zone ID to find.
Returns:: The DateTimeZone for the given ID or null if the provider does not support the given ID.

abstract property ids: Iterable[str]¶

Gets the list of valid time zone ids advertised by this provider.

This list will be sorted in ordinal lexicographic order. It cannot be modified by callers, and must not be modified by the provider either: client code can safely treat it as thread-safe and deeply immutable.

In addition to the list returned here, providers always support the fixed-offset timezones with IDs “UTC” and “UTC+/-Offset”. These may or may not be included explicitly in this list.

Returns:: The Iterable of string ids.

abstract property version_id: str¶

Gets the version ID of this provider.

Returns:: The version ID of this provider.

class pyoda_time.Instant¶

Bases: object

Represents an instant on the global timeline, with nanosecond resolution.

An Instant has no concept of a particular time zone or calendar: it simply represents a point in time that can be globally agreed-upon. Equality and ordering comparisons are defined in the natural way, with earlier points on the timeline being considered “less than” later points.

class property max_value: Instant¶

Represents the largest possible Instant.

This value is equivalent to 9999-12-31T23:59:59.999999999Z

class property min_value: Instant¶

Represents the smallest possible Instant.

This value is equivalent to -9998-01-01T00:00:00Z

__add__(other: Duration) → Instant¶

__eq__(other: object) → bool¶: Return self==value.

__ge__(other: Instant) → bool¶: Return self>=value.

__gt__(other: Instant) → bool¶: Return self>value.

__init__() → None¶

__le__(other: Instant) → bool¶: Return self<=value.

__lt__(other: Instant) → bool¶: Return self<value.

__sub__(other: Instant | Duration) → Instant | Duration¶

static add(left: Instant, right: Duration) → Instant¶

Adds a duration to an instant. Friendly alternative to +.

Parameters:

left – The left hand side of the operator.
right – >The right hand side of the operator.

Returns:

A new Instant representing the sum of the given values.

compare_to(other: Instant | None) → int¶

Compares the current object with another object of the same type. See the type documentation for a description of ordering semantics.

Parameters:: other – An object to compare with this object.
Returns:: An integer that indicates the relative order of the objects being compared.

The return value has the following meanings:

Value	Meaning
< 0	This object is less than the `other` parameter.
0	This object is equal to `other`.
> 0	This object is greater than `other`.

equals(other: Instant) → bool¶

classmethod from_aware_datetime(dt: datetime) → Instant¶

Converts an aware datetime.datetime into a new Instant representing the same instant in time.

This is the Pyoda Time equivalent to FromDateTimeOffset() and FromDateTimeUtc() in Noda Time.

Parameters:: dt – Date and time value which must be timezone-aware.
Returns:: An Instant value representing the same instant in time as the given aware datetime.datetime.
Raises:: ValueError – A timezone-naive datetime was provided.

classmethod from_julian_date(julian_date: float) → Instant¶

Converts a Julian Date representing the given number of days since PyodaConstants.JULIAN_EPOCH (noon on January 1st, 4713 BCE in the Julian calendar) into an Instant.

Parameters:: julian_date – The number of days since the Julian Epoch to convert into an Instant.
Returns:: An Instant value which is julianDate days after the Julian Epoch.

classmethod from_unix_time_milliseconds(milliseconds: int) → Instant¶: Initializes a new Instant struct based on a number of milliseconds since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.

classmethod from_unix_time_seconds(seconds: int) → Instant¶: Initializes a new Instant based on a number of seconds since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.

classmethod from_unix_time_ticks(ticks: int) → Instant¶: Initializes a new Instant based on a number of ticks since the Unix epoch.

classmethod from_utc(year: int, month_of_year: int, day_of_month: int, hour_of_day: int, minute_of_hour: int, second_of_minute: int = 0) → Instant¶

Returns a new Instant corresponding to the given UTC date and time in the ISO calendar.

In most cases applications should use ZonedDateTime to represent a date and time, but this method is useful in some situations where an Instant is required, such as time zone testing.

in_utc() → ZonedDateTime¶

Returns the ZonedDateTime representing the same point in time as this instant, in the UTC time zone and ISO-8601 calendar. This is a shortcut for calling in_zone(DateTimeZone) with an argument of DateTimeZone.utc.

Returns:: A ZonedDateTime for the same instant, in the UTC time zone and the ISO-8601 calendar.

in_zone(zone: DateTimeZone, calendar: CalendarSystem | None = None) → ZonedDateTime¶

static max(x: Instant, y: Instant) → Instant¶: Returns the later instant of the given two.

static min(x: Instant, y: Instant) → Instant¶: Returns the earlier instant of the given two.

minus(other: Instant | Duration, /) → Instant | Duration¶

plus(other: Duration) → Instant¶: Returns the result of adding a duration to this instant, for a fluent alternative to the + operator.

plus_nanoseconds(nanoseconds: int) → Instant¶

plus_ticks(ticks: int) → Instant¶: Returns a new value of this instant with the given number of ticks added to it.

static subtract(left: Instant, right: Instant | Duration, /) → Instant | Duration¶

to_datetime_utc() → datetime¶

Constructs an aware datetime.datetime from this Instant which has a tzinfo of utc.

If the date and time is not on a microsecond boundary (the unit of granularity of datetime) the value will be truncated towards the start of time.

Raises:: RuntimeError – The final date/time is outside the range of datetime.datetime.
Returns:: A timezone-aware datetime.datetime representing the same instant in time as this value, in the UTC timezone.

to_julian_date() → float¶

Returns the Julian Date of this instance - the number of days since PyodaConstants.JULIAN_EPOCH (noon on January 1st, 4713 BCE in the Julian calendar).

Returns:: The number of days (including fractional days) since the Julian Epoch.

to_unix_time_milliseconds() → int¶

Gets the number of milliseconds since the Unix epoch.

Negative values represent instants before the Unix epoch. If the number of nanoseconds in this instant is not an exact number of milliseconds, the value is truncated towards the start of time.

to_unix_time_seconds() → int¶

Gets the number of seconds since the Unix epoch.

Negative values represent instants before the Unix epoch. If the number of nanoseconds in this instant is not an exact number of seconds, the value is truncated towards the start of time.

to_unix_time_ticks() → int¶

Gets the number of ticks since the Unix epoch.

Negative values represent instants before the Unix epoch. A tick is equal to 100 nanoseconds. There are 10,000 ticks in a millisecond. If the number of nanoseconds in this instant is not an exact number of ticks, the value is truncated towards the start of time.

with_offset(offset: Offset, calendar: CalendarSystem = ISO) → OffsetDateTime¶

Returns the OffsetDateTime representing the same point in time as this instant, with the specified UTC offset and calendar system (defaulting to CalendarSystem.iso).

Parameters:

offset – The offset from UTC with which to represent this instant.
calendar – The calendar system in which to represent this instant. (defaults to CalendarSystem.iso).

Returns:

An OffsetDateTime for the same instant, with the given offset and calendar.

class pyoda_time.Interval¶

Bases: object

An interval between two instants in time (start and end).

Equality is defined in a component-wise fashion: two intervals are considered equal if their start instants are equal to each other and their end instants are equal to each other. Ordering between intervals is not defined.

The interval includes the start instant and excludes the end instant. However, an interval may be missing its start or end, in which case the interval is deemed to be infinite in that direction.

The end may equal the start (resulting in an empty interval), but will not be before the start.

The default value of this type is an empty interval with a start and end of PyodaConstant.UNIX_EPOCH.

__contains__(instant: Instant) → bool¶

Returns True if this interval contains the given Instant; otherwise False.

Parameters:: instant – The Instant to test.
Returns:: True if this interval contains the given Instant; otherwise False.

__eq__(other: object) → bool¶

Implements the operator ==.

See the type documentation for a description of equality semantics.

Parameters:: other – The object to compare with this instance.
Returns:: True if the value of this interval is equal to the value of the other parameter.

__init__(start: ~pyoda_time._instant.Instant | None = 1970-01-01T00:00:00Z, end: ~pyoda_time._instant.Instant | None = 1970-01-01T00:00:00Z) → None¶

Initializes a new instance of the Interval struct from two nullable Instant values.

If the start is null, the interval is deemed to stretch to the start of time. If the end is null, the interval is deemed to stretch to the end of time.

Parameters:

start – The start Instant or None.
end – The end Instant or None.

Raises:

ValueError – If end is earlier than start.

__iter__() → Iterator[Instant | None]¶

Deconstruct this value into its components.

Yields:: The start and end Instant of the interval, or None if it extends to the start or end of time.

contains(instant: Instant) → bool¶

Returns True if this interval contains the given Instant; otherwise False.

Friendly alternative to __contains__.

Parameters:: instant – The Instant to test.
Returns:: True if this interval contains the given Instant; otherwise False.

property duration: Duration¶

Returns the duration of the interval.

This will always be a non-negative duration, though it may be zero.

Returns:: The duration of the interval.
Raises:: RuntimeError – The interval extends to the start or end of time.

property end: Instant¶

Gets the end instant - the exclusive upper bound of the interval.

Returns:: The end Instant.
Raises:: RuntimeError – The interval extends to the end of time.
Seealso:: has_end

equals(other: Interval) → bool¶

Indicates whether the value of this interval is equal to the value of the specified interval.

See the type documentation for a description of equality semantics.

Parameters:: other – The value to compare with this instance.
Returns:: True if the value of this interval is equal to the value of the other parameter; otherwise, false.

property has_end: bool¶

Returns True if this interval has a fixed end point, or False if it extends to the end of time.

Returns:: True if this interval has a fixed end point, or False if it xtends to the end of time.

property has_start: bool¶

Returns True if this interval has a fixed start point, or False if it extends to the start of time.

Returns:: True if this interval has a fixed start point, False if it extends to the start of time.

property start: Instant¶

Gets the start instant - the inclusive lower bound of the interval.

This will never be later than end, though it may be equal to it.

Returns:: The start Instant.
Raises:: RuntimeError – The interval extends to the start of time.
Seealso:: has_start

class pyoda_time.IsoDayOfWeek¶

Bases: IntEnum

Equates the days of the week with their numerical value according to ISO-8601.

FRIDAY = 5¶

MONDAY = 1¶

NONE = 0¶

SATURDAY = 6¶

SUNDAY = 7¶

THURSDAY = 4¶

TUESDAY = 2¶

WEDNESDAY = 3¶

__new__(value)¶

class pyoda_time.LocalDate¶

Bases: object

LocalDate is an immutable object representing a date within the calendar, with no reference to a particular time zone or time of day.

Values can freely be compared for equality: a value in a different calendar system is not equal to a value in a different calendar system. However, ordering comparisons fail with ValueError; attempting to compare values in different calendars almost always indicates a bug in the calling code.

The default value of this type is 0001-01-01 (January 1st, 1 C.E.) in the ISO calendar.

class property max_iso_value: LocalDate¶: The maximum (latest) date representable in the ISO calendar system.

class property min_iso_value: LocalDate¶: The minimum (earliest) date representable in the ISO calendar system.

__add__(other: LocalTime | Period) → LocalDateTime | LocalDate¶

__eq__(other: object) → bool¶: Return self==value.

__ge__(other: LocalDate) → bool¶: Return self>=value.

__gt__(other: LocalDate) → bool¶: Return self>value.

__init__(year: int = 1, month: int = 1, day: int = 1, calendar: CalendarSystem = ISO, era: Era | None = None) → None¶

Initialises a new instance of LocalDate for the given year, month and day in a given calendar.

If era is not None, year is interpreted as the “year of era” rather than the absolute year, and is passed to CalendarSystem.get_absolute_year to determine the absolute year.

Parameters:

year – The year. If era is None, this is the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example. If era is provided, this is interpreted as the “year of era”.
month – The month of year.
day – The day of month.
calendar – Calendar system in which to create the date.
era – The era within which to create a date. Must be a valid era within the specified calendar.

__iter__() → Iterator[int]¶

Deconstructs the current instance into its components.

This enables instances of LocalDate to be unpacked into year, month and day, similar to the equivalent LocalDate.Deconstruct in Noda Time.

Returns:: An iterator of integers representing the “year”, “month” and “day” components of this date.

__le__(other: LocalDate) → bool¶: Return self<=value.

__lt__(other: LocalDate) → bool¶: Return self<value.

__sub__(other: LocalDate | Period) → LocalDate | Period¶

static add(date: LocalDate, period: Period) → LocalDate¶

Adds the specified period to the date. Fields are added in descending order of significance (years first, then months, and so on). Friendly alternative to +.

Parameters:

date – The date to add the period to.
period – The period to add. Must not contain any (non-zero) time units.

Returns:

The sum of the given date and period.

at(time: LocalTime) → LocalDateTime¶

Combines this LocalDate with the given LocalTime into a single LocalDateTime.

Fluent alternative to +.

Parameters:: time – The time to combine with this date.
Returns:: The LocalDateTime representation of the given time on this date.

at_midnight() → LocalDateTime¶

Gets a LocalDateTime at midnight on the date represented by this local date.

Returns:: The LocalDateTime representing midnight on this local date, in the same calendar system.

at_start_of_day_in_zone(zone: DateTimeZone) → ZonedDateTime¶

Resolves this local date into a ZonedDateTime in the given time zone representing the start of this date in the given zone.

This is a convenience method for calling DateTimeZone.at_start_of_day(LocalDate).

Parameters:: zone – The time zone to map this local date into
Raises:: SkippedTimeError – The entire day was skipped due to a very large time zone transition. (This is extremely rare.)
Returns:: The ZonedDateTime representing the earliest time on this date, in the given time zone.

property calendar: CalendarSystem¶: The calendar system associated with this local date.

compare_to(other: LocalDate | None) → int¶

property day: int¶: The day of this local date within the month.

property day_of_week: IsoDayOfWeek¶: The week day of this local date expressed as an IsoDayOfWeek.

property day_of_year: int¶: The day of this local date within the year.

property era: Era¶: The era of this local date.

classmethod from_date(date: date) → LocalDate¶

Constructs a LocalDate from a datetime.date.

Parameters:: date – The date to convert.
Returns:: The LocalDate equivalent, which is always in the ISO calendar system.

classmethod from_week_year_week_and_day(week_year: int, week_of_week_year: int, day_of_week: IsoDayOfWeek) → LocalDate¶

Returns the local date corresponding to the given “week year”, “week of week year”, and “day of week” in the ISO calendar system, using the ISO week-year rules.

Parameters:

week_year – ISO-8601 week year of value to return
week_of_week_year – ISO-8601 week of week year of value to return
day_of_week – ISO-8601 day of week to return

Returns:

The date corresponding to the given week year / week of week year / day of week.

classmethod from_year_month_week_and_day(year: int, month: int, occurrence: int, day_of_week: IsoDayOfWeek) → LocalDate¶

Returns the local date corresponding to a particular occurrence of a day-of-week within a year and month. For example, this method can be used to ask for “the third Monday in April 2012”.

The returned date is always in the ISO calendar. This method is unrelated to week-years and any rules for “business weeks” and the like - if a month begins on a Friday, then asking for the first Friday will give that day, for example.

Parameters:

year – The year of the value to return.
month – The month of the value to return.
occurrence – The occurrence of the value to return, which must be in the range [1, 5]. The value 5 can be used to always return the last occurrence of the specified day-of-week, even if there are only 4 occurrences of that day-of-week in the month.
day_of_week – The day-of-week of the value to return.

Returns:

The date corresponding to the given year and month, on the given occurrence of the given day of week.

classmethod max(x: LocalDate, y: LocalDate) → LocalDate¶

Returns the later date of the given two.

Parameters:

x – The first date to compare.
y – The second date to compare.

Raises:

ValueError – The two dates have different calendar systems.

Returns:

The later date of x or y.

classmethod min(x: LocalDate, y: LocalDate) → LocalDate¶

Returns the earlier date of the given two.

Parameters:

x – The first date to compare.
y – The second date to compare.

Raises:

ValueError – The two dates have different calendar systems.

Returns:

The earlier date of x or y.

minus(period: LocalDate | Period, /) → LocalDate | Period¶

property month: int¶: The month of this local date within the year.

next(target_day_of_week: IsoDayOfWeek) → LocalDate¶

Returns the next LocalDate falling on the specified IsoDayOfWeek.

This is a strict “next” - if this date on already falls on the target day of the week, the returned value will be a week later.

Parameters:

target_day_of_week – The ISO day of the week to return the next date of.

Returns:

The next LocalDate falling on the specified day of the week.

Raises:

RuntimeError – The underlying calendar doesn’t use ISO days of the week.
ValueError – target_day_of_week is not a valid day of the week (Monday to Sunday).

plus(period: Period) → LocalDate¶

Adds the specified period to this date. Fields are added in descending order of significance (years first, then months, and so on). Fluent alternative to +.

Parameters:: period – The period to add. Must not contain any (non-zero) time units.
Returns:: The sum of this date and the given period.

plus_days(days: int) → LocalDate¶

Returns a new LocalDate representing the current value with the given number of days added.

This method does not try to maintain the month or year of the current value, so adding 3 days to a value of January 30th will result in a value of February 2nd.

Parameters:: days – The number of days to add.
Returns:: The current value plus the given number of days.

plus_months(months: int) → LocalDate¶

Returns a new LocalDate representing the current value with the given number of months added.

This method does not try to maintain the year of the current value, so adding four months to a value in October will result in a value in the following February.

If the resulting date is invalid, the day of month is reduced to find a valid value. For example, adding one month to January 30th 2011 will return February 28th 2011; subtracting one month from March 30th 2011 will return February 28th 2011.

Parameters:: months – The number of months to add
Returns:: The current date plus the given number of months

plus_weeks(weeks: int) → LocalDate¶

Returns a new LocalDate representing the current value with the given number of weeks added.

Parameters:: weeks – The number of weeks to add.
Returns:: The current value plus the given number of weeks.

plus_years(years: int) → LocalDate¶

Returns a new LocalDate representing the current value with the given number of years added.

If the resulting date is invalid, lower fields (typically the day of month) are reduced to find a valid value. For example, adding one year to February 29th 2012 will return February 28th 2013; subtracting one year from February 29th 2012 will return February 28th 2011.

Parameters:: years – The number of years to add.
Returns:: The current value plus the given number of years.

previous(target_day_of_week: IsoDayOfWeek) → LocalDate¶

Returns the previous LocalDate falling on the specified IsoDayOfWeek.

This is a strict “previous” - if this date on already falls on the target day of the week, the returned value will be a week earlier.

Parameters:

target_day_of_week – The ISO day of the week to return the previous date of.

Returns:

The previous LocalDate falling on the specified day of the week.

Raises:

RuntimeError – The underlying calendar doesn’t use ISO days of the week.
ValueError – target_day_of_week is not a valid day of the week (Monday to Sunday).

static subtract(date: LocalDate, other: LocalDate | Period, /) → LocalDate | Period¶

to_date() → date¶

Converts this object to a datetime.date.

datetime.date uses the Gregorian calendar by definition, so the value is implicitly converted to the Gregorian calendar first. The result will be on the same physical day, but the values returned by the Year/Month/Day properties of the datetime.date may not match the Year/Month/Day properties of this value.

Returns:: A datetime.date value equivalent to this one.

to_year_month() → YearMonth¶

Creates a YearMonth value for the month containing this date.

Returns:: A year/month value containing this date.

with_calendar(calendar: CalendarSystem) → LocalDate¶

Creates a new LocalDate representing the same physical date, but in a different calendar.

The returned LocalDate is likely to have different field values to this one. For example, January 1st 1970 in the Gregorian calendar was December 19th 1969 in the Julian calendar.

Parameters:: calendar – The calendar system to convert this local date to.
Returns:: The converted LocalDate

with_date_adjuster(adjuster: Callable[[LocalDate], LocalDate]) → LocalDate¶

Returns this date, with the given adjuster applied to it.

If the adjuster attempts to construct an invalid date (such as by trying to set a day-of-month of 30 in February), any exception thrown by that construction attempt will be propagated through this method.

Parameters:: adjuster – The adjuster to apply.
Returns:: The adjusted date.

with_offset(offset: Offset) → OffsetDate¶

Returns an OffsetDate for this local date with the given offset.

This method is purely a convenient alternative to calling the OffsetDate constructor directly.

Parameters:: offset – The offset to apply.
Returns:: The result of this date offset by the given amount.

property year: int¶

The year of this local date.

This returns the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example.

property year_of_era: int¶: The year of this local date within the era.

class pyoda_time.LocalDateTime¶

Bases: object

A date and time in a particular calendar system.

A LocalDateTime value does not represent an instant on the global time line, because it has no associated time zone: “November 12th 2009 7pm, ISO calendar” occurred at different instants for different people around the world.

This type defaults to using the ISO calendar system unless a different calendar system is specified.

The default value of this type is 0001-01-01T00:00:00 (midnight on January 1st, 1 C.E.) in the ISO calendar.

class property max_iso_value: LocalDateTime¶

The maximum (latest) date and time representable in the ISO calendar system.

This is a nanosecond before midnight at the end of LocalDate.max_iso_value.

class property min_iso_value: LocalDateTime¶

The minimum (earliest) date and time representable in the ISO calendar system.

This is midnight at the start of LocalDate.min_iso_value.

__add__(other: Period) → LocalDateTime¶

Adds a period to a local date/time.

Fields are added in descending order of significance (years first, then months, and so on).

This is a convenience operator over the plus method.

Parameters:: other – Period to add
Returns:: The resulting local date and time

__eq__(other: object) → bool¶

Implements the operator == (equality).

See the type documentation for a description of equality semantics.

Parameters:: other – An object to compare with this object.
Returns:: True if the current object is equal to the other parameter; otherwise, False.

__ge__(other: LocalDateTime) → bool¶

Compares two LocalDateTime values to see if the left one is later than or equal to the right one.

See the type documentation for a description of ordering semantics.

Parameters:: other – An object to compare with this object.
Returns:: True if the current object is later than or equal to the other parameter; otherwise, False.

__gt__(other: LocalDateTime) → bool¶

Compares two LocalDateTime values to see if the left one is later than the right one.

See the type documentation for a description of ordering semantics.

Parameters:: other – An object to compare with this object.
Returns:: True if the current object is strictly later than the other parameter; otherwise, False.

__init__(year: int = 1, month: int = 1, day: int = 1, hour: int = 0, minute: int = 0, second: int = 0, millisecond: int = 0, calendar: CalendarSystem = ISO) → None¶

Initializes a new instance of the LocalDateTime class.

Parameters:

year – The year. This is the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example.
month – The month of year.
day – The day of month.
hour – The hour.
minute – The minute.
second – The second.
millisecond – The millisecond.
calendar – The calendar.

Raises:

ValueError – The parameters do not form a valid date and time.

__le__(other: LocalDateTime) → bool¶

Compares two LocalDateTime values to see if the left one is earlier than or equal to the right one.

See the type documentation for a description of ordering semantics.

Parameters:: other – An object to compare with this object.
Returns:: True if the current object is earlier than or equal to the other parameter; otherwise, False.

__lt__(other: LocalDateTime) → bool¶

Compares two LocalDateTime values to see if the left one is strictly earlier than the right one.

See the type documentation for a description of ordering semantics.

Parameters:: other – An object to compare with this object.
Returns:: True if the current object is equal to the other parameter; otherwise, False.

__sub__(other: Period | LocalDateTime) → LocalDateTime | Period¶

static add(local_date_time: LocalDateTime, period: Period) → LocalDateTime¶

Add the specified period to the date and time.

Fields are added in descending order of significance (years first, then months, and so on).

Friendly alternative to +.

Parameters:

local_date_time – Initial local date and time
period – Period to add

Returns:

The resulting local date and time

property calendar: CalendarSystem¶: The calendar system associated with this local date and time.

property clock_hour_of_half_day: int¶: The hour of the half-day of this local date and time, in the range 1 to 12 inclusive.

compare_to(other: LocalDateTime | None) → int¶

Indicates whether this date/time is earlier, later or the same as another one.

See the type documentation for a description of ordering semantics.

Parameters:: other – The other local date/time to compare with this value.
Raises:: ValueError – The calendar system of other is not the same as the calendar system of this value.
Returns:: A value less than zero if this date/time is earlier than other; zero if this date/time is the same as other; a value greater than zero if this value is later than other.

property date: LocalDate¶: The date portion of this local date and time as a LocalDate.

property day: int¶: The day of this local date and time within the month.

property day_of_week: IsoDayOfWeek¶: The week day of this local date and time expressed as an IsoDayOfWeek.

property day_of_year: int¶: The day of this local date and time within the year.

equals(other: LocalDateTime) → bool¶

Indicates whether the current object is equal to another object of the same type. See the type documentation for a description of equality semantics.

Parameters:: other – An object to compare with this object.
Returns:: True if the current object is equal to the other parameter; otherwise, False.

property era: Era¶: The era of this local date and time.

classmethod from_naive_datetime(dt: datetime, calendar: CalendarSystem = ISO) → LocalDateTime¶

Converts a timezone-naive datetime.datetime to a LocalDateTime, optionally in a specified calendar.

Parameters:

dt – Timezone-naive datetime to convert into a Pyoda Time local date and time.
calendar – The calendar system to convert into.

Returns:

A new LocalDateTime with the same values as the specified datetime.datetime.

Raises:

ValueError – If dt is a timezone-aware datetime.datetime.

property hour: int¶: The hour of day of this local date and time, in the range 0 to 23 inclusive.

in_utc() → ZonedDateTime¶

Returns the mapping of this local date/time within DateTimeZone.Utc.

As UTC is a fixed time zone, there is no chance that this local date/time is ambiguous or skipped.

Returns:: The result of mapping this local date/time in UTC.

in_zone(zone: DateTimeZone, resolver: ZoneLocalMappingResolver) → ZonedDateTime¶

Resolves this local date and time into a ZonedDateTime in the given time zone, following the given ZoneLocalMappingResolver to handle ambiguity and skipped times.

See in_zone_strictly and in_zone_leniently for alternative ways to map a local time to a specific instant.

This is a convenience method for calling DateTimeZone.resolve_local(LocalDateTime, ZoneLocalMappingResolver).

Parameters:

zone – The time zone in which to map this local date and time into.
resolver – The resolver to apply to the mapping.

Returns:

The result of resolving the mapping.

in_zone_leniently(zone: DateTimeZone) → ZonedDateTime¶

Returns the mapping of this local date/time within the given DateTimeZone, with “lenient” rules applied such that ambiguous values map to the earlier of the alternatives, and “skipped” values are shifted forward by the duration of the “gap”.

See in_zone_strictly and in_zone for alternative ways to map a local time to a specific instant. This is solely a convenience method for calling DateTimeZone.at_leniently.

Parameters:: zone – The time zone in which to map this local date/time.
Returns:: The result of mapping this local date/time in the given time zone.

in_zone_strictly(zone: DateTimeZone) → ZonedDateTime¶

Returns the mapping of this local date/time within the given DateTimeZone, with “strict” rules applied such that an exception is thrown if either the mapping is ambiguous or the time is skipped.

See in_zone_leniently and in_zone for alternative ways to map a local time to a specific instant. This is solely a convenience method for calling DateTimeZone.at_strictly.

Parameters:

zone – The time zone in which to map this local date/time.

Raises:

SkippedTimeError – This local date/time is skipped in the given time zone.
AmbiguousTimeError – This local date/time is ambiguous in the given time zone.

Returns:

The result of mapping this local date/time in the given time zone.

static max(x: LocalDateTime, y: LocalDateTime) → LocalDateTime¶

Returns the later date/time of the given two.

Parameters:

x – The first date/time to compare.
y – The second date/time to compare.

Raises:

ValueError – The two date/times have different calendar systems.

Returns:

The later date/time of x or y.

property microsecond: int¶: The microsecond of this local date and time within the second, in the range 0 to 999,999 inclusive.

property millisecond: int¶: The millisecond of this local date and time within the second, in the range 0 to 999 inclusive.

static min(x: LocalDateTime, y: LocalDateTime) → LocalDateTime¶

Returns the earlier date/time of the given two.

Parameters:

x – The first date/time to compare.
y – The second date/time to compare.

Raises:

ValueError – The two date/times have different calendar systems.

Returns:

The earlier date/time of x or y.

minus(other: Period | LocalDateTime, /) → LocalDateTime | Period¶

property minute: int¶: The minute of this local date and time, in the range 0 to 59 inclusive.

property month: int¶: The month of this local date and time within the year.

property nanosecond_of_day: int¶: The nanosecond of this local date and time within the day, in the range 0 to 86,399,999,999,999 inclusive.

property nanosecond_of_second: int¶: The nanosecond of this local time within the second, in the range 0 to 999,999,999 inclusive.

next(target_day_of_week: IsoDayOfWeek) → LocalDateTime¶

Returns the next LocalDateTime falling on the specified IsoDayOfWeek, at the same time of day as this value.

This is a strict “next” - if this value on already falls on the target day of the week, the returned value will be a week later.

Parameters:

target_day_of_week – The ISO day of the week to return the next date of.

Returns:

The next LocalDateTime falling on the specified day of the week.

Raises:

RuntimeError – The underlying calendar doesn’t use ISO days of the week.
ValueError – target_day_of_week is not a valid day of the week (Monday to Sunday).

plus(period: Period) → LocalDateTime¶

Adds a period to this local date/time.

Fields are added in descending order of significance (years first, then months, and so on).

Parameters:: period – Period to add
Returns:: The resulting local date and time

plus_days(days: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of days added.

This method does not try to maintain the month or year of the current value, so adding 3 days to a value on January 30th will result in a value on February 2nd.

Parameters:: days – The number of days to add
Returns:: The current value plus the given number of days.

plus_hours(hours: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of hours added.

Parameters:: hours – The number of hours to add
Returns:: The current value plus the given number of hours.

plus_milliseconds(milliseconds: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of milliseconds added.

Parameters:: milliseconds – The number of milliseconds to add
Returns:: The current value plus the given number of milliseconds.

plus_minutes(minutes: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of minutes added.

Parameters:: minutes – The number of minutes to add
Returns:: The current value plus the given number of minutes.

plus_months(months: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of months added.

This method does not try to maintain the year of the current value, so adding four months to a value in October will result in a value in the following February.

Parameters:: months – The number of months to add
Returns:: The current value plus the given number of months.

plus_nanoseconds(nanoseconds: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of nanoseconds added.

Parameters:: nanoseconds – The number of nanoseconds to add
Returns:: The current value plus the given number of nanoseconds.

plus_seconds(seconds: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of seconds added.

Parameters:: seconds – The number of seconds to add
Returns:: The current value plus the given number of seconds.

plus_ticks(ticks: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of ticks added.

Parameters:: ticks – The number of ticks to add
Returns:: The current value plus the given number of ticks.

plus_weeks(weeks: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of weeks added.

Parameters:: weeks – The number of weeks to add
Returns:: The current value plus the given number of weeks.

plus_years(years: int) → LocalDateTime¶

Returns a new LocalDateTime representing the current value with the given number of years added.

Parameters:: years – The number of years to add
Returns:: The current value plus the given number of years.

previous(target_day_of_week: IsoDayOfWeek) → LocalDateTime¶

Returns the previous LocalDateTime falling on the specified IsoDayOfWeek, at the same time of day as this value.

This is a strict “previous” - if this value on already falls on the target day of the week, the returned value will be a week earlier.

Parameters:

target_day_of_week – The ISO day of the week to return the previous date of.

Returns:

The previous LocalDateTime falling on the specified day of the week.

Raises:

RuntimeError – The underlying calendar doesn’t use ISO days of the week.
ValueError – target_day_of_week is not a valid day of the week (Monday to Sunday).

property second: int¶: The second of this local date and time within the minute, in the range 0 to 59 inclusive.

static subtract(local_date_time: LocalDateTime, other: Period | LocalDateTime, /) → LocalDateTime | Period¶

property tick_of_day: int¶: The tick of this local date and time within the day, in the range 0 to 863,999,999,999 inclusive.

property tick_of_second: int¶: The tick of this local time within the second, in the range 0 to 9,999,999 inclusive.

property time_of_day: LocalTime¶: The time portion of this local date and time as a LocalTime.

to_naive_datetime() → datetime¶

Constructs a naive datetime.datetime from this value.

If the date and time is not on a microsecond boundary (the unit of granularity of datetime.datetime) the value will be truncated towards the start of time.

datetime.datetime uses the Gregorian calendar by definition, so the value is implicitly converted to the Gregorian calendar first. The result will be on the same physical day, but the values returned by the Year/Month/Day properties of the datetime.datetime may not match the Year/Month/Day properties of this value.

Returns:: A datetime.datetime for the same date and time as this value.

with_calendar(calendar: CalendarSystem) → LocalDateTime¶

Creates a new LocalDateTime representing the same physical date and time, but in a different calendar. The returned LocalDateTime is likely to have different date field values to this one. For example, January 1st 1970 in the Gregorian calendar was December 19th 1969 in the Julian calendar.

Parameters:: calendar – The calendar system to convert this local date to.
Returns:: The converted LocalDateTime.

with_date_adjuster(adjuster: Callable[[LocalDate], LocalDate]) → LocalDateTime¶

Returns this date/time, with the given date adjuster applied to it, maintaining the existing time of day.

Parameters:: adjuster – The adjuster to apply.
Returns:: The adjusted date/time.

with_offset(offset: Offset) → OffsetDateTime¶

Returns an OffsetDateTime for this local date/time with the given offset.

This method is purely a convenient alternative to calling the OffsetDateTime constructor directly.

Parameters:: offset – The offset to apply.
Returns:: The result of this local date/time offset by the given amount.

with_time_adjuster(adjuster: Callable[[LocalTime], LocalTime]) → LocalDateTime¶

Returns this date/time, with the given time adjuster applied to it, maintaining the existing date.

If the adjuster attempts to construct an invalid time, any exception thrown by that construction attempt will be propagated through this method.

Parameters:: adjuster – The adjuster to apply.
Returns:: The adjusted date/time.

property year: int¶

The year of this local date and time.

This returns the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example.

property year_of_era: int¶: The year of this local date and time within its era.

class pyoda_time.LocalTime¶

Bases: object

LocalTime is an immutable struct representing a time of day, with no reference to a particular calendar, time zone or date.

class property max_value: LocalTime¶

The maximum value of this type, one nanosecond before midnight.

This is useful if you have to use an inclusive upper bound for some reason. In general, it’s better to use an exclusive upper bound, in which case use midnight of the following day.

class property midnight: LocalTime¶: Local time at midnight, i.e. 0 hours, 0 minutes, 0 seconds.

class property min_value: LocalTime¶: The minimum value of this type; equivalent to Midnight.

class property noon: LocalTime¶: Local time at noon, i.e. 12 hours, 0 minutes, 0 seconds.

__add__(other: Period) → LocalTime¶

Creates a new local time by adding a period to an existing time.

The period must not contain any date-related units (days etc.) with non-zero values.

Parameters:: other – The period to add
Returns:: The result of adding the period to the time, wrapping via midnight if necessary

__eq__(other: object) → bool¶: Return self==value.

__ge__(other: LocalTime) → bool¶: Return self>=value.

__gt__(other: LocalTime) → bool¶: Return self>value.

__init__(hour: int = 0, minute: int = 0, second: int = 0, millisecond: int = 0) → None¶

Initialises a LocalTime at the given hour, minute, second and millisecond.

Parameters:

hour – The hour of day.
minute – The minute of the hour.
second – The second of the minute.
millisecond – The millisecond of the second.

Raises:

ValueError – The parameters do not form a valid time.

__iter__() → Iterator[int]¶

Deconstruct this time into its components.

Returns:: An iterator of integers representing the hour, minute, and second components of the time.

__le__(other: LocalTime) → bool¶: Return self<=value.

__lt__(other: LocalTime) → bool¶: Return self<value.

__sub__(other: LocalTime | Period) → LocalTime | Period¶

static add(time: LocalTime, period: Period) → LocalTime¶

Adds the specified period to the time. Friendly alternative to +.

Parameters:

time – The time to add the period to
period – The period to add. Must not contain any (non-zero) date units.

Returns:

The sum of the given time and period

property clock_hour_of_half_day: int¶: The hour of the half-day of this local time, in the range 1 to 12 inclusive.

compare_to(other: LocalTime | None) → int¶

classmethod from_hour_minute_second_millisecond_tick(hour: int, minute: int, second: int, millisecond: int, tick_within_millisecond: int) → LocalTime¶

Factory method to create a local time at the given hour, minute, second, millisecond and tick within millisecond.

Parameters:

hour – The hour of day.
minute – The minute of the hour.
second – The second of the minute.
millisecond – The millisecond of the second.
tick_within_millisecond – The tick within the millisecond.

Returns:

The resulting time.

Raises:

ValueError – The parameters do not form a valid time.

classmethod from_hour_minute_second_nanosecond(hour: int, minute: int, second: int, nanosecond_within_second: int) → LocalTime¶

Factory method for creating a local time from the hour of day, minute of hour, second of minute, and nanosecond of second.

Parameters:

hour – The hour of day in the desired time, in the range [0, 23].
minute – The minute of hour in the desired time, in the range [0, 59].
second – The second of minute in the desired time, in the range [0, 59].
nanosecond_within_second – The nanosecond within the second in the desired time, in the range [0, 999999999].

Returns:

The resulting time.

Raises:

ValueError – The parameters do not form a valid time.

classmethod from_hour_minute_second_tick(hour: int, minute: int, second: int, tick_within_second: int) → LocalTime¶

Factory method for creating a local time from the hour of day, minute of hour, second of minute, and tick of second.

Parameters:

hour – The hour of day in the desired time, in the range [0, 23].
minute – The minute of hour in the desired time, in the range [0, 59].
second – The second of minute in the desired time, in the range [0, 59].
tick_within_second – The tick within the second in the desired time, in the range [0, 9999999].

Returns:

The resulting time.

Raises:

ValueError – The parameters do not form a valid time.

classmethod from_hours_since_midnight(hours: int) → LocalTime¶

Factory method for creating a local time from the number of hours which have elapsed since midnight.

Parameters:: hours – The number of hours, in the range [0, 23]
Returns:: The resulting time.

classmethod from_milliseconds_since_midnight(milliseconds: int) → LocalTime¶

Factory method for creating a local time from the number of milliseconds which have elapsed since midnight.

Parameters:: milliseconds – The number of milliseconds, in the range [0, 86,399,999]
Returns:: The resulting time.

classmethod from_minutes_since_midnight(minutes: int) → LocalTime¶

Factory method for creating a local time from the number of minutes which have elapsed since midnight.

Parameters:: minutes – The number of minutes, in the range [0, 1439]
Returns:: The resulting time.

classmethod from_nanoseconds_since_midnight(nanoseconds: int) → LocalTime¶

Factory method for creating a local time from the number of nanoseconds which have elapsed since midnight.

Parameters:: nanoseconds – The number of nanoseconds, in the range [0, 86,399,999,999,999]
Returns:: The resulting time.

classmethod from_seconds_since_midnight(seconds: int) → LocalTime¶

Factory method for creating a local time from the number of seconds which have elapsed since midnight.

Parameters:: seconds – The number of seconds, in the range [0, 86,399]
Returns:: The resulting time.

classmethod from_ticks_since_midnight(ticks: int) → LocalTime¶

Factory method for creating a local time from the number of ticks which have elapsed since midnight.

Parameters:: ticks – The number of ticks, in the range [0, 863,999,999,999]
Returns:: The resulting time.

classmethod from_time(time: time) → LocalTime¶

Constructs a LocalTime from a datetime.time.

Parameters:: time – The time of day to convert.
Returns:: The LocalTime equivalent.

property hour: int¶: The hour of day of this local time, in the range 0 to 23 inclusive.

static max(x: LocalTime, y: LocalTime) → LocalTime¶

Returns the later time of the given two.

Parameters:

x – The first time to compare.
y – The second time to compare.

Returns:

The later time of x or y.

property microsecond: int¶: The microsecond of this local time within the second, in the range 0 to 999,999 inclusive.

property millisecond: int¶: The millisecond of this local time within the second, in the range 0 to 999 inclusive.

static min(x: LocalTime, y: LocalTime) → LocalTime¶

Returns the earlier time of the given two.

Parameters:

x – The first time to compare.
y – The second time to compare.

Returns:

The earlier time of x or y.

minus(period_or_time: Period | LocalTime, /) → Period | LocalTime¶

property minute: int¶: The minute of this local time, in the range 0 to 59 inclusive.

property nanosecond_of_day: int¶: The nanosecond of this local time within the day, in the range 0 to 86,399,999,999,999 inclusive.

property nanosecond_of_second: int¶: The nanosecond of this local time within the second, in the range 0 to 999,999,999 inclusive.

on(date: LocalDate) → LocalDateTime¶

Combines this LocalTime with the given LocalDate into a single LocalDateTime.

Fluent alternative to +.

Parameters:: date – The date to combine with this time
Returns:: The LocalDateTime representation of the given time on this date.

plus(period: Period) → LocalTime¶

Adds the specified period to this time. Fluent alternative to +.

Parameters:: period – The period to add. Must not contain any (non-zero) date units.
Returns:: The sum of this time and the given period

plus_hours(hours: int) → LocalTime¶

Returns a new LocalTime representing the current value with the given number of hours added.

If the value goes past the start or end of the day, it wraps - so 11pm plus two hours is 1am, for example.

Parameters:: hours – The number of hours to add
Returns:: The current value plus the given number of hours.

plus_microseconds(microseconds: int) → LocalTime¶

Returns a new LocalTime representing the current value with the given number of microseconds added.

Parameters:: microseconds – The number of microseconds to add
Returns:: The current value plus the given number of microseconds.

plus_milliseconds(milliseconds: int) → LocalTime¶

Returns a new LocalTime representing the current value with the given number of milliseconds added.

Parameters:: milliseconds – The number of milliseconds to add
Returns:: The current value plus the given number of milliseconds.

plus_minutes(minutes: int) → LocalTime¶

Returns a new LocalTime representing the current value with the given number of minutes added.

If the value goes past the start or end of the day, it wraps - so 11pm plus 120 minutes is 1am, for example.

Parameters:: minutes – The number of minutes to add
Returns:: The current value plus the given number of minutes.

plus_nanoseconds(nanoseconds: int) → LocalTime¶

Returns a new LocalTime representing the current value with the given number of nanoseconds added.

Parameters:: nanoseconds – The number of nanoseconds to add
Returns:: The current value plus the given number of ticks.

plus_seconds(seconds: int) → LocalTime¶

Returns a new LocalTime representing the current value with the given number of seconds added.

If the value goes past the start or end of the day, it wraps - so 11:59pm plus 120 seconds is 12:01am, for example.

Parameters:: seconds – The number of seconds to add
Returns:: The current value plus the given number of seconds.

plus_ticks(ticks: int) → LocalTime¶

Returns a new LocalTime representing the current value with the given number of ticks added.

Parameters:: ticks – The number of ticks to add
Returns:: The current value plus the given number of ticks.

property second: int¶: The second of this local time within the minute, in the range 0 to 59 inclusive.

static subtract(lhs: LocalTime, rhs: LocalTime | Period, /) → LocalTime | Period¶

property tick_of_day: int¶

The tick of this local time within the day, in the range 0 to 863,999,999,999 inclusive.

If the value does not fall on a tick boundary, it will be truncated towards zero.

property tick_of_second: int¶: The tick of this local time within the second, in the range 0 to 9,999,999 inclusive.

to_time() → time¶

Converts this value to an equivalent datetime.time.

If the value does not fall on a microsecond boundary, it will be truncated to the earlier microsecond boundary.

Returns:: The equivalent datetime.time.

with_offset(offset: Offset) → OffsetTime¶

Returns an OffsetTime for this time-of-day with the given offset.

This method is purely a convenient alternative to calling the OffsetTime constructor directly.

Parameters:: offset – The offset to apply.
Returns:: The result of this time-of-day offset by the given amount.

with_time_adjuster(adjuster: Callable[[LocalTime], LocalTime]) → LocalTime¶

class pyoda_time.Offset¶

Bases: object

An offset from UTC in seconds.

class property max_value: Offset¶: The maximum permitted offset; 18 hours after UTC.

class property min_value: Offset¶: The minimum permitted offset; 18 hours before UTC.

class property zero: Offset¶: An offset of zero seconds - effectively the permanent offset for UTC.

__add__(other: Offset) → Offset¶

Implements the operator + (addition).

Parameters:: other – The offset to add.
Returns:: A new Offset representing the sum of the given values.
Raises:: ValueError – The result of the operation is outside the range of Offset.

__eq__(other: object) → bool¶

Implements the operator == (equality). See the type documentation for a description of equality semantics.

Parameters:: other – The object to compare this one to for equality.
Returns:: True if values are equal to each other, otherwise False.

__ge__(other: Offset) → bool¶

Implements the operator >= (greater than or equal). See the type documentation for a description of ordering semantics.

Parameters:: other – The offset to compare with this one.
Returns:: True if this offset is greater than or equal to other, otherwise False.

__gt__(other: Offset) → bool¶

Implements the operator > (greater than). See the type documentation for a description of ordering semantics.

Parameters:: other – The offset to compare with this one.
Returns:: True if this offset is greater than other, otherwise False.

__init__() → None¶

__le__(other: Offset) → bool¶

Implements the operator <= (less than or equal). See the type documentation for a description of ordering semantics.

Parameters:: other – The offset to compare with this one.
Returns:: True if this offset is less than or equal to other, otherwise False.

__lt__(other: Offset) → bool¶

Implements the operator < (less than). See the type documentation for a description of ordering semantics.

Parameters:: other – The offset to compare with this one.
Returns:: True if this offset is less than other, otherwise False.

__neg__() → Offset¶

Implements the unary operator - (negation).

Returns:: A new Offset instance with a negated value.

__sub__(other: Offset) → Offset¶

Implements the operator - (subtraction).

Parameters:: other – The offset to subtract.
Returns:: A new Offset representing the difference of the given values.
Raises:: ValueError – The result of the operation is outside the range of Offset.

static add(left: Offset, right: Offset) → Offset¶

Adds one Offset to another. Friendly alternative to +.

Parameters:

left – The left hand side of the operator.
right – The right hand side of the operator.

Returns:

A new Offset representing the sum of the given values.

Raises:

ValueError – The result of the operation is outside the range of Offset.

compare_to(other: Offset | None) → int¶

Compares the current object with another object of the same type. See the type documentation for a description of ordering semantics.

Parameters:: other – An object to compare with this object.
Returns:: An integer that indicates the relative order of the objects being compared.
Raises:: TypeError – An object of an incompatible type was passed to this method.

The return value has the following meanings:

Value	Meaning
< 0	This object is less than the `other` parameter.
0	This object is equal to `other`.
> 0	This object is greater than `other`.

equals(other: Offset) → bool¶

Indicates whether the current object is equal to another object of the same type. See the type documentation for a description of equality semantics.

Parameters:: other – An object to compare with this object.
Returns:: true if the current object is equal to the other parameter; otherwise, false.

classmethod from_hours(hours: int) → Offset¶

Returns an offset for the specified number of hours, which may be negative.

Parameters:: hours – The number of hours to represent in the new offset.
Returns:: An offset representing the given value.
Raises:: ValueError – The specified number of hours is outside the range of [-18, +18].

classmethod from_hours_and_minutes(hours: int, minutes: int) → Offset¶

Returns an offset for the specified number of hours and minutes.

Parameters:

hours – The number of hours to represent in the new offset.
minutes – The number of minutes to represent in the new offset.

Returns:

An offset representing the given value.

Raises:

ValueError – The result of the operation is outside the range of Offset.

The result simply takes the hours and minutes and converts each component into milliseconds separately. As a result, a negative offset should usually be obtained by making both arguments negative. For example, to obtain “three hours and ten minutes behind UTC” you might call Offset.from_hours_and_minutes(-3, -10).

classmethod from_milliseconds(milliseconds: int) → Offset¶

Returns an offset for the given milliseconds value, which may be negative.

Parameters:: milliseconds – The int milliseconds value.
Returns:: An offset representing the given number of milliseconds, to the (truncated) second.
Raises:: ValueError – The specified number of milliseconds is outside the range of [-18, +18] hours.

Offsets are only accurate to second precision; the given number of milliseconds is simply divided by 1,000 to give the number of seconds - any remainder is truncated.

classmethod from_nanoseconds(nanoseconds: int) → Offset¶

Returns an offset for the given number of nanoseconds, which may be negative.

Parameters:: nanoseconds – The number of nanoseconds specifying the length of the new offset.
Returns:: An offset representing the given number of nanoseconds, to the (truncated) second.
Raises:: ValueError – The specified number of nanoseconds is outside the range of [-18, +18] hours.

Offsets are only accurate to second precision; the given number of nanoseconds is simply divided by 1,000,000,000 to give the number of seconds - any remainder is truncated towards zero.

classmethod from_seconds(seconds: int) → Offset¶

Returns an offset for the given seconds value, which may be negative.

Parameters:: seconds – The int seconds value.
Returns:: An offset representing the given number of seconds.
Raises:: ValueError – The specified number of seconds is outside the range of [-18, +18] hours.

classmethod from_ticks(ticks: int) → Offset¶

Returns an offset for the given number of ticks, which may be negative.

Parameters:: ticks – The number of ticks specifying the length of the new offset.
Returns:: An offset representing the given number of ticks, to the (truncated) second.
Raises:: ValueError – The specified number of ticks is outside the range of [-18, +18] hours.

Offsets are only accurate to second precision; the given number of ticks is simply divided by 10,000,000 to give the number of seconds - any remainder is truncated.

classmethod from_timedelta(timedelta: timedelta) → Offset¶

Converts the given timedelta to an offset, with fractional seconds truncated.

Parameters:: timedelta – The timedelta to convert
Returns:: An offset for the same time as the given timedelta.
Raises:: ValueError – The given timedelta falls outside the range of +/- 18 hours.

static max(x: Offset, y: Offset) → Offset¶

Returns the greater offset of the given two, i.e. the one which will give a later local time when added to an instant.

Parameters:

x – The first offset
y – The second offset

Returns:

The greater offset of x and y.

property milliseconds: int¶

Gets the number of milliseconds represented by this offset, which may be negative.

Offsets are only accurate to second precision; the number of seconds is simply multiplied by 1,000 to give the number of milliseconds.

static min(x: Offset, y: Offset) → Offset¶

Returns the lower offset of the given two, i.e. the one which will give an earlier local time when added to an instant.

Parameters:

x – The first offset
y – The second offset

Returns:

The lower offset of x and y.

minus(other: Offset) → Offset¶

Returns the result of subtracting another Offset from this one, for a fluent alternative to -.

Parameters:: other – The offset to subtract
Returns:: The result of subtracting the other offset from this one.
Raises:: ValueError – The result of the operation is outside the range of Offset.

property nanoseconds: int¶

Gets the number of nanoseconds represented by this offset, which may be negative.

Offsets are only accurate to second precision; the number of seconds is simply multiplied by 1,000,000,000 to give the number of nanoseconds.

static negate(offset: Offset) → Offset¶

Returns the negation of the specified offset. This is the method form of the unary minus operator.

Parameters:: offset – The offset to negate.
Returns:: The negation of the specified offset.

plus(other: Offset) → Offset¶

Returns the result of adding another Offset to this one, for a fluent alternative to +.

Parameters:: other – The offset to add
Returns:: THe result of adding the other offset to this one.
Raises:: ValueError – The result of the operation is outside the range of Offset.

property seconds: int¶: Gets the number of seconds represented by this offset, which may be negative.

static subtract(minuend: Offset, subtrahend: Offset) → Offset¶

Subtracts one Offset from another. Friendly alternative to -.

Parameters:

minuend – The left hand side of the operator.
subtrahend – The right hand side of the operator.

Returns:

A new Offset representing the difference of the given values.

Raises:

ValueError – The result of the operation is outside the range of Offset.

property ticks: int¶

Gets the number of ticks represented by this offset, which may be negative.

Offsets are only accurate to second precision; the number of seconds is simply multiplied by 10,000,000 to give the number of ticks.

to_timedelta() → timedelta¶

Converts this offset to a stdlib datetime.timedelta value.

Returns:: An equivalent datetime.timedelta to this value.

class pyoda_time.OffsetDate¶

Bases: object

A combination of a LocalDate and an Offset, to represent a date at a specific offset from UTC but without any time-of-day information.

Equality is defined in a component-wise fashion: two values are the same if they represent equal dates (including being in the same calendar) and equal offsets from UTC.

The default value of this type is 0001-01-01 (January 1st, 1 C.E.) in the ISO calendar with a UTC offset of zero.

__eq__(other: object) → bool¶

Implements the operator == (equality).

See the type documentation for a description of equality semantics.

Parameters:: other – The value to compare this offset date with.
Returns:: True if values are equal to each other, otherwise False.

__init__(date: ~pyoda_time._local_date.LocalDate = Monday, January 1, 0001, offset: ~pyoda_time._offset.Offset = +00) → None¶

Constructs an instance of the specified date and offset.

Parameters:

date – The date part of the value.
offset – The offset part of the value.

at(time: LocalTime) → OffsetDateTime¶

Combines this OffsetDate with the given LocalTime into an OffsetDateTime.

Parameters:: time – The time to combine with this date.
Returns:: The OffsetDateTime representation of the given time on this date.

property calendar: CalendarSystem¶

Gets the calendar system associated with this offset date.

Returns:: The calendar system associated with this offset date.

property date: LocalDate¶

Gets the local date represented by this value.

Returns:: The local date represented by this value.

property day: int¶

Gets the day of this offset date within the month.

Returns:: The day of this offset date within the month.

property day_of_week: IsoDayOfWeek¶

Gets the week day of this offset date expressed as an IsoDayOfWeek value.

Returns:: The week day of this offset date expressed as an IsoDayOfWeek value.

property day_of_year: int¶

Gets the day of this offset date within the year.

Returns:: The day of this offset date within the year.

equals(other: OffsetDate) → bool¶

Compares two OffsetDate values for equality.

See the type documentation for a description of equality semantics.

Parameters:: other – The value to compare this offset date with.
Returns:: True if the given value is another offset date equal to this one; false otherwise.

property era: Era¶

Gets the era of this offset date.

Returns:: The era of this offset date.

property month: int¶

Gets the month of this offset date within the year.

Returns:: The month of this offset date within the year.

property offset: Offset¶

Gets the offset from UTC of this value.

Returns:: The offset from UTC of this value.

with_calendar(calendar: CalendarSystem) → OffsetDate¶

Creates a new OffsetDate representing the same physical date and offset, but in a different calendar.

The returned value is likely to have different date field values to this one. For example, January 1st 1970 in the Gregorian calendar was December 19th 1969 in the Julian calendar.

Parameters:: calendar – The calendar system to convert this offset date to.
Returns:: The converted OffsetDate.

with_date_adjuster(adjuster: Callable[[LocalDate], LocalDate]) → OffsetDate¶

Returns this offset date, with the given date adjuster applied to it, maintaining the existing offset.

Parameters:: adjuster – The adjuster to apply.
Returns:: The adjusted offset date.

with_offset(offset: Offset) → OffsetDate¶

Creates a new OffsetDate for the same date, but with the specified UTC offset.

Parameters:: offset – The new UTC offset.
Returns:: A new OffsetDate for the same date, but with the specified UTC offset.

property year: int¶

Gets the year of this offset date.

This returns the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example.

Returns:: The year of this offset date.

property year_of_era: int¶

Gets the year of this offset date within the era.

Returns:: The year of this offset date within the era.

class pyoda_time.OffsetDateTime¶

Bases: object

A local date and time in a particular calendar system, combined with an offset from UTC.

This is broadly similar to an aware datetime with a fixed-offset timezone.

Equality is defined in a component-wise fashion: two values are the same if they represent equal date/time values (including being in the same calendar) and equal offsets from UTC.

Ordering between offset date/time values has no natural definition; see comparer for built-in comparers.

A value of this type unambiguously represents both a local time and an instant on the timeline, but does not have a well-defined time zone. This means you cannot reliably know what the local time would be five minutes later, for example. While this doesn’t sound terribly useful, it’s very common in text representations.

The default value of this type is 0001-01-01T00:00:00Z (midnight on January 1st, 1 C.E. with a UTC offset of 0) in the ISO calendar.

__add__(duration: Duration) → OffsetDateTime¶

Returns a new OffsetDateTime with the time advanced by the given duration.

The returned value retains the calendar system and offset of the OffsetDateTime.

Parameters:: duration – The duration to add.
Returns:: A new value with the time advanced by the given duration, in the same calendar system and with the same offset.

__eq__(other: object) → bool¶

Implements the operator == (equality).

See the type documentation for a description of equality semantics.

Parameters:: other – The value to compare this offset date/time with.
Returns:: True if the given value is another offset date/time equal to this one; false otherwise..

__init__(local_date_time: ~pyoda_time._local_date_time.LocalDateTime = 1/1/0001 12:00:00 AM, offset: ~pyoda_time._offset.Offset = +00) → None¶

__sub__(other: Duration | OffsetDateTime) → OffsetDateTime | Duration¶

static add(offset_date_time: OffsetDateTime, duration: Duration) → OffsetDateTime¶

Adds a duration to an offset date and time.

This is an alternative way of calling OffsetDateTime + Duration.

Parameters:

offset_date_time – The value to add the duration to.
duration – The duration to add

Returns:

A new value with the time advanced by the given duration, in the same calendar system and with the same offset.

property calendar: CalendarSystem¶

Gets the calendar system associated with this offset date and time.

Returns:: The calendar system associated with this offset date and time.

property clock_hour_of_half_day: int¶

Gets the hour of the half-day of this offset date and time, in the range 1 to 12 inclusive.

Returns:: The hour of the half-day of this offset date and time, in the range 1 to 12 inclusive.

property date: LocalDate¶

Gets the local date represented by this offset date and time.

The returned LocalDate will have the same calendar system and return the same values for each of the date-based calendar properties (Year, MonthOfYear and so on), but will not have any offset information.

Returns:: The local date represented by this offset date and time.

property day: int¶

Gets the day of this offset date and time within the month.

Returns:: The day of this offset date and time within the month.

property day_of_week: IsoDayOfWeek¶

Gets the week day of this offset date and time expressed as an IsoDayOfWeek.

Returns:: The week day of this offset date and time expressed as an IsoDayOfWeek.

property day_of_year: int¶

Gets the day of this offset date and time within the year.

Returns:: The day of this offset date and time within the year.

equals(other: OffsetDateTime) → bool¶

Compares two OffsetDateTime values for equality.

See the type documentation for a description of equality semantics.

Parameters:: other – The object to compare this date with.
Returns:: True if the given value is another offset date/time equal to this one; False otherwise.

property era: Era¶

Gets the era of this offset date and time.

Returns:: The era of this offset date and time.

classmethod from_aware_datetime(aware_datetime: datetime) → OffsetDateTime¶

Builds an OffsetDateTime from an aware datetime.datetime.

Note that even if the tzinfo represents a real-world time zone, the offset will remain fixed.

Parameters:: aware_datetime – The aware datetime.datetime to convert.
Returns:: The converted offset date and time.

property hour: int¶

Gets the hour of day of this offset date and time, in the range 0 to 23 inclusive.

Returns:: The hour of day of this offset date and time, in the range 0 to 23 inclusive.

in_fixed_zone() → ZonedDateTime¶

Returns this value as a ZonedDateTime.

This method returns a ZonedDateTime with the same local date and time as this value, using a fixed time zone with the same offset as the offset for this value.

Note that because the resulting ZonedDateTime has a fixed time zone, it is generally not useful to use this result for arithmetic operations, as the zone will not adjust to account for daylight savings.

Returns:: A zoned date/time with the same local time and a fixed time zone using the offset from this value.

in_zone(zone: DateTimeZone) → ZonedDateTime¶

Returns this value in ths specified time zone.

This method does not expect the offset in the zone to be the same as for the current value; it simply converts this value into an Instant and finds the ZonedDateTime for that instant in the specified zone.

Parameters:: zone – The time zone of the new value.
Returns:: The instant represented by this value, in the specified time zone.

property local_date_time: LocalDateTime¶

Returns the local date and time represented within this offset date and time.

Returns:: The local date and time represented within this offset date and time.

property millisecond: int¶

Gets the millisecond of this offset date and time within the second, in the range 0 to 999 inclusive.

Returns:: The millisecond of this offset date and time within the second, in the range 0 to 999 inclusive.

minus(other: Duration | OffsetDateTime, /) → OffsetDateTime | Duration¶

property minute: int¶

Gets the minute of this offset date and time, in the range 0 to 59 inclusive.

Returns:: The minute of this offset date and time, in the range 0 to 59 inclusive.

property month: int¶

Gets the month of this offset date and time within the year.

Returns:: The month of this offset date and time within the year.

property nanosecond_of_day: int¶

Gets the nanosecond of this offset date and time within the day, in the range 0 to 86,399,999,999,999 inclusive.

Returns:: The nanosecond of this offset date and time within the day, in the range 0 to 86,399,999,999,999 inclusive.

property nanosecond_of_second: int¶

Gets the nanosecond of this offset date and time within the second, in the range 0 to 999,999,999 inclusive.

Returns:: The nanosecond of this offset date and time within the second, in the range 0 to 999,999,999 inclusive.

property offset: Offset¶

Gets the offset from UTC.

Returns:: The offset from UTC.

plus(duration: Duration) → OffsetDateTime¶

Returns the result of adding a duration to this offset date and time.

This is an alternative way of calling OffsetDateTime + Duration.

Parameters:: duration – The duration to add
Returns:: A new OffsetDateTime representing the result of the addition.

plus_hours(hours: int) → OffsetDateTime¶

Returns the result of adding a increment of hours to this offset date and time.

Parameters:: hours – The number of hours to add
Returns:: A new OffsetDateTime representing the result of the addition.

plus_milliseconds(milliseconds: int) → OffsetDateTime¶

Returns the result of adding an increment of milliseconds to this offset date and time.

Parameters:: milliseconds – The number of milliseconds to add
Returns:: A new OffsetDateTime representing the result of the addition.

plus_minutes(minutes: int) → OffsetDateTime¶

Returns the result of adding an increment of minutes to this offset date and time.

Parameters:: minutes – The number of minutes to add
Returns:: A new OffsetDateTime representing the result of the addition.

plus_nanoseconds(nanoseconds: int) → OffsetDateTime¶

Returns the result of adding an increment of nanoseconds to this offset date and time.

Parameters:: nanoseconds – The number of nanoseconds to add
Returns:: A new OffsetDateTime representing the result of the addition.

plus_seconds(seconds: int) → OffsetDateTime¶

Returns the result of adding an increment of seconds to this offset date and time.

Parameters:: seconds – The number of seconds to add
Returns:: A new OffsetDateTime representing the result of the addition.

plus_ticks(ticks: int) → OffsetDateTime¶

Returns the result of adding an increment of ticks to this offset date and time.

Parameters:: ticks – The number of ticks to add
Returns:: A new OffsetDateTime representing the result of the addition.

property second: int¶

Gets the second of this offset date and time within the minute, in the range 0 to 59 inclusive.

Returns:: The second of this offset date and time within the minute, in the range 0 to 59 inclusive.

static subtract(offset_date_time: OffsetDateTime, duration_or_offset: Duration | OffsetDateTime, /) → OffsetDateTime | Duration¶

property tick_of_day: int¶

Gets the tick of this offset date and time within the day, in the range 0 to 863,999,999,999 inclusive.

Returns:: The tick of this offset date and time within the day, in the range 0 to 863,999,999,999 inclusive.

property tick_of_second: int¶

Gets the tick of this offset date and time within the second, in the range 0 to 9,999,999 inclusive.

Returns:: The tick of this offset date and time within the second, in the range 0 to 9,999,999 inclusive.

property time_of_day: LocalTime¶

Gets the time portion of this offset date and time.

The returned LocalTime will return the same values for each of the time-based properties (Hour, Minute and so on), but will not have any offset information.

Returns:: The time portion of this offset date and time.

to_aware_datetime() → datetime¶

Returns an aware datetime.datetime correspdonding to this offset date and time.

Note that although the returned datetime.datetime is “aware”, the tzinfo will be an instance of datetime.timezone with a fixed utcoffset. It will not be associated with a real-word time zone.

If the date and time is not on a microsecond boundary (the unit of granularity of datetime) the value will be truncated towards the start of time.

datetime uses the Gregorian calendar by definition, so the value is implicitly converted to the Gregorian calendar first. The result will be the same instant in time (potentially truncated as described above), but the values returned by the Year/Month/Day properties of the datetime may not match the Year/Month/Day properties of this value.

Returns:: A datetime.datetime with the same local date/time and offset as this.

to_instant() → Instant¶

Converts this offset date and time to an instant in time by subtracting the offset from the local date and time.

Returns:: The instant represented by this offset date and time

to_offset_date() → OffsetDate¶

Constructs a new OffsetDate from the date and offset of this value, but omitting the time-of-day.

Returns:: A value representing the date and offset aspects of this value.

to_offset_time() → OffsetTime¶

Constructs a new OffsetTime from the time and offset of this value, but omitting the date.

Returns:: A value representing the time and offset aspects of this value.

with_calendar(calendar: CalendarSystem) → OffsetDateTime¶

Creates a new OffsetDateTime representing the same physical date, time and offset, but in a different calendar.

The returned OffsetDateTime is likely to have different date field values to this one.

For example, January 1st 1970 in the Gregorian calendar was December 19th 1969 in the Julian calendar.

Parameters:: calendar – The calendar system to convert this offset date and time to.
Returns:: The converted OffsetDateTime.

with_date_adjuster(adjuster: Callable[[LocalDate], LocalDate]) → OffsetDateTime¶

Returns this offset date/time, with the given date adjuster applied to it, maintaining the existing time of day and offset.

Parameters:: adjuster – The adjuster to apply.
Returns:: The adjusted offset date/time.

with_offset(offset: Offset) → OffsetDateTime¶

Creates a new OffsetDateTime representing the instant in time in the same calendar, but with a different offset. The local date and time is adjusted accordingly.

Parameters:: offset – The new offset to use.
Returns:: The converted OffsetDateTime.

with_time_adjuster(adjuster: Callable[[LocalTime], LocalTime]) → OffsetDateTime¶

Returns this offset date/time, with the given time adjuster applied to it, maintaining the existing date and offset.

If the adjuster attempts to construct an invalid time, any exception thrown by that construction attempt will be propagated through this method.

Parameters:: adjuster – The adjuster to apply.
Returns:: The adjusted offset date/time.

property year: int¶

Gets the year of this offset date and time.

This returns the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example.

Returns:: The year of this offset date and time.

property year_of_era: int¶

Gets the year of this offset date and time within the era.

Returns:: The year of this offset date and time within the era.

class pyoda_time.OffsetTime¶

Bases: object

A combination of a LocalTime and an Offset, to represent a time-of-day at a specific offset from UTC but without any date information.

Equality is defined in a component-wise fashion: two values are the same if they represent equal time-of-day values and equal offsets from UTC. Ordering between offset time values is not defined.

The default value of this type is midnight with a UTC offset of zero.

__eq__(other: object) → bool¶

Implements the operator == (equality).

See the type documentation for a description of equality semantics.

Parameters:: other – The value to compare this offset time with.
Returns:: True if the given value is another offset time equal to this one; false otherwise.

__init__(time: LocalTime, offset: Offset) → None¶

Constructs an instance of the specified time and offset.

Parameters:

time – The time part of the value.
offset – The offset part of the value.

property clock_hour_of_half_day: int¶

Gets the hour of the half-day of this offset time, in the range 1 to 12 inclusive.

Returns:: The hour of the half-day of this offset time, in the range 1 to 12 inclusive.

equals(other: OffsetTime) → bool¶

Compares two OffsetTime values for equality.

See the type documentation for a description of equality semantics.

Parameters:: other – The value to compare this offset time with.
Returns:: True if the given value is another offset time equal to this one; false otherwise.

property hour: int¶

Gets the hour of day of this offset time, in the range 0 to 23 inclusive.

Returns:: The hour of day of this offset time, in the range 0 to 23 inclusive.

property millisecond: int¶

Gets the millisecond of this offset time within the second, in the range 0 to 999 inclusive.

Returns:: The millisecond of this offset time within the second, in the range 0 to 999 inclusive.

property minute: int¶

Gets the minute of this offset time, in the range 0 to 59 inclusive.

Returns:: The minute of this offset time, in the range 0 to 59 inclusive.

property nanosecond_of_day: int¶

Gets the nanosecond of this offset time within the day, in the range 0 to 86,399,999,999,999 inclusive.

Returns:: The nanosecond of this offset time within the day, in the range 0 to 86,399,999,999,999 inclusive.

property nanosecond_of_second: int¶

Gets the nanosecond of this offset time within the second, in the range 0 to 999,999,999 inclusive.

Returns:: The nanosecond of this offset time within the second, in the range 0 to 999,999,999 inclusive.

property offset: Offset¶

Gets the offset from UTC of this value.

Returns:: The offset from UTC of this value.

on(date: LocalDate) → OffsetDateTime¶

Combines this OffsetTime with the given LocalDate into an OffsetDateTime.

Parameters:: date – The date to combine with this time-of-day.
Returns:: The OffsetDateTime representation of this time-of-day on the given date.

property second: int¶

Gets the second of this offset time within the minute, in the range 0 to 59 inclusive.

Returns:: The second of this offset time within the minute, in the range 0 to 59 inclusive.

property tick_of_day: int¶

Gets the tick of this offset time within the day, in the range 0 to 863,999,999,999 inclusive.

If the value does not fall on a tick boundary, it will be truncated towards zero.

Returns:: The tick of this offset time within the day, in the range 0 to 863,999,999,999 inclusive.

property tick_of_second: int¶

Gets the tick of this offset time within the second, in the range 0 to 9,999,999 inclusive.

Returns:: The tick of this offset time within the second, in the range 0 to 9,999,999 inclusive.

property time_of_day: LocalTime¶

Gets the time-of-day represented by this value.

Returns:: The time-of-day represented by this value.

with_offset(offset: Offset) → OffsetTime¶

Creates a new OffsetTime for the same time-of-day, but with the specified UTC offset.

Parameters:: offset – The new UTC offset.
Returns:: A new OffsetTime for the same date, but with the specified UTC offset.

with_time_adjuster(adjuster: Callable[[LocalTime], LocalTime]) → OffsetTime¶

Returns this offset time-of-day, with the given date adjuster applied to it, maintaining the existing offset.

If the adjuster attempts to construct an invalid time-of-day, any exception thrown by that construction attempt will be propagated through this method.

Parameters:: adjuster – The adjuster to apply.
Returns:: The adjusted offset date.

class pyoda_time.Period¶

Bases: object

class property zero: Period¶: A period containing only zero-valued properties.

__add__(other: Period) → Period¶

__eq__(other: object) → bool¶: Return self==value.

__init__() → None¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

__new__() → T¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

__sub__(other: Period) → Period¶

add(other: Period) → Period¶

Return the sum of the two periods.

The units of the result will be the union of those in both periods.

Returns the period between a start and an end date/time, using only the given units.

If end is before start, each property in the returned period will be negative. If the given set of units cannot exactly reach the end point (e.g. finding the difference between 1am and 3:15am in hours) the result will be such that adding it to start will give a value between start and end. In other words, any rounding is “towards start”; this is true whether the resulting period is negative or positive.

Parameters:

start – Start date/time
end – End date/time
units – Units to use for calculations

Returns:

The period between the given date/times, using the given units.

property days: int¶: The number of days within this period.

classmethod days_between(start: LocalDate, end: LocalDate) → int¶

Returns the number of days between two LocalDate objects.

Parameters:

start – Start date/time
end – End date/time

Returns:

The number of days between the given dates.

equals(other: Period) → bool¶

classmethod from_days(days: int) → Period¶

Creates a period representing the specified number of days.

Parameters:: days – The number of days in the new period
Returns:: A period consisting of the given number of days.

classmethod from_hours(hours: int) → Period¶

Creates a period representing the specified number of hours.

Parameters:: hours – The number of hours in the new period
Returns:: A period consisting of the given number of hours.

classmethod from_milliseconds(milliseconds: int) → Period¶

Creates a period representing the specified number of milliseconds.

Parameters:: milliseconds – The number of milliseconds in the new period
Returns:: A period consisting of the given number of milliseconds.

classmethod from_minutes(minutes: int) → Period¶

Creates a period representing the specified number of minutes.

Parameters:: minutes – The number of minutes in the new period
Returns:: A period consisting of the given number of minutes.

classmethod from_months(months: int) → Period¶

Creates a period representing the specified number of months.

Parameters:: months – The number of months in the new period
Returns:: A period consisting of the given number of months.

classmethod from_nanoseconds(nanoseconds: int) → Period¶

Creates a period representing the specified number of nanoseconds.

Parameters:: nanoseconds – The number of nanoseconds in the new period
Returns:: A period consisting of the given number of nanoseconds.

classmethod from_seconds(seconds: int) → Period¶

Creates a period representing the specified number of seconds.

Parameters:: seconds – The number of seconds in the new period
Returns:: A period consisting of the given number of seconds.

classmethod from_ticks(ticks: int) → Period¶

Creates a period representing the specified number of ticks.

Parameters:: ticks – The number of ticks in the new period
Returns:: A period consisting of the given number of ticks.

classmethod from_weeks(weeks: int) → Period¶

Creates a period representing the specified number of weeks.

Parameters:: weeks – The number of weeks in the new period
Returns:: A period consisting of the given number of weeks.

classmethod from_years(years: int) → Period¶

Creates a period representing the specified number of years.

Parameters:: years – The number of years in the new period
Returns:: A period consisting of the given number of years.

property has_date_component: bool¶: True if this period contains any non-zero date-based properties (days or higher); false otherwise.

property has_time_component: bool¶: True if the period contains any non-zero-valued time-based properties (hours or lower); false otherwise.

property hours: int¶: The number of hours within this period.

property milliseconds: int¶: The number of milliseconds within this period.

property minutes: int¶: The number of minutes within this period.

property months: int¶: The number of months within this period.

property nanoseconds: int¶: The number of nanoseconds within this period.

normalize() → Period¶

Returns a normalized version of this period, such that equivalent (but potentially non-equal) periods are changed to the same representation.

Months and years are unchanged (as they can vary in length), but weeks are multiplied by 7 and added to the Days property, and all time properties are normalized to their natural range. Subsecond values are normalized to millisecond and “nanosecond within millisecond” values. So for example, a period of 25 hours becomes a period of 1 day and 1 hour. A period of 1,500,750,000 nanoseconds becomes 1 second, 500 milliseconds and 750,000 nanoseconds. Aside from months and years, either all the properties end up positive, or they all end up negative. “Week” and “tick” units in the returned period are always 0.

Returns:: The normalized period.

property seconds: int¶: The number of seconds within this period.

subtract(other: Period) → Period¶

Subtracts one period from another, by simply subtracting each property value.

The units of the result will be the union of both periods, even if the subtraction caused some properties to become zero (so “2 weeks, 1 days” minus “2 weeks” is “zero weeks, 1 days”, not “1 days”).

Parameters:: other – The period to subtract this one.
Returns:: The result of subtracting all the values in the second operand from the values in the first.

property ticks: int¶: The number of ticks within this period.

to_builder() → PeriodBuilder¶

Creates a PeriodBuilder from this instance.

The new builder is populated with the values from this period, but is then detached from it: changes made to the builder are not reflected in this period.

Returns:: A builder with the same values and units as this period.

to_duration() → Duration¶

Return the duration of the period.

For periods that do not contain a non-zero number of years or months, returns a duration for this period assuming a standard 7-day week, 24-hour day, 60-minute hour etc.

property weeks: int¶: The number of weeks within this period.

property years: int¶: The number of years within this period.

class pyoda_time.PeriodBuilder¶

Bases: object

A mutable builder class for Period values.

Each property can be set independently, and then a Period can be created from the result using the build method.

__init__(years: int = 0, months: int = 0, weeks: int = 0, days: int = 0, hours: int = 0, minutes: int = 0, seconds: int = 0, milliseconds: int = 0, ticks: int = 0, nanoseconds: int = 0) → None¶

build() → Period¶

classmethod from_period(period: Period) → PeriodBuilder¶

class pyoda_time.PeriodUnits¶

Bases: Flag

The units within a Period.

When a period is created to find the difference between two local values, the caller may specify which units are required - for example, you can ask for the difference between two dates in “years and weeks”. Units are always applied largest-first in arithmetic.

ALL_DATE_UNITS = 15¶

ALL_TIME_UNITS = 1008¶

ALL_UNITS = 1023¶

DATE_AND_TIME = 1019¶

DAYS = 8¶

HOURS = 16¶

HOUR_MINUTE_SECOND = 112¶

MILLISECONDS = 128¶

MINUTES = 32¶

MONTHS = 2¶

NANOSECONDS = 512¶

NONE = 0¶

SECONDS = 64¶

TICKS = 256¶

WEEKS = 4¶

YEARS = 1¶

YEAR_MONTH_DAY = 11¶

__new__(value)¶

class pyoda_time.PyodaConstants¶

Bases: object

class property BCL_EPOCH: Instant¶: The instant at the BCL epoch of midnight 1st January 0001 UTC.

class property JULIAN_EPOCH: Instant¶: The instant at the Julian epoch of noon (UTC) January 1st 4713 BCE in the proleptic Julian calendar, or November 24th 4714 BCE in the proleptic Gregorian calendar.

class property UNIX_EPOCH: Instant¶: The instant at the Unix epoch of midnight 1st January 1970 UTC.

DAYS_PER_WEEK: Final[int] = 7¶

HOURS_PER_DAY: Final[int] = 24¶

MICROSECONDS_PER_DAY: Final[int] = 86400000000¶

MICROSECONDS_PER_HOUR: Final[int] = 3600000000¶

MICROSECONDS_PER_MILLISECOND: Final[int] = 1000¶

MICROSECONDS_PER_MINUTE: Final[int] = 60000000¶

MICROSECONDS_PER_SECOND: Final[int] = 1000000¶

MICROSECONDS_PER_WEEK: Final[int] = 604800000000¶

MILLISECONDS_PER_DAY: Final[int] = 86400000¶

MILLISECONDS_PER_HOUR: Final[int] = 3600000¶

MILLISECONDS_PER_MINUTE: Final[int] = 60000¶

MILLISECONDS_PER_SECOND: Final[int] = 1000¶

MINUTES_PER_DAY: Final[int] = 1440¶

MINUTES_PER_HOUR: Final[int] = 60¶

NANOSECONDS_PER_DAY: Final[int] = 86400000000000¶

NANOSECONDS_PER_HOUR: Final[int] = 3600000000000¶

NANOSECONDS_PER_MICROSECOND: Final[int] = 1000¶

NANOSECONDS_PER_MILLISECOND: Final[int] = 1000000¶

NANOSECONDS_PER_MINUTE: Final[int] = 60000000000¶

NANOSECONDS_PER_SECOND: Final[int] = 1000000000¶

NANOSECONDS_PER_TICK: Final[int] = 100¶

NANOSECONDS_PER_WEEK: Final[int] = 604800000000000¶

SECONDS_PER_DAY: Final[int] = 86400¶

SECONDS_PER_HOUR: Final[int] = 3600¶

SECONDS_PER_MINUTE: Final[int] = 60¶

TICKS_PER_DAY: Final[int] = 864000000000¶

TICKS_PER_HOUR: Final[int] = 36000000000¶

TICKS_PER_MICROSECOND: Final[int] = 10¶

TICKS_PER_MILLISECOND: Final[int] = 10000¶

TICKS_PER_MINUTE: Final[int] = 600000000¶

TICKS_PER_SECOND: Final[int] = 10000000¶

TICKS_PER_WEEK: Final[int] = 6048000000000¶

exception pyoda_time.SkippedTimeError¶

Bases: ValueError

Exception thrown to indicate that the specified local time doesn’t exist in a particular time zone due to daylight saving time changes.

This normally occurs for spring transitions, where the clock goes forward (usually by an hour). For example, suppose the time zone goes forward at 2am, so the second after 01:59:59 becomes 03:00:00. In that case, local times such as 02:30:00 never occur.

This exception is used to indicate such problems, as they’re usually not the same as other ValueError causes, such as entering “15” for a month number.

Note that it is possible (though extremely rare) for a whole day to be skipped due to a time zone transition, so this exception may also be thrown in cases where no local time is valid for a particular local date. (For example, Samoa skipped December 30th 2011 entirely, transitioning from UTC-10 to UTC+14 at midnight.)

__init__(local_date_time: LocalDateTime, zone: DateTimeZone) → None¶

Creates a new instance for the given local date/time and time zone.

User code is unlikely to need to deliberately call this constructor except possibly for testing.

Parameters:

local_date_time – The local date/time which is skipped in the specified time zone.
zone – The time zone in which the local date/time does not exist.

property local_date_time: LocalDateTime¶

Gets the local date/time which is invalid in the time zone, prompting this exception.

Returns:: The local date/time which is invalid in the time zone.

property zone: DateTimeZone¶

Gets the time zone in which the local date/time is invalid.

Returns:: The time zone in which the local date/time is invalid

class pyoda_time.SystemClock¶

Bases: IClock

Singleton implementation of IClock which reads the current system time.

It is recommended that for anything other than throwaway code, this is only referenced in a single place in your code: where you provide a value to inject into the rest of your application, which should only depend on the interface.

class property instance: SystemClock¶

The singleton instance of SystemClock.

Returns:: The singleton instance of SystemClock.

__init__() → None¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

__new__() → T¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

get_current_instant() → Instant¶

Gets the current time as an Instant.

Returns:: The current time in nanoseconds as an Instant.

class pyoda_time.TimeAdjusters¶

Bases: object

Factory class for time adjusters: functions from LocalTime to LocalTime, which can be applied to LocalTime, LocalDateTime, and OffsetDateTime.

class property truncate_to_hour: collections.abc.Callable[[pyoda_time._local_time.LocalTime], pyoda_time._local_time.LocalTime]¶

Get a time adjuster to truncate the time to the hour, discarding fractional hours.

Returns:: A time adjuster to truncate the time to the hour, discarding fractional hours.

class property truncate_to_minute: collections.abc.Callable[[pyoda_time._local_time.LocalTime], pyoda_time._local_time.LocalTime]¶

Gets a time adjuster to truncate the time to the minute, discarding fractional minutes.

Returns:: A time adjuster to truncate the time to the minute, discarding fractional minutes.

class property truncate_to_second: collections.abc.Callable[[pyoda_time._local_time.LocalTime], pyoda_time._local_time.LocalTime]¶

Gets a time adjuster to truncate the time to the second, discarding fractional seconds.

Returns:: A time adjuster to truncate the time to the second, discarding fractional seconds.

__init__() → None¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

__new__() → T¶

Raise TypeError if the decorated class has no public constructor.

Raises:: TypeError – This class is not intended to be instantiated directly.

class pyoda_time.YearMonth¶

Bases: object

A year and month in a particular calendar.

This is effectively LocalDate without the day-of-month component.

__eq__(other: object) → bool¶: Return self==value.

__ge__(other: YearMonth) → bool¶: Return self>=value.

__gt__(other: YearMonth) → bool¶: Return self>value.

__init__(*, year: int | None = None, month: int | None = None, era: Era | None = None, year_of_era: int | None = None, calendar: CalendarSystem = ISO) → None¶

__le__(other: YearMonth) → bool¶: Return self<=value.

__lt__(other: YearMonth) → bool¶: Return self<value.

property calendar: CalendarSystem¶: The calendar system associated with this year/month.

compare_to(other: YearMonth | None) → int¶

Indicates whether this year/month is earlier, later or the same as another one. See the type documentation for a description of ordering semantics.

Parameters:: other – The other year/month to compare this one with.
Returns:: A value less than zero if this year/month is earlier than other; zero if this year/month is the same as other; a value greater than zero if this date is later than other.

equals(other: YearMonth) → bool¶: Compares two YearMonth values for equality.

property era: Era¶: The era of this year/month.

property month: int¶: The month of this year/month within the year.

on_day_of_month(day: int) → LocalDate¶

Returns a LocalDate with the year/month of this value, and the given day of month.

Parameters:: day – The day within the month.
Returns:: The result of combining this year and month with day.

plus_months(months: int) → YearMonth¶

Returns a YearMonth object which is the result of adding the specified number of months to this object.

Parameters:: months – The number of months to add to this object.
Returns:: The resulting YearMonth after adding the specified number of months.

to_date_interval() → DateInterval¶: Return a DateInterval covering the month represented by this value.

property year: int¶

The year of this year/month.

This returns the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example.

property year_of_era: int¶: The year of this value within the era.

class pyoda_time.ZonedClock¶

Bases: IClock

A clock with an associated time zone and calendar.

This is effectively a convenience class decorating an IClock.

__init__(clock: IClock, zone: DateTimeZone, calendar: CalendarSystem) → None¶

Creates a new ZonedClock with the given clock, time zone and calendar system.

Parameters:

clock – Clock to use to obtain instants.
zone – Time zone to adjust instants into.
calendar – Calendar system to use.

property calendar: CalendarSystem¶

Gets the calendar system used when converting the current instant into a calendar-sensitive value.

Returns:: The calendar system associated with this zoned clock.

property clock: IClock¶

Gets the clock used to provide the current instant.

Returns:: The clock associated with this zoned clock.

get_curent_time_of_day() → LocalTime¶

Returns the local time of the current instant provided by the underlying clock, adjusted to the time zone of this object.

Returns:: The local time of the current instant provided by the underlying clock, adjusted to the time zone of this object.

get_current_date() → LocalDate¶

Returns the local date of the current instant provided by the underlying clock, adjusted to the time zone of this object.

Returns:: The local date of the current instant provided by the underlying clock, adjusted to the time zone of this object.

get_current_instant() → Instant¶

Returns the current instant provided by the underlying clock.

Returns:: The current instant provided by the underlying clock.

get_current_local_date_time() → LocalDateTime¶

Returns the local date/time of the current instant provided by the underlying clock, adjusted to the time zone of this object.

Returns:: The local date/time of the current instant provided by the underlying clock, adjusted to the time zone of this object.

get_current_offset_date_time() → OffsetDateTime¶

Returns the offset date/time of the current instant provided by the underlying clock, adjusted to the time zone of this object.

Returns:: The offset date/time of the current instant provided by the underlying clock, adjusted to the time zone of this object.

get_current_zoned_date_time() → ZonedDateTime¶

Returns the current instant provided by the underlying clock, adjusted to the time zone of this object.

Returns:: The current instant provided by the underlying clock, adjusted to the time zone of this object.

property zone: DateTimeZone¶

Gets the time zone used when converting the current instant into a zone-sensitive value.

Returns:: The time zone associated with this zoned clock.

class pyoda_time.ZonedDateTime¶

Bases: object

__add__(other: Duration) → ZonedDateTime¶

Returns a new ZonedDateTime with the time advanced by the given duration.

Note that due to daylight saving time changes this may not advance the local time by the same amount.

The returned value retains the calendar system and time zone of self.

Parameters:: other – The duration to add.
Returns:: A new value with the time advanced by the given duration, in the same calendar system and time zone.

__eq__(other: object) → bool¶

Implements the operator ==.

See the type documentation for a description of equality semantics.

Parameters:: other – The object to compare to this one.
Returns:: True if the specified value is a ZonedDateTime representing the same instant in the same time zone; false otherwise.

__init__(*, zone: DateTimeZone, instant: Instant | None = None, local_date_time: LocalDateTime | None = None, offset: Offset | None = None, calendar: CalendarSystem | None = None) → None¶

property calendar: CalendarSystem¶

Gets the calendar system associated with this zoned date and time.

Returns:: The calendar system associated with this zoned date and time.

property date: LocalDate¶

Gets the local date represented by this zoned date and time.

The returned LocalDate will have the same calendar system and return the same values for each of the date-based calendar properties (Year, MonthOfYear and so on), but will not be associated with any particular time zone.

Returns:: The local date represented by this zoned date and time.

property day: int¶

Gets the day of this zoned date and time within the month.

Returns:: The day of this zoned date and time within the month.

property day_of_week: IsoDayOfWeek¶

Gets the week day of this zoned date and time expressed as an IsoDayOfWeek value.

Returns:: The week day of this zoned date and time expressed as an IsoDayOfWeek value.

property day_of_year: int¶

Gets the day of this zoned date and time within the year.

Returns:: The day of this zoned date and time within the year.

property hour: int¶

Gets the hour of day of this zoned date and time, in the range 0 to 23 inclusive.

Returns:: The hour of day of this zoned date and time, in the range 0 to 23 inclusive.

property local_date_time: LocalDateTime¶

Gets the local date and time represented by this zoned date and time.

The returned LocalDateTime will have the same calendar system and return the same values for each of the calendar properties (Year, MonthOfYear and so on), but will not be associated with any particular time zone.

Returns:: The local date and time represented by this zoned date and time.

property minute: int¶

Gets the minute of this zoned date and time, in the range 0 to 59 inclusive.

Returns:: The minute of this zoned date and time, in the range 0 to 59 inclusive.

property month: int¶

Gets the month of this zoned date and time within the year.

Returns:: The month of this zoned date and time within the year.

property offset: Offset¶: The offset of the local representation of this value from UTC.

property second: int¶

Gets the second of this zoned date and time within the minute, in the range 0 to 59 inclusive.

Returns:: The second of this zoned date and time within the minute, in the range 0 to 59 inclusive.

property time_of_day: LocalTime¶

Gets the time portion of this zoned date and time.

The returned LocalTime will return the same values for each of the time-based properties (Hour, Minute and so on), but will not be associated with any particular time zone.

Returns:: The time portion of this zoned date and time.

to_instant() → Instant¶

Converts this value to the instant it represents on the timeline.

This is always an unambiguous conversion. Any difficulties due to daylight saving transitions or other changes in time zone are handled when converting from a LocalDateTime to a ZonedDateTime; the ZonedDateTime remembers the actual offset from UTC to local time, so it always knows the exact instant represented.

Returns:: The instant corresponding to this value.

to_offset_date_time() → OffsetDateTime¶

Constructs an OffsetDateTime with the same local date and time, and the same offset as this zoned date and time, effectively just “removing” the time zone itself.

Returns:: An OffsetDateTime with the same local date/time and offset as this value.

property year: int¶

Gets the year of this zoned date and time.

This returns the “absolute year”, so, for the ISO calendar, a value of 0 means 1 BC, for example.

Returns:: The year of this zoned date and time.

property zone: DateTimeZone¶

Gets the time zone associated with this value.

Returns:: The time zone associated with this value.