string

String utilities.

deltona.string.add_unidecode_custom_replacement(find: str, replace: str) → None

Add a custom replacement to the Unidecode cache.

Parameters:
find : str

Single character to find.

replace : str

Replacement string.

Raises:

ValueError – If the Unidecode cache section is too short for the codepoint.

deltona.string.cssq(selector: str, file: TextIO | str, limit: int = 0, *, debug_selector: bool = False, strip: bool = True, text: False = False) → Iterator[Tag]
deltona.string.cssq(selector: str, file: TextIO | str, limit: int = 0, *, debug_selector: bool = False, strip: bool = True, text: True = True) → Iterator[str]
deltona.string.cssq(selector: str, file: TextIO | str, limit: int = 0, *, debug_selector: bool = False, strip: bool = True, text: bool = False) → Iterator[str] | Iterator[Tag]

Filter HTML with CSS.

If passing limit=1, consider using cssq_one() instead.

Parameters:
selector : str

CSS selector.

file : TextIO | str

File-like object or string containing HTML.

limit : int

Limit number of results. 0 means no limit.

debug_selector : bool

Enable SoupSieve debug logging.

strip : bool

Strip whitespace from text content.

text : bool

Output content within the HTML tags only.

Yields:

Iterator[Tag] | Iterator[str] – The filtered items.

deltona.string.cssq_one(selector: str, file: TextIO | str, *, debug_selector: bool = False, strip: bool = True, text: False = False) → Tag | None
deltona.string.cssq_one(selector: str, file: TextIO | str, *, debug_selector: bool = False, strip: bool = True, text: True = True) → str | None
deltona.string.cssq_one(selector: str, file: TextIO | str, *, debug_selector: bool = False, strip: bool = True, text: bool = False) → str | Tag | None

Select a single item from HTML with CSS.

Parameters:
selector : str

CSS selector.

file : TextIO | str

File-like object or string containing HTML.

debug_selector : bool

Enable SoupSieve debug logging.

strip : bool

Strip whitespace from text content.

text : bool

Output content within the HTML tags only.

Returns:

The selected item, or None if no match was found.

Return type:

str | Tag | None

deltona.string.fix_apostrophes(word: str) → str

Title-case a word while preserving apostrophe contractions.

Parameters:
word : str

Word to fix.

Returns:

The word with correct casing, or unchanged if it contains no apostrophe.

Return type:

str

deltona.string.fullwidth_to_narrow(s: str) → str

Convert fullwidth characters in s to narrow or halfwidth.

Unlike Unidecode this will convert '￥' to its halfwidth form '¥'.

Parameters:
s : str

String containing fullwidth characters.

Returns:

The string with fullwidth characters replaced by their narrow equivalents.

Return type:

str

deltona.string.hexstr2bytes(s: str) → bytes

Convert a hex string such as "01020a" to its bytes form (0x1 0x2 0x10)).

Parameters:
s : str

Hex string to convert.

Returns:

The bytes representation.

Return type:

bytes

deltona.string.hexstr2bytes_generator(s: str) → Iterator[int]

Convert a hex string such as "01020a" to integers.

Parameters:
s : str

Hex string to convert.

Yields:

int – The integers in the hex string.

Raises:

ValueError – If the string is not a valid hex string.

deltona.string.is_ascii(s: collections.abc.Sequence[str]) → bool

Check if a string consists of only ASCII characters.

Parameters:
s : Sequence[str]

String to check.

Returns:

True if all characters are ASCII.

Return type:

bool

deltona.string.is_roman_numeral(string: str) → bool

Check if a string is a valid Roman numeral.

Parameters:
string : str

String to check.

Returns:

True if the string is a valid Roman numeral.

Return type:

bool

deltona.string.is_url(filename: str | PathLike[str]) → bool

Detect if filename is a URL.

This is the same method mpv uses to decide this.

Parameters:
filename : StrPath

Path or string to check.

Returns:

True if filename looks like a URL.

Return type:

bool

deltona.string.rev_sentences(sentences: collections.abc.Sequence[str]) → Iterator[str]

Reverse the word order of each sentence.

Parameters:
sentences : Sequence[str]

Sentences to reverse.

Yields:

str – Each sentence with its words in reversed order.

deltona.string.sanitize(s: str, *, restricted: bool = True) → str

Transform a string to a ‘sanitised’ form.

Parameters:
s : str

String to transform.

restricted : bool

If True, use a restricted form. This is suitable for filenames on Windows.

Returns:

Returns a transformed string, which will be at minimum '_'.

Return type:

str

deltona.string.slugify(s: str, *, no_lower: bool = False) → str

Generate a slug string.

Parameters:
s : str

String to slugify.

no_lower : bool

If True, do not convert to lowercase.

Returns:

The slugified string.

Return type:

str

deltona.string.strip_ansi(o: str) → str

Remove ANSI escape sequences from o.

As defined by ECMA-048 in http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-048.

Taken from https://github.com/ewen-lbh/python-strip-ansi/ due to installation issues with Poetry.

Parameters:
o : str

String to strip ANSI escape sequences from.

Returns:

The string without ANSI escape sequences.

Return type:

str

deltona.string.strip_ansi_if_no_colors(s: str) → str

Strip ANSI colour-codes if the NO_COLOR environment variable is set.

See https://no-color.org/.

Parameters:
s : str

String to conditionally strip.

Returns:

The string without ANSI escape sequences if NO_COLOR is set, otherwise unchanged.

Return type:

str

deltona.string.underscorize(s: str) → str

Replace all space-type characters with _.

Parameters:
s : str

String to transform.

Returns:

The transformed string.

Return type:

str

deltona.string.unix_path_to_wine(path: str | PathLike[str]) → str

Convert a UNIX path to an absolute Wine path.

If the path does not exist, the output will be the current path and the path passed in combined.

The output path will begin at letter Z:. Other drive letters are not supported.

Parameters:
path : StrPath

Path to convert.

Returns:

Window-style Wine absolute path.

Return type:

str