pyoda_time.text package¶

Subpackages¶

pyoda_time.text.patterns package

Module contents¶

class pyoda_time.text.AnnualDatePattern¶

Bases: IPattern[AnnualDate]

Represents a pattern for parsing and formatting AnnualDate values.

class property iso: AnnualDatePattern¶

Gets an invariant annual date pattern which is compatible with the month/day part of ISO-8601.

This corresponds to the text pattern “MM’-‘dd”.

Returns:: An invariant annual date pattern which is compatible with the month/day part of ISO-8601.

__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.

append_format(value: AnnualDate, builder: StringBuilder) → StringBuilder¶

Formats the given value as text according to the rules of this pattern, appending to the given StringBuilder.

Parameters:

value – The value to format.
builder – The StringBuilder to append to.

Returns:

The builder passed in as builder.

classmethod create(pattern_text: str, culture_info: CultureInfo = en - US - POSIX, template_value: AnnualDate | None = None) → AnnualDatePattern¶

Creates a pattern for the given pattern text and culture, with a template value of 2000-01-01.

See the user guide for the available pattern text options.

Parameters:

pattern_text – Pattern text to create the pattern for.
culture_info – The culture to use in the pattern; defaults to the current culture.
template_value – Template value to use for unspecified fields. Defaults to 2001-01-01 if not provided.

Returns:

A pattern for parsing and formatting annual dates.

Raises:

InvalidPatternError – The pattern text was invalid.

classmethod create_with_current_culture(pattern_text: str) → AnnualDatePattern¶

Creates a pattern for the given pattern text in the current thread’s current culture.

See the user guide for the available pattern text options. Note that the current culture is captured at the time this method is called - it is not captured at the point of parsing or formatting values.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting annual dates.
Raises:: InvalidPatternError – The pattern text was invalid.

classmethod create_with_invariant_culture(pattern_text: str) → AnnualDatePattern¶

Creates a pattern for the given pattern text in the invariant culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting annual dates.
Raises:: InvalidPatternError – The pattern text was invalid.

format(value: AnnualDate) → str¶

Formats the given annual date as text according to the rules of this pattern.

Parameters:: value – The annual date to format.
Returns:: The annual date formatted according to this pattern.

parse(text: str) → ParseResult[AnnualDate]¶

Parses the given text value according to the rules of this pattern.

This method never throws an exception (barring a bug in Pyoda Time itself). Even errors such as the argument being None are wrapped in a parse result.

Parameters:: text – The text value to parse.
Returns:: The result of parsing, which may be successful or unsuccessful.

property pattern_text: str¶

property template_value: AnnualDate¶

with_culture(culture_info: CultureInfo) → AnnualDatePattern¶

Creates a pattern for the same original pattern text as this pattern, but with the specified culture.

Parameters:: culture_info – The culture to use in the new pattern.
Returns:: A new pattern with the given culture.

with_template_value(template_value: AnnualDate) → AnnualDatePattern¶

Creates a pattern like this one, but with the specified template value.

Parameters:: template_value – The template value for the new pattern, used to fill in unspecified fields.
Returns:: A new pattern with the given template value.

class pyoda_time.text.DurationPattern¶

Bases: IPattern[Duration]

Represents a pattern for parsing and formatting Duration values.

class property json_roundtrip: DurationPattern¶

Gets a pattern for durations using the invariant culture, with a format string of “-H:mm:ss.FFFFFFFFF”.

This pattern round-trips. This corresponds to the “j” standard pattern.

Returns:: The pattern for durations using the invariant culture.

class property roundtrip: DurationPattern¶

Gets the general pattern for durations using the invariant culture, with a format string of “-D:hh:mm:ss.FFFFFFFFF”.

This pattern round-trips. This corresponds to the “o” standard pattern.

Returns:: The general pattern for durations using the invariant culture.

__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.

append_format(value: Duration, builder: StringBuilder) → StringBuilder¶

