py-text-toolkit 0.1.0__py3-none-any.whl

py_text_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: py-text-toolkit
+Version: 0.1.0
+Summary: A comprehensive string utility library for Python.
+Author-email: Dawood Afzal <dawoodafzal.62138@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: emoji>=2.0.0
+Dynamic: license-file
+
+# py-text-toolkit
+
+A lightweight, dependency-minimal Python library for everyday string operations — cleaning, validation, analysis, case conversion, and generation.
+
+---
+
+## Installation
+
+```bash
+pip install py-text-toolkit
+```
+
+> **Requires:** Python 3.8+  
+> **Optional dependency:** `emoji` (required only for `cleaning.remove_emojis`)
+
+---
+
+## Modules at a Glance
+
+| Module | What it does |
+|---|---|
+| `py-text-toolkit.cleaning` | Strip, replace, and normalize raw text |
+| `py-text-toolkit.validation` | Validate emails, URLs, passwords, and character sets |
+| `py-text-toolkit.analysis` | Count, compare, and measure strings |
+| `py-text-toolkit.format_cases` | Convert between naming conventions and formatting styles |
+| `py-text-toolkit.generation` | Generate slugs, masks, ciphers, and reversed strings |
+
+---
+
+## Quick Start
+
+```python
+from py-text-toolkit.cleaning import remove_html_tags, remove_urls
+from py-text-toolkit.validation import is_email, is_strong_password
+from py-text-toolkit.analysis import word_count, is_palindrome
+from py-text-toolkit.format_cases import to_snake_case, to_camel_case
+from py-text-toolkit.generation import generate_slug, mask_range
+
+# Clean
+remove_html_tags("<p>Hello <b>world</b></p>")   # "Hello world"
+remove_urls("Visit https://example.com today")  # "Visit today"
+
+# Validate
+is_email("user@example.com")        # True
+is_strong_password("Passw0rd!")     # True
+
+# Analyse
+word_count("Hello, world!")         # 2
+is_palindrome("A man a plan a canal Panama")  # True
+
+# Convert case
+to_snake_case("camelCaseText")      # "camel_case_text"
+to_camel_case("hello_world")        # "helloWorld"
+
+# Generate
+generate_slug("Hello World!")       # "hello-world"
+mask_range("1234-5678-9012", 5, 9, "*")  # "1234-****-9012"
+```
+
+---
+
+## Module Reference
+
+### `py-text-toolkit.cleaning`
+
+Functions for sanitising and normalising raw text.
+
+| Function | Signature | Description |
+|---|---|---|
+| `normalize_whitespace` | `(text) → str` | Collapse all whitespace runs to a single space and strip ends |
+| `remove_punctuation` | `(text, replace="") → str` | Remove or replace all punctuation characters |
+| `remove_digits` | `(text, replace="") → str` | Remove or replace all digit characters |
+| `remove_html_tags` | `(text, replace="") → str` | Strip or replace HTML tags |
+| `remove_urls` | `(text, replace="") → str` | Remove or replace HTTP/HTTPS and `www.` URLs |
+| `remove_emojis` | `(text, replace="") → str` | Remove or replace emoji characters (requires `emoji`) |
+| `collapse_spaces` | `(text) → str` | Remove **all** whitespace (not just collapse) |
+
+All cleaning functions accept an optional `replace` argument — the string substituted in place of each removed element (defaults to `""`). After replacement, whitespace is always normalized.
+
+```python
+from py-text-toolkit.cleaning import remove_punctuation, remove_html_tags, remove_emojis
+
+remove_punctuation("Hello, world!")              # "Hello world"
+remove_punctuation("Hello, world!", replace=" ") # "Hello world"
+
+remove_html_tags("<p>Hello <b>world</b></p>")    # "Hello world"
+remove_html_tags("<br/>line1<br/>line2", replace=" ")  # "line1 line2"
+
+remove_emojis("Great job! 🎉")                   # "Great job!"
+remove_emojis("Hello 😊", replace="[emoji]")     # "Hello [emoji]"
+```
+
+---
+
+### `py-text-toolkit.validation`
+
+Boolean predicates for common string formats.
+
+| Function | Signature | Description |
+|---|---|---|
+| `is_email` | `(text) → bool` | Check for a valid email address |
+| `is_url` | `(text) → bool` | Check for a valid HTTP or HTTPS URL |
+| `contains_only` | `(text, allowed_chars) → bool` | Check that every character is in the allowed set |
+| `is_strong_password` | `(text) → bool` | Check that a password meets strength requirements |
+
+**Password requirements** (`is_strong_password`):
+- Minimum 8 characters
+- At least one lowercase letter
+- At least one uppercase letter
+- At least one digit
+- At least one special character from `@$!%*?&`
+
+```python
+from py-text-toolkit.validation import is_email, is_url, contains_only, is_strong_password
+
+is_email("user@example.com")          # True
+is_email("not-an-email")              # False
+
+is_url("https://api.service.io/v1")   # True
+is_url("ftp://files.example.com")     # False
+
+contains_only("12345", "0123456789")  # True
+contains_only("hello!", "a-z")        # False  (literal chars only, not a range)
+
+is_strong_password("Passw0rd!")       # True
+is_strong_password("weakpass")        # False
+```
+
+> **Note on `contains_only`:** `allowed_chars` is treated as a set of literal characters. Special regex characters are escaped automatically, so `"a-z"` matches only the three characters `a`, `-`, and `z`, **not** a range.
+
+---
+
+### `py-text-toolkit.analysis`
+
+Functions that measure and compare strings.
+
+| Function | Signature | Description |
+|---|---|---|
+| `word_count` | `(text) → int` | Count words using regex word-boundary matching |
+| `char_frequency` | `(text, char) → int` | Count non-overlapping occurrences of a character or substring |
+| `count_vowels` | `(text) → int` | Count English vowels (a e i o u), case-insensitive |
+| `longest_word` | `(text) → int` | Return the length of the longest whitespace-delimited word |
+| `is_palindrome` | `(text, case_sensitive=False, ignore_formatting=True) → bool` | Check if a string is a palindrome |
+| `is_anagram` | `(word1, word2) → bool` | Check if two strings are anagrams (case-insensitive, ignores spaces) |
+
+```python
+from py-text-toolkit.analysis import word_count, is_palindrome, is_anagram, char_frequency
+
+word_count("Hello, world!")                   # 2
+word_count("  spaces   everywhere  ")         # 2
+
+char_frequency("banana", "an")                # 2
+
+is_palindrome("racecar")                      # True
+is_palindrome("A man a plan a canal Panama")  # True
+is_palindrome("Racecar", case_sensitive=True) # False
+
+is_anagram("listen", "silent")                # True
+is_anagram("Astronomer", "Moon starer")       # True
+```
+
+---
+
+### `py-text-toolkit.format_cases`
+
+Convert strings between naming conventions and apply text formatting.
+
+| Function | Signature | Description |
+|---|---|---|
+| `to_snake_case` | `(text) → str` | Convert to `snake_case` |
+| `to_camel_case` | `(text) → str` | Convert to `camelCase` |
+| `to_pascal_case` | `(text) → str` | Convert to `PascalCase` |
+| `to_kebab_case` | `(text) → str` | Convert to `kebab-case` |
+| `to_title_case` | `(text) → str` | Convert to `Title Case` |
+| `truncate` | `(text, max_length, suffix="...") → str` | Truncate to a maximum length with a suffix |
+| `pad_center` | `(text, width, fillchar=" ") → str` | Center-pad to a given width |
+
+All case converters handle mixed input (camelCase, PascalCase, snake_case, kebab-case, spaces).
+
+```python
+from py-text-toolkit.format_cases import to_snake_case, to_camel_case, truncate, pad_center
+
+to_snake_case("camelCaseText")    # "camel_case_text"
+to_snake_case("Hello World!")     # "hello_world"
+
+to_camel_case("hello_world")      # "helloWorld"
+to_camel_case("PascalCaseText")   # "pascalCaseText"
+
+to_pascal_case("kebab-case-text") # "KebabCaseText"
+to_kebab_case("camelCaseText")    # "camel-case-text"
+to_title_case("hello_world")      # "Hello World"
+
+truncate("Hello, World!", 8)      # "Hello..."
+truncate("Hi", 10)                # "Hi"
+
+pad_center("hello", 11)           # "   hello   "
+pad_center("hi", 10, "-")         # "----hi----"
+```
+
+---
+
+### `py-text-toolkit.generation`
+
+Functions that produce new strings from existing ones.
+
+| Function | Signature | Description |
+|---|---|---|
+| `generate_slug` | `(text) → str` | Convert to a URL-friendly slug |
+| `reverse_word` | `(text) → str` | Reverse all characters |
+| `mask_range` | `(text, start_index, end_index, placeholder="X") → str` | Mask a character range with a placeholder |
+| `ceasar_cipher` | `(text, shift) → str` | Encrypt/decrypt with the Caesar cipher |
+
+```python
+from py-text-toolkit.generation import generate_slug, mask_range, ceasar_cipher, reverse_word
+
+generate_slug("Hello World!")               # "hello-world"
+generate_slug("Python 3.11 -- Release Notes")  # "python-3-11-release-notes"
+
+reverse_word("hello")                       # "olleh"
+
+mask_range("1234-5678-9012", 5, 9, "*")     # "1234-****-9012"
+mask_range("secret", -3, -1)               # "secXXt"
+
+ceasar_cipher("Hello, World!", 3)           # "Khoor, Zruog!"
+ceasar_cipher("Khoor, Zruog!", -3)          # "Hello, World!"  (decrypt)
+```
+
+---
+
+## Dependencies
+
+| Package | Required | Used by |
+|---|---|---|
+| `re` (stdlib) | Always | All modules |
+| `string` (stdlib) | Always | `cleaning` |
+| `emoji` | Optional | `cleaning.remove_emojis` only |
+
+Install with the optional dependency:
+
+```bash
+pip install py-text-toolkit[emoji]
+```
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

