pregex.meta.essentials

This module contains various classes that can be used to match all sorts of commonly-search-for patterns.

Classes & methods

Below are listed all classes within pregex.meta.essentials along with any possible methods they may possess.

class pregex.meta.essentials.Date(formats: Optional[Union[str, list[str]]] = None, is_extensible: bool = False)[source]

Matches any date within a range of predefined formats.

Parameters

  • formats (str | list[str]) –

    Either a string or a list of strings through which it is determined what are the exact date formats that are to be considered possible matches. A valid date format can be either one of:

    • D<sep>M<sep>Y

    • M<sep>D<sep>Y

    • Y<sep>M<sep>D

    where:

    • <sep>: Either / or -

    • D: Either one of the following:

      • d: one-digit day of the month for days below 10, e.g. 2

      • dd: two-digit day of the month, e.g. 02

    • M: Either one of the following:

      • m: one-digit month for months below 10, e.g. 3

      • mm: two-digit month, e.g. 03

    • Y: Either one of the following:

      • yy: two-digit year, e.g. 21

      • yyyy: four-digit year, e.g. 2021

    For example, dd/mm/yyyy is considered a valid date format whereas mm/yyyy/dd is not. Lastly, If None is provided in place of this list, then all possible formats are considered. Defaults to None.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

InvalidArgumentValueException – At least one of the provided arguments is not a valid date format.

class pregex.meta.essentials.Decimal(start: int = 0, end: int = 2147483647, min_decimal: int = 1, max_decimal: Optional[int] = None, include_sign: bool = False, is_extensible: bool = False)[source]

Matches any decimal number within a specified range.

Parameters

  • start (int) – The starting value of the integer part range. Defaults to 0.

  • end (int) – The ending value of the integer part range. Defaults to 2147483647.

  • min_decimal (int) – The minimum number of digits within the decimal part. Defaults to 1.

  • max_decimal (int) – The maximum number of digits within the decimal part. Defaults to None.

  • include_sign (bool) – Determines whether to include any existing signs into the match. Defaults to False.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either one of parameters start, end, min_decimal or max_decimal is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than 0.

    • Parameter start has a greater value than that of parameter end.

    • Parameter min_decimal has a value of less than 1.

    • Parameter min_decimal has a greater value than that of parameter max_decimal.

Note

  • Be aware that parameter include_sign might not only play a role in deciding the content of the matches, but their number as well. For example, setting include_sign to False will result in Integer matching both 1.1 and 2.2 in 1.1+2.2, whereas setting it to True results in just matching 1.1. That is, because in case include_sign is True, +2.2 is considered a decimal number as a whole, and as such, it cannot match when another digit, namely 1, directly precedes it.

  • Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.Email(capture_local_part: bool = False, capture_domain: bool = False, is_extensible: bool = False)[source]

Matches any email address.

Parameters

  • capture_local_part (bool) – If set to True, then the local-part of each email address match is separately captured as well. Defaults to False.

  • capture_domain (bool) – If set to True, then the domain name of each email address match is separately captured as well. Defaults to False.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Note

Not guaranteed to match every possible email address.

class pregex.meta.essentials.HttpUrl(capture_domain: bool = False, is_extensible: bool = False)[source]

Matches any HTTP URL.

Parameters

  • capture_domain (bool) – If set to True, then the domain name of each URL match is separately captured as well. Defaults to False.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Note

Not guaranteed to match every possible HTTP URL.

class pregex.meta.essentials.IPv4(is_extensible: bool = False)[source]

Matches any IPv4 Address.

Parameters

is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

class pregex.meta.essentials.IPv6(is_extensible: bool = False)[source]

Matches any IPv6 Address.

Parameters

is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

class pregex.meta.essentials.Integer(start: int = 0, end: int = 2147483647, include_sign: bool = False, is_extensible: bool = False)[source]

Matches any integer within a specified range.

Parameters

  • start (int) – The starting value of the range. Defaults to 0.

  • end (int) – The ending value of the range. Defaults to 2147483647.

  • include_sign (bool) – Determines whether to include any existing signs into the match, or just ignore them. Defaults to False.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either parameter start or parameter end is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than zero.

    • Parameter start has a greater value than that of parameter end.