Formats the given value as text according to the rules of this pattern, appending to the given StringBuilder.

Parameters:

value – The value to format.
builder – The StringBuilder to append to.

Returns:

The builder passed in as builder.

classmethod create(pattern_text: str, culture_info: CultureInfo) → DurationPattern¶

Creates a pattern for the given pattern text and culture.

See the user guide for the available pattern text options.

Parameters:

pattern_text – Pattern text to create the pattern for
culture_info – The culture to use in the pattern

Returns:

A pattern for parsing and formatting offsets.

Raises:

InvalidPatternError – The pattern text was invalid.

classmethod create_with_current_culture(pattern_text: str) → DurationPattern¶

Creates a pattern for the given pattern text in the current thread’s current culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting offsets.
Raises:: InvalidPatternError – The pattern text was invalid.

classmethod create_with_invariant_culture(pattern_text: str) → DurationPattern¶

Creates a pattern for the given pattern text in the invariant culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting offsets.
Raises:: InvalidPatternError – The pattern text was invalid.

format(value: Duration) → str¶

Formats the given duration as text according to the rules of this pattern.

Parameters:: value – The duration to format.
Returns:: The duration formatted according to this pattern.

parse(text: str) → ParseResult[Duration]¶

Parses the given text value according to the rules of this pattern.

This method never throws an exception (barring a bug in Pyoda Time itself). Even errors such as the argument being null are wrapped in a parse result.

Parameters:: text – The text value to parse.
Returns:: The result of parsing, which may be successful or unsuccessful.

property pattern_text: str¶

Gets the pattern text for this pattern, as supplied on creation.

Returns:: The pattern text for this pattern, as supplied on creation.

with_culture(culture_info: CultureInfo) → DurationPattern¶

Creates a pattern for the same original pattern text as this pattern, but with the specified culture.

Parameters:: culture_info – The culture to use in the new pattern.
Returns:: A new pattern with the given culture.

class pyoda_time.text.InstantPattern¶

Bases: IPattern[Instant]

Represents a pattern for parsing and formatting Instant values.

class property extended_iso: InstantPattern¶

Gets an invariant instant pattern which is ISO-8601 compatible, providing up to 9 decimal places of sub- second accuracy. (These digits are omitted when unnecessary.) This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH’:’mm’:’ss;FFFFFFFFF’Z’”.

Returns:: An invariant instant pattern which is ISO-8601 compatible, providing up to 9 decimal places of sub- second accuracy.

class property general: InstantPattern¶

Gets the general pattern, which always uses an invariant culture. The general pattern represents an instant as a UTC date/time in ISO-8601 style “uuuu-MM-ddTHH:mm:ss’Z’”.

Returns:: The general pattern, which always uses an invariant culture.

__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.

append_format(value: Instant, builder: StringBuilder) → StringBuilder¶

Formats the given value as text according to the rules of this pattern, appending to the given StringBuilder.

Parameters:

value – The value to format.
builder – The StringBuilder to append to.

Returns:

The builder passed in as builder.

classmethod create(pattern_text: str, culture_info: CultureInfo) → InstantPattern¶

Creates a pattern for the given pattern text and culture.

See the user guide for the available pattern text options.

Parameters:

pattern_text – Pattern text to create the pattern for
culture_info – The culture to use in the pattern

Returns:

A pattern for parsing and formatting instants.

classmethod create_with_current_culture(pattern_text: str) → InstantPattern¶

Creates a pattern for the given pattern text in the current thread’s current culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting instants.

classmethod create_with_invariant_culture(pattern_text: str) → InstantPattern¶

Creates a pattern for the given pattern text in the invariant culture.

See the user guide for the available pattern text options.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting instants.

format(value: Instant) → str¶

Formats the given value as text according to the rules of this pattern.

Parameters:: value – The value to format.
Returns:: The value formatted according to this pattern.

parse(text: str) → ParseResult[Instant]¶

