XulbuX

Appearance

Regex Module ​

Provides utilities for dynamic regex pattern generation and compilation.
Includes composable pattern builders for color strings, balanced brackets, quotes, and function calls, alongside LazyRegex for deferred compilation.

quotes() ​

python
def quotes() -> str

Matches pairs of quotes. (strings)

Will create two named groups:

  • quote – The quote type (single or double).
  • string – Everything inside the found quote pair.

Attention:
Requires non-standard library regex, not standard library re!

Example Usage ​

python
import xulbux as xx
import regex

pattern = xx.regex.quotes()
text = "Some text with 'single quotes' and \"double quotes\"."
matches = regex.findall(pattern, text)
Matches
python
[
    ("'", "single quotes"),
    ('"', "double quotes")
]

brackets() ​

python
def brackets(
    bracket1: str = "(",
    bracket2: str = ")",
    /,
    *,
    is_group: bool = False,
    strip_spaces: bool = False,
    ignore_in_strings: bool = True,
) -> str

Matches everything inside pairs of brackets, including other nested brackets.

  • bracket1 – The opening bracket (e.g., (, {, [, …).
  • bracket2 – The closing bracket (e.g., ), }, ], …).
  • is_group – Whether to create a capturing group for the content inside the brackets.
  • strip_spaces – Whether to strip spaces from the bracket content or not.
  • ignore_in_strings – Whether to ignore closing brackets that are inside strings/quotes (e.g., '…)…' or "…)…").

Attention:
Requires non-standard library regex, not standard library re!

Example Usages ​

Default brackets:

python
import xulbux as xx
import regex

pattern = xx.regex.brackets()
text = "This (is a test) with (nested (brackets))."
# Use `overlapped=True` to extract nested overlapping brackets:
matches = regex.findall(pattern, text, overlapped=True)
Matches
python
[
    "(is a test)",
    "(nested (brackets))",
    "(brackets)"
]

Custom brackets:

python
import xulbux as xx
import regex

pattern = xx.regex.brackets("[", "]", is_group=True)
text = "List of items: [item1, item2 [nested item]]"
matches = regex.findall(pattern, text, overlapped=True)
Matches
python
[
    "item1, item2 [nested item]",
    "nested item"
]

Without ignoring strings:

python
import xulbux as xx
import regex

pattern = xx.regex.brackets(ignore_in_strings=False)
text = 'func(param = "f(x)")'
matches = regex.findall(pattern, text, overlapped=True)
Matches
python
[
    "(param = "f(x)")",
    "(x)"
]

Without stripping spaces:

python
import xulbux as xx
import regex

pattern = xx.regex.brackets(strip_spaces=False)
text = " ( spaced content ) and (regular content) "
matches = regex.findall(pattern, text)
Matches
python
[
    "( spaced content )",
    "(regular content)"
]

outside_strings() ​

python
def outside_strings(pattern: str = r".*", /) -> str

Matches the pattern only when it is not found inside a string ('…' or "…").

  • pattern – The pattern to match outside of strings/quotes.

Attention:
Requires non-standard library regex, not standard library re!

Example Usage ​

python
import xulbux as xx
import regex

pattern = xx.regex.outside_strings(r"\d+")
text = 'Number 123 and "string 456" and 789'
matches = regex.findall(pattern, text)
Matches
python
[
    "123",
    "789"
]

all_except() ​

python
def all_except(disallowed_pattern: str, /, ignore_pattern: str = "", *, is_group: bool = False) -> str

Matches everything up to the disallowed_pattern, unless the disallowed_pattern is found inside a string/quotes ('…' or "…").

  • disallowed_pattern – The pattern that is not allowed to be matched.
  • ignore_pattern – A pattern that, if found, will make the regex ignore the disallowed_pattern (even if it contains the disallowed_pattern inside it):
    For example if disallowed_pattern is > and ignore_pattern is ->, the ->-arrows will be allowed, even though they have > in them.
  • is_group – Whether to create a capturing group for the matched content.

Attention:
Requires non-standard library regex, not standard library re!

Example Usages ​

Single exclusion:

python
import xulbux as xx
import regex

pattern = xx.regex.all_except(">")
text = "Hello > World"
matches = regex.match(pattern, text)
Matches
python
[
    "Hello "
]

Multiple exclusions:

python
import xulbux as xx
import regex

pattern = xx.regex.all_except(">", "->")
text = "Arrow -> and greater > sign"
match = regex.match(pattern, text)
Matches
python
[
    "Arrow -> and greater "
]

func_call() ​

python
def func_call(func_name: str | None = None, /) -> str

Match a function call in code, including its arguments.

  • func_name – The name of the function to match. If None, it will match any function call.

Will create two groups:

  1. The function name (or any function name if func_name is None).
  2. Everything inside the function call's parentheses (the arguments).

Attention:
Requires non-standard library regex, not standard library re!

Example Usages ​

Any function:

python
import xulbux as xx
import regex

pattern = xx.regex.func_call()
text = "Call print('hello') and input('prompt')"
matches = regex.findall(pattern, text)
Matches
python
[
    ("print", "'hello'"),
    ("input", "'prompt'")
]

Specific function:

python
import xulbux as xx
import regex

pattern = xx.regex.func_call("input")
text = "Call print('hello') and input('prompt') and print('world')"
matches = regex.findall(pattern, text)
Matches
python
[
    ("input", "'prompt'")
]

rgba_str() ​

python
def rgba_str(fix_sep: str | None = ",", *, allow_alpha: bool = True) -> str