Note

  • Be aware that parameter include_sign might not only play a role in deciding the content of the matches, but their number as well. For example, setting include_sign to False will result in Integer matching both 1 and 2 in 1+2, whereas setting it to True results in just matching 1. That is, because in case include_sign is True, +2 is considered an integer as a whole, and as such, it cannot match when another digit, namely 1, directly precedes it.

  • Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.NegativeDecimal(start: int = 0, end: int = 2147483647, min_decimal: int = 1, max_decimal: Optional[int] = None, is_extensible: bool = False)[source]

Matches any negative decimal number within a specified range.

Parameters

  • start (int) – The starting value of the integer part range. Defaults to 0.

  • end (int) – The ending value of the integer part range. Defaults to 2147483647.

  • min_decimal (int) – The minimum number of digits within the decimal part. Defaults to 1.

  • max_decimal (int) – The maximum number of digits within the decimal part. Defaults to None.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either one of parameters start, end, min_decimal or max_decimal is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than 0.

    • Parameter start has a greater value than that of parameter end.

    • Parameter min_decimal has a value of less than 1.

    • Parameter min_decimal has a greater value than that of parameter max_decimal.

Note

Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.NegativeInteger(start: int = 0, end: int = 2147483647, is_extensible: bool = False)[source]

Matches any strictly negative integer within a specified range.

Parameters

  • start (int) – The starting value of the range. Defaults to 0.

  • end (int) – The ending value of the range. Defaults to 2147483647.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either parameter start or parameter end is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than zero.

    • Parameter start has a greater value than that of parameter end.

Note

Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.NonWhitespace(is_optional: bool = False)[source]

Matches any string of text of arbitrary length that does not contain any whitespace characters.

Parameters

is_optional (bool) – Determines whether this pattern is optional or not. Defaults to False.

class pregex.meta.essentials.Numeral(base: int = 10, n_min: int = 1, n_max: Optional[int] = None, is_extensible: bool = False)[source]

Matches any numeral.

Parameters

  • base (int) – An integer through which the numeral system is specified. Defaults to 10.

  • n_min (int) – The minimum amount of digits the number may contain. Defaults to 1.

  • n_max (int) – The maximum amount of digits the number may contain. Defaults to None.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException –

    • Parameter base or n_min is not an integer.

    • Parameter n_max is neither an integer nor None.

  • InvalidArgumentValueException –

    • Parameter base has a value of less than 2 or greater than 16.

    • Either parameter n_min or n_max has a value of less than zero.

    • Parameter n_min has a greater value than that of parameter n_max.

Note

Setting n_max equal to None indicates that there is no upper limit to the number of digits.

class pregex.meta.essentials.PositiveDecimal(start: int = 0, end: int = 2147483647, min_decimal: int = 1, max_decimal: Optional[int] = None, is_extensible: bool = False)[source]

Matches any strictly positive decimal number within a specified range.

Parameters

  • start (int) – The starting value of the integer part range. Defaults to 0.

  • end (int) – The ending value of the integer part range. Defaults to 2147483647.

  • min_decimal (int) – The minimum number of digits within the decimal part. Defaults to 1.

  • max_decimal (int) – The maximum number of digits within the decimal part. Defaults to None.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either one of parameters start, end, min_decimal or max_decimal is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than 0.

    • Parameter start has a greater value than that of parameter end.

    • Parameter min_decimal has a value of less than 1.

    • Parameter min_decimal has a greater value than that of parameter max_decimal.

Note

Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.PositiveInteger(start: int = 0, end: int = 2147483647, is_extensible: bool = False)[source]

Matches any strictly positive integer within a specified range.

Parameters

  • start (int) – The starting value of the range. Defaults to 0.

  • end (int) – The ending value of the range. Defaults to 2147483647.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either parameter start or parameter end is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than zero.

    • Parameter start has a greater value than that of parameter end.

Note

Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.Text(is_optional: bool = False)[source]

Matches any string of text of arbitrary length.

Parameters

is_optional (bool) – Determines whether this pattern is optional or not. Defaults to False.

class pregex.meta.essentials.UnsignedDecimal(start: int = 0, end: int = 2147483647, min_decimal: int = 1, max_decimal: Optional[int] = None, is_extensible: bool = False)[source]

