pregex.core.groups

This module contains all necessary classes that are used to construct both capturing and non-capturing groups, as well as any other classes which relate to concepts that are based on groups, such as backreferences and conditionals.

Pattern grouping

In general, one should not have to concern themselves with pattern grouping, as patterns are automatically wrapped within non-capturing groups whenever this is deemed necessary. Consider for instance the following code snippet:

from pregex.core.quantifiers import Optional

Optional('a').print_pattern() # This prints "a?"
Optional('aa').print_pattern() # This prints "(?:aa)?"

In the first case, quantifier Optional is applied to the pattern directly, whereas in the second case the pattern is placed into a non-capturing group so that “aa” is quantified as a whole. Be that as it may, there exists a separate class, namely Group, through which one is able to explicitly wrap any pattern within a non-capturing group if they wish to do so:

from pregex.core.groups import Group
from pregex.core.quantifiers import Optional

pre = Group(Optional('a'))

pre.print_pattern() # This prints "(?:a)?"

This class can also be used so as to apply various RegEx flags, also known as modifiers, to a pattern. As of yet, the only flag that is supported is the case-insensitive flag i:

from pregex.core.groups import Group

pre = Group('pregex', is_case_insensitive=True)

# This statement is "True"
pre.is_exact_match('PRegEx')

Capturing patterns

You’ll find however that Capture is probably the most important class of this module, as it is used to create a capturing group out of a pattern, so that said pattern is captured separately whenever a match occurs.

from pregex.core.groups import Capture
from pregex.core.classes import AnyLetter

pre = AnyLetter() + Capture(2 * AnyLetter())

text = "abc def"
print(pre.get_matches(text)) # This prints "['abc', 'def']"
print(pre.get_captures(text)) # This prints "[('bc'), ('ef')]"

As you can see, capturing is a very useful tool for whenever you are interested in isolating some specific part of a pattern.

Classes & methods

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

class pregex.core.groups.Backreference(ref: Union[int, str])[source]

Creates a backreference to some previously declared capturing group.

Parameters

ref (int | str) – A reference to some previously declared capturing group. This parameter can either be an integer, in which case the capturing group is referenced by order, or a string, in which case the capturing group is referenced by name.

Raises

InvalidArgumentTypeException – Parameter ref is neither an integer nor a string.
InvalidArgumentValueException – Parameter ref is an integer but has a value of either less than 1 or greater than 10.
InvalidCapturingGroupNameException – Parameter ref is a string but not a valid capturing group name. Such name must contain word characters only and start with a non-digit character.

class pregex.core.groups.Capture(pre: Union[Pregex, str], name: Optional[str] = None)[source]

Creates a capturing group out of the provided pattern.

Parameters

pre (Pregex | str) – The pattern out of which the capturing group is created.
name (str) – The name that is assigned to the captured group for backreference purposes. A value of None indicates that no name is to be assigned to the group. Defaults to None.

Raises

InvalidArgumentTypeException –
- Parameter pre is neither a Pregex instance nor a string.
- Parameter name is neither a string nor None.
InvalidCapturingGroupNameException – Parameter name is not a valid capturing group name. Such name must contain word characters only and start with a non-digit character.

Note

Creating a capturing group out of a capturing group does nothing to it.
Creating a capturing group out of a non-capturing group converts it into a capturing group, except if any flags have been applied to it, in which case, the non-capturing group is wrapped within a capturing group as a whole.
Creating a named capturing group out of an unnamed capturing group, assigns a name to it.
Creating a named capturing group out of a named capturing group, changes the group’s name.

class pregex.core.groups.Conditional(name: str, pre1: Union[Pregex, str], pre2: Optional[Union[Pregex, str]] = None)[source]

Given the name of a capturing group, matches pre1 only if said capturing group has been previously matched. Furthermore, if a second pattern pre2 is provided, then this pattern is matched in case the referenced capturing group was not, though one should be aware that for this to be possible, the referenced capturing group must be optional.

Parameters

name (str) – The name of the referenced capturing group.
pre1 (Pregex | str) – The pattern that is to be matched in case condition is true.
pre2 (Pregex | str) – The pattern that is to be matched in case condition is false. Defaults to None.

Raises

InvalidArgumentTypeException –
- Parameter name is not a string.
- Parameter pre1 is neither a Pregex instance nor a string.
- Parameter pre2 is neither a Pregex instance nor a string nor None.
InvalidCapturingGroupNameException – Parameter name is not a valid capturing group name. Such name must contain word characters only and start with a non-digit character.

class pregex.core.groups.Group(pre: Union[Pregex, str], is_case_insensitive: bool = False)[source]

Creates a non-capturing group out of the provided pattern.

Parameters

pre (Pregex | str) – The pattern that is to be wrapped within a non-capturing group.
is_case_insensitive (bool) – If True, then the “case insensitive” flag is applied to the group so that the pattern within it ignores case when it comes to matching. Defaults to False.

Raises

InvalidArgumentTypeException – Parameter pre is neither a Pregex instance nor a string.

Note

Creating a non-capturing group out of a non-capturing group does nothing, except for remove its flags if it has any.
Creating a non-capturing group out of a capturing group converts it into a non-capturing group.