Parses the given text value according to the rules of this pattern.

This method never raises an Exception (barring a bug in Pyoda Time itself).

Parameters:: text – The text value to parse.
Returns:: The result of parsing, which may be successful or unsuccessful.

property pattern_text: str¶

Gets the pattern text for this pattern, as supplied on creation.

Returns:: The pattern text for this pattern, as supplied on creation.

property template_value: Instant¶

Gets the value used as a template for parsing: any field values unspecified in the pattern are taken from the template.

Returns:: The value used as a template for parsing.

property two_digit_year_max: int¶

Maximum two-digit-year in the template to treat as the current century. If the value parsed is higher than this, the result is adjusted to the previous century. This value defaults to 30. To create a pattern with a different value, use with_two_digit_year_max(int).

Returns:: The value used for the maximum two-digit-year, in the range 0-99 inclusive.

with_culture(culture_info: CultureInfo) → InstantPattern¶

Creates a pattern for the same original pattern text as this pattern, but with the specified culture.

Parameters:: culture_info – The culture to use in the new pattern.
Returns:: A new pattern with the given culture.

with_template_value(new_template_value: Instant) → InstantPattern¶

Creates a pattern like this one, but with the specified template value.

Parameters:: new_template_value – The template value for the new pattern, used to fill in unspecified fields.
Returns:: A new pattern with the given template value.

with_two_digit_year_max(two_digit_year_max: int) → InstantPattern¶

Creates a pattern like this one, but with a different two_digit_year_max value.

Parameters:: two_digit_year_max – The value to use for two_digit_year_max in the new pattern, in the range 0-99 inclusive.
Returns:: A new pattern with the specified maximum two-digit-year.

exception pyoda_time.text.InvalidPatternError¶

Bases: ValueError

Exception thrown to indicate that the format pattern provided for either formatting or parsing is invalid.

__init__(message: str, *args: Any) → None¶

Creates a new InvalidPatternException by formatting the given format string with the specified parameters.

Parameters:

message – Format string to use in order to create the final message
args – Format string parameters

class pyoda_time.text.LocalDatePattern¶

Bases: IPattern[LocalDate]

Represents a pattern for parsing and formatting Instant values.

class property full_roundtrip: LocalDatePattern¶

Gets an invariant local date pattern which round trips values including the calendar system. This corresponds to the text pattern “uuuu’-‘MM’-‘dd ‘(‘c’)’”.

This pattern corresponds to the ‘r’ standard pattern.

Returns:: An invariant local date pattern which round trips values including the calendar system.

class property iso: LocalDatePattern¶

Gets an invariant local date pattern which is ISO-8601 compatible and which round trips values, but doesn’t include the calendar system. This corresponds to the text pattern “uuuu’-‘MM’-‘dd”.

This pattern corresponds to the ‘R’ standard pattern.

Returns:: An invariant local date pattern which is ISO-8601 compatible.

__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.

append_format(value: LocalDate, builder: StringBuilder) → StringBuilder¶

Formats the given value as text according to the rules of this pattern, appending to the given StringBuilder.

Parameters:

value – The value to format.
builder – The StringBuilder to append to.

Returns:

The builder passed in as builder.

classmethod create(pattern_text: str, culture_info: CultureInfo, template_value: LocalDate | None = None) → LocalDatePattern¶

Creates a pattern for the given pattern text, culture, and template value.

If no template value is provided, the default template value of 2000-01-01 will be used.

See the user guide for the available pattern text options.

Parameters:

pattern_text – Pattern text to create the pattern for
culture_info – The culture to use in the pattern
template_value – Maximum two-digit-year in the template to treat as the current century.

Returns:

A pattern for parsing and formatting local dates.

Raises:

InvalidPatternError – The pattern text was invalid.

classmethod create_with_current_culture(pattern_text: str) → LocalDatePattern¶

Creates a pattern for the given pattern text in the current thread’s current culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting local dates.
Raises:: InvalidPatternError – The pattern text was invalid.