py_text_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+py_text_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=TPjmzJvh2E7wUniQsHMR1XVxyX0SzXh1JKNTkNABqUU,1088
+strutils/__init__.py,sha256=yl8l7eXWNYt9NF3KvE5TESPGsLrgmYRE5bEq6rEtxfo,1262
+strutils/analysis.py,sha256=DZfb9D4OWOS4IK2hkQ10gCi-bI2cPhMTb_rlyLQQ9ZU,4956
+strutils/cleaning.py,sha256=rvMYNHi78TfH6IuqD1s0A2Zt9JFxhtd6wU-_w8choRY,5595
+strutils/format_cases.py,sha256=d0aP20Fz2dEpRoGbCKZHBxUsD058iRO2zVdnz8BHzn4,6680
+strutils/generation.py,sha256=MKed4-tgXzQkImFEHpaWgM7tAR7YSKpzoxP7hHUdeg4,3905
+strutils/validation.py,sha256=QVdrPLQfHm-b4kAIv1ZxWYZ49UkRQJwZGMixyihR0Po,4006
+py_text_toolkit-0.1.0.dist-info/METADATA,sha256=BVRsylSqdDfTyIDTfwddI3GMYGjP75yJV0nnUK3pDIM,9604
+py_text_toolkit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+py_text_toolkit-0.1.0.dist-info/top_level.txt,sha256=jOv2-Ma6MHfqFp8wQed3G2W88ceTT39Abb58ixN5ES8,9
+py_text_toolkit-0.1.0.dist-info/RECORD,,