Matches any decimal number within a specified range, provided that it is not preceded by a sign.

Parameters

  • start (int) – The starting value of the integer part range. Defaults to 0.

  • end (int) – The ending value of the integer part range. Defaults to 2147483647.

  • min_decimal (int) – The minimum number of decimal places. Defaults to 1.

  • max_decimal (int) – The maximum number of decimal places. Defaults to None.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either one of parameters start, end, min_decimal or max_decimal is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than 0.

    • Parameter start has a greater value than that of parameter end.

    • Parameter min_decimal has a value of less than 1.

    • Parameter min_decimal has a greater value than that of parameter max_decimal.

Note

Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.UnsignedInteger(start: int = 0, end: int = 2147483647, is_extensible: bool = False)[source]

Matches any integer within a specified range, provided that it is not preceded by a sign.

Parameters

  • start (int) – The starting value of the range. Defaults to 0.

  • end (int) – The ending value of the range. Defaults to 2147483647.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException – Either parameter start or parameter end is not an integer.

  • InvalidArgumentValueException –

    • Parameter start has a value of less than zero.

    • Parameter start has a greater value than that of parameter end.

Note

Even by setting parameter is_extensible to True, there still persists an assertion that is essential to the pattern, which dictates that this pattern must not be preceded by any numeric characters. For that reason, one should avoid concatenating an instance of this class to the right of a pattern that ends in such a character.

class pregex.meta.essentials.Whitespace(is_optional: bool = False)[source]

Matches any string of whitespace characters of arbitrary length.

Parameters

is_optional (bool) – Determines whether this pattern is optional or not. Defaults to False.

class pregex.meta.essentials.Word(min_chars: int = 1, max_chars: Optional[int] = None, is_global: bool = True, is_extensible: bool = False)[source]

Matches any word.

Parameters

  • min_chars (int) – The minimum amount of characters a word must have in order to be considered a match. Defaults to 1.

  • max_chars (int) – The maximum amount of characters a word must have in order to be considered a match. If set to “None”, then it is considered that there is no upper limit to the amount of characters a word can have. Defaults to None.

  • is_global – Determines whether to include foreign characters. Defaults to True.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

  • InvalidArgumentTypeException –

    • Parameter min_chars is not an integer.

    • Parameter max_chars is neither an integer nor None.

  • InvalidArgumentValueException –

    • Either parameter min_chars or max_chars has a value of less than 1.

    • Parameter min_chars has a greater value than that of parameter max_chars.

class pregex.meta.essentials.WordContains(infix: Union[str, list[str]], is_global: bool = True, is_extensible: bool = False)[source]

Matches any word that contains either one of the provided strings.

Parameters

  • infix (str | list[str]) – Either a string or a list of strings at least one of which a word must contain in order to be considered a match.

  • is_global – Determines whether to include foreign characters. Defaults to True.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

InvalidArgumentTypeException – At least one of the provided infixes is not a string.

class pregex.meta.essentials.WordEndsWith(suffix: Union[str, list[str]], is_global: bool = True, is_extensible: bool = False)[source]

Matches any word that ends with either one of the provided strings.

Parameters

  • suffix (str | list[str]) – Either a string or a list of strings with any of which a word must end in order to be considered a match.

  • is_global – Determines whether to include foreign characters. Defaults to True.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

InvalidArgumentTypeException – At least one of the provided suffixes is not a string.

class pregex.meta.essentials.WordStartsWith(prefix: Union[str, list[str]], is_global: bool = True, is_extensible: bool = False)[source]

Matches any word that starts with either one of the provided strings.

Parameters

  • prefix (str | list[str]) – Either a string or a list of strings with any of which a word must start in order to be considered a match.

  • is_global – Determines whether to include foreign characters. Defaults to True.

  • is_extensible (bool) – If True, then no additional assertions are imposed upon the underlying pattern, other than any necessary ones, which in turn prevents certain complications from arising whenever it serves as a building block to a larger pattern. As a general rule of thumb, set this parameter to True if you wish to extend the resulting instance’s underlying pattern, or to False if you are only using it for matching purposes. Defaults to False.

Raises

InvalidArgumentTypeException – At least one of the provided prefixes is not a string.