Time Module

Custom date/time input handlers for Parameters.

Warning

Uses locale.setlocale() if alternate locales are specified, which may cause problems on some systems. Using alternate locales in this manner should not be used in a multi-threaded application, as it will lead to unexpected output from other parts of the program.

If you need to handle multiple locales and this is a problem for your application, then you should leave the locale parameters empty / None and use a proper i18n library like babel for localization.

author:

Doug Skrypa

class cli_command_parser.inputs.time.different_locale(locale: str | Tuple[str | None, str | None] | None)

Bases: object

Context manager that allows the temporary use of an alternate locale for date/time parsing/formatting.

Not using python:calendar.different_locale because it results in incorrect string encoding for some locales (at least on Windows).

locale

original

class cli_command_parser.inputs.time.DTInput(locale: str | Tuple[str | None, str | None] = None, fix_default: bool | Any = True)

Bases: InputType[T], ABC

dt_type: str

classmethod __init_subclass__(dt_type: str = None, **kwargs)

Parameters:

dt_type – Used in InvalidChoiceError / ValueError messages

locale: str | Tuple[str | None, str | None] | None

abstractmethod choice_str(choice_delim: str = ',', sort_choices: bool = False) → str

fix_default(value: str | T | None) → T | None

class cli_command_parser.inputs.time.DTFormatMode(*values)

Bases: MissingMixin, Enum

FULL = 'full'

The full name of a given date/time unit

ABBREVIATION = 'abbreviation'

The abbreviation of a given date/time unit

NUMERIC = 'numeric'

The numeric representation of a given date/time unit

NUMERIC_ISO = 'numeric_iso'

The ISO numeric representation of a given date/time unit

class cli_command_parser.inputs.time.CalendarUnitInput(*, full: bool | Any = True, abbreviation: bool | Any = True, numeric: bool | Any = False, locale: str | Tuple[str | None, str | None] = None, out_format: str | DTFormatMode = DTFormatMode.FULL, out_locale: str | Tuple[str | None, str | None] = None, fix_default: bool | Any = True)

Bases: DTInput[str | int], ABC

Input type representing a date/time unit.

Parameters:

• full – Allow the full unit name to be provided

• abbreviation – Allow abbreviations of unit names to be provided

• numeric – Allow unit values to be specified as a decimal number

• locale – An alternate locale to use when parsing input

• out_format – A DTFormatMode or str that matches a format mode. Defaults to full weekday name.

• out_locale – Alternate locale to use for output. Defaults to the same value as locale.

• fix_default – Whether default values should be normalized using fix_default().

classmethod __init_subclass__(min_index: int = 0, **kwargs)

full

abbreviation

numeric

out_format

out_locale

choices(sort: bool = False) → Sequence[str]

choice_str(choice_delim: str = ',', sort_choices: bool = False) → str

format_metavar(choice_delim: str = ',', sort_choices: bool = False) → str

abstractmethod parse_numeric(value: str) → int

parse(value: str) → int

Parse the date/time unit from the given value.

This method does not use python:datetime.strptime() because it is not accurate for standalone numeric weekdays.

Parameters:

value – The value provided as input

Returns:

The numeric unit value

__call__(value: str) → str | int

dt_type: str = None

class cli_command_parser.inputs.time.Day(*, full: bool | Any = True, abbreviation: bool | Any = True, numeric: bool | Any = False, iso: bool | Any = False, locale: str | Tuple[str | None, str | None] = None, out_format: str | DTFormatMode = DTFormatMode.FULL, out_locale: str | Tuple[str | None, str | None] = None, fix_default: bool | Any = True)

Bases: CalendarUnitInput

Input type representing a day of the week.

Parameters:

• full – Allow the full day name to be provided

• abbreviation – Allow abbreviations of day names to be provided

• numeric – Allow weekdays to be specified as a decimal number

• iso – Ignored if numeric is False. If True, then numeric weekdays are treated as ISO 8601 weekdays, where 1 is Monday and 7 is Sunday. If False, then 0 is Monday and 6 is Sunday.

• locale – An alternate locale to use when parsing input

• out_format – A DTFormatMode or str that matches a format mode. Defaults to full weekday name.

• out_locale – Alternate locale to use for output. Defaults to the same value as locale.

• fix_default – Whether default values should be normalized using fix_default().

iso

parse_numeric(value: str) → int

dt_type: str = 'day of the week'

class cli_command_parser.inputs.time.Month(*, full: bool | Any = True, abbreviation: bool | Any = True, numeric: bool | Any = True, locale: str | Tuple[str | None, str | None] = None, out_format: str | DTFormatMode = DTFormatMode.FULL, out_locale: str | Tuple[str | None, str | None] = None, fix_default: bool | Any = True)