py_text_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_text_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dawood Afzal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_text_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+strutils

strutils/__init__.py

@@ -0,0 +1,35 @@
+"""
+Strutils: A comprehensive string utility library for Python.
+"""
+
+from .analysis import (
+    word_count, char_frequency, is_palindrome, 
+    is_anagram, count_vowels, longest_word
+)
+from .cleaning import (
+    normalize_whitespace, remove_punctuation, remove_digits,
+    remove_html_tags, remove_urls, remove_emojis, collapse_spaces
+)
+from .format_cases import (
+    to_snake_case, to_camel_case, to_pascal_case,
+    to_kebab_case, to_title_case, truncate, pad_center
+)
+from .generation import (
+    generate_slug, reverse_word, mask_range, ceasar_cipher
+)
+from .validation import (
+    is_email, is_url, contains_only, is_strong_password
+)
+
+__all__ = [
+    # Analysis
+    "word_count", "char_frequency", "is_palindrome", "is_anagram", "count_vowels", "longest_word",
+    # Cleaning
+    "normalize_whitespace", "remove_punctuation", "remove_digits", "remove_html_tags", "remove_urls", "remove_emojis", "collapse_spaces",
+    # Format Cases
+    "to_snake_case", "to_camel_case", "to_pascal_case", "to_kebab_case", "to_title_case", "truncate", "pad_center",
+    # Generation
+    "generate_slug", "reverse_word", "mask_range", "ceasar_cipher",
+    # Validation
+    "is_email", "is_url", "contains_only", "is_strong_password"
+]

strutils/analysis.py