classmethod create_with_invariant_culture(pattern_text: str) → LocalDatePattern¶

Creates a pattern for the given pattern text in the invariant culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting local dates.

format(value: LocalDate) → str¶

Formats the given local date as text according to the rules of this pattern.

Parameters:: value – The local date to format.
Returns:: The local date formatted according to this pattern.

parse(text: str) → ParseResult[LocalDate]¶

Parses the given text value according to the rules of this pattern.

This method never throws an exception (barring a bug in Pyoda Time itself). Even errors such as the argument being null are wrapped in a parse result.

Parameters:: text – The text value to parse.
Returns:: The result of parsing, which may be successful or unsuccessful.

property pattern_text: str¶

Gets the pattern text for this pattern, as supplied on creation.

Returns:: The pattern text for this pattern, as supplied on creation.

property template_value: LocalDate¶

Gets the value used as a template for parsing: any field values unspecified in the pattern are taken from the template.

Returns:: The value used as a template for parsing.

property two_digit_year_max: int¶

Returns:: The value used for the maximum two-digit-year, in the range 0-99 inclusive.

with_calendar(calendar: CalendarSystem) → LocalDatePattern¶

Creates a pattern like this one, but with the template value modified to use the specified calendar system.

Care should be taken in two (relatively rare) scenarios. Although the default template value is supported by all Noda Time calendar systems, if a pattern is created with a different template value and then this method is called with a calendar system which doesn’t support that date, an exception will be thrown. Additionally, if the pattern only specifies some date fields, it’s possible that the new template value will not be suitable for all values.

Parameters:: calendar – The calendar system to convert the template value into.
Returns:: A new pattern with a template value in the specified calendar system.

with_culture(culture_info: CultureInfo) → LocalDatePattern¶

Creates a pattern for the same original pattern text as this pattern, but with the specified culture.

Parameters:: culture_info – The culture to use in the new pattern.
Returns:: A new pattern with the given culture.

with_template_value(new_template_value: LocalDate) → LocalDatePattern¶

Creates a pattern like this one, but with the specified template value.

Parameters:: new_template_value – The template value for the new pattern, used to fill in unspecified fields.
Returns:: A new pattern with the given template value.

with_two_digit_year_max(two_digit_year_max: int) → LocalDatePattern¶

Creates a pattern like this one, but with a different two_digit_year_max value.

Parameters:: two_digit_year_max – The value to use for two_digit_year_max in the new pattern, in the range 0-99 inclusive.
Returns:: A new pattern with the specified maximum two-digit-year.

class pyoda_time.text.LocalDateTimePattern¶

Bases: IPattern[LocalDateTime]

Represents a pattern for parsing and formatting LocalDateTime values.

class property bcl_round_trip: LocalDateTimePattern¶

Gets an invariant local date/time pattern which is ISO-8601 compatible, providing up to 7 decimal places of sub-second accuracy which are always present (including trailing zeroes). This is compatible with the BCL round- trip formatting of <see cref=”DateTime”/> values with a kind of “unspecified”. This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffff”. It does not necessarily round-trip all LocalDateTime values as it will lose sub-tick information. Use full_roundtrip_without_calendar for full precision.

This pattern corresponds to the ‘o’ and ‘O’ standard patterns.

Returns:: An invariant local date/time pattern which is ISO-8601 compatible, providing up to 7 decimal places of sub-second accuracy which are always present (including trailing zeroes).

class property date_hour_iso: LocalDateTimePattern¶

Gets an invariant local date/time pattern which is ISO-8601 compatible, with a precision of just hours. This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH”.

Returns:: An invariant local time pattern which is ISO-8601 compatible, with no sub-hour precision.

class property date_hour_minute_iso: LocalDateTimePattern¶

Gets an invariant local date/time pattern which is ISO-8601 compatible, with precision of just minutes. This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH’:’mm”.