Matches an RGBA color inside a string.

  • fix_sep – The fixed separator between the RGBA values (e.g., ,, ; …):
    If set to nothing or None, any char that is not a letter or number can be used to separate the RGBA values, including just a space.
  • allow_alpha – Whether to include the alpha channel in the match.

Valid Formats ​

With fix_sep = ',', the RGBA color can be in the formats:

  • rgba(red, green, blue)
  • rgba(red, green, blue, alpha) (if allow_alpha=True)
  • (red, green, blue)
  • (red, green, blue, alpha) (if allow_alpha=True)
  • red, green, blue
  • red, green, blue, alpha (if allow_alpha=True)

Valid Ranges ​

  • red 0-255 (int: red)
  • green 0-255 (int: green)
  • blue 0-255 (int: blue)
  • alpha 0.0-1.0 (float: opacity)

Example Usages ​

Default pattern:

python
import xulbux as xx
import re

pattern = xx.regex.rgba_str()
text = "Color rgba(255, 128, 0) and (100, 200, 50, 0.5)"
matches = re.findall(pattern, text)
Matches
python
[
    ("255", "128", "0", ""),
    ("100", "200", "50", "0.5")
]

No alpha allowed:

python
import xulbux as xx
import re

pattern = xx.regex.rgba_str(allow_alpha=False)
text = "Color with rgb(255, 128, 0, 0.5) and without opacity rgb(255, 0, 0)"
matches = re.findall(pattern, text)
Matches
python
[
    ("255", "128", "0"),
    ("255", "0", "0")
]

Custom separator:

python
import xulbux as xx
import re

pattern = xx.regex.rgba_str(fix_sep="|")
text = "Color 255|128|0"
matches = re.findall(pattern, text)
Matches
python
[
    ("255", "128", "0", "")
]

hsla_str() ​

python
def hsla_str(fix_sep: str | None = ",", *, allow_alpha: bool = True) -> str

Matches a HSLA color inside a string.

  • fix_sep – The fixed separator between the HSLA values (e.g., ,, ; …):
    If set to nothing or None, any char that is not a letter or number can be used to separate the HSLA values, including just a space.
  • allow_alpha – Whether to include the alpha channel in the match.

Valid Formats ​

With fix_sep = ',', the HSLA color can be in the formats:

  • hsla(hue, sat, light)
  • hsla(hue, sat, light, alpha) (if allow_alpha=True)
  • (hue, sat, light)
  • (hue, sat, light, alpha) (if allow_alpha=True)
  • hue, sat, light
  • hue, sat, light, alpha (if allow_alpha=True)

Valid Ranges ​

  • hue 0-360 (int: hue)
  • sat 0-100 (int: saturation)
  • light 0-100 (int: lightness)
  • alpha 0.0-1.0 (float: opacity)

Example Usages ​

Default pattern:

python
import xulbux as xx
import re

pattern = xx.regex.hsla_str()
text = "Color hsla(240°, 100%, 50%) and (120, 80, 60, 0.8)"
matches = re.findall(pattern, text)
Matches
python
[
    ("240", "100", "50", ""),
    ("120", "80", "60", "0.8")
]

No alpha allowed:

python
import xulbux as xx
import re

pattern = xx.regex.hsla_str(allow_alpha=False)
text = "Color with hsl(240, 100%, 50%, 0.5) and without opacity hsl(360, 100%, 50%)"
matches = re.findall(pattern, text)
Matches
python
[
    ("240", "100", "50"),
    ("360", "100", "50")
]

Custom separator:

python
import xulbux as xx
import re

pattern = xx.regex.hsla_str(fix_sep=" ")
text = "Color 240 100% 50%"
matches = re.findall(pattern, text)
Matches
python
[
    ("240", "100", "50", "")
]

hexa_str() ​

python
def hexa_str(*, allow_alpha: bool = True) -> str

Matches a hex color inside a string.

  • allow_alpha – Whether to include the alpha channel in the match.

Valid Formats ​

The hex color can be in the formats (prefix #, 0x or no prefix):

  • RGB
  • RGBA (if allow_alpha=True)
  • RRGGBB
  • RRGGBBAA (if allow_alpha=True)

Valid Ranges ​

Every channel from 0-9 and A-F (case insensitive)

Example Usages ​

Default pattern:

python
import xulbux as xx
import re

pattern = xx.regex.hexa_str()
text = "Colors: #FF0000, 0xABCDEF, F00 and FF000080"
matches = re.findall(pattern, text)
Matches
python
[
    "FF0000",
    "ABCDEF",
    "F00",
    "FF0000FF"
]

No alpha allowed:

python
import xulbux as xx
import re

pattern = xx.regex.hexa_str(allow_alpha=False)
text = "Without #FF0000 #F00 and with opacity #FF000080 #F008"
matches = re.findall(pattern, text)
Matches
python
[
    "FF0000",
    "F00",
    "FF0000",
    "F00"
]

LazyRegex ​

python
class LazyRegex(self, **patterns: str)

A class that lazily compiles and caches regex patterns on first access.

  • **patterns – Keyword arguments where the key is the name of the pattern and the value is the regex pattern string to compile.

Attention:
Requires non-standard library regex, not standard library re!

Example Usage ​

python
PATTERNS = LazyRegex(
    email=r"(?i)[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}",
    phone=r"\+?\d{1,3}[-.\s]?\(?\d{1,4}\)?[-.\s]?\d{1,4}[-.\s]?\d{1,9}",
)

# Accessing `email` compiles and caches it for future use:
match = PATTERNS.email.match("test@example.com")
# Accessing `phone` compiles and caches it for future use:
match = PATTERNS.phone.fullmatch("+1 (555) 123-4567")

Released under the MIT License.

✨ From XulbuX ✨