@@ -0,0 +1,175 @@
+import re
+from .cleaning import remove_punctuation, collapse_spaces 
+
+
+def word_count(text: str) -> int:
+    """
+    Count the number of words in a string.
+
+    Uses regex word-boundary matching to identify tokens, so punctuation
+    attached to words (e.g. "don't", "end.") is handled gracefully and
+    does not produce false word counts.
+
+    Args:
+        text (str): The input string to count words in.
+
+    Returns:
+        int: The total number of words found.
+
+    Examples:
+        >>> word_count("Hello, world!")
+        2
+        >>> word_count("  spaces   everywhere  ")
+        2
+        >>> word_count("")
+        0
+    """
+    text = re.findall(r"\b\w+\b", text)
+    return len(text)
+
+
+def char_frequency(text: str, char: str) -> int:
+    """
+    Count how many times a character (or substring) appears in a string.
+
+    Delegates directly to Python's built-in str.count(), which performs
+    non-overlapping matches.
+
+    Args:
+        text (str): The input string to search within.
+        char (str): The character or substring to count.
+
+    Returns:
+        int: The number of non-overlapping occurrences of char in text.
+
+    Examples:
+        >>> char_frequency("hello world", "l")
+        3
+        >>> char_frequency("banana", "an")
+        2
+        >>> char_frequency("hello", "z")
+        0
+    """
+    return text.count(char)
+
+
+def is_palindrome(text: str, case_sensitive: bool = False, ignore_formatting: bool = True) -> bool:
+    """
+    Check whether a string reads the same forwards and backwards.
+
+    Optionally strips punctuation and collapses extra whitespace before
+    checking, and optionally treats the comparison as case-insensitive.
+    Cleaning is done via the shared helpers ``remove_punctuation`` and
+    ``collapse_spaces`` from the cleaning module.
+
+    Args:
+        text (str): The input string to check.
+        case_sensitive (bool): If False (default), comparison is
+            case-insensitive. If True, casing must match exactly.
+        ignore_formatting (bool): If True (default), punctuation is removed
+            and consecutive spaces are collapsed before comparison.
+            If False, the raw string is used as-is.
+
+    Returns:
+        bool: True if the string is a palindrome, False otherwise.
+
+    Examples:
+        >>> is_palindrome("racecar")
+        True
+        >>> is_palindrome("A man a plan a canal Panama")
+        True
+        >>> is_palindrome("Hello")
+        False
+        >>> is_palindrome("Racecar", case_sensitive=True)
+        False
+    """
+    if ignore_formatting:
+        text = remove_punctuation(text)
+        text = collapse_spaces(text)
+
+    if not case_sensitive:
+        text = text.lower()
+
+    return text == text[::-1]
+
+
+def is_anagram(word1: str, word2: str) -> bool:
+    """
+    Check whether two strings are anagrams of each other.
+
+    Comparison is case-insensitive and ignores extra whitespace (via
+    ``collapse_spaces``). Two strings are considered anagrams if they
+    contain exactly the same characters in any order.
+
+    Args:
+        word1 (str): The first string to compare.
+        word2 (str): The second string to compare.
+
+    Returns:
+        bool: True if the two strings are anagrams, False otherwise.
+
+    Examples:
+        >>> is_anagram("listen", "silent")
+        True
+        >>> is_anagram("hello", "world")
+        False
+        >>> is_anagram("Astronomer", "Moon starer")
+        True
+    """
+    list1 = sorted(collapse_spaces(word1.lower()))
+    list2 = sorted(collapse_spaces(word2.lower()))
+    return list1 == list2
+
+
+def count_vowels(text: str) -> int:
+    """
+    Count the number of vowels (a, e, i, o, u) in a string.
+
+    The check is case-insensitive; both uppercase and lowercase vowels
+    are counted. Only standard English vowels are matched.
+
+    Args:
+        text (str): The input string to scan.
+
+    Returns:
+        int: The total number of vowel characters found.
+
+    Examples:
+        >>> count_vowels("Hello World")
+        3
+        >>> count_vowels("rhythm")
+        0
+        >>> count_vowels("AEIOU")
+        5
+    """
+    return len(re.findall(r"[aeiou]", text.lower()))
+
+
+def longest_word(text: str) -> int:
+    """
+    Return the length of the longest word in a string.
+
+    Words are determined by splitting on whitespace. If the input is
+    empty or contains only whitespace, 0 is returned.
+
+    Args:
+        text (str): The input string to search.
+
+    Returns:
+        int: The character length of the longest word, or 0 if there
+             are no words.
+
+    Examples:
+        >>> longest_word("The quick brown fox")
+        5
+        >>> longest_word("hi")
+        2
+        >>> longest_word("")
+        0
+    """
+    words = text.split()
+    if not words:
+        return 0
+    return len(max(words, key=len))
+
+

strutils/cleaning.py

