shillelagh.adapters.api.gsheets.parsing package

Submodules

shillelagh.adapters.api.gsheets.parsing.base module

Token for parsing date and time.

exception shillelagh.adapters.api.gsheets.parsing.base.InvalidPattern

Bases: Exception

Raised when the pattern can’t be consumed.

exception shillelagh.adapters.api.gsheets.parsing.base.InvalidValue

Bases: Exception

Raised when the value can’t be consumed.

class shillelagh.adapters.api.gsheets.parsing.base.LITERAL(token: str)

Bases: Token

A literal.

format(value: Valid, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '(\\\\.)|(".*?")|(.)'

class shillelagh.adapters.api.gsheets.parsing.base.Token(token: str)

Bases: Generic[Valid]

A token.

classmethod consume(pattern: str, history: list[Token]) → tuple[Token, str]

Consume the pattern, returning the token and the remaining pattern.

format(value: Valid, tokens: list[Token]) → str

Format the value using the pattern.

classmethod match(pattern: str, history: list[Token]) → bool

Check if token handles the beginning of the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str

shillelagh.adapters.api.gsheets.parsing.base.is_unescaped_literal(token: Token) → bool

Return true if the token is an unescaped literal.

shillelagh.adapters.api.gsheets.parsing.base.tokenize(pattern: str, classes: list[type[Token]]) → Iterator[Token]

Tokenize a pattern.

shillelagh.adapters.api.gsheets.parsing.date module

Parse and format Google Sheet date/time patterns.

https://developers.google.com/sheets/api/guides/formats?hl=en#date_and_time_format_patterns

class shillelagh.adapters.api.gsheets.parsing.date.AMPM(token: str)

Bases: AP

As above, but displays “AM” or “PM” instead and is always capitalized.

format(value: datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'am/pm'

class shillelagh.adapters.api.gsheets.parsing.date.AP(token: str)

Bases: Token

Displays “a” for AM, and “p” for PM. Also changes hours to 12-hour format. If the token letter is capitalized, the output is as well.

format(value: datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '(a/p)|(A/P)'

class shillelagh.adapters.api.gsheets.parsing.date.D(token: str)

Bases: Token

Day of the month, no leading 0 for numbers less than 10.

format(value: date | datetime, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'd(?!d)'

class shillelagh.adapters.api.gsheets.parsing.date.DD(token: str)

Bases: D

Day of the month, with a leading 0 for numbers less than 10.

format(value: date | datetime, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'dd(?!d)'

class shillelagh.adapters.api.gsheets.parsing.date.DDD(token: str)

Bases: D

Day of the week, three letter abbreviation (e.g., “Mon”).

format(value: date | datetime, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'ddd(?!d)'

class shillelagh.adapters.api.gsheets.parsing.date.DDDDPlus(token: str)

Bases: D

Day of the week, full name.

format(value: date | datetime, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'd{4,}'

class shillelagh.adapters.api.gsheets.parsing.date.DurationToken(token: str)

Bases: Token

A token for durations.

Durations are special because often only the first token is annotated. For example:

• [h]:mm:ss

• [ss].000

But apparently it is valid to annotate subsequent tokens:

• [hh]:[mm]:[ss].000

Who knows?

Because of this, their regexes are dynamic, and depend on the token history.

classmethod consume(pattern: str, history: list[Token]) → tuple[Token, str]

Consume the pattern, returning the token and the remaining pattern.

is_duration = True

classmethod match(pattern: str, history: list[Token]) → bool

Check if token handles the beginning of the pattern.

regexes: tuple[str, str]

class shillelagh.adapters.api.gsheets.parsing.date.H(token: str)

Bases: Token

Hour of the day.

Switches between 12 and 24 hour format depending on whether an am/pm indicator is present in the string.

format(value: datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'h(?!h)'

class shillelagh.adapters.api.gsheets.parsing.date.HHPlus(token: str)

Bases: H

Same as previous, but with a leading 0 for 1-9.

format(value: datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'hh+'

class shillelagh.adapters.api.gsheets.parsing.date.HPlusDuration(token: str)

Bases: DurationToken

Number of elapsed hours in a time duration. Number of letters indicates minimum number of digits (adds leading 0s).

format(value: timedelta, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regexes: tuple[str, str] = ('\\[h+\\]', '(h+)|(\\[h+\\])')

class shillelagh.adapters.api.gsheets.parsing.date.M(token: str)

Bases: Token

If the previous non-literal token was hours or the subsequent one is seconds, then it represents minutes in the hour (no leading 0). Otherwise, it represents the month of the year as a number (no leading 0).

format(value: date | datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'm(?!m)'

class shillelagh.adapters.api.gsheets.parsing.date.MM(token: str)

Bases: M

As above, but with a leading 0 for both cases.

format(value: date | datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'mm(?!m)'

class shillelagh.adapters.api.gsheets.parsing.date.MMM(token: str)

Bases: Token

Three letter month abbreviation (e.g., “Feb”).

format(value: date | datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'mmm(?!m)'

class shillelagh.adapters.api.gsheets.parsing.date.MMMM(token: str)

Bases: MMM

Full month name. mmmmmm+ also matches this.

format(value: date | datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '(mmmm(?!m))|(m{6,})'

class shillelagh.adapters.api.gsheets.parsing.date.MMMMM(token: str)

Bases: MMM

First letter of the month (e.g., “J” for June).

format(value: date | datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'mmmmm'

class shillelagh.adapters.api.gsheets.parsing.date.MPlusDuration(token: str)

Bases: DurationToken

Number of elapsed minutes in a time duration. Number of letters indicates minimum number of digits (adds leading 0s).

format(value: timedelta, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regexes: tuple[str, str] = ('\\[m+\\]', '(m+)|(\\[m+\\])')

class shillelagh.adapters.api.gsheets.parsing.date.Meridiem(value)

Bases: Enum

Represent ante or post meridiem.

AM = 'AM'

PM = 'PM'

class shillelagh.adapters.api.gsheets.parsing.date.S(token: str)

Bases: Token

Seconds in the minute without a leading 0.

format(value: datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 's(?!s)'

class shillelagh.adapters.api.gsheets.parsing.date.SPlusDuration(token: str)

Bases: DurationToken

Number of elapsed seconds in a time duration. Number of letters indicates minimum number of digits (adds leading 0s).

format(value: timedelta, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regexes: tuple[str, str] = ('\\[s+\\]', '(s+)|(\\[s+\\])')

class shillelagh.adapters.api.gsheets.parsing.date.SS(token: str)

Bases: S

Seconds in the minute with a leading 0.

format(value: datetime | time, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'ss'

class shillelagh.adapters.api.gsheets.parsing.date.YY(token: str)

Bases: Token

2-digit year.

format(value: date | datetime, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'y{1,2}(?!y)'

class shillelagh.adapters.api.gsheets.parsing.date.YYYY(token: str)

Bases: Token

4-digit year.

format(value: date | datetime, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = 'y{3,}'

class shillelagh.adapters.api.gsheets.parsing.date.ZERO(token: str)

Bases: Token

Tenths of seconds. You can increase the precision to 2 digits with 00 or 3 digits (milliseconds) with 000.

format(value: datetime | time | timedelta, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '0{1,3}(?!0)'

shillelagh.adapters.api.gsheets.parsing.date.format_date_time_pattern(value: DateTime, pattern: str) → str

Format a date/time related object to a given pattern.

See https://developers.google.com/sheets/api/guides/formats?hl=en.

shillelagh.adapters.api.gsheets.parsing.date.infer_column_type(pattern: str) → str

Infer the correct date-related type.

GSheets returns datetime as the type for timestamps, but also for time of day and durations. We need to parse the pattern to figure out the exact type.

This also handles a case where a timestamp (1/2/24 14:41) with a proper pattern (M/D/YY h:mm) was being returned as type timeofday.

shillelagh.adapters.api.gsheets.parsing.date.parse_date_time_pattern(value: str, pattern: str, class_: type[DateTime]) → DateTime

Parse a value using a given pattern.

See https://developers.google.com/sheets/api/guides/formats?hl=en.

shillelagh.adapters.api.gsheets.parsing.number module

Parse and format Google Sheet number formats.

https://developers.google.com/sheets/api/guides/formats#number_format_tokens

class shillelagh.adapters.api.gsheets.parsing.number.AT(token: str)

Bases: Token

Inserts the raw text for the cell, if the cell has text input.

Not compatible with any of the other special characters and won’t display for numeric values (which are displayed as general format).

format(value: int | float | str, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '@'

class shillelagh.adapters.api.gsheets.parsing.number.COLOR(token: str)

Bases: Token

Causes any value that is rendered by this sub-format to appear with the given text color.

Valid values for Color are Black, Blue, Cyan, Green, Magenta, Red, White or Yellow. Valid values for the “#” in Color# are 0 - 56 (this color palette shows a list of the colors that correspond to each number). Number format colors will override any user-entered colors on the cell, but will not override colors set by conditional formatting.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '\\[(Black|Blue|Cyan|Green|Magenta|Red|White|Yellow|Color\\d{1,2})\\]'

class shillelagh.adapters.api.gsheets.parsing.number.COMMA(token: str)

Bases: Token

Multiplier.

When appearing after the digit characters the comma scales the digits by one thousand per comma.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = ',+'

class shillelagh.adapters.api.gsheets.parsing.number.CONDITION(token: str)

Bases: Token

Replaces the default comparison section with another conditional expression.

Replaces the default positive, negative, or zero comparison section with another conditional expression. For example, [<100]”Low”;[>1000]”High”;000 will render the word “Low” for values below 100, “High” for values above 1000 and a three digit number (with leading 0s) for anything in between. Conditions can only be applied to the first two sub-formats and if a number matches more than one, it will use the first one it matches. If there is a third format, it will be used for “everything else”, otherwise if a number doesn’t match either format, it will be rendered as all “#”s filling up the cell width. The fourth format is always used for text, if it exists.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '\\[(>|>=|<|<=|=)\\d*(\\.\\d*)?\\]'

class shillelagh.adapters.api.gsheets.parsing.number.DIGITS(token: str)

Bases: Token

One or more digits in the number.

Each token renders digits differently:

• 0: if the digit is an insignificant 0, it is rendered as 0.

• #: if the digit is an insignificant 0, it is not rendered.

• ?: if the digit is an insignificant 0, it is rendered as a space.

If there’s a comma between tokens it renders the entire number with grouping separators (grouping by the thousands)

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '(0|#|\\?)+(,(0|#|\\?){3})?'

class shillelagh.adapters.api.gsheets.parsing.number.E(token: str)

Bases: Token

Scientific format.

Renders the number in scientific format, with the formatting to the left of the E used for the non-exponent portion and the formatting to the right of the E used for the exponent portion. E+ will show a + sign for positive exponents. E- will only show a sign for negative exponents. If lowercase is used, the output e is lowercased as well.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '(E|e)(-|\\+)((0|#|\\?)+)'

class shillelagh.adapters.api.gsheets.parsing.number.FRACTION(token: str)

Bases: Token

Fractional format.

If it appears between two digit characters (0, # or ?), then it treats those digit groups as a fractional format. For example, the number format 0 #/# renders the number 23.25 as 23 1/4. The denominator can also be a literal integer, in which case it will enforce that integer as the denominator. The number format 0 #/8 displays the number 23.25 as 23 2/8. The fraction part is not rendered at all if the numerator would become 0. The number 23.1 with the number format 0 #/3 renders as just 23 (because the 0.1 rounded to 0/3). / is not compatible with scientific format or a format with a decimal point in it.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '(?:((?:0|#|\\?)+))/(?:((?:0|#|\\?)+)|(\\d+))'

class shillelagh.adapters.api.gsheets.parsing.number.PERCENT(token: str)

Bases: Token

Literal percent sign.

Appears as a literal but also causes existing numbers to be multiplied by 100 before being rendered, in order to make percentages more readable.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '%'

class shillelagh.adapters.api.gsheets.parsing.number.PERIOD(token: str)

Bases: Token

The decimal point in the number.

The first period represents the decimal point in the number. Subsequent periods are rendered as literals. If you include a decimal point in the format, it will always be rendered, even for whole numbers.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '\\.'

class shillelagh.adapters.api.gsheets.parsing.number.STAR(token: str)

Bases: Token

This is included for compatibility with Excel number formats. It is currently ignored.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '\\*'

class shillelagh.adapters.api.gsheets.parsing.number.UNDERSCORE(token: str)

Bases: Token

Skips the next character and renders a space.

This is used to line up number formats where the negative value is surrounded by parenthesis.

format(value: int | float, tokens: list[Token]) → str

Format the value using the pattern.

parse(value: str, tokens: list[Token]) → tuple[dict[str, Any], str]

Parse the value given a pattern.

Returns the consumed parameter as an argument, and the rest of the value.

regex: str = '_.'

shillelagh.adapters.api.gsheets.parsing.number.adjust_value(value: int | float, tokens: list[Token]) → int | float

Adjust value applying percent, scientific notation, and comma multiplier.

shillelagh.adapters.api.gsheets.parsing.number.condition_matches(value: int | float, format_: str) → bool

Return true if the value matches the condition in the pattern.

shillelagh.adapters.api.gsheets.parsing.number.fix_periods(tokens: Iterator[Token]) → Iterator[Token]

Convert periods into literals after the first one.

shillelagh.adapters.api.gsheets.parsing.number.format_number_pattern(value: int | float | str, pattern: str) → str

Format a number to a given pattern.

shillelagh.adapters.api.gsheets.parsing.number.get_fraction(number: str) → float

Return the fraction associated with a fractional part.

>>> get_fraction("9")
0.9
>>> get_fraction("123")
0.123
>>> get_fraction("1")
0.1
>>> get_fraction("001")
0.001

shillelagh.adapters.api.gsheets.parsing.number.has_condition(pattern: str) → bool

Return true if the pattern has condition instructions.

shillelagh.adapters.api.gsheets.parsing.number.is_fractional(token: Token, tokens: list[Token]) → bool

Return true if the token is after the period.

shillelagh.adapters.api.gsheets.parsing.number.parse_number_format(value: str, format_: str) → float

Parse a value using a given format pattern.

shillelagh.adapters.api.gsheets.parsing.number.parse_number_pattern(value: str, pattern: str) → float

Parse a value using a given pattern.

Module contents