Returns:: An invariant local time pattern which is ISO-8601 compatible, with no sub-minute precision.

class property extended_iso: LocalDateTimePattern¶

Gets an invariant local date/time pattern which is ISO-8601 compatible, providing up to 9 decimal places of sub-second accuracy. (These digits are omitted when unnecessary.) This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH’:’mm’:’ss;FFFFFFFFF”.

This pattern corresponds to the ‘S’ standard pattern (“longer sortable”).

Returns:: An invariant local date/time pattern which is ISO-8601 compatible, providing up to 9 decimal places of sub-second accuracy.

class property full_roundtrip: LocalDateTimePattern¶

Gets an invariant local date/time pattern which round trips values including the calendar system. This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffff ‘(‘c’)’”.

This pattern corresponds to the ‘R’ standard pattern.

Returns:: An invariant local date/time pattern which round trips values including the calendar system.

class property full_roundtrip_without_calendar: LocalDateTimePattern¶

Gets an invariant local date/time pattern which round trips values, but doesn’t include the calendar system. It provides up to 9 decimal places of sub-second accuracy which are always present (including trailing zeroes). This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH’:’mm’:’ss’.’fffffffff”. It will round-trip all LocalDateTime values if the calendar system of the template value is the same as the calendar system of the original value.

This pattern corresponds to the ‘r’ standard pattern.

Returns:: An invariant local date/time pattern which is ISO-8601 compatible, providing up to 7 decimal places of sub-second accuracy which are always present (including trailing zeroes).

class property general_iso: LocalDateTimePattern¶

Gets an invariant local date/time pattern which is ISO-8601 compatible, down to the second. This corresponds to the text pattern “uuuu’-‘MM’-‘dd’T’HH’:’mm’:’ss”.

This pattern corresponds to the ‘s’ standard pattern (“shorter sortable”).

Returns:: An invariant local date/time pattern which is ISO-8601 compatible, down to the second.

class property variable_precision_iso: IPattern[LocalDateTime]¶

Gets an invariant local date/time pattern which can parse any ISO-8601 compatible value with a calendar date (in extended format, that is, with separators), regardless of precision in the time part. Valid values for time include “just hours”, “hours and minutes”, “hours, minutes and seconds”, and values with fractions of seconds (as far as nanoseconds). The time part must be present, however; this pattern will not parse date-only values. (It will also not parse ordinal dates or week dates, as described in ISO-8601.)

Returns:: This is expressed as an IPattern[LocalDateTime] rather than a LocalDateTimePattern, as it has no single pattern text.

__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.

append_format(value: LocalDateTime, builder: StringBuilder) → StringBuilder¶

Formats the given value as text according to the rules of this pattern, appending to the given StringBuilder.

Parameters:

value – The value to format.
builder – The StringBuilder to append to.

Returns:

The builder passed in as builder.

classmethod create(pattern_text: str, culture_info: CultureInfo, template_value: LocalDateTime | None = None) → LocalDateTimePattern¶

Creates a pattern for the given pattern text, format info, and template value.

Parameters:

pattern_text – Pattern text to create the pattern for
culture_info – The culture to use in the pattern
template_value – Template value to use for unspecified fields. Defaults to midnight on 2000-01-01 if not provided.

Returns:

A pattern for parsing and formatting local date/times.

Raises:

InvalidPatternError – The pattern text was invalid.

classmethod create_with_current_culture(pattern_text: str) → LocalDateTimePattern¶

Creates a pattern for the given pattern text in the current thread’s current culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting local date/times.

classmethod create_with_invariant_culture(pattern_text: str) → LocalDateTimePattern¶

Creates a pattern for the given pattern text in the invariant culture.

See the user guide for the available pattern text options.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting local date/times.

format(value: LocalDateTime) → str¶

Formats the given local date/time as text according to the rules of this pattern.

Parameters:: value – The local date/time to format.
Returns:: The local date/time formatted according to this pattern.