@@ -0,0 +1,170 @@
+import re
+import string
+import emoji
+
+
+def normalize_whitespace(text: str) -> str:
+    """Collapse any sequence of whitespace characters into a single space.
+
+    Replaces one or more consecutive whitespace characters (spaces, tabs,
+    newlines, etc.) with a single space, then strips leading and trailing
+    whitespace from the result.
+
+    Args:
+        text: The input string to normalize.
+
+    Returns:
+        A new string with all whitespace sequences reduced to a single space
+        and no leading or trailing whitespace.
+
+    Example:
+        >>> normalize_whitespace("hello   world\\n\\tfoo")
+        'hello world foo'
+    """
+    return re.sub(r"\s+", " ", string=text).strip()
+
+
+def remove_punctuation(text: str, replace: str = "") -> str:
+    """Remove or replace all punctuation characters from a string.
+
+    Replaces every character found in ``string.punctuation`` with the given
+    replacement string, then normalizes any resulting extra whitespace.
+
+    Args:
+        text: The input string to process.
+        replace: The string to substitute in place of each punctuation
+            character. Defaults to ``""`` (deletion).
+
+    Returns:
+        A new string with all punctuation characters replaced and whitespace
+        normalized.
+
+    Example:
+        >>> remove_punctuation("Hello, world!")
+        'Hello world'
+        >>> remove_punctuation("Hello, world!", replace=" ")
+        'Hello world'
+    """
+    return normalize_whitespace(re.sub(f"[{re.escape(string.punctuation)}]", replace, string=text))
+
+
+def remove_digits(text: str, replace: str = "") -> str:
+    """Remove or replace all digit characters from a string.
+
+    Replaces every decimal digit (0–9) with the given replacement string,
+    then normalizes any resulting extra whitespace.
+
+    Args:
+        text: The input string to process.
+        replace: The string to substitute in place of each digit character.
+            Defaults to ``""`` (deletion).
+
+    Returns:
+        A new string with all digit characters replaced and whitespace
+        normalized.
+
+    Example:
+        >>> remove_digits("abc123def456")
+        'abcdef'
+        >>> remove_digits("abc123", replace="#")
+        'abc###'
+    """
+    return normalize_whitespace(re.sub(r"\d", replace, text))
+
+
+def remove_html_tags(text: str, replace: str = "") -> str:
+    """Strip or replace HTML tags from a string.
+
+    Matches anything of the form ``<...>`` and replaces it with the given
+    replacement string, then normalizes any resulting extra whitespace.
+
+    Args:
+        text: The input string potentially containing HTML markup.
+        replace: The string to substitute in place of each HTML tag.
+            Defaults to ``""`` (deletion).
+
+    Returns:
+        A new string with all HTML tags replaced and whitespace normalized.
+
+    Example:
+        >>> remove_html_tags("<p>Hello <b>world</b></p>")
+        'Hello world'
+        >>> remove_html_tags("<br/>line1<br/>line2", replace=" ")
+        'line1 line2'
+    """
+    return normalize_whitespace(re.sub(r"<[^>]+>", replace, text))
+
+
+def remove_urls(text: str, replace: str = "") -> str:
+    """Remove or replace URLs from a string.
+
+    Matches both ``http://`` / ``https://`` URLs and bare ``www.`` URLs,
+    replaces each with the given replacement string, then normalizes any
+    resulting extra whitespace.
+
+    Args:
+        text: The input string potentially containing URLs.
+        replace: The string to substitute in place of each matched URL.
+            Defaults to ``""`` (deletion).
+
+    Returns:
+        A new string with all URLs replaced and whitespace normalized.
+
+    Example:
+        >>> remove_urls("Visit https://example.com for details.")
+        'Visit for details.'
+        >>> remove_urls("Go to www.example.com now", replace="[link]")
+        'Go to [link] now'
+    """
+    return normalize_whitespace(
+        re.sub(r"(?:https?:\/\/)?www\.[\w./?=#&%-]+|https?:\/\/[\w./?=#&%-]+", replace, text)
+    )
+
+
+def remove_emojis(text: str, replace: str = "") -> str:
+    """Remove or replace emoji characters from a string.
+
+    Uses the ``emoji`` library to detect and replace all emoji characters,
+    then normalizes any resulting extra whitespace.
+
+    Args:
+        text: The input string potentially containing emoji characters.
+        replace: The string to substitute in place of each emoji.
+            Defaults to ``""`` (deletion).
+
+    Returns:
+        A new string with all emoji characters replaced and whitespace
+        normalized.
+
+    Example:
+        >>> remove_emojis("Hello 😊 world 🌍")
+        'Hello world'
+        >>> remove_emojis("Great job! 🎉", replace="[emoji]")
+        'Great job! [emoji]'
+    """
+    text = emoji.replace_emoji(text, replace)
+    return normalize_whitespace(text)
+
+
+def collapse_spaces(text: str) -> str:
+    """Remove all whitespace characters from a string.
+
+    Replaces every whitespace character (spaces, tabs, newlines, etc.)
+    with an empty string, effectively joining all tokens together.
+
+    Note:
+        Unlike ``normalize_whitespace``, this function removes *all*
+        whitespace rather than collapsing it to single spaces.
+
+    Args:
+        text: The input string to process.
+
+    Returns:
+        A new string with every whitespace character removed.
+
+    Example:
+        >>> collapse_spaces("hello   world\\nfoo")
+        'helloworldfoo'
+    """
+    return re.sub(r"\s+", "", string=text)
+

strutils/format_cases.py