Bases: CalendarUnitInput

Input type representing a month.

Parameters:

• full – Allow the full month name to be provided

• abbreviation – Allow abbreviations of month names to be provided

• numeric – Allow months to be specified as a decimal number

• locale – An alternate locale to use when parsing input

• out_format – A DTFormatMode or str that matches a format mode. Defaults to full month name.

• out_locale – Alternate locale to use for output. Defaults to the same value as locale.

• fix_default – Whether default values should be normalized using fix_default().

parse_numeric(value: str) → int

dt_type: str = 'month'

class cli_command_parser.inputs.time.TimeDelta(unit: Literal['microseconds', 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'weeks'], *, min: NT | None = None, max: NT | None = None, include_min: bool | Any = True, include_max: bool | Any = False, int_only: bool | Any = False, fix_default: bool | Any = True)

Bases: RangeMixin, InputType[timedelta]

unit

min: Number

max: Number

include_min: bool

include_max: bool

int_only

__call__(value: str | int | float) → timedelta

fix_default(value: int | float | timedelta | None) → timedelta | None

format_metavar(choice_delim: str = ',', sort_choices: bool = False) → str

class cli_command_parser.inputs.time.DateTimeInput(formats: Collection[str], locale: str | Tuple[str | None, str | None] = None, earliest: datetime | date | time | timedelta | None = None, latest: datetime | date | time | timedelta | None = None, fix_default: bool | Any = True)

Bases: DTInput[DT], ABC

classmethod __init_subclass__(type: Type[DT], **kwargs)

formats: Collection[str]

property earliest: DT | None

property latest: DT | None

parse_dt(value: str) → datetime

parse(value: str) → DT

choice_str(choice_delim: str = ' | ', sort_choices: bool = False) → str

format_metavar(choice_delim: str = ' | ', sort_choices: bool = False) → str

__call__(value: str) → DT

locale: str | Tuple[str | None, str | None] | None

dt_type: str = None

class cli_command_parser.inputs.time.DateTime(*formats: str, locale: str | Tuple[str | None, str | None] = None, earliest: datetime | date | time | timedelta | None = None, latest: datetime | date | time | timedelta | None = None, fix_default: bool | Any = True)

Bases: DateTimeInput[datetime]

Input type that accepts any number of datetime format strings for parsing input. Parsing results in returning a datetime.datetime object.

Parameters:

• formats – One or more datetime format strings. Defaults to DEFAULT_DT_FMT.

• locale – An alternate locale to use when parsing input

• earliest – If specified, the parsed value must be later than or equal to this

• latest – If specified, the parsed value must be earlier than or equal to this

• fix_default – Whether default values should be normalized using fix_default().

locale: str | Tuple[str | None, str | None] | None

dt_type: str = 'datetime'

class cli_command_parser.inputs.time.Date(*formats: str, locale: str | Tuple[str | None, str | None] = None, earliest: datetime | date | time | timedelta | None = None, latest: datetime | date | time | timedelta | None = None, fix_default: bool | Any = True)

Bases: DateTimeInput[date]

Input type that accepts any number of datetime format strings for parsing input. Parsing results in returning a datetime.date object.

Parameters:

• formats – One or more datetime format strings. Defaults to DEFAULT_DT_FMT.

• locale – An alternate locale to use when parsing input

• earliest – If specified, the parsed value must be later than or equal to this

• latest – If specified, the parsed value must be earlier than or equal to this

• fix_default – Whether default values should be normalized using fix_default().

locale: str | Tuple[str | None, str | None] | None

dt_type: str = 'date'

class cli_command_parser.inputs.time.Time(*formats: str, locale: str | Tuple[str | None, str | None] = None, earliest: datetime | date | time | timedelta | None = None, latest: datetime | date | time | timedelta | None = None, fix_default: bool | Any = True)

Bases: DateTimeInput[time]

Input type that accepts any number of datetime format strings for parsing input. Parsing results in returning a datetime.time object.

Parameters:

• formats – One or more datetime format strings. Defaults to DEFAULT_DT_FMT.

• locale – An alternate locale to use when parsing input

• earliest – If specified, the parsed value must be later than or equal to this

• latest – If specified, the parsed value must be earlier than or equal to this

• fix_default – Whether default values should be normalized using fix_default().

locale: str | Tuple[str | None, str | None] | None

dt_type: str = 'time'

cli_command_parser.inputs.time.dt_repr(dt: datetime | date | time, use_repr: bool = True) → str

cli_command_parser.inputs.time.normalize_dt(value: datetime | date | time | timedelta | None, now: datetime = None) → datetime | None