parse(text: str) → ParseResult[LocalDateTime]¶

Parses the given text value according to the rules of this pattern.

This method never throws an exception (barring a bug in Noda Time itself). Even errors such as the argument being null are wrapped in a parse result.

Parameters:: text – The text value to parse.
Returns:: The result of parsing, which may be successful or unsuccessful.

with_calendar(calendar: CalendarSystem) → LocalDateTimePattern¶

Creates a pattern like this one, but with the template value modified to use the specified calendar system.

Care should be taken in two (relatively rare) scenarios. Although the default template value is supported by all Pyoda Time calendar systems, if a pattern is created with a different template value and then this method is called with a calendar system which doesn’t support that date, an exception will be thrown. Additionally, if the pattern only specifies some date fields, it’s possible that the new template value will not be suitable for all values.

Parameters:: calendar – The calendar system to convert the template value into.
Returns:: A new pattern with a template value in the specified calendar system.

with_culture(culture_info: CultureInfo) → LocalDateTimePattern¶

Creates a pattern for the same original pattern text as this pattern, but with the specified culture.

Parameters:: culture_info – The culture to use in the new pattern.
Returns:: A new pattern with the given culture.

with_template_value(new_template_value: LocalDateTime) → LocalDateTimePattern¶

Creates a pattern like this one, but with the specified template value.

Parameters:: new_template_value – The template value for the new pattern, used to fill in unspecified fields.
Returns:: A new pattern with the given template value.

with_two_digit_year_max(two_digit_year_max: int) → LocalDateTimePattern¶

Creates a pattern like this one, but with a different two_digit_year_max value.

Parameters:: two_digit_year_max – The value to use for two_digit_year_max in the new pattern, in the range 0-99 inclusive.
Returns:: A new pattern with the specified maximum two-digit-year.

class pyoda_time.text.LocalTimePattern¶

Bases: IPattern[LocalTime]

class property extended_iso: LocalTimePattern¶

Gets an invariant local time pattern which is ISO-8601 compatible, providing up to 9 decimal places. (These digits are omitted when unnecessary.) This corresponds to the text pattern “HH’:’mm’:’ss;FFFFFFFFF”.

This pattern corresponds to the ‘o’ standard pattern.

Returns:: An invariant local time pattern which is ISO-8601 compatible, providing up to 9 decimal places.

class property general_iso: LocalTimePattern¶

Gets an invariant local time pattern which is ISO-8601 compatible, with precision of just seconds. This corresponds to the text pattern “HH’:’mm’:’ss”.

Returns:: An invariant local time pattern which is ISO-8601 compatible, with no sub-second precision.

class property hour_iso: LocalTimePattern¶

Gets an invariant local time pattern which is ISO-8601 compatible, with a precision of just hours. This corresponds to the text pattern “HH”.

Returns:: An invariant local time pattern which is ISO-8601 compatible, with no sub-hour precision.

class property hour_minute_iso: LocalTimePattern¶

Gets an invariant local time pattern which is ISO-8601 compatible, with precision of just minutes. This corresponds to the text pattern “HH’:’mm”.

Returns:: An invariant local time pattern which is ISO-8601 compatible, with no sub-minute precision.

class property long_extended_iso: LocalTimePattern¶

Gets an invariant local time pattern which is ISO-8601 compatible, providing exactly 9 decimal places. This corresponds to the text pattern “HH’:’mm’:’ss;fffffffff”.

This pattern corresponds to the ‘O’ standard pattern.

Returns:: An invariant local time pattern which is ISO-8601 compatible, providing exactly 9 decimal places.

class property variable_precision_iso: IPattern[LocalTime]¶

Gets an invariant local time pattern which can parse any ISO-8601 compatible value (in extended format, that is, with separators), regardless of precision. Valid values include “just hours”, “hours and minutes”, “hours, minutes and seconds”, and values with fractions of seconds (as far as nanoseconds).