@@ -0,0 +1,220 @@
+import re
+
+
+def to_snake_case(text: str) -> str:
+    """
+    Convert a string to snake_case.
+
+    Handles camelCase, PascalCase, kebab-case, spaces, and mixed formats
+    by inserting underscores at camelCase boundaries, replacing all
+    non-alphanumeric characters with underscores, and lowercasing the result.
+
+    Args:
+        text (str): The input string to convert.
+
+    Returns:
+        str: The converted snake_case string.
+
+    Examples:
+        >>> to_snake_case("camelCaseText")
+        'camel_case_text'
+        >>> to_snake_case("Hello World!")
+        'hello_world'
+        >>> to_snake_case("kebab-case-text")
+        'kebab_case_text'
+    """
+    text = re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', text)
+    text = re.sub(r'[^a-zA-Z0-9]+', '_', text)
+    return text.lower().strip('_')
+
+
+def to_camel_case(text: str) -> str:
+    """
+    Convert a string to camelCase.
+
+    Handles camelCase, PascalCase, snake_case, kebab-case, spaces, and mixed
+    formats by splitting on non-alphanumeric boundaries, lowercasing the first
+    word, and capitalizing subsequent words.
+
+    Args:
+        text (str): The input string to convert.
+
+    Returns:
+        str: The converted camelCase string, or an empty string if input
+             contains no alphanumeric characters.
+
+    Examples:
+        >>> to_camel_case("hello_world")
+        'helloWorld'
+        >>> to_camel_case("PascalCaseText")
+        'pascalCaseText'
+        >>> to_camel_case("kebab-case-text")
+        'kebabCaseText'
+    """
+    text = re.sub(r'([a-z0-9])([A-Z])', r'\1 \2', text)
+    text = re.sub(r'[^a-zA-Z0-9]+', ' ', text)
+    words = text.split()
+
+    if not words:
+        return ""
+
+    return words[0].lower() + "".join(word.capitalize() for word in words[1:])
+
+
+def to_pascal_case(text: str) -> str:
+    """
+    Convert a string to PascalCase (also known as UpperCamelCase).
+
+    Handles camelCase, snake_case, kebab-case, spaces, and mixed formats
+    by splitting on non-alphanumeric boundaries and capitalizing every word,
+    including the first.
+
+    Args:
+        text (str): The input string to convert.
+
+    Returns:
+        str: The converted PascalCase string, or an empty string if input
+             contains no alphanumeric characters.
+
+    Examples:
+        >>> to_pascal_case("hello_world")
+        'HelloWorld'
+        >>> to_pascal_case("camelCaseText")
+        'CamelCaseText'
+        >>> to_pascal_case("kebab-case-text")
+        'KebabCaseText'
+    """
+    text = re.sub(r'([a-z0-9])([A-Z])', r'\1 \2', text)
+    text = re.sub(r'[^a-zA-Z0-9]+', ' ', text)
+    words = text.split()
+
+    if not words:
+        return ""
+
+    return "".join(word.capitalize() for word in words)
+
+
+def to_kebab_case(text: str) -> str:
+    """
+    Convert a string to kebab-case.
+
+    Handles camelCase, PascalCase, snake_case, spaces, and mixed formats
+    by inserting hyphens at camelCase boundaries, replacing all
+    non-alphanumeric characters with hyphens, and lowercasing the result.
+
+    Args:
+        text (str): The input string to convert.
+
+    Returns:
+        str: The converted kebab-case string.
+
+    Examples:
+        >>> to_kebab_case("camelCaseText")
+        'camel-case-text'
+        >>> to_kebab_case("Hello World!")
+        'hello-world'
+        >>> to_kebab_case("snake_case_text")
+        'snake-case-text'
+    """
+    text = re.sub(r'([a-z0-9])([A-Z])', r'\1-\2', text)
+    text = re.sub(r'[^a-zA-Z0-9]+', '-', text)
+    return text.lower().strip('-')
+
+
+def to_title_case(text: str) -> str:
+    """
+    Convert a string to Title Case.
+
+    Handles camelCase, PascalCase, snake_case, kebab-case, spaces, and mixed
+    formats by splitting on non-alphanumeric boundaries and capitalizing the
+    first letter of every word, joining them with a single space.
+
+    Args:
+        text (str): The input string to convert.
+
+    Returns:
+        str: The converted Title Case string, or an empty string if input
+             contains no alphanumeric characters.
+
+    Examples:
+        >>> to_title_case("hello_world")
+        'Hello World'
+        >>> to_title_case("camelCaseText")
+        'Camel Case Text'
+        >>> to_title_case("kebab-case-text")
+        'Kebab Case Text'
+    """
+    text = re.sub(r'([a-z0-9])([A-Z])', r'\1 \2', text)
+    text = re.sub(r'[^a-zA-Z0-9]+', ' ', text)
+    words = text.split()
+
+    if not words:
+        return ""
+
+    return " ".join(word.capitalize() for word in words)
+
+
+def truncate(text: str, max_length: int, suffix: str = "...") -> str:
+    """
+    Truncate a string to a maximum length, appending a suffix if truncated.
+
+    If the string exceeds max_length, it is cut short and the suffix is
+    appended so the total length equals max_length. If max_length is less
+    than or equal to the suffix length, only the suffix (trimmed to
+    max_length) is returned.
+
+    Args:
+        text (str): The input string to truncate.
+        max_length (int): The maximum allowed length of the returned string,
+                          including the suffix.
+        suffix (str): The string to append when truncation occurs.
+                      Defaults to "...".
+
+    Returns:
+        str: The original string if it fits within max_length, otherwise the
+             truncated string with the suffix appended.
+
+    Examples:
+        >>> truncate("Hello, World!", 8)
+        'Hello...'
+        >>> truncate("Hi", 10)
+        'Hi'
+        >>> truncate("Hello", 2, "...")
+        '..'
+    """
+    if max_length <= len(suffix):
+        return suffix[:max_length]
+
+    if len(text) > max_length:
+        return text[:max_length - len(suffix)] + suffix
+
+    return text
+
+
+def pad_center(text: str, width: int, fillchar: str = " ") -> str:
+    """
+    Center a string within a field of a given width, padding with a fill character.
+
+    Delegates directly to Python's built-in str.center(). If the string is
+    already longer than width, it is returned unchanged.
+
+    Args:
+        text (str): The input string to center.
+        width (int): The total width of the resulting string.
+        fillchar (str): A single character used for padding on both sides.
+                        Defaults to a space " ".
+
+    Returns:
+        str: The centered string padded to the specified width.
+
+
+
+    Examples:
+        >>> pad_center("hello", 11)
+        '   hello   '
+        >>> pad_center("hi", 10, "-")
+        '----hi----'
+        >>> pad_center("toolong", 3)
+        'toolong'
+    """
+    return text.center(width, fillchar)

