upsies.utils.types

CLI argument types

All types return normalized values and raise ValueError for invalid values.

Functions

upsies.utils.types.Choice(options, *, empty_ok=False, case_sensitive=True)

Return str subclass that can only have instances that are equal to an item of options

Parameters:

• options – Iterable of allowed instances

• empty_ok (bool) – Whether an emptry string is valid even if it is not in options

• case_sensitive (bool) – Whether case is considered

Raises:

ValueError – if instantiation is attempted with a value that is not in options

upsies.utils.types.Imagehost(allowed=None, disallowed=None)

Return new Choice subclass that only accepts allowed image host names

Parameters:

• allowed – Sequence of allowed image host names or None to allow all supported image host names

• disallowed – Sequence of disallowed image host names or None to allow all supported image host names

upsies.utils.types.Integer(min=None, max=None)

Return int subclass with minimum and maximum value

>>> i = Integer(min=0, max=10)
>>> i(100)
>>> ValueError: Maximum is 10

upsies.utils.types.ListOf(item_type, separator=None)

Return immutable sequence type that can only contain item_type objects

Parameters:

item_type – Any callable that returns a valid object for any items added to the list or raises ValueError or TypeError

Raises:

ValueError – if any invalid value is added to the list

Returns:

subclass of Sequence

Classes

class upsies.utils.types.Bool(value)

Bases: str

str subclass with boolean value

Truthy strings: true, yes, on, 1 Falsy strings: false, no, off, 0

truthy = ('true', 'yes', '1', 'on', 'aye')

Valid True values (case-insensitive)

falsy = ('false', 'no', '0', 'off', 'nay')

Valid False values (case-insensitive)

class upsies.utils.types.Bytes(value)

Bases: int

int subclass with binary or decimal unit prefix

classmethod from_string(string)

Parse string like 4kB or 1.024 KiB

format(*, prefix='shortest', decimal_places=2, trailing_zeros=False)

Return human-readable string

Parameters:

• prefix (str) – Unit prefix, must be one of binary (1000 -> “1 kB”), decimal (1024 -> “1 KiB”) or shortest (automatically pick the string representation with the fewest decimal places)

• decimal_places (int) – How many decimal places to include

• trailing_zeros (bool) – Whether to remove zeros on the right of the decimal places

class upsies.utils.types.PathTranslation(string)

Bases: object

Translate beginning of path

Parameters:

string (str) – Translation in the form of /from/path -> /to/path

Windows paths are detected by a single ASCII letter followed by a colon (e.g. c:) at the beginning of a path. All other paths are interpreted as POSIX.

~ is interpreted via os.path.expanduser() for local paths.

property local

pathlib.PurePath instance of the first/source path

property remote

pathlib.PurePath instance of the second/target path

translate(path)

Replace local at the beginning of path with remote

The returned path is always translated to the remote path flavour (POSIX or Windows).

If path does not start with local, return None.

class upsies.utils.types.PathTranslations(items=())

Bases: ListOfPathTranslation

ListOf PathTranslation instances

translate(path)

Use the first matching PathTranslation to translate path

Return path unmodified by default.

class upsies.utils.types.Regex(pattern)

Bases: object

Special class that behaves like re.Pattern (return value of re.compile()) but more intuitively

Its string representation is re.Pattern.pattern instead of re.compile('<pattern>').

Instead of raising re.error, it raises ValueError on invalid regular expressions.

Raises:

ValueError – instead of re.error

class upsies.utils.types.ReleaseType(value)

Bases: Enum

Enum with the values movie, season, episode and unknown

series is an alias for season.

All values are truthy except for unknown.

class upsies.utils.types.ReleaseYear(year)

Bases: int

int within a reasonable range

Raises:

ValueError – if year cannot be converted to int or is not reasonable

class upsies.utils.types.SceneCheckResult(value)

Bases: Enum

Enum with the values true, false, renamed, altered and unknown

All values are falsy except for true.

class upsies.utils.types.Timestamp(seconds)

Bases: float

Subclass of float that can parse and format timestamp/duration strings

Parameters:

seconds (int or float or "[[H+:]M+:]S+") – Number of seconds or hours, minutes and seconds as “:”-separated string

Raises:

• ValueError – if seconds is not a valid timestamp

• TypeError – if seconds is not a int, float or str

classmethod from_string(string)

Parse string of the format “[[H+:]MM:]SS”

Parameters:

string (str) – Hours, minutes and seconds as “:”-separated string or number of seconds

Raises:

ValueError – if string has an invalid format