feat: validatior errors

theskumar · theskumar · commit a236cc922da5 · 2025-10-28T16:32:34.000+05:30
diff --git a/README.md b/README.md
@@ -16,13 +16,16 @@ applications where use can choose login names and sub-domains.
 -   Validates against list of [banned
     words](https://github.com/theskumar/python-usernames/blob/master/usernames/reserved_words.py)
     that should not be used as username.
+-   **Detailed validation results** with specific error messages and suggestions
 -   Python 3.8+
 
 ## Installation
 
     pip install python-usernames
 
-## Usages
+## Usage
+
+### Simple Validation (Boolean Result)
 
 ```python
 from python_usernames import is_safe_username
@@ -34,7 +37,27 @@ False  # contains one of the banned words
 False  # contains non-url friendly `!`
 ```
 
-**is\_safe\_username** takes the following optional arguments:
+### Detailed Validation (With Error Messages)
+
+```python
+from python_usernames import validate_username
+
+>>> result = validate_username("user@name")
+>>> result.is_valid
+False
+>>> result.message
+"Username contains invalid characters: '@'. Only alphanumeric characters, underscore (_), dash (-), and dot (.) are allowed"
+>>> result.suggested_fix
+'username'
+
+>>> result = validate_username("john_doe")
+>>> result.is_valid
+True
+```
+
+### Options
+
+Both **is\_safe\_username** and **validate\_username** take the following optional arguments:
 
 -   `whitelist`: a case insensitive list of words that should be
     considered as always safe. Default: `[]`
@@ -43,10 +66,24 @@ False  # contains non-url friendly `!`
 -   `max_length`: specify the maximun character a username can have.
     Default: `None`
 
-- `regex`: regular expression string that must pass before the banned
-:   words is checked.
+-   `regex`: regular expression string that must pass before the banned
+    words is checked. **Note**: When a custom regex is provided, only that
+    regex, max_length, and reserved word checks are performed. Built-in format
+    checks (like consecutive special characters) are skipped.
+
+### Validation Reasons
+
+The `validate_username()` function returns a `ValidationResult` with:
 
-The default regular expression is as follows:
+-   **is_valid**: `True` if valid, `False` otherwise
+-   **reason**: Specific validation failure reason (enum)
+-   **message**: Human-readable error message
+-   **suggested_fix**: Automatic correction suggestion (when available)
+
+Available reasons: `VALID`, `TOO_LONG`, `EMPTY`, `ONLY_UNDERSCORE`, `STARTS_WITH_SPECIAL`, 
+`ENDS_WITH_SPECIAL`, `CONSECUTIVE_SPECIAL`, `INVALID_CHARACTERS`, `RESERVED_WORD`
+
+### Default Regular Expression
 
     ^                       # beginning of string
     (?!_$)                  # no only _
@@ -56,6 +93,30 @@ The default regular expression is as follows:
     (?<![.-])               # no - or . at the end
     $                       # end of string
 
+### Real-World Example
+
+```python
+from python_usernames import validate_username
+
+def register_user(username: str):
+    result = validate_username(username, max_length=20)
+    
+    if not result.is_valid:
+        print(f"Error: {result.message}")
+        if result.suggested_fix:
+            print(f"Try: '{result.suggested_fix}'")
+        return False
+    
+    # Create user account
+    return True
+```
+
+## Documentation
+
+-   [Detailed Validation Guide](DETAILED_VALIDATION.md) - Comprehensive usage examples
+-   [Migration Guide](MIGRATION_GUIDE.md) - How to upgrade from `is_safe_username()`
+-   [Examples](examples/detailed_validation.py) - Real-world usage patterns
+
 ## Credits
 
 - [The-Big-Username-Blocklist](https://github.com/marteinn/The-Big-Username-Blocklist)
diff --git a/src/python_usernames/__init__.py b/src/python_usernames/__init__.py
@@ -1,5 +1,15 @@
-from .validators import is_safe_username
+from .validators import (
+    is_safe_username,
+    validate_username,
+    ValidationResult,
+    ValidationReason,
+)
 
 __version__ = "0.4.1"
 
-__all__ = ["is_safe_username"]
+__all__ = [
+    "is_safe_username",
+    "validate_username",
+    "ValidationResult",
+    "ValidationReason",
+]
diff --git a/src/python_usernames/validators.py b/src/python_usernames/validators.py
@@ -1,8 +1,34 @@
 import re
+from dataclasses import dataclass
+from enum import Enum
 
 from .reserved_words import get_reserved_words
 
 
+class ValidationReason(Enum):
+    """Enum representing different validation failure reasons."""
+
+    VALID = "valid"
+    TOO_LONG = "too_long"
+    EMPTY = "empty"
+    ONLY_UNDERSCORE = "only_underscore"
+    STARTS_WITH_SPECIAL = "starts_with_special"
+    ENDS_WITH_SPECIAL = "ends_with_special"
+    CONSECUTIVE_SPECIAL = "consecutive_special"
+    INVALID_CHARACTERS = "invalid_characters"
+    RESERVED_WORD = "reserved_word"
+
+
+@dataclass
+class ValidationResult:
+    """Result of username validation with detailed information."""
+
+    is_valid: bool
+    reason: ValidationReason
+    message: str
+    suggested_fix: str | None = None
+
+
 username_regex = re.compile(
     r"""
     ^                       # beginning of string
@@ -17,16 +43,127 @@
 )
 
 
-def is_safe_username(
+def validate_username(
     username: str, whitelist=None, blacklist=None, regex=username_regex, max_length=None
-) -> bool:
+) -> ValidationResult:
+    """
+    Validate a username and return detailed validation result.
+
+    Args:
+        username: The username to validate
+        whitelist: List of words that should be considered safe (case insensitive)
+        blacklist: List of words that should be considered unsafe (case insensitive)
+        regex: Regular expression pattern for validation. If a custom regex is provided,
+               only that regex will be used (skipping detailed format checks)
+        max_length: Maximum allowed length for username
+
+    Returns:
+        ValidationResult with is_valid, reason, message, and optional suggested_fix
+
+    Note:
+        When a custom regex is provided, only max_length, regex, and reserved word
+        checks are performed. Built-in format checks are skipped.
+    """
+    # Determine if custom regex is provided
+    is_custom_regex = regex is not username_regex
+
     # check for max length
     if max_length and len(username) > max_length:
-        return False
+        return ValidationResult(
+            is_valid=False,
+            reason=ValidationReason.TOO_LONG,
+            message=f"Username must be {max_length} characters or less (currently {len(username)} characters)",
+            suggested_fix=username[:max_length] if username[:max_length] else None,
+        )
+
+    # If custom regex provided, skip detailed checks and only use regex + reserved words
+    if is_custom_regex:
+        # Check against custom regex
+        if not re.match(regex, username):
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.INVALID_CHARACTERS,
+                message="Username does not match the required format",
+                suggested_fix=None,
+            )
+    else:
+        # Use detailed built-in validation checks
+        # check for empty username
+        if not username:
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.EMPTY,
+                message="Username cannot be empty",
+                suggested_fix=None,
+            )
+
+        # check for only underscore
+        if username == "_":
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.ONLY_UNDERSCORE,
+                message="Username cannot be only an underscore",
+                suggested_fix=None,
+            )
 
-    # check against provided regex
-    if not re.match(regex, username):
-        return False
+        # check if starts with special character
+        if username[0] in "-.":
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.STARTS_WITH_SPECIAL,
+                message="Username cannot start with a dash (-) or dot (.)",
+                suggested_fix=username.lstrip("-."),
+            )
+
+        # check if ends with special character
+        if username[-1] in "-.":
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.ENDS_WITH_SPECIAL,
+                message="Username cannot end with a dash (-) or dot (.)",
+                suggested_fix=username.rstrip("-."),
+            )
+
+        # check for consecutive special characters
+        consecutive_patterns = ["__", "..", "--", "_.", "._", "-.", ".-"]
+        found_pattern = next((p for p in consecutive_patterns if p in username), None)
+        if found_pattern:
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.CONSECUTIVE_SPECIAL,
+                message=f"Username cannot contain consecutive special characters like '{found_pattern}'",
+                suggested_fix=None,
+            )
+
+        # check for invalid characters
+        valid_chars = set(
+            "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.-"
+        )
+        invalid_chars = [c for c in username if c not in valid_chars]
+        if invalid_chars:
+            unique_invalid = list(
+                dict.fromkeys(invalid_chars)
+            )  # preserve order, remove duplicates
+            invalid_display = ", ".join(
+                f"'{c}'" for c in unique_invalid[:5]
+            )  # show first 5
+            if len(unique_invalid) > 5:
+                invalid_display += ", ..."
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.INVALID_CHARACTERS,
+                message=f"Username contains invalid characters: {invalid_display}. Only alphanumeric characters, underscore (_), dash (-), and dot (.) are allowed",
+                suggested_fix="".join(c for c in username if c in valid_chars) or None,
+            )
+
+        # final regex check (should pass if all above checks passed)
+        if not re.match(regex, username):
+            return ValidationResult(
+                is_valid=False,
+                reason=ValidationReason.INVALID_CHARACTERS,
+                message="Username format is invalid",
+                suggested_fix=None,
+            )
 
     # ensure the word is not in the blacklist and is not a reserved word
     if whitelist is None:
@@ -47,4 +184,40 @@ def is_safe_username(
     default_words = default_words - whitelist
     default_words = default_words.union(blacklist)
 
-    return False if username.lower() in default_words else True
+    if username.lower() in default_words:
+        return ValidationResult(
+            is_valid=False,
+            reason=ValidationReason.RESERVED_WORD,
+            message=f"Username '{username}' is not allowed (reserved word or in blocklist)",
+            suggested_fix=None,
+        )
+
+    return ValidationResult(
+        is_valid=True,
+        reason=ValidationReason.VALID,
+        message="Username is valid",
+        suggested_fix=None,
+    )
+
+
+def is_safe_username(
+    username: str, whitelist=None, blacklist=None, regex=username_regex, max_length=None
+) -> bool:
+    """
+    Check if a username is safe/valid (backward compatible function).
+
+    Args:
+        username: The username to validate
+        whitelist: List of words that should be considered safe (case insensitive)
+        blacklist: List of words that should be considered unsafe (case insensitive)
+        regex: Regular expression pattern for validation
+        max_length: Maximum allowed length for username
+
+    Returns:
+        bool: True if username is valid, False otherwise
+
+    Note:
+        For detailed validation information, use validate_username() instead.
+    """
+    result = validate_username(username, whitelist, blacklist, regex, max_length)
+    return result.is_valid
diff --git a/tests/test_validate_username.py b/tests/test_validate_username.py