strutils/generation.py

@@ -0,0 +1,119 @@
+import re
+
+def generate_slug(text: str) -> str:
+    """
+    Convert a string into a URL-friendly slug.
+
+    Lowercases the input, replaces any sequence of non-alphanumeric
+    characters with a hyphen, and strips leading/trailing hyphens.
+
+    Args:
+        text: The string to slugify.
+
+    Returns:
+        A lowercase, hyphen-separated slug suitable for use in URLs.
+
+    Examples:
+        >>> generate_slug("Hello World!")
+        'hello-world'
+        >>> generate_slug("  Python 3.11 -- Release Notes  ")
+        'python-3-11-release-notes'
+    """
+    text = text.lower()
+    text = re.sub(r'[^a-z0-9]+', '-', text)
+    return text.strip("-")
+
+
+def reverse_word(text: str) -> str:
+    """
+    Reverse the characters in a string.
+
+    Args:
+        text: The string to reverse.
+
+    Returns:
+        A new string with characters in reversed order.
+
+    Examples:
+        >>> reverse_word("hello")
+        'olleh'
+        >>> reverse_word("racecar")
+        'racecar'
+    """
+    return text[::-1]
+
+
+def mask_range(text: str, start_index: int, end_index: int, placeholder: str = "X") -> str:
+    """
+    Mask a slice of a string with a repeated placeholder character.
+
+    Replaces characters from ``start_index`` up to (but not including)
+    ``end_index`` with repeated ``placeholder`` characters. Supports
+    negative indices, which are resolved relative to the end of the string.
+    Returns the original string unchanged if ``start_index >= end_index``
+    after index resolution.
+
+    Args:
+        text: The source string to mask.
+        start_index: Index of the first character to mask. Negative values
+            count from the end of the string.
+        end_index: Index one past the last character to mask. Negative values
+            count from the end of the string.
+        placeholder: Single character used for masking. Defaults to ``"X"``.
+
+    Returns:
+        A new string with the specified range replaced by the placeholder.
+
+    Examples:
+        >>> mask_range("Hello, World!", 7, 12)
+        'Hello, XXXXX!'
+        >>> mask_range("1234-5678-9012", 5, 9, "*")
+        '1234-****-9012'
+        >>> mask_range("secret", -3, -1)
+        'secXXt'
+    """
+    start_index = start_index if start_index >= 0 else len(text) + start_index
+    end_index = end_index if end_index >= 0 else len(text) + end_index
+
+    if start_index >= end_index:
+        return text
+    first_text = text[:start_index]
+    len_text_to_hide = len(text[start_index:end_index])
+    second_text = text[end_index:]
+    return first_text + (placeholder * len_text_to_hide) + second_text
+
+
+def ceasar_cipher(text: str, shift: int) -> str:
+    """
+    Encrypt or decrypt a string using the Caesar cipher.
+
+    Shifts each alphabetic character in ``text`` forward by ``shift``
+    positions in the alphabet, wrapping around at Z/z. Non-alphabetic
+    characters (digits, spaces, punctuation) are left unchanged.
+    To decrypt, pass the negated shift value (e.g. ``shift=-3``).
+
+    Args:
+        text: The string to encrypt or decrypt.
+        shift: Number of positions to shift each letter. May be negative
+            for a leftward shift (i.e. decryption with the positive key).
+
+    Returns:
+        A new string with each letter shifted by ``shift`` positions.
+
+    Examples:
+        >>> ceasar_cipher("Hello, World!", 3)
+        'Khoor, Zruog!'
+        >>> ceasar_cipher("Khoor, Zruog!", -3)
+        'Hello, World!'
+        >>> ceasar_cipher("abc", 26)
+        'abc'
+    """
+    result = []
+    for char in text:
+        if char.isalpha():
+            base = ord('a') if char.islower() else ord('A')
+            shifted_char = chr((ord(char) - base + shift) % 26 + base)
+            result.append(shifted_char)
+        else:
+            result.append(char)
+    return "".join(result)