This is expressed as an IPattern[LocalTime] rather than a LocalTimePattern, as it has no single pattern text.

Returns:: An invariant local time pattern which is ISO-8601 compatible for all precisions.

__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.

append_format(value: LocalTime, builder: StringBuilder) → StringBuilder¶

Formats the given value as text according to the rules of this pattern, appending to the given StringBuilder.

Parameters:

value – The value to format.
builder – The StringBuilder to append to.

Returns:

The builder passed in as builder.

classmethod create(pattern_text: str, culture_info: CultureInfo, template_value: LocalTime = 12:00:00 AM) → LocalTimePattern¶

Creates a pattern for the given pattern text, culture, and template value, with a default template value of midnight.

See the user guide for the available pattern text options.

Parameters:

pattern_text – Pattern text to create the pattern for
culture_info – The culture to use in the pattern
template_value – Template value to use for unspecified fields

Returns:

A pattern for parsing and formatting local times.

classmethod create_with_current_culture(pattern_text: str) → LocalTimePattern¶

Creates a pattern for the given pattern text in the current thread’s current culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting local times.

classmethod create_with_invariant_culture(pattern_text: str) → LocalTimePattern¶

Creates a pattern for the given pattern text in the invariant culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting local times.

format(value: LocalTime) → str¶

Formats the given local time as text according to the rules of this pattern.

Parameters:: value – The local time to format.
Returns:: The local time formatted according to this pattern.

parse(text: str) → ParseResult[LocalTime]¶

Parses the given text value according to the rules of this pattern.

This method never throws an exception (barring a bug in Noda Time itself). Even errors such as the argument being null are wrapped in a parse result.

Parameters:: text – The text value to parse.
Returns:: The result of parsing, which may be successful or unsuccessful.

property pattern_text: str¶

Gets the pattern text for this pattern, as supplied on creation.

Returns:: The pattern text for this pattern, as supplied on creation.

property template_value: LocalTime¶

Gets the value used as a template for parsing.

Any field values unspecified in the pattern are taken from the template.

Returns:: The value used as a template for parsing.

with_culture(culture_info: CultureInfo) → LocalTimePattern¶

Creates a pattern for the same original pattern text as this pattern, but with the specified culture.

Parameters:: culture_info – The culture to use in the new pattern.
Returns:: A new pattern with the given culture.

with_template_value(template_value: LocalTime) → LocalTimePattern¶

Creates a pattern like this one, but with the specified template value.

Parameters:: template_value – The template value for the new pattern, used to fill in unspecified fields.
Returns:: A new pattern with the given template value.

class pyoda_time.text.OffsetPattern¶

Bases: IPattern[Offset]

Represents a pattern for parsing and formatting Offset values.

class property general_invariant: OffsetPattern¶: The “general” offset pattern (e.g. +HH, +HH:mm, +HH:mm:ss, +HH:mm:ss.fff) for the invariant culture.

class property general_invariant_with_z: OffsetPattern¶: The “general” offset pattern (e.g. +HH, +HH:mm, +HH:mm:ss, +HH:mm:ss.fff) for the invariant culture, but producing (and allowing) Z as a value for a zero offset.

__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.

append_format(value: Offset, builder: StringBuilder) → StringBuilder¶

Formats the given value as text according to the rules of this pattern, appending to the given StringBuilder.

Parameters:

value – The value to format.
builder – The StringBuilder to append to.

Returns:

The builder passed in as builder.

classmethod create(pattern_text: str, culture_info: CultureInfo) → OffsetPattern¶

Creates a pattern for the given pattern text and culture.

See the user guide for the available pattern text options.

Parameters:

pattern_text – Pattern text to create the pattern for
culture_info – The culture to use in the pattern

Returns:

A pattern for parsing and formatting offsets.

Raises:

InvalidPatternException – The pattern text was invalid.

classmethod create_with_current_culture(pattern_text: str) → OffsetPattern¶