strutils/validation.py

@@ -0,0 +1,129 @@
+import re
+
+
+def is_email(text: str) -> bool:
+    """
+    Check whether a string is a valid email address.
+
+    Uses a regular expression that requires a local part (letters, digits,
+    dots, plus signs, or hyphens), an ``@`` symbol, a domain name, and a
+    top-level domain of at least two letters.
+
+    Args:
+        text: The string to validate.
+
+    Returns:
+        ``True`` if ``text`` matches the email pattern, ``False`` otherwise.
+
+    Examples:
+        >>> is_email("user@example.com")
+        True
+        >>> is_email("invalid-email")
+        False
+        >>> is_email("user@sub.domain.org")
+        True
+    """
+    match = re.fullmatch(r"[\w.+-]+@[\w.-]+\.[a-zA-Z]{2,}", text)
+    if match:
+        return True
+    return False
+
+
+def is_url(text: str) -> bool:
+    """
+    Check whether a string is a valid HTTP or HTTPS URL.
+
+    Accepts URLs that start with ``http://`` or ``https://`` followed by
+    a non-empty path containing word characters and common URL symbols
+    (dots, slashes, query strings, fragments, etc.).
+
+    Args:
+        text: The string to validate.
+
+    Returns:
+        ``True`` if ``text`` matches the URL pattern, ``False`` otherwise.
+
+    Examples:
+        >>> is_url("https://www.example.com")
+        True
+        >>> is_url("http://api.service.io/v1/users?id=42")
+        True
+        >>> is_url("ftp://files.example.com")
+        False
+        >>> is_url("not a url")
+        False
+    """
+    match = re.fullmatch(r"https?:\/\/[\w./?=#&%:-]+", text)
+    if match:
+        return True
+    return False
+
+
+def contains_only(text: str, allowed_chars: str) -> bool:
+    """
+    Check whether a string is composed entirely of allowed characters.
+
+    Builds a character-class pattern from ``allowed_chars`` and tests
+    whether every character in ``text`` belongs to that set. Returns the
+    original falsy value (empty string, ``None``, etc.) unchanged when
+    ``text`` is empty or falsy, so callers can distinguish an empty input
+    from a non-matching one.
+
+    Args:
+        text: The string to validate.
+        allowed_chars: A string whose characters form the permitted set.
+            Special regex characters are automatically escaped, so passing
+            ``"a-z"`` matches only the literal characters ``a``, ``-``,
+            and ``z`` — not a range.
+
+    Returns:
+        ``True`` if every character in ``text`` is in ``allowed_chars``,
+        the original falsy value of ``text`` if ``text`` is empty/falsy,
+        or ``False`` if any character falls outside the allowed set.
+
+    Examples:
+        >>> contains_only("hello", "helo")
+        True
+        >>> contains_only("hello!", "helo")
+        False
+        >>> contains_only("12345", "0123456789")
+        True
+        >>> contains_only("", "abc")
+        ''
+    """
+    if not text:
+        return text
+    pattern = rf"[{re.escape(allowed_chars)}]+"
+    return bool(re.fullmatch(pattern, text))
+
+
+def is_strong_password(text: str) -> bool:
+    """
+    Check whether a string meets strong-password requirements.
+
+    A strong password must satisfy all of the following:
+
+    - At least 8 characters long.
+    - Contains at least one lowercase letter (``a``–``z``).
+    - Contains at least one uppercase letter (``A``–``Z``).
+    - Contains at least one digit (``0``–``9``).
+    - Contains at least one special character from ``@$!%*?&``.
+
+    Args:
+        text: The password string to validate.
+
+    Returns:
+        ``True`` if ``text`` satisfies all password requirements,
+        ``False`` otherwise.
+
+    Examples:
+        >>> is_strong_password("Passw0rd!")
+        True
+        >>> is_strong_password("weakpass")
+        False
+        >>> is_strong_password("NoSpecial1")
+        False
+        >>> is_strong_password("Short1!")
+        False
+    """
+    return bool(re.fullmatch(r"(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&]).{8,}", text))