Creates a pattern for the given pattern text in the current thread’s current culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting offsets.
Raises:: InvalidPatternException – The pattern text was invalid.

classmethod create_with_invariant_culture(pattern_text: str) → OffsetPattern¶

Creates a pattern for the given pattern text in the invariant culture.

Parameters:: pattern_text – Pattern text to create the pattern for
Returns:: A pattern for parsing and formatting offsets.
Raises:: InvalidPatternException – The pattern text was invalid.

format(value: Offset) → str¶

Formats the given offset as text according to the rules of this pattern.

Parameters:: value – The offset to format.
Returns:: The offset formatted according to this pattern.

parse(text: str) → ParseResult[Offset]¶

Parses the given text value according to the rules of this pattern.

This method never throws an exception (barring a bug in Pyoda Time itself). Even errors such as the argument being null are wrapped in a parse result.

Parameters:: text – The text value to parse.
Returns:: The result of parsing, which may be successful or unsuccessful.

property pattern_text: str¶: Gets the pattern text for this pattern, as supplied on creation.

with_culture(culture_info: CultureInfo) → OffsetPattern¶

Creates a pattern for the same original pattern text as this pattern, but with the specified culture.

Parameters:: culture_info – The culture to use in the new pattern.
Returns:: A new pattern with the given culture.

class pyoda_time.text.ParseResult¶

Bases: Generic

The result of a parse operation.

__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.

convert(projection: Callable[[T], TTarget]) → ParseResult[TTarget]¶

Converts this result to a new target type, either by executing the given projection for a success result, or propagating the exception provider for failure.

Parameters:: projection – The projection to apply for the value of this result, if it’s a success result.
Returns:: A ParseResult for the target type, either with a value obtained by applying the specified projection to the value in this result, or with the same error as this result.

convert_error(target_type: type[TTarget]) → ParseResult[TTarget]¶

property exception: Exception¶

Gets an exception indicating the cause of the parse failure.

This property is typically used to wrap parse failures in higher level exceptions.

Returns:: The exception indicating the cause of the parse failure.
Raises:: RuntimeError – The parse operation succeeded.

classmethod for_exception(exception_provider: Callable[[], Exception]) → ParseResult[T]¶

Produces a ParseResult which represents a failed parsing operation.

This method accepts a Callable rather than the exception itself because if the client doesn’t need the actual exception - just the information that the parse failed - there’s no point in creating the exception.

Parameters:: exception_provider – A Callable which produces the exception representing the error that caused the parse to fail.
Returns:: A ParseResult representing a failed parsing operation.

classmethod for_value(value: T) → ParseResult[T]¶

Produces a ParseResult which represents a successful parse operation.

Parameters:: value – The successfully parsed value.
Returns:: A ParseResult representing a successful parsing operation.

get_value_or_throw() → T¶

Gets the value from the parse operation if it was successful, or throws an exception indicating the parse failure otherwise.

This method is exactly equivalent to fetching the value property, but more explicit in terms of throwing an exception on failure.

Returns:: The result of the parsing operation if it was successful.

property success: bool¶

Indicates whether the parse operation was successful.

Returns:: True if the parse operation was successful; otherwise False.

try_get_value(failure_value: T) → tuple[bool, T]¶

Returns a two-tuple of the success value, and either the default failure_value of T or the successful parse result value.

Parameters:: failure_value – The “default” value to set in result if parsing failed.
Returns:: A two-tuple of a boolean representing success, and either the parsed value or the default value.

property value: T¶

Gets the value from the parse operation if it was successful, or throws an exception indicating the parse failure otherwise.

This method is exactly equivalent to calling the get_value_or_throw() method, but is terser if the code is already clear that it will throw if the parse failed.

Returns:: The result of the parsing operation if it was successful.

exception pyoda_time.text.UnparsableValueError¶

Bases: Exception

Exception thrown to indicate that the specified value could not be parsed.