Skip to content

Utils

The helpers/utils subpackage provides utility classes with static methods for common operations including date/time handling, string manipulation, file I/O, JWT tokens, passwords, TOTP, Keycloak integration, Prometheus metrics, and application-level utilities.

Base Utils

Base utility class providing foundational helpers shared across other utility classes.

archipy.helpers.utils.base_utils.BaseUtils

Bases: ErrorUtils, DatetimeUtils, PasswordUtils, JWTUtils, TOTPUtils, FileUtils, StringUtils

A utility class that combines multiple utility functionalities into a single class.

This class inherits from various utility classes to provide a centralized place for common utility methods.

Source code in archipy/helpers/utils/base_utils.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
class BaseUtils(ErrorUtils, DatetimeUtils, PasswordUtils, JWTUtils, TOTPUtils, FileUtils, StringUtils):
    """A utility class that combines multiple utility functionalities into a single class.

    This class inherits from various utility classes to provide a centralized place for common utility methods.
    """

    @staticmethod
    def sanitize_iranian_landline_or_phone_number(landline_or_phone_number: str) -> str:
        """Sanitizes an Iranian landline or mobile phone number by removing non-numeric characters and standardizing the format.

        Args:
            landline_or_phone_number (str): The phone number to sanitize.

        Returns:
            str: The sanitized phone number in a standardized format.
        """
        # Remove non-numeric characters
        cleaned_number = re.sub(r"\D", "", landline_or_phone_number)

        # Standardize international format to local Iran format
        if cleaned_number.startswith("0098"):  # Handles "0098"
            cleaned_number = "0" + cleaned_number[4:]  # Replace "0098" with "0"
        elif cleaned_number.startswith("98"):  # Handles "+98"
            cleaned_number = "0" + cleaned_number[2:]  # Replace "98" with "0"

        # Ensure mobile numbers start with '09'
        if len(cleaned_number) == 10 and cleaned_number.startswith("9"):
            cleaned_number = "0" + cleaned_number  # Convert "9123456789" → "09123456789"

        return cleaned_number

    @classmethod
    def validate_iranian_phone_number(cls, phone_number: str) -> None:
        """Validates an Iranian mobile phone number.

        Args:
            phone_number (str): The phone number to validate.

        Raises:
            InvalidPhoneNumberError: If the phone number is invalid.
        """
        # Sanitize the input to remove spaces, dashes, or other non-numeric characters
        sanitized_number = cls.sanitize_iranian_landline_or_phone_number(phone_number)
        # Define the regular expression pattern for Iranian phone numbers
        iranian_mobile_pattern = re.compile(r"^09\d{9}$")  # Mobile numbers

        # Check if the phone number matches either mobile or landline pattern
        if not iranian_mobile_pattern.match(sanitized_number):
            raise InvalidPhoneNumberError(phone_number)

    @classmethod
    def validate_iranian_landline_number(cls, landline_number: str) -> None:
        """Validates an Iranian landline number.

        Args:
            landline_number (str): The landline number to validate.

        Raises:
            InvalidLandlineNumberError: If the landline number is invalid.
        """
        # Sanitize the input to remove spaces, dashes, or other non-numeric characters
        sanitized_number = cls.sanitize_iranian_landline_or_phone_number(landline_number)
        # Landline examples: `0` + 2 to 4-digit area code + 7 to 8-digit local number
        iranian_landline_pattern = re.compile(r"^0\d{2,4}\d{7,8}$")

        if not iranian_landline_pattern.match(sanitized_number):
            raise InvalidLandlineNumberError(landline_number)

    @classmethod
    def validate_iranian_national_code_pattern(cls, national_code: str) -> None:
        """Validates an Iranian National ID number using the official algorithm.

        To see how the algorithm works, see http://www.aliarash.com/article/codemeli/codemeli.htm

        The algorithm works by:
        1. Checking if the ID is exactly 10 digits
        2. Multiplying each digit (except the last) by its position weight
        3. Summing these products
        4. Calculating the remainder when divided by 11
        5. Comparing the check digit based on specific rules

        Args:
            national_code (str): A string containing the national ID to validate.

        Raises:
            InvalidNationalCodeError: If the ID is invalid due to length or checksum.
        """

        def _validate_length(national_code: str) -> None:
            """Validates that the national code is exactly 10 digits long.

            Args:
                national_code (str): The national code to validate.

            Raises:
                InvalidNationalCodeError: If the length is not 10 digits.
            """
            if not len(national_code) == 10:
                raise InvalidNationalCodeError(national_code)

        def _calculate_weighted_sum(national_code: str) -> int:
            """Calculates the weighted sum of the national code digits.

            Args:
                national_code (str): The national code to calculate the weighted sum for.

            Returns:
                int: The weighted sum of the national code digits.
            """
            return sum(int(digit) * (10 - i) for i, digit in enumerate(national_code[:-1]))

        def _get_checksums(national_code: str) -> tuple[int, int]:
            """Calculates the expected and actual checksums for the national code.

            Args:
                national_code (str): The national code to calculate checksums for.

            Returns:
                tuple[int, int]: A tuple containing the calculated checksum and the actual checksum.
            """
            weighted_sum = _calculate_weighted_sum(national_code)
            remainder = weighted_sum % 11

            calculated_checksum = remainder if remainder < 2 else 11 - remainder
            actual_checksum = int(national_code[-1])

            return calculated_checksum, actual_checksum

        _validate_length(national_code)
        calculated_checksum, actual_checksum = _get_checksums(national_code)
        if calculated_checksum != actual_checksum:
            raise InvalidNationalCodeError(national_code)

archipy.helpers.utils.base_utils.BaseUtils.arabic_vowel_translate_table class-attribute instance-attribute 

arabic_vowel_translate_table = maketrans(fromkeys("ًٌَُِّْٓءٍٰۖۗۘۙۚۛ", ""))

archipy.helpers.utils.base_utils.BaseUtils.alphabet_akoolad_alef_translate_table class-attribute instance-attribute 

alphabet_akoolad_alef_translate_table = maketrans(
    fromkeys("ﺁ", "آ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_alef_translate_table class-attribute instance-attribute 

alphabet_alef_translate_table = maketrans(
    fromkeys("ﺎٲٱإﺍأٵٳ", "ا")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_be_translate_table class-attribute instance-attribute 

alphabet_be_translate_table = maketrans(
    fromkeys("ﺐﺏﺑٻٮ", "ب")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_pe_translate_table class-attribute instance-attribute 

alphabet_pe_translate_table = maketrans(
    fromkeys("ﭖﭗﭙﺒﭘڀݐݒݕ", "پ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_te_translate_table class-attribute instance-attribute 

alphabet_te_translate_table = maketrans(
    fromkeys("ﭡٺٹﭞٿټﺕﺗﺖﺘݓ", "ت")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_se_translate_table class-attribute instance-attribute 

alphabet_se_translate_table = maketrans(
    fromkeys("ﺙﺛٽﺚﺜ", "ث")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_jim_translate_table class-attribute instance-attribute 

alphabet_jim_translate_table = maketrans(
    fromkeys("ﺝﺠﺟﺞۚ", "ج")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_che_translate_table class-attribute instance-attribute 

alphabet_che_translate_table = maketrans(
    fromkeys("ڃﭽﭼڇڄݘڿﭻ", "چ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_he_translate_table class-attribute instance-attribute 

alphabet_he_translate_table = maketrans(
    fromkeys("ﺢﺤڅځﺣﺡ", "ح")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_khe_translate_table class-attribute instance-attribute 

alphabet_khe_translate_table = maketrans(
    fromkeys("ﺥﺦﺨﺧڂݗ", "خ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_dal_translate_table class-attribute instance-attribute 

alphabet_dal_translate_table = maketrans(
    fromkeys("ډﺪﺩڊڈڍܥ", "د")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_zal_translate_table class-attribute instance-attribute 

alphabet_zal_translate_table = maketrans(
    fromkeys("ﺫﺬﻧڐڏڎڌ", "ذ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_re_translate_table class-attribute instance-attribute 

alphabet_re_translate_table = maketrans(
    fromkeys("ڗڒڑڕﺭﺮږڔړڒڑۯ", "ر")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_ze_translate_table class-attribute instance-attribute 

alphabet_ze_translate_table = maketrans(fromkeys("ﺰﺯ", "ز"))

archipy.helpers.utils.base_utils.BaseUtils.alphabet_zhe_translate_table class-attribute instance-attribute 

alphabet_zhe_translate_table = maketrans(
    fromkeys("ﮊڙﮋ", "ژ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_sin_translate_table class-attribute instance-attribute 

alphabet_sin_translate_table = maketrans(
    fromkeys("ݭݜﺱﺲﺴﺳڛښۣݾݽ", "س")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_shin_translate_table class-attribute instance-attribute 

alphabet_shin_translate_table = maketrans(
    fromkeys("ﺵﺶﺸﺷڜۺ", "ش")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_sad_translate_table class-attribute instance-attribute 

alphabet_sad_translate_table = maketrans(
    fromkeys("ﺹﺺﺼﺻڝ", "ص")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_zad_translate_table class-attribute instance-attribute 

alphabet_zad_translate_table = maketrans(
    fromkeys("ﺽﺾﺿﻀۻڞ", "ض")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_ta_translate_table class-attribute instance-attribute 

alphabet_ta_translate_table = maketrans(
    fromkeys("ﻁﻂﻃﻄ", "ط")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_za_translate_table class-attribute instance-attribute 

alphabet_za_translate_table = maketrans(
    fromkeys("ﻆﻇﻈڟﻅ", "ظ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_eyn_translate_table class-attribute instance-attribute 

alphabet_eyn_translate_table = maketrans(
    fromkeys("ڠﻉﻊﻋﻌ", "ع")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_gheyn_translate_table class-attribute instance-attribute 

alphabet_gheyn_translate_table = maketrans(
    fromkeys("ﻎۼﻍﻐﻏݝݞݟ", "غ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_fe_translate_table class-attribute instance-attribute 

alphabet_fe_translate_table = maketrans(
    fromkeys("ﻒﻑﻔﻓڡڥڦڤ\u0603ڣڢ", "ف")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_ghaf_translate_table class-attribute instance-attribute 

alphabet_ghaf_translate_table = maketrans(
    fromkeys("ﻕﻖﻗڧڨ؋ﻘ", "ق")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_kaf_translate_table class-attribute instance-attribute 

alphabet_kaf_translate_table = maketrans(
    fromkeys("ڭﻚﮎﻜﮏګﻛﮑﮐڪكݢݣݤڬڮݿﻙ", "ک")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_gaf_translate_table class-attribute instance-attribute 

alphabet_gaf_translate_table = maketrans(
    fromkeys("ﮚﮒﮓﮕﮔڱڰڲڳڴ", "گ")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_lam_translate_table class-attribute instance-attribute 

alphabet_lam_translate_table = maketrans(
    fromkeys("ﻟﻝﻞﻠݪڷڸڶڵ", "ل")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_mim_translate_table class-attribute instance-attribute 

alphabet_mim_translate_table = maketrans(
    fromkeys("ﻡﻤﻢﻣݦݥ", "م")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_nun_translate_table class-attribute instance-attribute 

alphabet_nun_translate_table = maketrans(
    fromkeys("ڼﻦﻥﻨݩݨݧڻڽںڹ", "ن")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_vav_translate_table class-attribute instance-attribute 

alphabet_vav_translate_table = maketrans(
    fromkeys("ވﯙۈۋﺆۊۇۏۅۉﻭﻮؤۆۄ", "و")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_ha_translate_table class-attribute instance-attribute 

alphabet_ha_translate_table = maketrans(
    fromkeys("ﺓﮭﺔﻬھﻩﻫﻪۀەةہܣܤܝ", "ه")
)

archipy.helpers.utils.base_utils.BaseUtils.alphabet_ye_translate_table class-attribute instance-attribute 

alphabet_ye_translate_table = maketrans(
    fromkeys("ﯨﭛﻯۍﻰﻱﻲﻳﻴﯼېﯽﯾﯿێےىيٸۑؽؾؿﺉﺋﺌ", "ی")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table1 class-attribute instance-attribute 

punctuation_translate_table1 = maketrans(fromkeys("¬", " "))

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table2 class-attribute instance-attribute 

punctuation_translate_table2 = maketrans(
    fromkeys("•·●·・∙｡ⴰ", ".")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table3 class-attribute instance-attribute 

punctuation_translate_table3 = maketrans(
    fromkeys(",٬٫‚，", "،")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table4 class-attribute instance-attribute 

punctuation_translate_table4 = maketrans(
    fromkeys("ʕ?⁉�", "؟")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table5 class-attribute instance-attribute 

punctuation_translate_table5 = maketrans(
    fromkeys("‼❕", "!")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table6 class-attribute instance-attribute 

punctuation_translate_table6 = maketrans(fromkeys("_", "ـ"))

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table7 class-attribute instance-attribute 

punctuation_translate_table7 = maketrans(
    fromkeys("－━−‐‑–—─−ー⁃", "-")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table8 class-attribute instance-attribute 

punctuation_translate_table8 = maketrans(
    fromkeys("‹《﴾", "«")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table9 class-attribute instance-attribute 

punctuation_translate_table9 = maketrans(
    fromkeys("›》﴿", "»")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table10 class-attribute instance-attribute 

punctuation_translate_table10 = maketrans(
    fromkeys(";", "؛")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table11 class-attribute instance-attribute 

punctuation_translate_table11 = maketrans(
    fromkeys("%", "٪")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table12 class-attribute instance-attribute 

punctuation_translate_table12 = maketrans(
    fromkeys("ˈ‘’“”", "'")
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_translate_table13 class-attribute instance-attribute 

punctuation_translate_table13 = maketrans(
    fromkeys("：", ":")
)

archipy.helpers.utils.base_utils.BaseUtils.character_refinement_patterns class-attribute instance-attribute 

character_refinement_patterns: list = compile_patterns(
    [(" +", " "), ("\\n\\n+", "\n"), (" ?\\.\\.\\.", " …")]
)

archipy.helpers.utils.base_utils.BaseUtils.punctuation_after class-attribute instance-attribute 

punctuation_after = '\\.:!،؛؟»\\]\\)\\}'

archipy.helpers.utils.base_utils.BaseUtils.punctuation_before class-attribute instance-attribute 

punctuation_before = '«\\[\\(\\{'

archipy.helpers.utils.base_utils.BaseUtils.punctuation_spacing_patterns class-attribute instance-attribute 

punctuation_spacing_patterns = compile_patterns(
    [
        (f" ([{punctuation_after}])", "\\1"),
        (f"([{punctuation_before}]) ", "\\1"),
        (
            f"([{punctuation_after[:3]}])([^ {punctuation_after}"
            + "\\d])",
            "\\1 \\2",
        ),
        (
            f"([{punctuation_after[3:]}])([^ {punctuation_after}])",
            "\\1 \\2",
        ),
        (
            f"([^ {punctuation_before}])([{punctuation_before}])",
            "\\1 \\2",
        ),
    ]
)

archipy.helpers.utils.base_utils.BaseUtils.number_zero_translate_table class-attribute instance-attribute 

number_zero_translate_table = maketrans(fromkeys("۰٠", "0"))

archipy.helpers.utils.base_utils.BaseUtils.number_one_translate_table class-attribute instance-attribute 

number_one_translate_table = maketrans(fromkeys('۱١', '1'))

archipy.helpers.utils.base_utils.BaseUtils.number_two_translate_table class-attribute instance-attribute 

number_two_translate_table = maketrans(fromkeys('۲٢', '2'))

archipy.helpers.utils.base_utils.BaseUtils.number_three_translate_table class-attribute instance-attribute 

number_three_translate_table = maketrans(
    fromkeys("۳٣", "3")
)

archipy.helpers.utils.base_utils.BaseUtils.number_four_translate_table class-attribute instance-attribute 

number_four_translate_table = maketrans(fromkeys("۴٤", "4"))

archipy.helpers.utils.base_utils.BaseUtils.number_five_translate_table class-attribute instance-attribute 

number_five_translate_table = maketrans(fromkeys("۵٥", "5"))

archipy.helpers.utils.base_utils.BaseUtils.number_six_translate_table class-attribute instance-attribute 

number_six_translate_table = maketrans(fromkeys('۶٦', '6'))

archipy.helpers.utils.base_utils.BaseUtils.number_seven_translate_table class-attribute instance-attribute 

number_seven_translate_table = maketrans(
    fromkeys("۷٧", "7")
)

archipy.helpers.utils.base_utils.BaseUtils.number_eight_translate_table class-attribute instance-attribute 

number_eight_translate_table = maketrans(
    fromkeys("۸٨", "8")
)

archipy.helpers.utils.base_utils.BaseUtils.number_nine_translate_table class-attribute instance-attribute 

number_nine_translate_table = maketrans(fromkeys("۹٩", "9"))

archipy.helpers.utils.base_utils.BaseUtils.punctuation_persian_marks_to_space_translate_table class-attribute instance-attribute 

punctuation_persian_marks_to_space_translate_table = (
    maketrans(fromkeys(".:!،؛؟»])}«[({-ـ٪!'\"#+/", " "))
)

archipy.helpers.utils.base_utils.BaseUtils.sanitize_iranian_landline_or_phone_number staticmethod 

sanitize_iranian_landline_or_phone_number(
    landline_or_phone_number: str,
) -> str

Sanitizes an Iranian landline or mobile phone number by removing non-numeric characters and standardizing the format.

Parameters:

Name Type Description Default
landline_or_phone_number str

The phone number to sanitize.

 required

Returns:

Name Type Description
str str

The sanitized phone number in a standardized format.
Source code in archipy/helpers/utils/base_utils.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@staticmethod
def sanitize_iranian_landline_or_phone_number(landline_or_phone_number: str) -> str:
    """Sanitizes an Iranian landline or mobile phone number by removing non-numeric characters and standardizing the format.

    Args:
        landline_or_phone_number (str): The phone number to sanitize.

    Returns:
        str: The sanitized phone number in a standardized format.
    """
    # Remove non-numeric characters
    cleaned_number = re.sub(r"\D", "", landline_or_phone_number)

    # Standardize international format to local Iran format
    if cleaned_number.startswith("0098"):  # Handles "0098"
        cleaned_number = "0" + cleaned_number[4:]  # Replace "0098" with "0"
    elif cleaned_number.startswith("98"):  # Handles "+98"
        cleaned_number = "0" + cleaned_number[2:]  # Replace "98" with "0"

    # Ensure mobile numbers start with '09'
    if len(cleaned_number) == 10 and cleaned_number.startswith("9"):
        cleaned_number = "0" + cleaned_number  # Convert "9123456789" → "09123456789"

    return cleaned_number

archipy.helpers.utils.base_utils.BaseUtils.validate_iranian_phone_number classmethod 

validate_iranian_phone_number(phone_number: str) -> None

Validates an Iranian mobile phone number.

Parameters:

Name Type Description Default
phone_number str

The phone number to validate.

 required

Raises:

Type Description
InvalidPhoneNumberError

If the phone number is invalid.
Source code in archipy/helpers/utils/base_utils.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
@classmethod
def validate_iranian_phone_number(cls, phone_number: str) -> None:
    """Validates an Iranian mobile phone number.

    Args:
        phone_number (str): The phone number to validate.

    Raises:
        InvalidPhoneNumberError: If the phone number is invalid.
    """
    # Sanitize the input to remove spaces, dashes, or other non-numeric characters
    sanitized_number = cls.sanitize_iranian_landline_or_phone_number(phone_number)
    # Define the regular expression pattern for Iranian phone numbers
    iranian_mobile_pattern = re.compile(r"^09\d{9}$")  # Mobile numbers

    # Check if the phone number matches either mobile or landline pattern
    if not iranian_mobile_pattern.match(sanitized_number):
        raise InvalidPhoneNumberError(phone_number)

archipy.helpers.utils.base_utils.BaseUtils.validate_iranian_landline_number classmethod 

validate_iranian_landline_number(
    landline_number: str,
) -> None

Validates an Iranian landline number.

Parameters:

Name Type Description Default
landline_number str

The landline number to validate.

 required

Raises:

Type Description
InvalidLandlineNumberError

If the landline number is invalid.
Source code in archipy/helpers/utils/base_utils.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@classmethod
def validate_iranian_landline_number(cls, landline_number: str) -> None:
    """Validates an Iranian landline number.

    Args:
        landline_number (str): The landline number to validate.

    Raises:
        InvalidLandlineNumberError: If the landline number is invalid.
    """
    # Sanitize the input to remove spaces, dashes, or other non-numeric characters
    sanitized_number = cls.sanitize_iranian_landline_or_phone_number(landline_number)
    # Landline examples: `0` + 2 to 4-digit area code + 7 to 8-digit local number
    iranian_landline_pattern = re.compile(r"^0\d{2,4}\d{7,8}$")

    if not iranian_landline_pattern.match(sanitized_number):
        raise InvalidLandlineNumberError(landline_number)

archipy.helpers.utils.base_utils.BaseUtils.validate_iranian_national_code_pattern classmethod 

validate_iranian_national_code_pattern(
    national_code: str,
) -> None

Validates an Iranian National ID number using the official algorithm.

To see how the algorithm works, see http://www.aliarash.com/article/codemeli/codemeli.htm

The algorithm works by: 1. Checking if the ID is exactly 10 digits 2. Multiplying each digit (except the last) by its position weight 3. Summing these products 4. Calculating the remainder when divided by 11 5. Comparing the check digit based on specific rules

Parameters:

Name Type Description Default
national_code str

A string containing the national ID to validate.

 required

Raises:

Type Description
InvalidNationalCodeError

If the ID is invalid due to length or checksum.
Source code in archipy/helpers/utils/base_utils.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
@classmethod
def validate_iranian_national_code_pattern(cls, national_code: str) -> None:
    """Validates an Iranian National ID number using the official algorithm.

    To see how the algorithm works, see http://www.aliarash.com/article/codemeli/codemeli.htm

    The algorithm works by:
    1. Checking if the ID is exactly 10 digits
    2. Multiplying each digit (except the last) by its position weight
    3. Summing these products
    4. Calculating the remainder when divided by 11
    5. Comparing the check digit based on specific rules

    Args:
        national_code (str): A string containing the national ID to validate.

    Raises:
        InvalidNationalCodeError: If the ID is invalid due to length or checksum.
    """

    def _validate_length(national_code: str) -> None:
        """Validates that the national code is exactly 10 digits long.

        Args:
            national_code (str): The national code to validate.

        Raises:
            InvalidNationalCodeError: If the length is not 10 digits.
        """
        if not len(national_code) == 10:
            raise InvalidNationalCodeError(national_code)

    def _calculate_weighted_sum(national_code: str) -> int:
        """Calculates the weighted sum of the national code digits.

        Args:
            national_code (str): The national code to calculate the weighted sum for.

        Returns:
            int: The weighted sum of the national code digits.
        """
        return sum(int(digit) * (10 - i) for i, digit in enumerate(national_code[:-1]))

    def _get_checksums(national_code: str) -> tuple[int, int]:
        """Calculates the expected and actual checksums for the national code.

        Args:
            national_code (str): The national code to calculate checksums for.

        Returns:
            tuple[int, int]: A tuple containing the calculated checksum and the actual checksum.
        """
        weighted_sum = _calculate_weighted_sum(national_code)
        remainder = weighted_sum % 11

        calculated_checksum = remainder if remainder < 2 else 11 - remainder
        actual_checksum = int(national_code[-1])

        return calculated_checksum, actual_checksum

    _validate_length(national_code)
    calculated_checksum, actual_checksum = _get_checksums(national_code)
    if calculated_checksum != actual_checksum:
        raise InvalidNationalCodeError(national_code)

archipy.helpers.utils.base_utils.BaseUtils.remove_arabic_vowels classmethod 

remove_arabic_vowels(text: str) -> str

Removes Arabic vowels (tashkeel) from the text.

Parameters:

Name Type Description Default
text str

The input text containing Arabic vowels.

 required

Returns:

Name Type Description
str str

The text with Arabic vowels removed.
Source code in archipy/helpers/utils/string_utils.py 
15
16
17
18
19
20
21
22
23
24
25
@classmethod
def remove_arabic_vowels(cls, text: str) -> str:
    """Removes Arabic vowels (tashkeel) from the text.

    Args:
        text (str): The input text containing Arabic vowels.

    Returns:
        str: The text with Arabic vowels removed.
    """
    return text.translate(cls.arabic_vowel_translate_table)

archipy.helpers.utils.base_utils.BaseUtils.normalize_persian_chars classmethod 

normalize_persian_chars(text: str) -> str

Normalizes Persian characters to their standard forms.

Parameters:

Name Type Description Default
text str

The input text containing Persian characters.

 required

Returns:

Name Type Description
str str

The text with Persian characters normalized.
Source code in archipy/helpers/utils/string_utils.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@classmethod
def normalize_persian_chars(cls, text: str) -> str:
    """Normalizes Persian characters to their standard forms.

    Args:
        text (str): The input text containing Persian characters.

    Returns:
        str: The text with Persian characters normalized.
    """
    text = text.translate(cls.alphabet_akoolad_alef_translate_table)
    text = text.translate(cls.alphabet_alef_translate_table)
    text = text.translate(cls.alphabet_be_translate_table)
    text = text.translate(cls.alphabet_pe_translate_table)
    text = text.translate(cls.alphabet_te_translate_table)
    text = text.translate(cls.alphabet_se_translate_table)
    text = text.translate(cls.alphabet_jim_translate_table)
    text = text.translate(cls.alphabet_che_translate_table)
    text = text.translate(cls.alphabet_he_translate_table)
    text = text.translate(cls.alphabet_khe_translate_table)
    text = text.translate(cls.alphabet_dal_translate_table)
    text = text.translate(cls.alphabet_zal_translate_table)
    text = text.translate(cls.alphabet_re_translate_table)
    text = text.translate(cls.alphabet_ze_translate_table)
    text = text.translate(cls.alphabet_zhe_translate_table)
    text = text.translate(cls.alphabet_sin_translate_table)
    text = text.translate(cls.alphabet_shin_translate_table)
    text = text.translate(cls.alphabet_sad_translate_table)
    text = text.translate(cls.alphabet_zad_translate_table)
    text = text.translate(cls.alphabet_ta_translate_table)
    text = text.translate(cls.alphabet_za_translate_table)
    text = text.translate(cls.alphabet_eyn_translate_table)
    text = text.translate(cls.alphabet_gheyn_translate_table)
    text = text.translate(cls.alphabet_fe_translate_table)
    text = text.translate(cls.alphabet_ghaf_translate_table)
    text = text.translate(cls.alphabet_kaf_translate_table)
    text = text.translate(cls.alphabet_gaf_translate_table)
    text = text.translate(cls.alphabet_lam_translate_table)
    text = text.translate(cls.alphabet_mim_translate_table)
    text = text.translate(cls.alphabet_nun_translate_table)
    text = text.translate(cls.alphabet_vav_translate_table)
    text = text.translate(cls.alphabet_ha_translate_table)
    return text.translate(cls.alphabet_ye_translate_table)

archipy.helpers.utils.base_utils.BaseUtils.normalize_punctuation classmethod 

normalize_punctuation(text: str) -> str

Normalizes punctuation marks in the text.

Parameters:

Name Type Description Default
text str

The input text containing punctuation marks.

 required

Returns:

Name Type Description
str str

The text with punctuation marks normalized.
Source code in archipy/helpers/utils/string_utils.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
@classmethod
def normalize_punctuation(cls, text: str) -> str:
    """Normalizes punctuation marks in the text.

    Args:
        text (str): The input text containing punctuation marks.

    Returns:
        str: The text with punctuation marks normalized.
    """
    text = text.translate(cls.punctuation_translate_table1)
    text = text.translate(cls.punctuation_translate_table2)
    text = text.translate(cls.punctuation_translate_table3)
    text = text.translate(cls.punctuation_translate_table4)
    text = text.translate(cls.punctuation_translate_table5)
    text = text.translate(cls.punctuation_translate_table6)
    text = text.translate(cls.punctuation_translate_table7)
    text = text.translate(cls.punctuation_translate_table8)
    text = text.translate(cls.punctuation_translate_table9)
    text = text.translate(cls.punctuation_translate_table10)
    text = text.translate(cls.punctuation_translate_table11)
    text = text.translate(cls.punctuation_translate_table12)
    return text.translate(cls.punctuation_translate_table13)

archipy.helpers.utils.base_utils.BaseUtils.normalize_numbers classmethod 

normalize_numbers(text: str) -> str

Normalizes numbers in the text to English format.

Parameters:

Name Type Description Default
text str

The input text containing numbers.

 required

Returns:

Name Type Description
str str

The text with numbers normalized to English format.
Source code in archipy/helpers/utils/string_utils.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
@classmethod
def normalize_numbers(cls, text: str) -> str:
    """Normalizes numbers in the text to English format.

    Args:
        text (str): The input text containing numbers.

    Returns:
        str: The text with numbers normalized to English format.
    """
    text = text.translate(cls.number_zero_translate_table)
    text = text.translate(cls.number_one_translate_table)
    text = text.translate(cls.number_two_translate_table)
    text = text.translate(cls.number_three_translate_table)
    text = text.translate(cls.number_four_translate_table)
    text = text.translate(cls.number_five_translate_table)
    text = text.translate(cls.number_six_translate_table)
    text = text.translate(cls.number_seven_translate_table)
    text = text.translate(cls.number_eight_translate_table)
    return text.translate(cls.number_nine_translate_table)

archipy.helpers.utils.base_utils.BaseUtils.clean_spacing classmethod 

clean_spacing(text: str) -> str

Cleans up spacing issues in the text, such as non-breaking spaces and zero-width non-joiners.

Parameters:

Name Type Description Default
text str

The input text with spacing issues.

 required

Returns:

Name Type Description
str str

The text with spacing cleaned up.
Source code in archipy/helpers/utils/string_utils.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@classmethod
def clean_spacing(cls, text: str) -> str:
    """Cleans up spacing issues in the text, such as non-breaking spaces and zero-width non-joiners.

    Args:
        text (str): The input text with spacing issues.

    Returns:
        str: The text with spacing cleaned up.
    """
    text = text.replace("\u200c", " ")  # ZWNJ
    text = text.replace("\xa0", " ")  # NBSP

    for pattern, repl in cls.character_refinement_patterns:
        text = pattern.sub(repl, text)

    return text

archipy.helpers.utils.base_utils.BaseUtils.normalize_punctuation_spacing classmethod 

normalize_punctuation_spacing(text: str) -> str

Applies proper spacing around punctuation marks.

Parameters:

Name Type Description Default
text str

The input text with punctuation spacing issues.

 required

Returns:

Name Type Description
str str

The text with proper spacing around punctuation marks.
Source code in archipy/helpers/utils/string_utils.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
@classmethod
def normalize_punctuation_spacing(cls, text: str) -> str:
    """Applies proper spacing around punctuation marks.

    Args:
        text (str): The input text with punctuation spacing issues.

    Returns:
        str: The text with proper spacing around punctuation marks.
    """
    for pattern, repl in cls.punctuation_spacing_patterns:
        text = pattern.sub(repl, text)
    return text

archipy.helpers.utils.base_utils.BaseUtils.remove_punctuation_marks classmethod 

remove_punctuation_marks(text: str) -> str

Removes punctuation marks from the text.

Parameters:

Name Type Description Default
text str

The input text containing punctuation marks.

 required

Returns:

Name Type Description
str str

The text with punctuation marks removed.
Source code in archipy/helpers/utils/string_utils.py 
148
149
150
151
152
153
154
155
156
157
158
@classmethod
def remove_punctuation_marks(cls, text: str) -> str:
    """Removes punctuation marks from the text.

    Args:
        text (str): The input text containing punctuation marks.

    Returns:
        str: The text with punctuation marks removed.
    """
    return text.translate(cls.punctuation_persian_marks_to_space_translate_table)

archipy.helpers.utils.base_utils.BaseUtils.mask_urls classmethod 

mask_urls(text: str, mask: str | None = None) -> str

Masks URLs in the text with a specified mask.

Parameters:

Name Type Description Default
text str

The input text containing URLs.

 required
mask str | None

The mask to replace URLs with. Defaults to "MASK_URL".

 None

Returns:

Name Type Description
str str

The text with URLs masked.
Source code in archipy/helpers/utils/string_utils.py 
160
161
162
163
164
165
166
167
168
169
170
171
172
@classmethod
def mask_urls(cls, text: str, mask: str | None = None) -> str:
    """Masks URLs in the text with a specified mask.

    Args:
        text (str): The input text containing URLs.
        mask (str | None): The mask to replace URLs with. Defaults to "MASK_URL".

    Returns:
        str: The text with URLs masked.
    """
    mask = mask or "MASK_URL"
    return re_compile(r"https?://\S+|www\.\S+").sub(f" {mask} ", text)

archipy.helpers.utils.base_utils.BaseUtils.mask_emails classmethod 

mask_emails(text: str, mask: str | None = None) -> str

Masks email addresses in the text with a specified mask.

Parameters:

Name Type Description Default
text str

The input text containing email addresses.

 required
mask str | None

The mask to replace emails with. Defaults to "MASK_EMAIL".

 None

Returns:

Name Type Description
str str

The text with email addresses masked.
Source code in archipy/helpers/utils/string_utils.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
@classmethod
def mask_emails(cls, text: str, mask: str | None = None) -> str:
    """Masks email addresses in the text with a specified mask.

    Args:
        text (str): The input text containing email addresses.
        mask (str | None): The mask to replace emails with. Defaults to "MASK_EMAIL".

    Returns:
        str: The text with email addresses masked.
    """
    mask = mask or "MASK_EMAIL"
    return re_compile(r"\S+@\S+\.\S+").sub(f" {mask} ", text)

archipy.helpers.utils.base_utils.BaseUtils.mask_phones classmethod 

mask_phones(text: str, mask: str | None = None) -> str

Masks phone numbers in the text with a specified mask.

Parameters:

Name Type Description Default
text str

The input text containing phone numbers.

 required
mask str | None

The mask to replace phone numbers with. Defaults to "MASK_PHONE".

 None

Returns:

Name Type Description
str str

The text with phone numbers masked.
Source code in archipy/helpers/utils/string_utils.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
@classmethod
def mask_phones(cls, text: str, mask: str | None = None) -> str:
    """Masks phone numbers in the text with a specified mask.

    Args:
        text (str): The input text containing phone numbers.
        mask (str | None): The mask to replace phone numbers with. Defaults to "MASK_PHONE".

    Returns:
        str: The text with phone numbers masked.
    """
    mask = mask or "MASK_PHONE"
    return re_compile(r"(?:\+98|0)?(?:\d{3}\s*?\d{3}\s*?\d{4})").sub(f" {mask} ", text)

archipy.helpers.utils.base_utils.BaseUtils.convert_english_number_to_persian classmethod 

convert_english_number_to_persian(text: str) -> str

Converts English numbers to Persian numbers in the text.

Parameters:

Name Type Description Default
text str

The input text containing English numbers.

 required

Returns:

Name Type Description
str str

The text with English numbers converted to Persian numbers.
Source code in archipy/helpers/utils/string_utils.py 
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
@classmethod
def convert_english_number_to_persian(cls, text: str) -> str:
    """Converts English numbers to Persian numbers in the text.

    Args:
        text (str): The input text containing English numbers.

    Returns:
        str: The text with English numbers converted to Persian numbers.
    """
    table = {
        48: 1776,  # 0
        49: 1777,  # 1
        50: 1778,  # 2
        51: 1779,  # 3
        52: 1780,  # 4
        53: 1781,  # 5
        54: 1782,  # 6
        55: 1783,  # 7
        56: 1784,  # 8
        57: 1785,  # 9
        44: 1548,  # ,
    }
    return text.translate(table)

archipy.helpers.utils.base_utils.BaseUtils.convert_numbers_to_english classmethod 

convert_numbers_to_english(text: str) -> str

Converts Persian/Arabic numbers to English numbers in the text.

Parameters:

Name Type Description Default
text str

The input text containing Persian/Arabic numbers.

 required

Returns:

Name Type Description
str str

The text with Persian/Arabic numbers converted to English numbers.
Source code in archipy/helpers/utils/string_utils.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
@classmethod
def convert_numbers_to_english(cls, text: str) -> str:
    """Converts Persian/Arabic numbers to English numbers in the text.

    Args:
        text (str): The input text containing Persian/Arabic numbers.

    Returns:
        str: The text with Persian/Arabic numbers converted to English numbers.
    """
    table = {
        1776: 48,  # 0
        1777: 49,  # 1
        1778: 50,  # 2
        1779: 51,  # 3
        1780: 52,  # 4
        1781: 53,  # 5
        1782: 54,  # 6
        1783: 55,  # 7
        1784: 56,  # 8
        1785: 57,  # 9
        1632: 48,  # 0
        1633: 49,  # 1
        1634: 50,  # 2
        1635: 51,  # 3
        1636: 52,  # 4
        1637: 53,  # 5
        1638: 54,  # 6
        1639: 55,  # 7
        1640: 56,  # 8
        1641: 57,  # 9
    }
    return text.translate(table)

archipy.helpers.utils.base_utils.BaseUtils.convert_add_3digit_delimiter classmethod 

convert_add_3digit_delimiter(value: int) -> str

Adds thousand separators to numbers.

Parameters:

Name Type Description Default
value int

The number to format.

 required

Returns:

Name Type Description
str str

The formatted number with thousand separators.
Source code in archipy/helpers/utils/string_utils.py 
261
262
263
264
265
266
267
268
269
270
271
@classmethod
def convert_add_3digit_delimiter(cls, value: int) -> str:
    """Adds thousand separators to numbers.

    Args:
        value (int): The number to format.

    Returns:
        str: The formatted number with thousand separators.
    """
    return f"{value:,}" if isinstance(value, int) else value

archipy.helpers.utils.base_utils.BaseUtils.remove_emoji classmethod 

remove_emoji(text: str) -> str

Removes emoji characters from the text.

Parameters:

Name Type Description Default
text str

The input text containing emojis.

 required

Returns:

Name Type Description
str str

The text with emojis removed.
Source code in archipy/helpers/utils/string_utils.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
@classmethod
def remove_emoji(cls, text: str) -> str:
    """Removes emoji characters from the text.

    Args:
        text (str): The input text containing emojis.

    Returns:
        str: The text with emojis removed.
    """
    emoji_pattern = re.compile(
        r"["
        r"\U0001F600-\U0001F64F"  # emoticons
        r"\U0001F300-\U0001F5FF"  # symbols & pictographs
        r"\U0001F680-\U0001F6FF"  # transport & map symbols
        r"\U0001F1E0-\U0001F1FF"  # flags
        r"\U0001F900-\U0001F9FF"  # supplemental symbols and pictographs
        r"\U0001FA00-\U0001FA6F"  # symbols and pictographs extended-A
        r"\U00002600-\U000026FF"  # miscellaneous symbols (some are emojis)
        r"\U00002700-\U000027BF"  # dingbats (some are emojis)
        r"\U00002190-\U000021FF"  # arrows (some are emojis)
        r"]+",
        re.UNICODE,
    )
    return emoji_pattern.sub(r"", text)

archipy.helpers.utils.base_utils.BaseUtils.replace_currencies_with_mask classmethod 

replace_currencies_with_mask(
    text: str, mask: str | None = None
) -> str

Masks currency symbols and amounts in the text.

Parameters:

Name Type Description Default
text str

The input text containing currency symbols and amounts.

 required
mask str | None

The mask to replace currencies with. Defaults to "MASK_CURRENCIES".

 None

Returns:

Name Type Description
str str

The text with currency symbols and amounts masked.
Source code in archipy/helpers/utils/string_utils.py 
299
300
301
302
303
304
305
306
307
308
309
310
311
312
@classmethod
def replace_currencies_with_mask(cls, text: str, mask: str | None = None) -> str:
    """Masks currency symbols and amounts in the text.

    Args:
        text (str): The input text containing currency symbols and amounts.
        mask (str | None): The mask to replace currencies with. Defaults to "MASK_CURRENCIES".

    Returns:
        str: The text with currency symbols and amounts masked.
    """
    mask = mask or "MASK_CURRENCIES"
    currency_pattern = re_compile(r"(\\|zł|£|\$|₡|₦|¥|₩|₪|₫|€|₱|₲|₴|₹|﷼)+")
    return currency_pattern.sub(f" {mask} ", text)

archipy.helpers.utils.base_utils.BaseUtils.replace_numbers_with_mask classmethod 

replace_numbers_with_mask(
    text: str, mask: str | None = None
) -> str

Masks numbers in the text.

Parameters:

Name Type Description Default
text str

The input text containing numbers.

 required
mask str | None

The mask to replace numbers with. Defaults to "MASK_NUMBERS".

 None

Returns:

Name Type Description
str str

The text with numbers masked.
Source code in archipy/helpers/utils/string_utils.py 
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
@classmethod
def replace_numbers_with_mask(cls, text: str, mask: str | None = None) -> str:
    """Masks numbers in the text.

    Args:
        text (str): The input text containing numbers.
        mask (str | None): The mask to replace numbers with. Defaults to "MASK_NUMBERS".

    Returns:
        str: The text with numbers masked.
    """
    mask = mask or "MASK_NUMBERS"
    numbers = re.findall("[0-9]+", text)
    result: str = text
    for number in sorted(numbers, key=len, reverse=True):
        result = result.replace(number, f" {mask} ")  # type: ignore[arg-type]
    return result

archipy.helpers.utils.base_utils.BaseUtils.is_string_none_or_empty classmethod 

is_string_none_or_empty(text: str) -> bool

Checks if a string is None or empty (after stripping whitespace).

Parameters:

Name Type Description Default
text str

The input string to check.

 required

Returns:

Name Type Description
bool bool

True if the string is None or empty, False otherwise.
Source code in archipy/helpers/utils/string_utils.py 
332
333
334
335
336
337
338
339
340
341
342
@classmethod
def is_string_none_or_empty(cls, text: str) -> bool:
    """Checks if a string is `None` or empty (after stripping whitespace).

    Args:
        text (str): The input string to check.

    Returns:
        bool: `True` if the string is `None` or empty, `False` otherwise.
    """
    return text is None or (isinstance(text, str) and not text.strip())

archipy.helpers.utils.base_utils.BaseUtils.normalize_persian_text classmethod 

normalize_persian_text(
    text: str,
    *,
    remove_vowels: bool = True,
    normalize_punctuation: bool = True,
    normalize_numbers: bool = True,
    normalize_persian_chars: bool = True,
    mask_urls: bool = False,
    mask_emails: bool = False,
    mask_phones: bool = False,
    mask_currencies: bool = False,
    mask_all_numbers: bool = False,
    remove_emojis: bool = False,
    url_mask: str | None = None,
    email_mask: str | None = None,
    phone_mask: str | None = None,
    currency_mask: str | None = None,
    number_mask: str | None = None,
    clean_spacing: bool = True,
    remove_punctuation: bool = False,
    normalize_punctuation_spacing: bool = False,
) -> str

Normalizes Persian text with configurable options.

Parameters:

Name Type Description Default
text str

The input text to normalize.

 required
remove_vowels bool

Whether to remove Arabic vowels. Defaults to True.

 True
normalize_punctuation bool

Whether to normalize punctuation marks. Defaults to True.

 True
normalize_numbers bool

Whether to normalize numbers to English format. Defaults to True.

 True
normalize_persian_chars bool

Whether to normalize Persian characters. Defaults to True.

 True
mask_urls bool

Whether to mask URLs. Defaults to False.

 False
mask_emails bool

Whether to mask email addresses. Defaults to False.

 False
mask_phones bool

Whether to mask phone numbers. Defaults to False.

 False
mask_currencies bool

Whether to mask currency symbols and amounts. Defaults to False.

 False
mask_all_numbers bool

Whether to mask all numbers. Defaults to False.

 False
remove_emojis bool

Whether to remove emojis. Defaults to False.

 False
url_mask str | None

The mask to replace URLs with. Defaults to None.

 None
email_mask str | None

The mask to replace email addresses with. Defaults to None.

 None
phone_mask str | None

The mask to replace phone numbers with. Defaults to None.

 None
currency_mask str | None

The mask to replace currency symbols and amounts with. Defaults to None.

 None
number_mask str | None

The mask to replace numbers with. Defaults to None.

 None
clean_spacing bool

Whether to clean up spacing issues. Defaults to True.

 True
remove_punctuation bool

Whether to remove punctuation marks. Defaults to False.

 False
normalize_punctuation_spacing bool

Whether to apply proper spacing around punctuation marks. Defaults to False.

 False

Returns:

Name Type Description
str str

The normalized text.
Source code in archipy/helpers/utils/string_utils.py 
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
@classmethod
def normalize_persian_text(
    cls,
    text: str,
    *,
    remove_vowels: bool = True,
    normalize_punctuation: bool = True,
    normalize_numbers: bool = True,
    normalize_persian_chars: bool = True,
    mask_urls: bool = False,
    mask_emails: bool = False,
    mask_phones: bool = False,
    mask_currencies: bool = False,
    mask_all_numbers: bool = False,
    remove_emojis: bool = False,
    url_mask: str | None = None,
    email_mask: str | None = None,
    phone_mask: str | None = None,
    currency_mask: str | None = None,
    number_mask: str | None = None,
    clean_spacing: bool = True,
    remove_punctuation: bool = False,
    normalize_punctuation_spacing: bool = False,
) -> str:
    """Normalizes Persian text with configurable options.

    Args:
        text (str): The input text to normalize.
        remove_vowels (bool): Whether to remove Arabic vowels. Defaults to `True`.
        normalize_punctuation (bool): Whether to normalize punctuation marks. Defaults to `True`.
        normalize_numbers (bool): Whether to normalize numbers to English format. Defaults to `True`.
        normalize_persian_chars (bool): Whether to normalize Persian characters. Defaults to `True`.
        mask_urls (bool): Whether to mask URLs. Defaults to `False`.
        mask_emails (bool): Whether to mask email addresses. Defaults to `False`.
        mask_phones (bool): Whether to mask phone numbers. Defaults to `False`.
        mask_currencies (bool): Whether to mask currency symbols and amounts. Defaults to `False`.
        mask_all_numbers (bool): Whether to mask all numbers. Defaults to `False`.
        remove_emojis (bool): Whether to remove emojis. Defaults to `False`.
        url_mask (str | None): The mask to replace URLs with. Defaults to `None`.
        email_mask (str | None): The mask to replace email addresses with. Defaults to `None`.
        phone_mask (str | None): The mask to replace phone numbers with. Defaults to `None`.
        currency_mask (str | None): The mask to replace currency symbols and amounts with. Defaults to `None`.
        number_mask (str | None): The mask to replace numbers with. Defaults to `None`.
        clean_spacing (bool): Whether to clean up spacing issues. Defaults to `True`.
        remove_punctuation (bool): Whether to remove punctuation marks. Defaults to `False`.
        normalize_punctuation_spacing (bool): Whether to apply proper spacing around punctuation marks. Defaults to `False`.

    Returns:
        str: The normalized text.
    """
    if not text:
        return text

    # Remove emojis if requested
    if remove_emojis:
        text = cls.remove_emoji(text)

    # Apply normalizations
    if remove_vowels:
        text = cls.remove_arabic_vowels(text)
    if normalize_persian_chars:
        text = cls.normalize_persian_chars(text)
    if normalize_punctuation:
        text = cls.normalize_punctuation(text)
    if remove_punctuation:
        text = cls.remove_punctuation_marks(text)
    if normalize_numbers:
        text = cls.normalize_numbers(text)

    # Apply masking
    if mask_urls:
        text = cls.mask_urls(text, mask=url_mask)
    if mask_emails:
        text = cls.mask_emails(text, mask=email_mask)
    if mask_phones:
        text = cls.mask_phones(text, mask=phone_mask)
    if mask_currencies:
        text = cls.replace_currencies_with_mask(text, mask=currency_mask)
    if mask_all_numbers:
        text = cls.replace_numbers_with_mask(text, mask=number_mask)

    if clean_spacing:
        text = cls.clean_spacing(text)
    if normalize_punctuation_spacing:
        text = cls.normalize_punctuation_spacing(text)

    return text.strip()

archipy.helpers.utils.base_utils.BaseUtils.snake_to_camel_case classmethod 

snake_to_camel_case(text: str) -> str

Converts snake_case to camelCase.

Parameters:

Name Type Description Default
text str

The input text in snake_case format.

 required

Returns:

Name Type Description
str str

The text converted to camelCase format.
Source code in archipy/helpers/utils/string_utils.py 
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
@classmethod
def snake_to_camel_case(cls, text: str) -> str:
    """Converts snake_case to camelCase.

    Args:
        text (str): The input text in snake_case format.

    Returns:
        str: The text converted to camelCase format.
    """
    if cls.is_string_none_or_empty(text):
        return text

    components = text.split("_")
    # First component remains lowercase, the rest get capitalized
    return components[0] + "".join(x.title() for x in components[1:])

archipy.helpers.utils.base_utils.BaseUtils.camel_to_snake_case classmethod 

camel_to_snake_case(text: str) -> str

Converts camelCase to snake_case.

Parameters:

Name Type Description Default
text str

The input text in camelCase format.

 required

Returns:

Name Type Description
str str

The text converted to snake_case format.
Source code in archipy/helpers/utils/string_utils.py 
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
@classmethod
def camel_to_snake_case(cls, text: str) -> str:
    """Converts camelCase to snake_case.

    Args:
        text (str): The input text in camelCase format.

    Returns:
        str: The text converted to snake_case format.
    """
    if cls.is_string_none_or_empty(text):
        return text

    # Add underscore before each capital letter and convert to lowercase
    s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", text)
    return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()

create_secure_link(
    path: str,
    minutes: int | None = None,
    file_config: FileConfig | None = None,
) -> str

Creates a secure link with expiration for file access.

Parameters:

Name Type Description Default
path str

The file path to create a secure link for.

 required
minutes int | None

Number of minutes until link expiration. Defaults to the config's DEFAULT_EXPIRY_MINUTES.

 None
file_config FileConfig | None

Optional file configuration object. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

A secure link with a hash and expiration timestamp.

Raises:

Type Description
InvalidArgumentError

If the path is empty.
OutOfRangeError

If minutes is less than 1.
Source code in archipy/helpers/utils/file_utils.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
@classmethod
def create_secure_link(
    cls,
    path: str,
    minutes: int | None = None,
    file_config: FileConfig | None = None,
) -> str:
    """Creates a secure link with expiration for file access.

    Args:
        path (str): The file path to create a secure link for.
        minutes (int | None): Number of minutes until link expiration. Defaults to the config's `DEFAULT_EXPIRY_MINUTES`.
        file_config (FileConfig | None): Optional file configuration object. If not provided, uses the global config.

    Returns:
        str: A secure link with a hash and expiration timestamp.

    Raises:
        InvalidArgumentError: If the `path` is empty.
        OutOfRangeError: If `minutes` is less than 1.
    """
    if not path:
        raise InvalidArgumentError(argument_name="path")

    configs: FileConfig = file_config or BaseConfig.global_config().FILE
    expiry_minutes: int = minutes if minutes is not None else configs.DEFAULT_EXPIRY_MINUTES

    if expiry_minutes < 1:
        raise OutOfRangeError(field_name="minutes")

    expires_at = int(DatetimeUtils.get_datetime_after_given_datetime_or_now(minutes=expiry_minutes).timestamp())
    secure_link_hash = cls._create_secure_link_hash(path, expires_at, file_config)

    return f"{path}?md5={secure_link_hash}&expires_at={expires_at}"

archipy.helpers.utils.base_utils.BaseUtils.validate_file_name classmethod 

validate_file_name(
    file_name: str, file_config: FileConfig | None = None
) -> bool

Validates a file name based on allowed extensions.

Parameters:

Name Type Description Default
file_name str

The file name to validate.

 required
file_config FileConfig | None

Optional file configuration object. If not provided, uses the global config.

 None

Returns:

Name Type Description
bool bool

True if the file name has an allowed extension, False otherwise.

Raises:

Type Description
InvalidArgumentError

If file_name is not a string or allowed_extensions is not a list.
Source code in archipy/helpers/utils/file_utils.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
@classmethod
def validate_file_name(
    cls,
    file_name: str,
    file_config: FileConfig | None = None,
) -> bool:
    """Validates a file name based on allowed extensions.

    Args:
        file_name (str): The file name to validate.
        file_config (FileConfig | None): Optional file configuration object. If not provided, uses the global config.

    Returns:
        bool: `True` if the file name has an allowed extension, `False` otherwise.

    Raises:
        InvalidArgumentError: If `file_name` is not a string or `allowed_extensions` is not a list.
    """
    configs: FileConfig = file_config or BaseConfig.global_config().FILE
    allowed_extensions: list[str] = configs.ALLOWED_EXTENSIONS

    if not isinstance(file_name, str):
        raise InvalidArgumentError(argument_name="file_name")

    if not allowed_extensions:
        raise InvalidArgumentError(argument_name="allowed_extensions")

    file_path = Path(file_name)
    ext = file_path.suffix[1:].lower()
    return ext in allowed_extensions and bool(ext)

archipy.helpers.utils.base_utils.BaseUtils.generate_totp classmethod 

generate_totp(
    secret: str | UUID,
    auth_config: AuthConfig | None = None,
) -> tuple[str, datetime]

Generates a TOTP code using the configured hash algorithm.

Parameters:

Name Type Description Default
secret str | UUID

The secret key used to generate the TOTP code.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
tuple[str, datetime]

A tuple containing the generated TOTP code and its expiration time.

Raises:

Type Description
InvalidArgumentError

If the secret is invalid or empty.
Source code in archipy/helpers/utils/totp_utils.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
@classmethod
def generate_totp(cls, secret: str | UUID, auth_config: AuthConfig | None = None) -> tuple[str, datetime]:
    """Generates a TOTP code using the configured hash algorithm.

    Args:
        secret: The secret key used to generate the TOTP code.
        auth_config: Optional auth configuration override. If not provided, uses the global config.

    Returns:
        A tuple containing the generated TOTP code and its expiration time.

    Raises:
        InvalidArgumentError: If the secret is invalid or empty.
    """
    if not secret:
        raise InvalidArgumentError(
            argument_name="secret",
        )

    configs = auth_config or BaseConfig.global_config().AUTH

    # Convert secret to bytes if it's UUID
    if isinstance(secret, UUID):
        secret = str(secret)

    # Get current timestamp and calculate time step
    current_time = DatetimeUtils.get_epoch_time_now()
    time_step_counter = int(current_time / configs.TOTP_TIME_STEP)

    # Generate HMAC hash
    secret_bytes = str(secret).encode("utf-8")
    time_bytes = struct.pack(">Q", time_step_counter)

    # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
    hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

    hmac_obj = hmac.new(secret_bytes, time_bytes, hash_algo)
    hmac_result = hmac_obj.digest()

    # Get offset and truncate
    offset = hmac_result[-1] & 0xF
    truncated_hash = (
        ((hmac_result[offset] & 0x7F) << 24)
        | ((hmac_result[offset + 1] & 0xFF) << 16)
        | ((hmac_result[offset + 2] & 0xFF) << 8)
        | (hmac_result[offset + 3] & 0xFF)
    )

    # Generate TOTP code
    totp_code = str(truncated_hash % (10**configs.TOTP_LENGTH)).zfill(configs.TOTP_LENGTH)

    # Calculate expiration time
    expires_in = DatetimeUtils.get_datetime_after_given_datetime_or_now(seconds=configs.TOTP_EXPIRES_IN)

    return totp_code, expires_in

archipy.helpers.utils.base_utils.BaseUtils.verify_totp classmethod 

verify_totp(
    secret: str | UUID,
    totp_code: str,
    auth_config: AuthConfig | None = None,
) -> bool

Verifies a TOTP code against the provided secret.

Parameters:

Name Type Description Default
secret str | UUID

The secret key used to generate the TOTP code.

 required
totp_code str

The TOTP code to verify.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
bool

True if the TOTP code is valid, False otherwise.

Raises:

Type Description
InvalidArgumentError

If the secret is invalid or empty.
InvalidTokenError

If the TOTP code format is invalid.
Source code in archipy/helpers/utils/totp_utils.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
@classmethod
def verify_totp(cls, secret: str | UUID, totp_code: str, auth_config: AuthConfig | None = None) -> bool:
    """Verifies a TOTP code against the provided secret.

    Args:
        secret: The secret key used to generate the TOTP code.
        totp_code: The TOTP code to verify.
        auth_config: Optional auth configuration override. If not provided, uses the global config.

    Returns:
        `True` if the TOTP code is valid, `False` otherwise.

    Raises:
        InvalidArgumentError: If the secret is invalid or empty.
        InvalidTokenError: If the TOTP code format is invalid.
    """
    if not secret:
        raise InvalidArgumentError(
            argument_name="secret",
        )

    if not totp_code:
        raise InvalidArgumentError(
            argument_name="totp_code",
        )

    if not totp_code.isdigit():
        raise InvalidTokenError

    configs = auth_config or BaseConfig.global_config().AUTH

    current_time = DatetimeUtils.get_epoch_time_now()

    # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
    hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

    # Check codes within verification window
    for i in range(-configs.TOTP_VERIFICATION_WINDOW, configs.TOTP_VERIFICATION_WINDOW + 1):
        time_step_counter = int(current_time / configs.TOTP_TIME_STEP) + i

        secret_bytes = str(secret).encode("utf-8")
        time_bytes = struct.pack(">Q", time_step_counter)
        hmac_obj = hmac.new(secret_bytes, time_bytes, hash_algo)
        hmac_result = hmac_obj.digest()

        offset = hmac_result[-1] & 0xF
        truncated_hash = (
            ((hmac_result[offset] & 0x7F) << 24)
            | ((hmac_result[offset + 1] & 0xFF) << 16)
            | ((hmac_result[offset + 2] & 0xFF) << 8)
            | (hmac_result[offset + 3] & 0xFF)
        )

        computed_totp = str(truncated_hash % (10 ** len(totp_code))).zfill(len(totp_code))

        if hmac.compare_digest(totp_code, computed_totp):
            return True

    return False

archipy.helpers.utils.base_utils.BaseUtils.generate_secret_key_for_totp staticmethod 

generate_secret_key_for_totp(
    auth_config: AuthConfig | None = None,
) -> str

Generates a random secret key for TOTP initialization.

Parameters:

Name Type Description Default
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
str

A base32-encoded secret key for TOTP initialization.

Raises:

Type Description
InvalidArgumentError

If the TOTP_SECRET_KEY is not configured.
InternalError

If there is an error generating the secret key.
Source code in archipy/helpers/utils/totp_utils.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
@staticmethod
def generate_secret_key_for_totp(auth_config: AuthConfig | None = None) -> str:
    """Generates a random secret key for TOTP initialization.

    Args:
        auth_config: Optional auth configuration override. If not provided, uses the global config.

    Returns:
        A base32-encoded secret key for TOTP initialization.

    Raises:
        InvalidArgumentError: If the TOTP_SECRET_KEY is not configured.
        InternalError: If there is an error generating the secret key.
    """
    try:
        configs = auth_config or BaseConfig.global_config().AUTH

        # Use secrets module instead of random for better security
        random_bytes = secrets.token_bytes(configs.SALT_LENGTH)

        # Check if TOTP secret key is configured
        if not configs.TOTP_SECRET_KEY:
            # Disable linter for this specific case since we're already in a try-except block
            # and creating nested functions would reduce code readability
            raise InvalidArgumentError(
                argument_name="TOTP_SECRET_KEY",
            )

        master_key = configs.TOTP_SECRET_KEY.get_secret_value().encode("utf-8")

        # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
        hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

        # Use HMAC with master key for additional security
        hmac_obj = hmac.new(master_key, random_bytes, hash_algo)
        return base64.b32encode(hmac_obj.digest()).decode("utf-8")
    except Exception as e:
        # Convert any errors to our custom errors
        raise InternalError() from e

archipy.helpers.utils.base_utils.BaseUtils.create_token classmethod 

create_token(
    data: dict[str, Any],
    expires_in: int,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str

Creates a JWT token with enhanced security features.

Parameters:

Name Type Description Default
data dict[str, Any]

Base claims data to include in the token.

 required
expires_in int

Token expiration time in seconds.

 required
additional_claims dict[str, Any] | None

Optional additional claims to include in the token.

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

The encoded JWT token.

Raises:

Type Description
ValueError

If data is empty or expiration is invalid
Source code in archipy/helpers/utils/jwt_utils.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@classmethod
def create_token(
    cls,
    data: dict[str, Any],
    expires_in: int,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str:
    """Creates a JWT token with enhanced security features.

    Args:
        data (dict[str, Any]): Base claims data to include in the token.
        expires_in (int): Token expiration time in seconds.
        additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        str: The encoded JWT token.

    Raises:
        ValueError: If data is empty or expiration is invalid
    """
    import jwt

    configs = auth_config or BaseConfig.global_config().AUTH
    current_time = DatetimeUtils.get_datetime_utc_now()

    # Define argument names
    arg_data = "data"
    arg_expires_in = "expires_in"

    if not data:
        raise InvalidArgumentError(arg_data)
    if expires_in <= 0:
        raise InvalidArgumentError(arg_expires_in)

    to_encode = data.copy()
    expire = DatetimeUtils.get_datetime_after_given_datetime_or_now(seconds=expires_in, datetime_given=current_time)

    # Add standard claims
    to_encode.update(
        {
            # Registered claims (RFC 7519)
            "iss": configs.JWT_ISSUER,
            "aud": configs.JWT_AUDIENCE,
            "exp": expire,
            "iat": current_time,
            "nbf": current_time,
        },
    )

    # Add JWT ID if enabled
    if configs.ENABLE_JTI_CLAIM:
        to_encode["jti"] = str(uuid4())

    # Add additional claims
    if additional_claims:
        to_encode.update(additional_claims)

    # Validate SECRET_KEY
    secret_key = configs.SECRET_KEY
    if secret_key is None:
        raise InvalidArgumentError("SECRET_KEY")
    return jwt.encode(to_encode, secret_key.get_secret_value(), algorithm=configs.HASH_ALGORITHM)

archipy.helpers.utils.base_utils.BaseUtils.create_access_token classmethod 

create_access_token(
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str

Creates an access token for a user.

Parameters:

Name Type Description Default
user_uuid UUID

The user's UUID to include in the token.

 required
additional_claims dict[str, Any] | None

Optional additional claims to include in the token.

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

The encoded access token.
Source code in archipy/helpers/utils/jwt_utils.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
@classmethod
def create_access_token(
    cls,
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str:
    """Creates an access token for a user.

    Args:
        user_uuid (UUID): The user's UUID to include in the token.
        additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        str: The encoded access token.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    return cls.create_token(
        data={
            "sub": str(user_uuid),
            "type": "access",
            "token_version": configs.TOKEN_VERSION,
        },
        expires_in=configs.ACCESS_TOKEN_EXPIRES_IN,
        additional_claims=additional_claims,
        auth_config=configs,
    )

archipy.helpers.utils.base_utils.BaseUtils.create_refresh_token classmethod 

create_refresh_token(
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str

Creates a refresh token for a user.

Parameters:

Name Type Description Default
user_uuid UUID

The user's UUID to include in the token.

 required
additional_claims dict[str, Any] | None

Optional additional claims to include in the token.

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

The encoded refresh token.
Source code in archipy/helpers/utils/jwt_utils.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
@classmethod
def create_refresh_token(
    cls,
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str:
    """Creates a refresh token for a user.

    Args:
        user_uuid (UUID): The user's UUID to include in the token.
        additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        str: The encoded refresh token.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    return cls.create_token(
        data={
            "sub": str(user_uuid),
            "type": "refresh",
            "token_version": configs.TOKEN_VERSION,
        },
        expires_in=configs.REFRESH_TOKEN_EXPIRES_IN,
        additional_claims=additional_claims,
        auth_config=configs,
    )

archipy.helpers.utils.base_utils.BaseUtils.decode_token classmethod 

decode_token(
    token: str,
    verify_type: str | None = None,
    auth_config: AuthConfig | None = None,
) -> dict[str, Any]

Decodes and verifies a JWT token with enhanced security checks.

Parameters:

Name Type Description Default
token str

The JWT token to decode.

 required
verify_type str | None

Optional token type to verify (e.g., "access" or "refresh").

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
dict[str, Any]

dict[str, Any]: The decoded token payload.

Raises:

Type Description
TokenExpiredError

If the token has expired.
InvalidTokenError

If the token is invalid (e.g., invalid signature, audience, issuer, or type).
Source code in archipy/helpers/utils/jwt_utils.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
@classmethod
def decode_token(
    cls,
    token: str,
    verify_type: str | None = None,
    auth_config: AuthConfig | None = None,
) -> dict[str, Any]:
    """Decodes and verifies a JWT token with enhanced security checks.

    Args:
        token (str): The JWT token to decode.
        verify_type (str | None): Optional token type to verify (e.g., "access" or "refresh").
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        dict[str, Any]: The decoded token payload.

    Raises:
        TokenExpiredError: If the token has expired.
        InvalidTokenError: If the token is invalid (e.g., invalid signature, audience, issuer, or type).
    """
    import jwt
    from jwt.exceptions import (
        ExpiredSignatureError,
        InvalidAudienceError,
        InvalidIssuerError,
        InvalidSignatureError,
        InvalidTokenError as JWTInvalidTokenError,
    )

    configs = auth_config or BaseConfig.global_config().AUTH
    required_claims = ["exp", "iat", "nbf", "aud", "iss", "sub", "type", "token_version"]
    if configs.ENABLE_JTI_CLAIM:
        required_claims.append("jti")

    try:
        # Validate SECRET_KEY
        secret_key = configs.SECRET_KEY
        if secret_key is None:
            raise InvalidArgumentError("SECRET_KEY")

        payload = jwt.decode(
            token,
            secret_key.get_secret_value(),
            algorithms=[configs.HASH_ALGORITHM],
            options={
                "verify_signature": True,
                "verify_exp": True,
                "verify_nbf": True,
                "verify_iat": True,
                "verify_aud": True,
                "verify_iss": True,
                "require": required_claims,
            },
            audience=configs.JWT_AUDIENCE,
            issuer=configs.JWT_ISSUER,
        )

        # Verify token type
        if verify_type and payload.get("type") != verify_type:
            raise InvalidTokenError

        # Verify token version
        if payload.get("token_version") != configs.TOKEN_VERSION:
            raise InvalidTokenError

        # Ensure the return type is dict[str, Any] as declared
        return dict(payload)

    except ExpiredSignatureError as exception:
        raise TokenExpiredError from exception
    except InvalidSignatureError as exception:
        raise InvalidTokenError from exception
    except InvalidAudienceError as exception:
        raise InvalidTokenError from exception
    except InvalidIssuerError as exception:
        raise InvalidTokenError from exception
    except JWTInvalidTokenError as exception:
        raise InvalidTokenError from exception

archipy.helpers.utils.base_utils.BaseUtils.verify_access_token classmethod 

verify_access_token(
    token: str, auth_config: AuthConfig | None = None
) -> dict[str, Any]

Verifies an access token.

Parameters:

Name Type Description Default
token str

The access token to verify.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
dict[str, Any]

dict[str, Any]: The decoded access token payload.

Raises:

Type Description
InvalidTokenException

If the token is invalid or not an access token.
TokenExpiredException

If the token has expired.
Source code in archipy/helpers/utils/jwt_utils.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
@classmethod
def verify_access_token(cls, token: str, auth_config: AuthConfig | None = None) -> dict[str, Any]:
    """Verifies an access token.

    Args:
        token (str): The access token to verify.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        dict[str, Any]: The decoded access token payload.

    Raises:
        InvalidTokenException: If the token is invalid or not an access token.
        TokenExpiredException: If the token has expired.
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    return cls.decode_token(token, verify_type="access", auth_config=configs)

archipy.helpers.utils.base_utils.BaseUtils.verify_refresh_token classmethod 

verify_refresh_token(
    token: str, auth_config: AuthConfig | None = None
) -> dict[str, Any]

Verifies a refresh token.

Parameters:

Name Type Description Default
token str

The refresh token to verify.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
dict[str, Any]

dict[str, Any]: The decoded refresh token payload.

Raises:

Type Description
InvalidTokenException

If the token is invalid or not a refresh token.
TokenExpiredException

If the token has expired.
Source code in archipy/helpers/utils/jwt_utils.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
@classmethod
def verify_refresh_token(cls, token: str, auth_config: AuthConfig | None = None) -> dict[str, Any]:
    """Verifies a refresh token.

    Args:
        token (str): The refresh token to verify.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        dict[str, Any]: The decoded refresh token payload.

    Raises:
        InvalidTokenException: If the token is invalid or not a refresh token.
        TokenExpiredException: If the token has expired.
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    return cls.decode_token(token, verify_type="refresh", auth_config=configs)

archipy.helpers.utils.base_utils.BaseUtils.extract_user_uuid staticmethod 

extract_user_uuid(payload: dict[str, Any]) -> UUID

Extracts the user UUID from the token payload.

Parameters:

Name Type Description Default
payload dict[str, Any]

The decoded token payload.

 required

Returns:

Name Type Description
UUID UUID

The user's UUID.

Raises:

Type Description
InvalidTokenException

If the user identifier is invalid or missing.
Source code in archipy/helpers/utils/jwt_utils.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
@staticmethod
def extract_user_uuid(payload: dict[str, Any]) -> UUID:
    """Extracts the user UUID from the token payload.

    Args:
        payload (dict[str, Any]): The decoded token payload.

    Returns:
        UUID: The user's UUID.

    Raises:
        InvalidTokenException: If the user identifier is invalid or missing.
    """
    try:
        return UUID(payload["sub"])
    except (KeyError, ValueError) as exception:
        raise InvalidTokenError from exception

archipy.helpers.utils.base_utils.BaseUtils.get_token_expiry classmethod 

get_token_expiry(
    token: str, auth_config: AuthConfig | None = None
) -> int

Gets the token expiry timestamp.

Parameters:

Name Type Description Default
token str

The JWT token.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
int int

The token expiry timestamp in seconds.

Raises:

Type Description
InvalidTokenException

If the token is invalid.
Source code in archipy/helpers/utils/jwt_utils.py 
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@classmethod
def get_token_expiry(cls, token: str, auth_config: AuthConfig | None = None) -> int:
    """Gets the token expiry timestamp.

    Args:
        token (str): The JWT token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        int: The token expiry timestamp in seconds.

    Raises:
        InvalidTokenException: If the token is invalid.
    """
    payload = cls.decode_token(token, auth_config=auth_config)
    return int(payload["exp"])

archipy.helpers.utils.base_utils.BaseUtils.hash_password staticmethod 

hash_password(
    password: str, auth_config: AuthConfig | None = None
) -> str

Hashes a password using PBKDF2 with SHA256.

Parameters:

Name Type Description Default
password str

The password to hash.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

A base64-encoded string containing the salt and hash in the format "salt:hash".
Source code in archipy/helpers/utils/password_utils.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@staticmethod
def hash_password(password: str, auth_config: AuthConfig | None = None) -> str:
    """Hashes a password using PBKDF2 with SHA256.

    Args:
        password (str): The password to hash.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Returns:
        str: A base64-encoded string containing the salt and hash in the format "salt:hash".
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    salt = os.urandom(configs.SALT_LENGTH)
    pw_hash = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, configs.HASH_ITERATIONS)

    # Combine salt and hash, encode in base64
    return b64encode(salt + pw_hash).decode("utf-8")

archipy.helpers.utils.base_utils.BaseUtils.verify_password staticmethod 

verify_password(
    password: str,
    stored_password: str,
    auth_config: AuthConfig | None = None,
) -> bool

Verifies a password against a stored hash.

Parameters:

Name Type Description Default
password str

The password to verify.

 required
stored_password str

The stored password hash to compare against.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
bool bool

True if the password matches the stored hash, False otherwise.
Source code in archipy/helpers/utils/password_utils.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@staticmethod
def verify_password(password: str, stored_password: str, auth_config: AuthConfig | None = None) -> bool:
    """Verifies a password against a stored hash.

    Args:
        password (str): The password to verify.
        stored_password (str): The stored password hash to compare against.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Returns:
        bool: True if the password matches the stored hash, False otherwise.
    """
    try:
        configs = auth_config or BaseConfig.global_config().AUTH

        # Decode the stored password
        decoded = b64decode(stored_password.encode("utf-8"))
        salt = decoded[: configs.SALT_LENGTH]
        stored_hash = decoded[configs.SALT_LENGTH :]

        # Hash the provided password with the same salt
        pw_hash = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, configs.HASH_ITERATIONS)

        # Compare in constant time to prevent timing attacks
        return hmac.compare_digest(pw_hash, stored_hash)
    except ValueError, TypeError, IndexError:
        # Catch specific exceptions that could occur during decoding or comparison
        return False

archipy.helpers.utils.base_utils.BaseUtils.validate_password staticmethod 

validate_password(
    password: str, auth_config: AuthConfig | None = None
) -> None

Validates a password against the password policy.

Parameters:

Name Type Description Default
password str

The password to validate.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Raises:

Type Description
InvalidPasswordError

If the password does not meet the policy requirements.
Source code in archipy/helpers/utils/password_utils.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
@staticmethod
def validate_password(
    password: str,
    auth_config: AuthConfig | None = None,
) -> None:
    """Validates a password against the password policy.

    Args:
        password (str): The password to validate.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Raises:
        InvalidPasswordError: If the password does not meet the policy requirements.
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    errors = []

    if len(password) < configs.MIN_LENGTH:
        errors.append(f"Password must be at least {configs.MIN_LENGTH} characters long.")

    if configs.REQUIRE_DIGIT and not any(char.isdigit() for char in password):
        errors.append("Password must contain at least one digit.")

    if configs.REQUIRE_LOWERCASE and not any(char.islower() for char in password):
        errors.append("Password must contain at least one lowercase letter.")

    if configs.REQUIRE_UPPERCASE and not any(char.isupper() for char in password):
        errors.append("Password must contain at least one uppercase letter.")

    if configs.REQUIRE_SPECIAL and not any(char in configs.SPECIAL_CHARACTERS for char in password):
        errors.append(f"Password must contain at least one special character: {configs.SPECIAL_CHARACTERS}")

    if errors:
        raise InvalidPasswordError(requirements=errors)

archipy.helpers.utils.base_utils.BaseUtils.generate_password staticmethod 

generate_password(
    auth_config: AuthConfig | None = None,
) -> str

Generates a random password that meets the policy requirements.

Parameters:

Name Type Description Default
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

A randomly generated password that meets the policy requirements.
Source code in archipy/helpers/utils/password_utils.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@staticmethod
def generate_password(auth_config: AuthConfig | None = None) -> str:
    """Generates a random password that meets the policy requirements.

    Args:
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Returns:
        str: A randomly generated password that meets the policy requirements.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    lowercase_chars = string.ascii_lowercase
    uppercase_chars = string.ascii_uppercase
    digit_chars = string.digits
    special_chars = "".join(configs.SPECIAL_CHARACTERS)

    # Initialize with required characters
    password_chars = []
    if configs.REQUIRE_LOWERCASE:
        password_chars.append(secrets.choice(lowercase_chars))
    if configs.REQUIRE_UPPERCASE:
        password_chars.append(secrets.choice(uppercase_chars))
    if configs.REQUIRE_DIGIT:
        password_chars.append(secrets.choice(digit_chars))
    if configs.REQUIRE_SPECIAL:
        password_chars.append(secrets.choice(special_chars))

    # Calculate remaining length
    remaining_length = max(0, configs.MIN_LENGTH - len(password_chars))

    # Add random characters to meet minimum length
    all_chars = lowercase_chars + uppercase_chars + digit_chars + special_chars
    password_chars.extend(secrets.choice(all_chars) for _ in range(remaining_length))

    # Shuffle the password characters
    shuffled = list(password_chars)
    secrets.SystemRandom().shuffle(shuffled)

    return "".join(shuffled)

archipy.helpers.utils.base_utils.BaseUtils.validate_password_history classmethod 

validate_password_history(
    new_password: str,
    password_history: list[str],
    auth_config: AuthConfig | None = None,
    lang: LanguageType | None = None,
) -> None

Validates a new password against the password history.

Parameters:

Name Type Description Default
new_password str

The new password to validate.

 required
password_history list[str]

A list of previous password hashes.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None
lang LanguageType

The language to use for error messages. Defaults to Persian.

 None

Raises:

Type Description
InvalidPasswordError

If the new password has been used recently or does not meet the policy requirements.
Source code in archipy/helpers/utils/password_utils.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
@classmethod
def validate_password_history(
    cls,
    new_password: str,
    password_history: list[str],
    auth_config: AuthConfig | None = None,
    lang: LanguageType | None = None,
) -> None:
    """Validates a new password against the password history.

    Args:
        new_password (str): The new password to validate.
        password_history (list[str]): A list of previous password hashes.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.
        lang (LanguageType): The language to use for error messages. Defaults to Persian.

    Raises:
        InvalidPasswordError: If the new password has been used recently or does not meet the policy requirements.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    # First validate against password policy
    cls.validate_password(new_password, configs)

    # Check password history
    if any(
        cls.verify_password(new_password, old_password, configs)
        for old_password in password_history[-configs.PASSWORD_HISTORY_SIZE :]
    ):
        raise InvalidPasswordError(requirements=["Password has been used recently"], lang=lang)

archipy.helpers.utils.base_utils.BaseUtils.convert_to_jalali staticmethod 

convert_to_jalali(target_date: date) -> jdatetime.date

Converts a Gregorian date to a Jalali (Persian) date.

Parameters:

Name Type Description Default
target_date date

The Gregorian date to convert.

 required

Returns:

Type Description
date

jdatetime.date: The corresponding Jalali date.
Source code in archipy/helpers/utils/datetime_utils.py 
25
26
27
28
29
30
31
32
33
34
35
@staticmethod
def convert_to_jalali(target_date: date) -> jdatetime.date:
    """Converts a Gregorian date to a Jalali (Persian) date.

    Args:
        target_date (date): The Gregorian date to convert.

    Returns:
        jdatetime.date: The corresponding Jalali date.
    """
    return jdatetime.date.fromgregorian(date=target_date)

archipy.helpers.utils.base_utils.BaseUtils.is_holiday_in_iran classmethod 

is_holiday_in_iran(target_date: date) -> bool

Determines if the target date is a holiday in Iran.

This method leverages caching and an external API to check if the given date is a holiday.

Parameters:

Name Type Description Default
target_date date

The date to check for holiday status.

 required

Returns:

Name Type Description
bool bool

True if the date is a holiday, False otherwise.
Source code in archipy/helpers/utils/datetime_utils.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
@classmethod
def is_holiday_in_iran(cls, target_date: date) -> bool:
    """Determines if the target date is a holiday in Iran.

    This method leverages caching and an external API to check if the given date is a holiday.

    Args:
        target_date (date): The date to check for holiday status.

    Returns:
        bool: True if the date is a holiday, False otherwise.
    """
    # Convert to Jalali date first
    jalali_date = cls.convert_to_jalali(target_date)
    date_str = target_date.strftime("%Y-%m-%d")
    current_time = cls.get_datetime_utc_now()

    # Check cache first
    is_cached, is_holiday = cls._check_cache(date_str, current_time)
    if is_cached:
        return is_holiday

    # Fetch holiday status and cache it
    return cls._fetch_and_cache_holiday_status(jalali_date, date_str, current_time)

archipy.helpers.utils.base_utils.BaseUtils.ensure_timezone_aware classmethod 

ensure_timezone_aware(dt: datetime) -> datetime

Ensures a datetime object is timezone-aware, converting it to UTC if necessary.

Parameters:

Name Type Description Default
dt datetime

The datetime object to make timezone-aware.

 required

Returns:

Name Type Description
datetime datetime

The timezone-aware datetime object.
Source code in archipy/helpers/utils/datetime_utils.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
@classmethod
def ensure_timezone_aware(cls, dt: datetime) -> datetime:
    """Ensures a datetime object is timezone-aware, converting it to UTC if necessary.

    Args:
        dt (datetime): The datetime object to make timezone-aware.

    Returns:
        datetime: The timezone-aware datetime object.
    """
    if dt.tzinfo is None:
        return dt.replace(tzinfo=UTC)
    return dt

archipy.helpers.utils.base_utils.BaseUtils.daterange classmethod 

daterange(
    start_date: datetime, end_date: datetime
) -> Generator[date]

Generates a range of dates from start_date to end_date, exclusive of end_date.

Parameters:

Name Type Description Default
start_date datetime

The start date of the range.

 required
end_date datetime

The end date of the range.

 required

Yields:

Name Type Description
date Generator[date]

Each date in the range.
Source code in archipy/helpers/utils/datetime_utils.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
@classmethod
def daterange(cls, start_date: datetime, end_date: datetime) -> Generator[date]:
    """Generates a range of dates from start_date to end_date, exclusive of end_date.

    Args:
        start_date (datetime): The start date of the range.
        end_date (datetime): The end date of the range.

    Yields:
        date: Each date in the range.
    """
    for n in range((end_date - start_date).days):
        yield (start_date + timedelta(n)).date()

archipy.helpers.utils.base_utils.BaseUtils.get_string_datetime_from_datetime classmethod 

get_string_datetime_from_datetime(
    dt: datetime, format_: str | None = None
) -> str

Converts a datetime object to a formatted string. Default format is ISO 8601.

Parameters:

Name Type Description Default
dt datetime

The datetime object to format.

 required
format_ str | None

The format string. If None, uses ISO 8601.

 None

Returns:

Name Type Description
str str

The formatted datetime string.
Source code in archipy/helpers/utils/datetime_utils.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
@classmethod
def get_string_datetime_from_datetime(cls, dt: datetime, format_: str | None = None) -> str:
    """Converts a datetime object to a formatted string. Default format is ISO 8601.

    Args:
        dt (datetime): The datetime object to format.
        format_ (str | None): The format string. If None, uses ISO 8601.

    Returns:
        str: The formatted datetime string.
    """
    format_ = format_ or "%Y-%m-%dT%H:%M:%S.%f"
    return dt.strftime(format_)

archipy.helpers.utils.base_utils.BaseUtils.standardize_string_datetime classmethod 

standardize_string_datetime(date_string: str) -> str

Standardizes a datetime string to the default format.

Parameters:

Name Type Description Default
date_string str

The datetime string to standardize.

 required

Returns:

Name Type Description
str str

The standardized datetime string.
Source code in archipy/helpers/utils/datetime_utils.py 
235
236
237
238
239
240
241
242
243
244
245
246
@classmethod
def standardize_string_datetime(cls, date_string: str) -> str:
    """Standardizes a datetime string to the default format.

    Args:
        date_string (str): The datetime string to standardize.

    Returns:
        str: The standardized datetime string.
    """
    datetime_ = cls.get_datetime_from_string_datetime(date_string)
    return cls.get_string_datetime_from_datetime(datetime_)

archipy.helpers.utils.base_utils.BaseUtils.get_datetime_from_string_datetime classmethod 

get_datetime_from_string_datetime(
    date_string: str, format_: str | None = None
) -> datetime

Parses a string to a datetime object using the given format, or ISO 8601 by default.

Parameters:

Name Type Description Default
date_string str

The datetime string to parse.

 required
format_ str | None

The format string. If None, uses ISO 8601.

 None

Returns:

Name Type Description
datetime datetime

The parsed datetime object with UTC timezone.
Source code in archipy/helpers/utils/datetime_utils.py 
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
@classmethod
def get_datetime_from_string_datetime(cls, date_string: str, format_: str | None = None) -> datetime:
    """Parses a string to a datetime object using the given format, or ISO 8601 by default.

    Args:
        date_string (str): The datetime string to parse.
        format_ (str | None): The format string. If None, uses ISO 8601.

    Returns:
        datetime: The parsed datetime object with UTC timezone.
    """
    # Parse using a single expression and immediately make timezone-aware for both cases
    dt = (
        datetime.fromisoformat(date_string)
        if format_ is None
        else datetime.strptime(date_string, format_).replace(tzinfo=UTC)
    )

    # Handle the fromisoformat case which might already have timezone info
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=UTC)

    return dt

archipy.helpers.utils.base_utils.BaseUtils.get_string_datetime_now classmethod 

get_string_datetime_now() -> str

Gets the current datetime as a formatted string. Default format is ISO 8601.

Returns:

Name Type Description
str str

The formatted datetime string.
Source code in archipy/helpers/utils/datetime_utils.py 
272
273
274
275
276
277
278
279
@classmethod
def get_string_datetime_now(cls) -> str:
    """Gets the current datetime as a formatted string. Default format is ISO 8601.

    Returns:
        str: The formatted datetime string.
    """
    return cls.get_string_datetime_from_datetime(cls.get_datetime_now())

archipy.helpers.utils.base_utils.BaseUtils.get_datetime_now classmethod 

get_datetime_now() -> datetime

Gets the current local datetime.

Returns:

Name Type Description
datetime datetime

The current local datetime.
Source code in archipy/helpers/utils/datetime_utils.py 
281
282
283
284
285
286
287
288
@classmethod
def get_datetime_now(cls) -> datetime:
    """Gets the current local datetime.

    Returns:
        datetime: The current local datetime.
    """
    return datetime.now()

archipy.helpers.utils.base_utils.BaseUtils.get_datetime_utc_now classmethod 

get_datetime_utc_now() -> datetime

Gets the current UTC datetime.

Returns:

Name Type Description
datetime datetime

The current UTC datetime.
Source code in archipy/helpers/utils/datetime_utils.py 
290
291
292
293
294
295
296
297
@classmethod
def get_datetime_utc_now(cls) -> datetime:
    """Gets the current UTC datetime.

    Returns:
        datetime: The current UTC datetime.
    """
    return datetime.now(UTC)

archipy.helpers.utils.base_utils.BaseUtils.get_epoch_time_now classmethod 

get_epoch_time_now() -> int

Gets the current time in seconds since the epoch.

Returns:

Name Type Description
int int

The current epoch time.
Source code in archipy/helpers/utils/datetime_utils.py 
299
300
301
302
303
304
305
306
@classmethod
def get_epoch_time_now(cls) -> int:
    """Gets the current time in seconds since the epoch.

    Returns:
        int: The current epoch time.
    """
    return int(time.time())

archipy.helpers.utils.base_utils.BaseUtils.get_datetime_before_given_datetime_or_now classmethod 

get_datetime_before_given_datetime_or_now(
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime

Subtracts time from a given datetime or the current datetime if not specified.

Parameters:

Name Type Description Default
weeks int

The number of weeks to subtract.

 0
days int

The number of days to subtract.

 0
hours int

The number of hours to subtract.

 0
minutes int

The number of minutes to subtract.

 0
seconds int

The number of seconds to subtract.

 0
datetime_given datetime | None

The datetime to subtract from. If None, uses the current datetime.

 None

Returns:

Name Type Description
datetime datetime

The resulting datetime after subtraction.
Source code in archipy/helpers/utils/datetime_utils.py 
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
@classmethod
def get_datetime_before_given_datetime_or_now(
    cls,
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime:
    """Subtracts time from a given datetime or the current datetime if not specified.

    Args:
        weeks (int): The number of weeks to subtract.
        days (int): The number of days to subtract.
        hours (int): The number of hours to subtract.
        minutes (int): The number of minutes to subtract.
        seconds (int): The number of seconds to subtract.
        datetime_given (datetime | None): The datetime to subtract from. If None, uses the current datetime.

    Returns:
        datetime: The resulting datetime after subtraction.
    """
    datetime_given = datetime_given or cls.get_datetime_now()
    return datetime_given - timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)

archipy.helpers.utils.base_utils.BaseUtils.get_datetime_after_given_datetime_or_now classmethod 

get_datetime_after_given_datetime_or_now(
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime

Adds time to a given datetime or the current datetime if not specified.

Parameters:

Name Type Description Default
weeks int

The number of weeks to add.

 0
days int

The number of days to add.

 0
hours int

The number of hours to add.

 0
minutes int

The number of minutes to add.

 0
seconds int

The number of seconds to add.

 0
datetime_given datetime | None

The datetime to add to. If None, uses the current datetime.

 None

Returns:

Name Type Description
datetime datetime

The resulting datetime after addition.
Source code in archipy/helpers/utils/datetime_utils.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
@classmethod
def get_datetime_after_given_datetime_or_now(
    cls,
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime:
    """Adds time to a given datetime or the current datetime if not specified.

    Args:
        weeks (int): The number of weeks to add.
        days (int): The number of days to add.
        hours (int): The number of hours to add.
        minutes (int): The number of minutes to add.
        seconds (int): The number of seconds to add.
        datetime_given (datetime | None): The datetime to add to. If None, uses the current datetime.

    Returns:
        datetime: The resulting datetime after addition.
    """
    datetime_given = datetime_given or cls.get_datetime_now()
    return datetime_given + timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)

archipy.helpers.utils.base_utils.BaseUtils.format_validation_errors staticmethod 

format_validation_errors(
    validation_error: ValidationError,
    *,
    include_type: bool = False,
) -> list[dict[str, str]]

Formats Pydantic validation errors into a structured format.

Parameters:

Name Type Description Default
validation_error ValidationError

The validation error to format.

 required
include_type bool

Whether to include the error type in the output. Defaults to False.

 False

Returns:

Type Description
list[dict[str, str]]

list[dict[str, str]]: A list of formatted validation error details.
Source code in archipy/helpers/utils/error_utils.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@staticmethod
def format_validation_errors(
    validation_error: ValidationError,
    *,
    include_type: bool = False,
) -> list[dict[str, str]]:
    """Formats Pydantic validation errors into a structured format.

    Args:
        validation_error (ValidationError): The validation error to format.
        include_type (bool): Whether to include the error type in the output. Defaults to False.

    Returns:
        list[dict[str, str]]: A list of formatted validation error details.
    """
    formatted_errors = []
    for error in validation_error.errors():
        error_dict = {
            "field": ".".join(str(x) for x in error["loc"]),
            "message": error["msg"],
            "value": str(error.get("input", "")),
        }
        if include_type:
            error_dict["type"] = error["type"]
        formatted_errors.append(error_dict)

    return formatted_errors

archipy.helpers.utils.base_utils.BaseUtils.capture_exception staticmethod 

capture_exception(exception: BaseException) -> None

Captures an exception and reports it to configured external services.

This method logs the exception locally and optionally reports it to Sentry and Elastic APM, depending on the configuration.

Parameters:

Name Type Description Default
exception BaseException

The exception to capture and report.

 required
Source code in archipy/helpers/utils/error_utils.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
@staticmethod
def capture_exception(exception: BaseException) -> None:
    """Captures an exception and reports it to configured external services.

    This method logs the exception locally and optionally reports it to Sentry and Elastic APM,
    depending on the configuration.

    Args:
        exception (BaseException): The exception to capture and report.
    """
    # Always log the exception locally
    logger.exception("An exception occurred")
    config: Any = BaseConfig.global_config()

    # Report exception to Sentry if enabled
    if config.SENTRY.IS_ENABLED:
        try:
            import sentry_sdk

            sentry_sdk.capture_exception(exception)
        except ImportError:
            logger.exception("sentry_sdk is not installed, cannot capture exception in Sentry.")

    # Report exception to Elastic APM if enabled
    if config.ELASTIC_APM.IS_ENABLED:
        try:
            import elasticapm

            # Type ignoring elasticapm.get_client() as it's a third-party function
            client = elasticapm.get_client()
            client.capture_exception()
        except ImportError:
            logger.exception("elasticapm is not installed, cannot capture exception in Elastic APM.")

archipy.helpers.utils.base_utils.BaseUtils.async_handle_fastapi_exception async staticmethod 

async_handle_fastapi_exception(
    _request: RequestProtocol, exception: BaseError
) -> JSONResponseProtocol

Handles a FastAPI exception and returns a JSON response.

Parameters:

Name Type Description Default
_request Request

The incoming FastAPI request.

 required
exception BaseError

The exception to handle.

 required

Returns:

Name Type Description
JSONResponse JSONResponseProtocol

A JSON response containing the exception details.

Raises:

Type Description
NotImplementedError

If FastAPI is not available.
Source code in archipy/helpers/utils/error_utils.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
@staticmethod
async def async_handle_fastapi_exception(_request: RequestProtocol, exception: BaseError) -> JSONResponseProtocol:
    """Handles a FastAPI exception and returns a JSON response.

    Args:
        _request (Request): The incoming FastAPI request.
        exception (BaseError): The exception to handle.

    Returns:
        JSONResponse: A JSON response containing the exception details.

    Raises:
        NotImplementedError: If FastAPI is not available.
    """
    if not HTTP_AVAILABLE:
        raise NotImplementedError
    return JSONResponse(
        status_code=exception.http_status or HTTPStatus.INTERNAL_SERVER_ERROR,
        content=exception.to_dict(),
    )

archipy.helpers.utils.base_utils.BaseUtils.handle_grpc_exception staticmethod 

handle_grpc_exception(
    exception: BaseError,
) -> tuple[int, str]

Handles a gRPC exception and returns a tuple of status code and message.

Parameters:

Name Type Description Default
exception BaseError

The exception to handle.

 required

Returns:

Type Description
tuple[int, str]

tuple[int, str]: A tuple containing the gRPC status code and error message.

Raises:

Type Description
NotImplementedError

If gRPC is not available.
Source code in archipy/helpers/utils/error_utils.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
@staticmethod
def handle_grpc_exception(exception: BaseError) -> tuple[int, str]:
    """Handles a gRPC exception and returns a tuple of status code and message.

    Args:
        exception (BaseError): The exception to handle.

    Returns:
        tuple[int, str]: A tuple containing the gRPC status code and error message.

    Raises:
        NotImplementedError: If gRPC is not available.
    """
    if not GRPC_AVAILABLE:
        raise NotImplementedError
    return exception.grpc_status or StatusCode.UNKNOWN.value[0], exception.get_message()

archipy.helpers.utils.base_utils.BaseUtils.get_fastapi_exception_responses staticmethod 

get_fastapi_exception_responses(
    exceptions: list[type[BaseError]],
) -> dict[int, dict[str, Any]]

Generates OpenAPI response documentation for the given errors.

This method creates OpenAPI-compatible response schemas for FastAPI errors, including validation errors and custom errors.

Parameters:

Name Type Description Default
exceptions list[type[BaseError]]

A list of exception types to generate responses for.

 required

Returns:

Type Description
dict[int, dict[str, Any]]

dict[int, dict[str, Any]]: A dictionary mapping HTTP status codes to their corresponding response schemas.
Source code in archipy/helpers/utils/error_utils.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
@staticmethod
def get_fastapi_exception_responses(exceptions: list[type[BaseError]]) -> dict[int, dict[str, Any]]:
    """Generates OpenAPI response documentation for the given errors.

    This method creates OpenAPI-compatible response schemas for FastAPI errors,
    including validation errors and custom errors.

    Args:
        exceptions (list[type[BaseError]]): A list of exception types to generate responses for.

    Returns:
        dict[int, dict[str, Any]]: A dictionary mapping HTTP status codes to their corresponding response schemas.
    """
    responses: dict[int, dict[str, Any]] = {}

    # Add validation error response by default
    validation_error_response = ValidationErrorResponseDTO()
    if validation_error_response.status_code is not None:
        responses[validation_error_response.status_code] = validation_error_response.model

    exception_schemas = {
        "InvalidPhoneNumberError": {
            "phone_number": {"type": "string", "example": "1234567890", "description": "The invalid phone number"},
        },
        "InvalidLandlineNumberError": {
            "landline_number": {
                "type": "string",
                "example": "02112345678",
                "description": "The invalid landline number",
            },
        },
        "NotFoundError": {
            "resource_type": {
                "type": "string",
                "example": "user",
                "description": "Type of resource that was not found",
            },
        },
        "AlreadyExistsError": {
            "resource_type": {
                "type": "string",
                "example": "user",
                "description": "Type of resource that was not found",
            },
        },
        "InvalidNationalCodeError": {
            "national_code": {
                "type": "string",
                "example": "1234567890",
                "description": "The invalid national code",
            },
        },
        "InvalidArgumentError": {
            "argument": {
                "type": "string",
                "example": "mobile_number",
                "description": "Argument that was invalid",
            },
        },
    }

    for exc in exceptions:
        # Use exception class directly (error details are now class attributes)
        if exc.http_status:
            additional_properties = exception_schemas.get(exc.__name__)
            response = FastAPIErrorResponseDTO(exc, additional_properties)
            if response.status_code is not None:
                responses[response.status_code] = response.model

    return responses

options: show_root_toc_entry: false heading_level: 3

App Utils

Application-level utilities for runtime environment inspection and process management.

archipy.helpers.utils.app_utils.CreateGrpcServerType module-attribute 

CreateGrpcServerType = Callable[..., Server]

archipy.helpers.utils.app_utils.logger module-attribute 

logger = getLogger(__name__)

archipy.helpers.utils.app_utils.create_grpc_server module-attribute 

create_grpc_server: CreateGrpcServerType = server

archipy.helpers.utils.app_utils.GRPC_APP module-attribute 

GRPC_APP = True

archipy.helpers.utils.app_utils.FASTAPI_APP module-attribute 

FASTAPI_APP = True

archipy.helpers.utils.app_utils.FastAPIExceptionHandler

Handles various types of errors and converts them to appropriate JSON responses.

Source code in archipy/helpers/utils/app_utils.py 
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
class FastAPIExceptionHandler:
    """Handles various types of errors and converts them to appropriate JSON responses."""

    @staticmethod
    def create_error_response(exception: BaseError) -> JSONResponse:
        """Creates a standardized error response.

        Args:
            exception (BaseError): The exception to be converted into a response.

        Returns:
            JSONResponse: A JSON response containing the exception details.
        """
        BaseUtils.capture_exception(exception)
        # Default to internal server error if status code is not set
        status_code = exception.http_status or HTTPStatus.INTERNAL_SERVER_ERROR.value
        return JSONResponse(status_code=status_code, content=exception.to_dict())

    @staticmethod
    async def custom_exception_handler(request: Request, exception: BaseError) -> JSONResponse:
        """Handles custom errors.

        Args:
            request (Request): The incoming request.
            exception (BaseError): The custom exception to handle.

        Returns:
            JSONResponse: A JSON response containing the exception details.
        """
        return FastAPIExceptionHandler.create_error_response(exception)

    @staticmethod
    async def generic_exception_handler(request: Request, exception: Exception) -> JSONResponse:
        """Handles generic errors.

        Args:
            request (Request): The incoming request.
            exception (Exception): The generic exception to handle.

        Returns:
            JSONResponse: A JSON response containing the exception details.
        """
        return FastAPIExceptionHandler.create_error_response(UnknownError())

    @staticmethod
    async def validation_exception_handler(
        request: Request,
        exception: ValidationError,
    ) -> JSONResponse:
        """Handles validation errors.

        Args:
            request (Request): The incoming request.
            exception (ValidationError): The validation exception to handle.

        Returns:
            JSONResponse: A JSON response containing the validation error details.
        """
        BaseUtils.capture_exception(exception)
        errors = BaseUtils.format_validation_errors(exception)
        return JSONResponse(
            status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
            content={"error": "VALIDATION_ERROR", "detail": errors},
        )

archipy.helpers.utils.app_utils.FastAPIExceptionHandler.create_error_response staticmethod 

create_error_response(exception: BaseError) -> JSONResponse

Creates a standardized error response.

Parameters:

Name Type Description Default
exception BaseError

The exception to be converted into a response.

 required

Returns:

Name Type Description
JSONResponse JSONResponse

A JSON response containing the exception details.
Source code in archipy/helpers/utils/app_utils.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
@staticmethod
def create_error_response(exception: BaseError) -> JSONResponse:
    """Creates a standardized error response.

    Args:
        exception (BaseError): The exception to be converted into a response.

    Returns:
        JSONResponse: A JSON response containing the exception details.
    """
    BaseUtils.capture_exception(exception)
    # Default to internal server error if status code is not set
    status_code = exception.http_status or HTTPStatus.INTERNAL_SERVER_ERROR.value
    return JSONResponse(status_code=status_code, content=exception.to_dict())

archipy.helpers.utils.app_utils.FastAPIExceptionHandler.custom_exception_handler async staticmethod 

custom_exception_handler(
    request: Request, exception: BaseError
) -> JSONResponse

Handles custom errors.

Parameters:

Name Type Description Default
request Request

The incoming request.

 required
exception BaseError

The custom exception to handle.

 required

Returns:

Name Type Description
JSONResponse JSONResponse

A JSON response containing the exception details.
Source code in archipy/helpers/utils/app_utils.py 
78
79
80
81
82
83
84
85
86
87
88
89
@staticmethod
async def custom_exception_handler(request: Request, exception: BaseError) -> JSONResponse:
    """Handles custom errors.

    Args:
        request (Request): The incoming request.
        exception (BaseError): The custom exception to handle.

    Returns:
        JSONResponse: A JSON response containing the exception details.
    """
    return FastAPIExceptionHandler.create_error_response(exception)

archipy.helpers.utils.app_utils.FastAPIExceptionHandler.generic_exception_handler async staticmethod 

generic_exception_handler(
    request: Request, exception: Exception
) -> JSONResponse

Handles generic errors.

Parameters:

Name Type Description Default
request Request

The incoming request.

 required
exception Exception

The generic exception to handle.

 required

Returns:

Name Type Description
JSONResponse JSONResponse

A JSON response containing the exception details.
Source code in archipy/helpers/utils/app_utils.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
@staticmethod
async def generic_exception_handler(request: Request, exception: Exception) -> JSONResponse:
    """Handles generic errors.

    Args:
        request (Request): The incoming request.
        exception (Exception): The generic exception to handle.

    Returns:
        JSONResponse: A JSON response containing the exception details.
    """
    return FastAPIExceptionHandler.create_error_response(UnknownError())

archipy.helpers.utils.app_utils.FastAPIExceptionHandler.validation_exception_handler async staticmethod 

validation_exception_handler(
    request: Request, exception: ValidationError
) -> JSONResponse

Handles validation errors.

Parameters:

Name Type Description Default
request Request

The incoming request.

 required
exception ValidationError

The validation exception to handle.

 required

Returns:

Name Type Description
JSONResponse JSONResponse

A JSON response containing the validation error details.
Source code in archipy/helpers/utils/app_utils.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
@staticmethod
async def validation_exception_handler(
    request: Request,
    exception: ValidationError,
) -> JSONResponse:
    """Handles validation errors.

    Args:
        request (Request): The incoming request.
        exception (ValidationError): The validation exception to handle.

    Returns:
        JSONResponse: A JSON response containing the validation error details.
    """
    BaseUtils.capture_exception(exception)
    errors = BaseUtils.format_validation_errors(exception)
    return JSONResponse(
        status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
        content={"error": "VALIDATION_ERROR", "detail": errors},
    )

archipy.helpers.utils.app_utils.FastAPIUtils

Utility class for FastAPI configuration and setup.

Source code in archipy/helpers/utils/app_utils.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
class FastAPIUtils:
    """Utility class for FastAPI configuration and setup."""

    @staticmethod
    def custom_generate_unique_id(route: APIRoute) -> str:
        """Generates a unique ID for API routes.

        Args:
            route (APIRoute): The route for which to generate a unique ID.

        Returns:
            str: A unique ID for the route.
        """
        return f"{route.tags[0]}-{route.name}" if route.tags else route.name

    @staticmethod
    def setup_sentry(config: BaseConfig) -> None:
        """Initializes Sentry configuration if enabled.

        Args:
            config (BaseConfig): The configuration object containing Sentry settings.
        """
        if not config.SENTRY.IS_ENABLED:
            return

        try:
            import sentry_sdk

            sentry_sdk.init(
                dsn=config.SENTRY.DSN,
                debug=config.SENTRY.DEBUG,
                release=config.SENTRY.RELEASE,
                sample_rate=config.SENTRY.SAMPLE_RATE,
                traces_sample_rate=config.SENTRY.TRACES_SAMPLE_RATE,
                environment=config.ENVIRONMENT,
            )
        except Exception:
            logger.exception("Failed to initialize Sentry")

    @staticmethod
    def setup_cors(app: FastAPI, config: BaseConfig) -> None:
        """Configures CORS middleware.

        Args:
            app (FastAPI): The FastAPI application instance.
            config (BaseConfig): The configuration object containing CORS settings.
        """
        origins = [str(origin).strip("/") for origin in config.FASTAPI.CORS_MIDDLEWARE_ALLOW_ORIGINS]
        # Use app.add_middleware with CORSMiddleware directly
        # CORSMiddleware is compatible with FastAPI's middleware system at runtime
        app.add_middleware(
            CORSMiddleware,  # type: ignore[arg-type]
            allow_origins=origins,
            allow_credentials=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_CREDENTIALS,
            allow_methods=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_METHODS,
            allow_headers=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_HEADERS,
        )

    @staticmethod
    def setup_elastic_apm(app: FastAPI, config: BaseConfig) -> None:
        """Configures Elastic APM if enabled.

        Args:
            app (FastAPI): The FastAPI application instance.
            config (BaseConfig): The configuration object containing Elastic APM settings.
        """
        if not config.ELASTIC_APM.IS_ENABLED:
            return

        try:
            from elasticapm.contrib.starlette import ElasticAPM, make_apm_client

            apm_client = make_apm_client(config.ELASTIC_APM.model_dump())
            # Use app.add_middleware with ElasticAPM directly
            # ElasticAPM is compatible with FastAPI's middleware system at runtime
            app.add_middleware(ElasticAPM, client=apm_client)  # type: ignore[arg-type]
        except Exception:
            logger.exception("Failed to initialize Elastic APM")

    @staticmethod
    def setup_metric_interceptor(app: FastAPI, config: BaseConfig) -> None:
        """Configures metric interceptor for FastAPI if Prometheus is enabled.

        Args:
            app (FastAPI): The FastAPI application instance.
            config (BaseConfig): The configuration object containing Prometheus settings.
        """
        if not config.PROMETHEUS.IS_ENABLED:
            return

        try:
            from archipy.helpers.interceptors.fastapi.metric.interceptor import FastAPIMetricInterceptor
            from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

            start_prometheus_server_if_needed(config.PROMETHEUS.SERVER_PORT)

            app.add_middleware(FastAPIMetricInterceptor)  # type: ignore[arg-type]
        except Exception:
            logger.exception("Failed to initialize Metric Interceptor")

    @staticmethod
    def setup_exception_handlers(app: FastAPI) -> None:
        """Configures exception handlers for the FastAPI application.

        Args:
            app (FastAPI): The FastAPI application instance.
        """

        # These handlers return JSONResponse which is a subclass of Response,
        # so they are compatible with FastAPI's exception handler requirements.
        # We create wrapper functions to match the expected signature
        async def validation_wrapper(request: Request, exception: Exception) -> Response:
            if isinstance(exception, ValidationError):
                return await FastAPIExceptionHandler.validation_exception_handler(request, exception)
            if isinstance(exception, RequestValidationError):
                # RequestValidationError has errors() method that returns validation errors
                # Format them directly since RequestValidationError has a similar structure
                BaseUtils.capture_exception(exception)
                formatted_errors = []
                for error in exception.errors():
                    error_dict = {
                        "field": ".".join(str(x) for x in error.get("loc", [])),
                        "message": error.get("msg", ""),
                        "value": str(error.get("input", "")),
                    }
                    if "type" in error:
                        error_dict["type"] = error["type"]
                    formatted_errors.append(error_dict)
                return JSONResponse(
                    status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
                    content={"error": "VALIDATION_ERROR", "detail": formatted_errors},
                )
            return await FastAPIExceptionHandler.generic_exception_handler(request, exception)

        async def custom_wrapper(request: Request, exception: Exception) -> Response:
            if isinstance(exception, BaseError):
                return await FastAPIExceptionHandler.custom_exception_handler(request, exception)
            return await FastAPIExceptionHandler.generic_exception_handler(request, exception)

        async def generic_wrapper(request: Request, exception: Exception) -> Response:
            return await FastAPIExceptionHandler.generic_exception_handler(request, exception)

        app.add_exception_handler(RequestValidationError, validation_wrapper)
        app.add_exception_handler(ValidationError, validation_wrapper)
        app.add_exception_handler(BaseError, custom_wrapper)
        app.add_exception_handler(Exception, generic_wrapper)

archipy.helpers.utils.app_utils.FastAPIUtils.custom_generate_unique_id staticmethod 

custom_generate_unique_id(route: APIRoute) -> str

Generates a unique ID for API routes.

Parameters:

Name Type Description Default
route APIRoute

The route for which to generate a unique ID.

 required

Returns:

Name Type Description
str str

A unique ID for the route.
Source code in archipy/helpers/utils/app_utils.py 
129
130
131
132
133
134
135
136
137
138
139
@staticmethod
def custom_generate_unique_id(route: APIRoute) -> str:
    """Generates a unique ID for API routes.

    Args:
        route (APIRoute): The route for which to generate a unique ID.

    Returns:
        str: A unique ID for the route.
    """
    return f"{route.tags[0]}-{route.name}" if route.tags else route.name

archipy.helpers.utils.app_utils.FastAPIUtils.setup_sentry staticmethod 

setup_sentry(config: BaseConfig) -> None

Initializes Sentry configuration if enabled.

Parameters:

Name Type Description Default
config BaseConfig

The configuration object containing Sentry settings.

 required
Source code in archipy/helpers/utils/app_utils.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
@staticmethod
def setup_sentry(config: BaseConfig) -> None:
    """Initializes Sentry configuration if enabled.

    Args:
        config (BaseConfig): The configuration object containing Sentry settings.
    """
    if not config.SENTRY.IS_ENABLED:
        return

    try:
        import sentry_sdk

        sentry_sdk.init(
            dsn=config.SENTRY.DSN,
            debug=config.SENTRY.DEBUG,
            release=config.SENTRY.RELEASE,
            sample_rate=config.SENTRY.SAMPLE_RATE,
            traces_sample_rate=config.SENTRY.TRACES_SAMPLE_RATE,
            environment=config.ENVIRONMENT,
        )
    except Exception:
        logger.exception("Failed to initialize Sentry")

archipy.helpers.utils.app_utils.FastAPIUtils.setup_cors staticmethod 

setup_cors(app: FastAPI, config: BaseConfig) -> None

Configures CORS middleware.

Parameters:

Name Type Description Default
app FastAPI

The FastAPI application instance.

 required
config BaseConfig

The configuration object containing CORS settings.

 required
Source code in archipy/helpers/utils/app_utils.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
@staticmethod
def setup_cors(app: FastAPI, config: BaseConfig) -> None:
    """Configures CORS middleware.

    Args:
        app (FastAPI): The FastAPI application instance.
        config (BaseConfig): The configuration object containing CORS settings.
    """
    origins = [str(origin).strip("/") for origin in config.FASTAPI.CORS_MIDDLEWARE_ALLOW_ORIGINS]
    # Use app.add_middleware with CORSMiddleware directly
    # CORSMiddleware is compatible with FastAPI's middleware system at runtime
    app.add_middleware(
        CORSMiddleware,  # type: ignore[arg-type]
        allow_origins=origins,
        allow_credentials=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_CREDENTIALS,
        allow_methods=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_METHODS,
        allow_headers=config.FASTAPI.CORS_MIDDLEWARE_ALLOW_HEADERS,
    )

archipy.helpers.utils.app_utils.FastAPIUtils.setup_elastic_apm staticmethod 

setup_elastic_apm(app: FastAPI, config: BaseConfig) -> None

Configures Elastic APM if enabled.

Parameters:

Name Type Description Default
app FastAPI

The FastAPI application instance.

 required
config BaseConfig

The configuration object containing Elastic APM settings.

 required
Source code in archipy/helpers/utils/app_utils.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
@staticmethod
def setup_elastic_apm(app: FastAPI, config: BaseConfig) -> None:
    """Configures Elastic APM if enabled.

    Args:
        app (FastAPI): The FastAPI application instance.
        config (BaseConfig): The configuration object containing Elastic APM settings.
    """
    if not config.ELASTIC_APM.IS_ENABLED:
        return

    try:
        from elasticapm.contrib.starlette import ElasticAPM, make_apm_client

        apm_client = make_apm_client(config.ELASTIC_APM.model_dump())
        # Use app.add_middleware with ElasticAPM directly
        # ElasticAPM is compatible with FastAPI's middleware system at runtime
        app.add_middleware(ElasticAPM, client=apm_client)  # type: ignore[arg-type]
    except Exception:
        logger.exception("Failed to initialize Elastic APM")

archipy.helpers.utils.app_utils.FastAPIUtils.setup_metric_interceptor staticmethod 

setup_metric_interceptor(
    app: FastAPI, config: BaseConfig
) -> None

Configures metric interceptor for FastAPI if Prometheus is enabled.

Parameters:

Name Type Description Default
app FastAPI

The FastAPI application instance.

 required
config BaseConfig

The configuration object containing Prometheus settings.

 required
Source code in archipy/helpers/utils/app_utils.py 
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
@staticmethod
def setup_metric_interceptor(app: FastAPI, config: BaseConfig) -> None:
    """Configures metric interceptor for FastAPI if Prometheus is enabled.

    Args:
        app (FastAPI): The FastAPI application instance.
        config (BaseConfig): The configuration object containing Prometheus settings.
    """
    if not config.PROMETHEUS.IS_ENABLED:
        return

    try:
        from archipy.helpers.interceptors.fastapi.metric.interceptor import FastAPIMetricInterceptor
        from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

        start_prometheus_server_if_needed(config.PROMETHEUS.SERVER_PORT)

        app.add_middleware(FastAPIMetricInterceptor)  # type: ignore[arg-type]
    except Exception:
        logger.exception("Failed to initialize Metric Interceptor")

archipy.helpers.utils.app_utils.FastAPIUtils.setup_exception_handlers staticmethod 

setup_exception_handlers(app: FastAPI) -> None

Configures exception handlers for the FastAPI application.

Parameters:

Name Type Description Default
app FastAPI

The FastAPI application instance.

 required
Source code in archipy/helpers/utils/app_utils.py 
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
@staticmethod
def setup_exception_handlers(app: FastAPI) -> None:
    """Configures exception handlers for the FastAPI application.

    Args:
        app (FastAPI): The FastAPI application instance.
    """

    # These handlers return JSONResponse which is a subclass of Response,
    # so they are compatible with FastAPI's exception handler requirements.
    # We create wrapper functions to match the expected signature
    async def validation_wrapper(request: Request, exception: Exception) -> Response:
        if isinstance(exception, ValidationError):
            return await FastAPIExceptionHandler.validation_exception_handler(request, exception)
        if isinstance(exception, RequestValidationError):
            # RequestValidationError has errors() method that returns validation errors
            # Format them directly since RequestValidationError has a similar structure
            BaseUtils.capture_exception(exception)
            formatted_errors = []
            for error in exception.errors():
                error_dict = {
                    "field": ".".join(str(x) for x in error.get("loc", [])),
                    "message": error.get("msg", ""),
                    "value": str(error.get("input", "")),
                }
                if "type" in error:
                    error_dict["type"] = error["type"]
                formatted_errors.append(error_dict)
            return JSONResponse(
                status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
                content={"error": "VALIDATION_ERROR", "detail": formatted_errors},
            )
        return await FastAPIExceptionHandler.generic_exception_handler(request, exception)

    async def custom_wrapper(request: Request, exception: Exception) -> Response:
        if isinstance(exception, BaseError):
            return await FastAPIExceptionHandler.custom_exception_handler(request, exception)
        return await FastAPIExceptionHandler.generic_exception_handler(request, exception)

    async def generic_wrapper(request: Request, exception: Exception) -> Response:
        return await FastAPIExceptionHandler.generic_exception_handler(request, exception)

    app.add_exception_handler(RequestValidationError, validation_wrapper)
    app.add_exception_handler(ValidationError, validation_wrapper)
    app.add_exception_handler(BaseError, custom_wrapper)
    app.add_exception_handler(Exception, generic_wrapper)

archipy.helpers.utils.app_utils.AsyncGrpcAPIUtils

async grpc api utilities.

Source code in archipy/helpers/utils/app_utils.py 
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
class AsyncGrpcAPIUtils:
    """async grpc api utilities."""

    @staticmethod
    def setup_trace_interceptor(config: BaseConfig, interceptors: list) -> None:
        """Configures trace interceptor for gRPC server if tracing is enabled.

        Args:
            config (BaseConfig): The configuration object containing tracing settings.
            interceptors (List): List of gRPC interceptors to add the trace interceptor to.
        """
        if not config.ELASTIC_APM.IS_ENABLED and not config.SENTRY.IS_ENABLED:
            return

        try:
            from archipy.helpers.interceptors.grpc.trace.server_interceptor import AsyncGrpcServerTraceInterceptor

            interceptors.append(AsyncGrpcServerTraceInterceptor())
        except Exception:
            logger.exception("Failed to initialize Trace Interceptor")

    @staticmethod
    def setup_metric_interceptor(config: BaseConfig, interceptors: list) -> None:
        """Configures metric interceptor for gRPC server if Prometheus is enabled.

        Args:
            config (BaseConfig): The configuration object containing Prometheus settings.
            interceptors (List): List of gRPC interceptors to add the metric interceptor to.
        """
        if not config.PROMETHEUS.IS_ENABLED:
            return

        try:
            from archipy.helpers.interceptors.grpc.metric.server_interceptor import AsyncGrpcServerMetricInterceptor
            from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

            start_prometheus_server_if_needed(config.PROMETHEUS.SERVER_PORT)

            interceptors.append(AsyncGrpcServerMetricInterceptor())

        except Exception:
            logger.exception("Failed to initialize Metric Interceptor")

archipy.helpers.utils.app_utils.AsyncGrpcAPIUtils.setup_trace_interceptor staticmethod 

setup_trace_interceptor(
    config: BaseConfig, interceptors: list
) -> None

Configures trace interceptor for gRPC server if tracing is enabled.

Parameters:

Name Type Description Default
config BaseConfig

The configuration object containing tracing settings.

 required
interceptors List

List of gRPC interceptors to add the trace interceptor to.

 required
Source code in archipy/helpers/utils/app_utils.py 
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
@staticmethod
def setup_trace_interceptor(config: BaseConfig, interceptors: list) -> None:
    """Configures trace interceptor for gRPC server if tracing is enabled.

    Args:
        config (BaseConfig): The configuration object containing tracing settings.
        interceptors (List): List of gRPC interceptors to add the trace interceptor to.
    """
    if not config.ELASTIC_APM.IS_ENABLED and not config.SENTRY.IS_ENABLED:
        return

    try:
        from archipy.helpers.interceptors.grpc.trace.server_interceptor import AsyncGrpcServerTraceInterceptor

        interceptors.append(AsyncGrpcServerTraceInterceptor())
    except Exception:
        logger.exception("Failed to initialize Trace Interceptor")

archipy.helpers.utils.app_utils.AsyncGrpcAPIUtils.setup_metric_interceptor staticmethod 

setup_metric_interceptor(
    config: BaseConfig, interceptors: list
) -> None

Configures metric interceptor for gRPC server if Prometheus is enabled.

Parameters:

Name Type Description Default
config BaseConfig

The configuration object containing Prometheus settings.

 required
interceptors List

List of gRPC interceptors to add the metric interceptor to.

 required
Source code in archipy/helpers/utils/app_utils.py 
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
@staticmethod
def setup_metric_interceptor(config: BaseConfig, interceptors: list) -> None:
    """Configures metric interceptor for gRPC server if Prometheus is enabled.

    Args:
        config (BaseConfig): The configuration object containing Prometheus settings.
        interceptors (List): List of gRPC interceptors to add the metric interceptor to.
    """
    if not config.PROMETHEUS.IS_ENABLED:
        return

    try:
        from archipy.helpers.interceptors.grpc.metric.server_interceptor import AsyncGrpcServerMetricInterceptor
        from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

        start_prometheus_server_if_needed(config.PROMETHEUS.SERVER_PORT)

        interceptors.append(AsyncGrpcServerMetricInterceptor())

    except Exception:
        logger.exception("Failed to initialize Metric Interceptor")

archipy.helpers.utils.app_utils.GrpcAPIUtils

grpc api utilities.

Source code in archipy/helpers/utils/app_utils.py 
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
class GrpcAPIUtils:
    """grpc api utilities."""

    @staticmethod
    def setup_trace_interceptor(config: BaseConfig, interceptors: list) -> None:
        """Configures trace interceptor for gRPC server if tracing is enabled.

        Args:
            config (BaseConfig): The configuration object containing tracing settings.
            interceptors (List): List of gRPC interceptors to add the trace interceptor to.
        """
        if not config.ELASTIC_APM.IS_ENABLED and not config.SENTRY.IS_ENABLED:
            return

        try:
            from archipy.helpers.interceptors.grpc.trace.server_interceptor import GrpcServerTraceInterceptor

            interceptors.append(GrpcServerTraceInterceptor())
        except Exception:
            logger.exception("Failed to initialize Trace Interceptor")

    @staticmethod
    def setup_metric_interceptor(config: BaseConfig, interceptors: list) -> None:
        """Configures metric interceptor for gRPC server if Prometheus is enabled.

        Args:
            config (BaseConfig): The configuration object containing Prometheus settings.
            interceptors (List): List of gRPC interceptors to add the metric interceptor to.
        """
        if not config.PROMETHEUS.IS_ENABLED:
            return

        try:
            from archipy.helpers.interceptors.grpc.metric.server_interceptor import GrpcServerMetricInterceptor
            from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

            start_prometheus_server_if_needed(config.PROMETHEUS.SERVER_PORT)

            interceptors.append(GrpcServerMetricInterceptor())

        except Exception:
            logger.exception("Failed to initialize Metric Interceptor")

archipy.helpers.utils.app_utils.GrpcAPIUtils.setup_trace_interceptor staticmethod 

setup_trace_interceptor(
    config: BaseConfig, interceptors: list
) -> None

Configures trace interceptor for gRPC server if tracing is enabled.

Parameters:

Name Type Description Default
config BaseConfig

The configuration object containing tracing settings.

 required
interceptors List

List of gRPC interceptors to add the trace interceptor to.

 required
Source code in archipy/helpers/utils/app_utils.py 
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
@staticmethod
def setup_trace_interceptor(config: BaseConfig, interceptors: list) -> None:
    """Configures trace interceptor for gRPC server if tracing is enabled.

    Args:
        config (BaseConfig): The configuration object containing tracing settings.
        interceptors (List): List of gRPC interceptors to add the trace interceptor to.
    """
    if not config.ELASTIC_APM.IS_ENABLED and not config.SENTRY.IS_ENABLED:
        return

    try:
        from archipy.helpers.interceptors.grpc.trace.server_interceptor import GrpcServerTraceInterceptor

        interceptors.append(GrpcServerTraceInterceptor())
    except Exception:
        logger.exception("Failed to initialize Trace Interceptor")

archipy.helpers.utils.app_utils.GrpcAPIUtils.setup_metric_interceptor staticmethod 

setup_metric_interceptor(
    config: BaseConfig, interceptors: list
) -> None

Configures metric interceptor for gRPC server if Prometheus is enabled.

Parameters:

Name Type Description Default
config BaseConfig

The configuration object containing Prometheus settings.

 required
interceptors List

List of gRPC interceptors to add the metric interceptor to.

 required
Source code in archipy/helpers/utils/app_utils.py 
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
@staticmethod
def setup_metric_interceptor(config: BaseConfig, interceptors: list) -> None:
    """Configures metric interceptor for gRPC server if Prometheus is enabled.

    Args:
        config (BaseConfig): The configuration object containing Prometheus settings.
        interceptors (List): List of gRPC interceptors to add the metric interceptor to.
    """
    if not config.PROMETHEUS.IS_ENABLED:
        return

    try:
        from archipy.helpers.interceptors.grpc.metric.server_interceptor import GrpcServerMetricInterceptor
        from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

        start_prometheus_server_if_needed(config.PROMETHEUS.SERVER_PORT)

        interceptors.append(GrpcServerMetricInterceptor())

    except Exception:
        logger.exception("Failed to initialize Metric Interceptor")

archipy.helpers.utils.app_utils.AppUtils

Utility class for creating and configuring FastAPI applications.

Source code in archipy/helpers/utils/app_utils.py 
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
class AppUtils:
    """Utility class for creating and configuring FastAPI applications."""

    @classmethod
    def create_fastapi_app(
        cls,
        config: BaseConfig | None = None,
        *,
        configure_exception_handlers: bool = True,
        include_common_responses: bool = True,
        lifespan: Callable[..., AbstractAsyncContextManager] | None = None,
    ) -> FastAPI:
        """Create and configure a FastAPI application.

        Args:
            config (BaseConfig | None, optional): Custom configuration. If not provided, uses global config.
            configure_exception_handlers (bool, optional): Whether to configure exception handlers. Defaults to True.
            include_common_responses (bool, optional): Whether to configure common response definitions for all endpoints.
                                                Defaults to True.
            lifespan (Callable[..., AbstractAsyncContextManager] | None, optional): Custom lifespan context manager for the app.
                                                                          Defaults to None.

        Returns:
            FastAPI: The configured FastAPI application instance.
        """
        config = config or BaseConfig.global_config()

        # Define common responses for all endpoints
        common_responses = BaseUtils.get_fastapi_exception_responses(
            [UnknownError, UnavailableError, InvalidArgumentError],
        )
        # Convert dict[int, ...] to dict[int | str, ...] for FastAPI compatibility
        responses_dict: dict[int | str, dict[str, Any]] | None = None
        if include_common_responses and common_responses:
            responses_dict = dict(common_responses.items())
        app = FastAPI(
            title=config.FASTAPI.PROJECT_NAME,
            openapi_url=config.FASTAPI.OPENAPI_URL,
            generate_unique_id_function=FastAPIUtils.custom_generate_unique_id,
            swagger_ui_parameters=config.FASTAPI.SWAGGER_UI_PARAMS,
            docs_url=config.FASTAPI.DOCS_URL,
            redoc_url=config.FASTAPI.RE_DOC_URL,
            responses=responses_dict,
            lifespan=lifespan,
        )

        FastAPIUtils.setup_sentry(config)
        FastAPIUtils.setup_cors(app, config)
        FastAPIUtils.setup_elastic_apm(app, config)
        FastAPIUtils.setup_metric_interceptor(app, config)

        if configure_exception_handlers:
            FastAPIUtils.setup_exception_handlers(app)

        return app

    @classmethod
    def create_async_grpc_app(
        cls,
        config: BaseConfig,
        customized_interceptors: set[Any] | None = None,
        compression: grpc.Compression | None = None,
    ) -> GrpcAioServer:
        """Create and configure an async gRPC application."""
        from archipy.helpers.interceptors.grpc.exception import AsyncGrpcServerExceptionInterceptor

        async_interceptors = [AsyncGrpcServerExceptionInterceptor()]

        AsyncGrpcAPIUtils.setup_trace_interceptor(config, async_interceptors)
        AsyncGrpcAPIUtils.setup_metric_interceptor(config, async_interceptors)

        if create_grpc_server is None:
            raise ImportError("grpc.aio is not available")
        app = create_grpc_server(
            futures.ThreadPoolExecutor(max_workers=config.GRPC.THREAD_WORKER_COUNT),
            interceptors=async_interceptors,
            compression=compression,
            options=config.GRPC.SERVER_OPTIONS_CONFIG_LIST,
            maximum_concurrent_rpcs=config.GRPC.MAX_CONCURRENT_RPCS,
        )
        if customized_interceptors:
            async_interceptors.extend(customized_interceptors)
        return app

    @classmethod
    def create_grpc_app(
        cls,
        config: BaseConfig,
        customized_interceptors: set[Any] | None = None,
        compression: grpc.Compression | None = None,
    ) -> grpc.Server:
        """Create and configure an async gRPC application."""
        from archipy.helpers.interceptors.grpc.exception import GrpcServerExceptionInterceptor

        interceptors: list[grpc.ServerInterceptor] = [GrpcServerExceptionInterceptor()]

        GrpcAPIUtils.setup_trace_interceptor(config, interceptors)
        GrpcAPIUtils.setup_metric_interceptor(config, interceptors)
        if customized_interceptors:
            interceptors.extend(customized_interceptors)

        app = grpc.server(
            futures.ThreadPoolExecutor(max_workers=config.GRPC.THREAD_WORKER_COUNT),
            interceptors=interceptors,
            compression=compression,
            options=config.GRPC.SERVER_OPTIONS_CONFIG_LIST,
            maximum_concurrent_rpcs=config.GRPC.MAX_CONCURRENT_RPCS,
        )

        return app

archipy.helpers.utils.app_utils.AppUtils.create_fastapi_app classmethod 

create_fastapi_app(
    config: BaseConfig | None = None,
    *,
    configure_exception_handlers: bool = True,
    include_common_responses: bool = True,
    lifespan: Callable[..., AbstractAsyncContextManager]
    | None = None,
) -> FastAPI

Create and configure a FastAPI application.

Parameters:

Name Type Description Default
config BaseConfig | None

Custom configuration. If not provided, uses global config.

 None
configure_exception_handlers bool

Whether to configure exception handlers. Defaults to True.

 True
include_common_responses bool

Whether to configure common response definitions for all endpoints. Defaults to True.

 True
lifespan Callable[..., AbstractAsyncContextManager] | None

Custom lifespan context manager for the app. Defaults to None.

 None

Returns:

Name Type Description
FastAPI FastAPI

The configured FastAPI application instance.
Source code in archipy/helpers/utils/app_utils.py 
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
@classmethod
def create_fastapi_app(
    cls,
    config: BaseConfig | None = None,
    *,
    configure_exception_handlers: bool = True,
    include_common_responses: bool = True,
    lifespan: Callable[..., AbstractAsyncContextManager] | None = None,
) -> FastAPI:
    """Create and configure a FastAPI application.

    Args:
        config (BaseConfig | None, optional): Custom configuration. If not provided, uses global config.
        configure_exception_handlers (bool, optional): Whether to configure exception handlers. Defaults to True.
        include_common_responses (bool, optional): Whether to configure common response definitions for all endpoints.
                                            Defaults to True.
        lifespan (Callable[..., AbstractAsyncContextManager] | None, optional): Custom lifespan context manager for the app.
                                                                      Defaults to None.

    Returns:
        FastAPI: The configured FastAPI application instance.
    """
    config = config or BaseConfig.global_config()

    # Define common responses for all endpoints
    common_responses = BaseUtils.get_fastapi_exception_responses(
        [UnknownError, UnavailableError, InvalidArgumentError],
    )
    # Convert dict[int, ...] to dict[int | str, ...] for FastAPI compatibility
    responses_dict: dict[int | str, dict[str, Any]] | None = None
    if include_common_responses and common_responses:
        responses_dict = dict(common_responses.items())
    app = FastAPI(
        title=config.FASTAPI.PROJECT_NAME,
        openapi_url=config.FASTAPI.OPENAPI_URL,
        generate_unique_id_function=FastAPIUtils.custom_generate_unique_id,
        swagger_ui_parameters=config.FASTAPI.SWAGGER_UI_PARAMS,
        docs_url=config.FASTAPI.DOCS_URL,
        redoc_url=config.FASTAPI.RE_DOC_URL,
        responses=responses_dict,
        lifespan=lifespan,
    )

    FastAPIUtils.setup_sentry(config)
    FastAPIUtils.setup_cors(app, config)
    FastAPIUtils.setup_elastic_apm(app, config)
    FastAPIUtils.setup_metric_interceptor(app, config)

    if configure_exception_handlers:
        FastAPIUtils.setup_exception_handlers(app)

    return app

archipy.helpers.utils.app_utils.AppUtils.create_async_grpc_app classmethod 

create_async_grpc_app(
    config: BaseConfig,
    customized_interceptors: set[Any] | None = None,
    compression: Compression | None = None,
) -> GrpcAioServer

Create and configure an async gRPC application.

Source code in archipy/helpers/utils/app_utils.py 
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
@classmethod
def create_async_grpc_app(
    cls,
    config: BaseConfig,
    customized_interceptors: set[Any] | None = None,
    compression: grpc.Compression | None = None,
) -> GrpcAioServer:
    """Create and configure an async gRPC application."""
    from archipy.helpers.interceptors.grpc.exception import AsyncGrpcServerExceptionInterceptor

    async_interceptors = [AsyncGrpcServerExceptionInterceptor()]

    AsyncGrpcAPIUtils.setup_trace_interceptor(config, async_interceptors)
    AsyncGrpcAPIUtils.setup_metric_interceptor(config, async_interceptors)

    if create_grpc_server is None:
        raise ImportError("grpc.aio is not available")
    app = create_grpc_server(
        futures.ThreadPoolExecutor(max_workers=config.GRPC.THREAD_WORKER_COUNT),
        interceptors=async_interceptors,
        compression=compression,
        options=config.GRPC.SERVER_OPTIONS_CONFIG_LIST,
        maximum_concurrent_rpcs=config.GRPC.MAX_CONCURRENT_RPCS,
    )
    if customized_interceptors:
        async_interceptors.extend(customized_interceptors)
    return app

archipy.helpers.utils.app_utils.AppUtils.create_grpc_app classmethod 

create_grpc_app(
    config: BaseConfig,
    customized_interceptors: set[Any] | None = None,
    compression: Compression | None = None,
) -> grpc.Server

Create and configure an async gRPC application.

Source code in archipy/helpers/utils/app_utils.py 
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
@classmethod
def create_grpc_app(
    cls,
    config: BaseConfig,
    customized_interceptors: set[Any] | None = None,
    compression: grpc.Compression | None = None,
) -> grpc.Server:
    """Create and configure an async gRPC application."""
    from archipy.helpers.interceptors.grpc.exception import GrpcServerExceptionInterceptor

    interceptors: list[grpc.ServerInterceptor] = [GrpcServerExceptionInterceptor()]

    GrpcAPIUtils.setup_trace_interceptor(config, interceptors)
    GrpcAPIUtils.setup_metric_interceptor(config, interceptors)
    if customized_interceptors:
        interceptors.extend(customized_interceptors)

    app = grpc.server(
        futures.ThreadPoolExecutor(max_workers=config.GRPC.THREAD_WORKER_COUNT),
        interceptors=interceptors,
        compression=compression,
        options=config.GRPC.SERVER_OPTIONS_CONFIG_LIST,
        maximum_concurrent_rpcs=config.GRPC.MAX_CONCURRENT_RPCS,
    )

    return app

options: show_root_toc_entry: false heading_level: 3

Datetime Utils

Utilities for timezone-aware date and time operations with microsecond precision.

archipy.helpers.utils.datetime_utils.DatetimeUtils

A utility class for handling date and time operations, including conversions, caching, and API integrations.

This class provides methods for working with both Gregorian and Jalali (Persian) calendars, as well as utility functions for timezone-aware datetime objects, date ranges, and string formatting.

Source code in archipy/helpers/utils/datetime_utils.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
class DatetimeUtils:
    """A utility class for handling date and time operations, including conversions, caching, and API integrations.

    This class provides methods for working with both Gregorian and Jalali (Persian) calendars, as well as
    utility functions for timezone-aware datetime objects, date ranges, and string formatting.
    """

    """A class-level cache for storing holiday statuses to avoid redundant API calls."""
    _holiday_cache: ClassVar[dict[str, tuple[bool, datetime]]] = {}

    @staticmethod
    def convert_to_jalali(target_date: date) -> jdatetime.date:
        """Converts a Gregorian date to a Jalali (Persian) date.

        Args:
            target_date (date): The Gregorian date to convert.

        Returns:
            jdatetime.date: The corresponding Jalali date.
        """
        return jdatetime.date.fromgregorian(date=target_date)

    @classmethod
    def is_holiday_in_iran(cls, target_date: date) -> bool:
        """Determines if the target date is a holiday in Iran.

        This method leverages caching and an external API to check if the given date is a holiday.

        Args:
            target_date (date): The date to check for holiday status.

        Returns:
            bool: True if the date is a holiday, False otherwise.
        """
        # Convert to Jalali date first
        jalali_date = cls.convert_to_jalali(target_date)
        date_str = target_date.strftime("%Y-%m-%d")
        current_time = cls.get_datetime_utc_now()

        # Check cache first
        is_cached, is_holiday = cls._check_cache(date_str, current_time)
        if is_cached:
            return is_holiday

        # Fetch holiday status and cache it
        return cls._fetch_and_cache_holiday_status(jalali_date, date_str, current_time)

    @classmethod
    def _check_cache(cls, date_str: str, current_time: datetime) -> tuple[bool, bool]:
        """Checks the cache for holiday status to avoid redundant API calls.

        Args:
            date_str (str): The date string to check in the cache.
            current_time (datetime): The current time to compare against cache expiration.

        Returns:
            tuple[bool, bool]: A tuple where the first element indicates if the cache was hit,
                               and the second element is the cached holiday status.
        """
        cached_data = cls._holiday_cache.get(date_str)
        if cached_data:
            is_holiday, expiry_time = cached_data
            if current_time < expiry_time:
                return True, is_holiday

            # Remove expired cache entry
            del cls._holiday_cache[date_str]

        return False, False

    @classmethod
    def _fetch_and_cache_holiday_status(
        cls,
        jalali_date: jdatetime.date,
        date_str: str,
        current_time: datetime,
    ) -> bool:
        """Fetches holiday status from the API and caches the result.

        This method calls an external API to determine if the given Jalali date is a holiday.
        If the API call is successful, the result is cached with an expiration time to avoid
        redundant API calls. If the API call fails, an `UnknownError` is raised.

        Args:
            jalali_date (jdatetime.date): The Jalali date to check for holiday status.
            date_str (str): The date string to use as a cache key.
            current_time (datetime): The current time to set cache expiration.

        Returns:
            bool: True if the date is a holiday, False otherwise.

        Raises:
            UnknownError: If the API request fails due to a network issue or other request-related errors.
        """
        try:
            config: Any = BaseConfig.global_config()
            response = cls._call_holiday_api(jalali_date)
            is_holiday = cls._parse_holiday_response(response, jalali_date)

            # Determine cache TTL based on whether the date is historical
            target_date = datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=UTC).date()
            is_historical = target_date <= current_time.date()
            cache_ttl = config.DATETIME.HISTORICAL_CACHE_TTL if is_historical else config.DATETIME.CACHE_TTL

            # Cache the result with appropriate expiration
            expiry_time = current_time + timedelta(seconds=cache_ttl)
            cls._holiday_cache[date_str] = (is_holiday, expiry_time)
        except requests.RequestException as exception:
            raise UnknownError from exception

        return is_holiday

    @staticmethod
    def _call_holiday_api(jalali_date: jdatetime.date) -> dict[str, Any]:
        """Calls the Time.ir API to fetch holiday data for the given Jalali date.

        Args:
            jalali_date (jdatetime.date): The Jalali date to fetch data for.

        Returns:
            Dict[str, Any]: The JSON response from the API.

        Raises:
            requests.RequestException: If the API request fails.
        """
        config: Any = BaseConfig.global_config()
        retry_strategy = Retry(
            total=config.DATETIME.MAX_RETRIES,
            status_forcelist=[429, 500, 502, 503, 504],
            allowed_methods=["HEAD", "GET", "OPTIONS"],
        )
        adapter = HTTPAdapter(max_retries=retry_strategy)
        session = requests.Session()
        session.mount("https://", adapter)

        url = DatetimeUtils._build_api_url(jalali_date)
        headers = {"x-api-key": config.DATETIME.TIME_IR_API_KEY}
        response = session.get(url, headers=headers, timeout=config.DATETIME.REQUEST_TIMEOUT)
        response.raise_for_status()
        result: dict[str, Any] = response.json()
        return result

    @staticmethod
    def _build_api_url(jalali_date: jdatetime.date) -> str:
        """Builds the API URL with Jalali date parameters.

        Args:
            jalali_date (jdatetime.date): The Jalali date to include in the URL.

        Returns:
            str: The constructed API URL.
        """
        config: Any = BaseConfig.global_config()
        base_url = config.DATETIME.TIME_IR_API_ENDPOINT
        return f"{base_url}?year={jalali_date.year}&month={jalali_date.month}&day={jalali_date.day}"

    @staticmethod
    def _parse_holiday_response(response_data: dict[str, Any], jalali_date: jdatetime.date) -> bool:
        """Parses the API response to extract and return the holiday status.

        Args:
            response_data (Dict[str, Any]): The JSON response from the API.
            jalali_date (jdatetime.date): The Jalali date to check.

        Returns:
            bool: True if the date is a holiday, False otherwise.
        """
        event_list = response_data.get("data", {}).get("event_list", [])
        for event_info in event_list:
            if (
                event_info.get("jalali_year") == jalali_date.year
                and event_info.get("jalali_month") == jalali_date.month
                and event_info.get("jalali_day") == jalali_date.day
            ):
                is_holiday = event_info.get("is_holiday", False)
                return bool(is_holiday)
        return False

    @classmethod
    def ensure_timezone_aware(cls, dt: datetime) -> datetime:
        """Ensures a datetime object is timezone-aware, converting it to UTC if necessary.

        Args:
            dt (datetime): The datetime object to make timezone-aware.

        Returns:
            datetime: The timezone-aware datetime object.
        """
        if dt.tzinfo is None:
            return dt.replace(tzinfo=UTC)
        return dt

    @classmethod
    def daterange(cls, start_date: datetime, end_date: datetime) -> Generator[date]:
        """Generates a range of dates from start_date to end_date, exclusive of end_date.

        Args:
            start_date (datetime): The start date of the range.
            end_date (datetime): The end date of the range.

        Yields:
            date: Each date in the range.
        """
        for n in range((end_date - start_date).days):
            yield (start_date + timedelta(n)).date()

    @classmethod
    def get_string_datetime_from_datetime(cls, dt: datetime, format_: str | None = None) -> str:
        """Converts a datetime object to a formatted string. Default format is ISO 8601.

        Args:
            dt (datetime): The datetime object to format.
            format_ (str | None): The format string. If None, uses ISO 8601.

        Returns:
            str: The formatted datetime string.
        """
        format_ = format_ or "%Y-%m-%dT%H:%M:%S.%f"
        return dt.strftime(format_)

    @classmethod
    def standardize_string_datetime(cls, date_string: str) -> str:
        """Standardizes a datetime string to the default format.

        Args:
            date_string (str): The datetime string to standardize.

        Returns:
            str: The standardized datetime string.
        """
        datetime_ = cls.get_datetime_from_string_datetime(date_string)
        return cls.get_string_datetime_from_datetime(datetime_)

    @classmethod
    def get_datetime_from_string_datetime(cls, date_string: str, format_: str | None = None) -> datetime:
        """Parses a string to a datetime object using the given format, or ISO 8601 by default.

        Args:
            date_string (str): The datetime string to parse.
            format_ (str | None): The format string. If None, uses ISO 8601.

        Returns:
            datetime: The parsed datetime object with UTC timezone.
        """
        # Parse using a single expression and immediately make timezone-aware for both cases
        dt = (
            datetime.fromisoformat(date_string)
            if format_ is None
            else datetime.strptime(date_string, format_).replace(tzinfo=UTC)
        )

        # Handle the fromisoformat case which might already have timezone info
        if dt.tzinfo is None:
            dt = dt.replace(tzinfo=UTC)

        return dt

    @classmethod
    def get_string_datetime_now(cls) -> str:
        """Gets the current datetime as a formatted string. Default format is ISO 8601.

        Returns:
            str: The formatted datetime string.
        """
        return cls.get_string_datetime_from_datetime(cls.get_datetime_now())

    @classmethod
    def get_datetime_now(cls) -> datetime:
        """Gets the current local datetime.

        Returns:
            datetime: The current local datetime.
        """
        return datetime.now()

    @classmethod
    def get_datetime_utc_now(cls) -> datetime:
        """Gets the current UTC datetime.

        Returns:
            datetime: The current UTC datetime.
        """
        return datetime.now(UTC)

    @classmethod
    def get_epoch_time_now(cls) -> int:
        """Gets the current time in seconds since the epoch.

        Returns:
            int: The current epoch time.
        """
        return int(time.time())

    @classmethod
    def get_datetime_before_given_datetime_or_now(
        cls,
        weeks: int = 0,
        days: int = 0,
        hours: int = 0,
        minutes: int = 0,
        seconds: int = 0,
        datetime_given: datetime | None = None,
    ) -> datetime:
        """Subtracts time from a given datetime or the current datetime if not specified.

        Args:
            weeks (int): The number of weeks to subtract.
            days (int): The number of days to subtract.
            hours (int): The number of hours to subtract.
            minutes (int): The number of minutes to subtract.
            seconds (int): The number of seconds to subtract.
            datetime_given (datetime | None): The datetime to subtract from. If None, uses the current datetime.

        Returns:
            datetime: The resulting datetime after subtraction.
        """
        datetime_given = datetime_given or cls.get_datetime_now()
        return datetime_given - timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)

    @classmethod
    def get_datetime_after_given_datetime_or_now(
        cls,
        weeks: int = 0,
        days: int = 0,
        hours: int = 0,
        minutes: int = 0,
        seconds: int = 0,
        datetime_given: datetime | None = None,
    ) -> datetime:
        """Adds time to a given datetime or the current datetime if not specified.

        Args:
            weeks (int): The number of weeks to add.
            days (int): The number of days to add.
            hours (int): The number of hours to add.
            minutes (int): The number of minutes to add.
            seconds (int): The number of seconds to add.
            datetime_given (datetime | None): The datetime to add to. If None, uses the current datetime.

        Returns:
            datetime: The resulting datetime after addition.
        """
        datetime_given = datetime_given or cls.get_datetime_now()
        return datetime_given + timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)

archipy.helpers.utils.datetime_utils.DatetimeUtils.convert_to_jalali staticmethod 

convert_to_jalali(target_date: date) -> jdatetime.date

Converts a Gregorian date to a Jalali (Persian) date.

Parameters:

Name Type Description Default
target_date date

The Gregorian date to convert.

 required

Returns:

Type Description
date

jdatetime.date: The corresponding Jalali date.
Source code in archipy/helpers/utils/datetime_utils.py 
25
26
27
28
29
30
31
32
33
34
35
@staticmethod
def convert_to_jalali(target_date: date) -> jdatetime.date:
    """Converts a Gregorian date to a Jalali (Persian) date.

    Args:
        target_date (date): The Gregorian date to convert.

    Returns:
        jdatetime.date: The corresponding Jalali date.
    """
    return jdatetime.date.fromgregorian(date=target_date)

archipy.helpers.utils.datetime_utils.DatetimeUtils.is_holiday_in_iran classmethod 

is_holiday_in_iran(target_date: date) -> bool

Determines if the target date is a holiday in Iran.

This method leverages caching and an external API to check if the given date is a holiday.

Parameters:

Name Type Description Default
target_date date

The date to check for holiday status.

 required

Returns:

Name Type Description
bool bool

True if the date is a holiday, False otherwise.
Source code in archipy/helpers/utils/datetime_utils.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
@classmethod
def is_holiday_in_iran(cls, target_date: date) -> bool:
    """Determines if the target date is a holiday in Iran.

    This method leverages caching and an external API to check if the given date is a holiday.

    Args:
        target_date (date): The date to check for holiday status.

    Returns:
        bool: True if the date is a holiday, False otherwise.
    """
    # Convert to Jalali date first
    jalali_date = cls.convert_to_jalali(target_date)
    date_str = target_date.strftime("%Y-%m-%d")
    current_time = cls.get_datetime_utc_now()

    # Check cache first
    is_cached, is_holiday = cls._check_cache(date_str, current_time)
    if is_cached:
        return is_holiday

    # Fetch holiday status and cache it
    return cls._fetch_and_cache_holiday_status(jalali_date, date_str, current_time)

archipy.helpers.utils.datetime_utils.DatetimeUtils.ensure_timezone_aware classmethod 

ensure_timezone_aware(dt: datetime) -> datetime

Ensures a datetime object is timezone-aware, converting it to UTC if necessary.

Parameters:

Name Type Description Default
dt datetime

The datetime object to make timezone-aware.

 required

Returns:

Name Type Description
datetime datetime

The timezone-aware datetime object.
Source code in archipy/helpers/utils/datetime_utils.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
@classmethod
def ensure_timezone_aware(cls, dt: datetime) -> datetime:
    """Ensures a datetime object is timezone-aware, converting it to UTC if necessary.

    Args:
        dt (datetime): The datetime object to make timezone-aware.

    Returns:
        datetime: The timezone-aware datetime object.
    """
    if dt.tzinfo is None:
        return dt.replace(tzinfo=UTC)
    return dt

archipy.helpers.utils.datetime_utils.DatetimeUtils.daterange classmethod 

daterange(
    start_date: datetime, end_date: datetime
) -> Generator[date]

Generates a range of dates from start_date to end_date, exclusive of end_date.

Parameters:

Name Type Description Default
start_date datetime

The start date of the range.

 required
end_date datetime

The end date of the range.

 required

Yields:

Name Type Description
date Generator[date]

Each date in the range.
Source code in archipy/helpers/utils/datetime_utils.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
@classmethod
def daterange(cls, start_date: datetime, end_date: datetime) -> Generator[date]:
    """Generates a range of dates from start_date to end_date, exclusive of end_date.

    Args:
        start_date (datetime): The start date of the range.
        end_date (datetime): The end date of the range.

    Yields:
        date: Each date in the range.
    """
    for n in range((end_date - start_date).days):
        yield (start_date + timedelta(n)).date()

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_string_datetime_from_datetime classmethod 

get_string_datetime_from_datetime(
    dt: datetime, format_: str | None = None
) -> str

Converts a datetime object to a formatted string. Default format is ISO 8601.

Parameters:

Name Type Description Default
dt datetime

The datetime object to format.

 required
format_ str | None

The format string. If None, uses ISO 8601.

 None

Returns:

Name Type Description
str str

The formatted datetime string.
Source code in archipy/helpers/utils/datetime_utils.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
@classmethod
def get_string_datetime_from_datetime(cls, dt: datetime, format_: str | None = None) -> str:
    """Converts a datetime object to a formatted string. Default format is ISO 8601.

    Args:
        dt (datetime): The datetime object to format.
        format_ (str | None): The format string. If None, uses ISO 8601.

    Returns:
        str: The formatted datetime string.
    """
    format_ = format_ or "%Y-%m-%dT%H:%M:%S.%f"
    return dt.strftime(format_)

archipy.helpers.utils.datetime_utils.DatetimeUtils.standardize_string_datetime classmethod 

standardize_string_datetime(date_string: str) -> str

Standardizes a datetime string to the default format.

Parameters:

Name Type Description Default
date_string str

The datetime string to standardize.

 required

Returns:

Name Type Description
str str

The standardized datetime string.
Source code in archipy/helpers/utils/datetime_utils.py 
235
236
237
238
239
240
241
242
243
244
245
246
@classmethod
def standardize_string_datetime(cls, date_string: str) -> str:
    """Standardizes a datetime string to the default format.

    Args:
        date_string (str): The datetime string to standardize.

    Returns:
        str: The standardized datetime string.
    """
    datetime_ = cls.get_datetime_from_string_datetime(date_string)
    return cls.get_string_datetime_from_datetime(datetime_)

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_datetime_from_string_datetime classmethod 

get_datetime_from_string_datetime(
    date_string: str, format_: str | None = None
) -> datetime

Parses a string to a datetime object using the given format, or ISO 8601 by default.

Parameters:

Name Type Description Default
date_string str

The datetime string to parse.

 required
format_ str | None

The format string. If None, uses ISO 8601.

 None

Returns:

Name Type Description
datetime datetime

The parsed datetime object with UTC timezone.
Source code in archipy/helpers/utils/datetime_utils.py 
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
@classmethod
def get_datetime_from_string_datetime(cls, date_string: str, format_: str | None = None) -> datetime:
    """Parses a string to a datetime object using the given format, or ISO 8601 by default.

    Args:
        date_string (str): The datetime string to parse.
        format_ (str | None): The format string. If None, uses ISO 8601.

    Returns:
        datetime: The parsed datetime object with UTC timezone.
    """
    # Parse using a single expression and immediately make timezone-aware for both cases
    dt = (
        datetime.fromisoformat(date_string)
        if format_ is None
        else datetime.strptime(date_string, format_).replace(tzinfo=UTC)
    )

    # Handle the fromisoformat case which might already have timezone info
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=UTC)

    return dt

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_string_datetime_now classmethod 

get_string_datetime_now() -> str

Gets the current datetime as a formatted string. Default format is ISO 8601.

Returns:

Name Type Description
str str

The formatted datetime string.
Source code in archipy/helpers/utils/datetime_utils.py 
272
273
274
275
276
277
278
279
@classmethod
def get_string_datetime_now(cls) -> str:
    """Gets the current datetime as a formatted string. Default format is ISO 8601.

    Returns:
        str: The formatted datetime string.
    """
    return cls.get_string_datetime_from_datetime(cls.get_datetime_now())

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_datetime_now classmethod 

get_datetime_now() -> datetime

Gets the current local datetime.

Returns:

Name Type Description
datetime datetime

The current local datetime.
Source code in archipy/helpers/utils/datetime_utils.py 
281
282
283
284
285
286
287
288
@classmethod
def get_datetime_now(cls) -> datetime:
    """Gets the current local datetime.

    Returns:
        datetime: The current local datetime.
    """
    return datetime.now()

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_datetime_utc_now classmethod 

get_datetime_utc_now() -> datetime

Gets the current UTC datetime.

Returns:

Name Type Description
datetime datetime

The current UTC datetime.
Source code in archipy/helpers/utils/datetime_utils.py 
290
291
292
293
294
295
296
297
@classmethod
def get_datetime_utc_now(cls) -> datetime:
    """Gets the current UTC datetime.

    Returns:
        datetime: The current UTC datetime.
    """
    return datetime.now(UTC)

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_epoch_time_now classmethod 

get_epoch_time_now() -> int

Gets the current time in seconds since the epoch.

Returns:

Name Type Description
int int

The current epoch time.
Source code in archipy/helpers/utils/datetime_utils.py 
299
300
301
302
303
304
305
306
@classmethod
def get_epoch_time_now(cls) -> int:
    """Gets the current time in seconds since the epoch.

    Returns:
        int: The current epoch time.
    """
    return int(time.time())

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_datetime_before_given_datetime_or_now classmethod 

get_datetime_before_given_datetime_or_now(
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime

Subtracts time from a given datetime or the current datetime if not specified.

Parameters:

Name Type Description Default
weeks int

The number of weeks to subtract.

 0
days int

The number of days to subtract.

 0
hours int

The number of hours to subtract.

 0
minutes int

The number of minutes to subtract.

 0
seconds int

The number of seconds to subtract.

 0
datetime_given datetime | None

The datetime to subtract from. If None, uses the current datetime.

 None

Returns:

Name Type Description
datetime datetime

The resulting datetime after subtraction.
Source code in archipy/helpers/utils/datetime_utils.py 
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
@classmethod
def get_datetime_before_given_datetime_or_now(
    cls,
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime:
    """Subtracts time from a given datetime or the current datetime if not specified.

    Args:
        weeks (int): The number of weeks to subtract.
        days (int): The number of days to subtract.
        hours (int): The number of hours to subtract.
        minutes (int): The number of minutes to subtract.
        seconds (int): The number of seconds to subtract.
        datetime_given (datetime | None): The datetime to subtract from. If None, uses the current datetime.

    Returns:
        datetime: The resulting datetime after subtraction.
    """
    datetime_given = datetime_given or cls.get_datetime_now()
    return datetime_given - timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)

archipy.helpers.utils.datetime_utils.DatetimeUtils.get_datetime_after_given_datetime_or_now classmethod 

get_datetime_after_given_datetime_or_now(
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime

Adds time to a given datetime or the current datetime if not specified.

Parameters:

Name Type Description Default
weeks int

The number of weeks to add.

 0
days int

The number of days to add.

 0
hours int

The number of hours to add.

 0
minutes int

The number of minutes to add.

 0
seconds int

The number of seconds to add.

 0
datetime_given datetime | None

The datetime to add to. If None, uses the current datetime.

 None

Returns:

Name Type Description
datetime datetime

The resulting datetime after addition.
Source code in archipy/helpers/utils/datetime_utils.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
@classmethod
def get_datetime_after_given_datetime_or_now(
    cls,
    weeks: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    datetime_given: datetime | None = None,
) -> datetime:
    """Adds time to a given datetime or the current datetime if not specified.

    Args:
        weeks (int): The number of weeks to add.
        days (int): The number of days to add.
        hours (int): The number of hours to add.
        minutes (int): The number of minutes to add.
        seconds (int): The number of seconds to add.
        datetime_given (datetime | None): The datetime to add to. If None, uses the current datetime.

    Returns:
        datetime: The resulting datetime after addition.
    """
    datetime_given = datetime_given or cls.get_datetime_now()
    return datetime_given + timedelta(weeks=weeks, days=days, hours=hours, minutes=minutes, seconds=seconds)

options: show_root_toc_entry: false heading_level: 3

String Utils

Utilities for string manipulation including slugification, truncation, random string generation, and HTML sanitization.

archipy.helpers.utils.string_utils.StringUtils

Bases: StringUtilsConstants

String utilities for text normalization, cleaning, and masking.

This class provides methods for handling Persian and Arabic text, including normalization, punctuation cleaning, number conversion, and masking of sensitive information like URLs, emails, and phone numbers.

Source code in archipy/helpers/utils/string_utils.py 
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
class StringUtils(StringUtilsConstants):
    """String utilities for text normalization, cleaning, and masking.

    This class provides methods for handling Persian and Arabic text, including normalization,
    punctuation cleaning, number conversion, and masking of sensitive information like URLs,
    emails, and phone numbers.
    """

    @classmethod
    def remove_arabic_vowels(cls, text: str) -> str:
        """Removes Arabic vowels (tashkeel) from the text.

        Args:
            text (str): The input text containing Arabic vowels.

        Returns:
            str: The text with Arabic vowels removed.
        """
        return text.translate(cls.arabic_vowel_translate_table)

    @classmethod
    def normalize_persian_chars(cls, text: str) -> str:
        """Normalizes Persian characters to their standard forms.

        Args:
            text (str): The input text containing Persian characters.

        Returns:
            str: The text with Persian characters normalized.
        """
        text = text.translate(cls.alphabet_akoolad_alef_translate_table)
        text = text.translate(cls.alphabet_alef_translate_table)
        text = text.translate(cls.alphabet_be_translate_table)
        text = text.translate(cls.alphabet_pe_translate_table)
        text = text.translate(cls.alphabet_te_translate_table)
        text = text.translate(cls.alphabet_se_translate_table)
        text = text.translate(cls.alphabet_jim_translate_table)
        text = text.translate(cls.alphabet_che_translate_table)
        text = text.translate(cls.alphabet_he_translate_table)
        text = text.translate(cls.alphabet_khe_translate_table)
        text = text.translate(cls.alphabet_dal_translate_table)
        text = text.translate(cls.alphabet_zal_translate_table)
        text = text.translate(cls.alphabet_re_translate_table)
        text = text.translate(cls.alphabet_ze_translate_table)
        text = text.translate(cls.alphabet_zhe_translate_table)
        text = text.translate(cls.alphabet_sin_translate_table)
        text = text.translate(cls.alphabet_shin_translate_table)
        text = text.translate(cls.alphabet_sad_translate_table)
        text = text.translate(cls.alphabet_zad_translate_table)
        text = text.translate(cls.alphabet_ta_translate_table)
        text = text.translate(cls.alphabet_za_translate_table)
        text = text.translate(cls.alphabet_eyn_translate_table)
        text = text.translate(cls.alphabet_gheyn_translate_table)
        text = text.translate(cls.alphabet_fe_translate_table)
        text = text.translate(cls.alphabet_ghaf_translate_table)
        text = text.translate(cls.alphabet_kaf_translate_table)
        text = text.translate(cls.alphabet_gaf_translate_table)
        text = text.translate(cls.alphabet_lam_translate_table)
        text = text.translate(cls.alphabet_mim_translate_table)
        text = text.translate(cls.alphabet_nun_translate_table)
        text = text.translate(cls.alphabet_vav_translate_table)
        text = text.translate(cls.alphabet_ha_translate_table)
        return text.translate(cls.alphabet_ye_translate_table)

    @classmethod
    def normalize_punctuation(cls, text: str) -> str:
        """Normalizes punctuation marks in the text.

        Args:
            text (str): The input text containing punctuation marks.

        Returns:
            str: The text with punctuation marks normalized.
        """
        text = text.translate(cls.punctuation_translate_table1)
        text = text.translate(cls.punctuation_translate_table2)
        text = text.translate(cls.punctuation_translate_table3)
        text = text.translate(cls.punctuation_translate_table4)
        text = text.translate(cls.punctuation_translate_table5)
        text = text.translate(cls.punctuation_translate_table6)
        text = text.translate(cls.punctuation_translate_table7)
        text = text.translate(cls.punctuation_translate_table8)
        text = text.translate(cls.punctuation_translate_table9)
        text = text.translate(cls.punctuation_translate_table10)
        text = text.translate(cls.punctuation_translate_table11)
        text = text.translate(cls.punctuation_translate_table12)
        return text.translate(cls.punctuation_translate_table13)

    @classmethod
    def normalize_numbers(cls, text: str) -> str:
        """Normalizes numbers in the text to English format.

        Args:
            text (str): The input text containing numbers.

        Returns:
            str: The text with numbers normalized to English format.
        """
        text = text.translate(cls.number_zero_translate_table)
        text = text.translate(cls.number_one_translate_table)
        text = text.translate(cls.number_two_translate_table)
        text = text.translate(cls.number_three_translate_table)
        text = text.translate(cls.number_four_translate_table)
        text = text.translate(cls.number_five_translate_table)
        text = text.translate(cls.number_six_translate_table)
        text = text.translate(cls.number_seven_translate_table)
        text = text.translate(cls.number_eight_translate_table)
        return text.translate(cls.number_nine_translate_table)

    @classmethod
    def clean_spacing(cls, text: str) -> str:
        """Cleans up spacing issues in the text, such as non-breaking spaces and zero-width non-joiners.

        Args:
            text (str): The input text with spacing issues.

        Returns:
            str: The text with spacing cleaned up.
        """
        text = text.replace("\u200c", " ")  # ZWNJ
        text = text.replace("\xa0", " ")  # NBSP

        for pattern, repl in cls.character_refinement_patterns:
            text = pattern.sub(repl, text)

        return text

    @classmethod
    def normalize_punctuation_spacing(cls, text: str) -> str:
        """Applies proper spacing around punctuation marks.

        Args:
            text (str): The input text with punctuation spacing issues.

        Returns:
            str: The text with proper spacing around punctuation marks.
        """
        for pattern, repl in cls.punctuation_spacing_patterns:
            text = pattern.sub(repl, text)
        return text

    @classmethod
    def remove_punctuation_marks(cls, text: str) -> str:
        """Removes punctuation marks from the text.

        Args:
            text (str): The input text containing punctuation marks.

        Returns:
            str: The text with punctuation marks removed.
        """
        return text.translate(cls.punctuation_persian_marks_to_space_translate_table)

    @classmethod
    def mask_urls(cls, text: str, mask: str | None = None) -> str:
        """Masks URLs in the text with a specified mask.

        Args:
            text (str): The input text containing URLs.
            mask (str | None): The mask to replace URLs with. Defaults to "MASK_URL".

        Returns:
            str: The text with URLs masked.
        """
        mask = mask or "MASK_URL"
        return re_compile(r"https?://\S+|www\.\S+").sub(f" {mask} ", text)

    @classmethod
    def mask_emails(cls, text: str, mask: str | None = None) -> str:
        """Masks email addresses in the text with a specified mask.

        Args:
            text (str): The input text containing email addresses.
            mask (str | None): The mask to replace emails with. Defaults to "MASK_EMAIL".

        Returns:
            str: The text with email addresses masked.
        """
        mask = mask or "MASK_EMAIL"
        return re_compile(r"\S+@\S+\.\S+").sub(f" {mask} ", text)

    @classmethod
    def mask_phones(cls, text: str, mask: str | None = None) -> str:
        """Masks phone numbers in the text with a specified mask.

        Args:
            text (str): The input text containing phone numbers.
            mask (str | None): The mask to replace phone numbers with. Defaults to "MASK_PHONE".

        Returns:
            str: The text with phone numbers masked.
        """
        mask = mask or "MASK_PHONE"
        return re_compile(r"(?:\+98|0)?(?:\d{3}\s*?\d{3}\s*?\d{4})").sub(f" {mask} ", text)

    @classmethod
    def convert_english_number_to_persian(cls, text: str) -> str:
        """Converts English numbers to Persian numbers in the text.

        Args:
            text (str): The input text containing English numbers.

        Returns:
            str: The text with English numbers converted to Persian numbers.
        """
        table = {
            48: 1776,  # 0
            49: 1777,  # 1
            50: 1778,  # 2
            51: 1779,  # 3
            52: 1780,  # 4
            53: 1781,  # 5
            54: 1782,  # 6
            55: 1783,  # 7
            56: 1784,  # 8
            57: 1785,  # 9
            44: 1548,  # ,
        }
        return text.translate(table)

    @classmethod
    def convert_numbers_to_english(cls, text: str) -> str:
        """Converts Persian/Arabic numbers to English numbers in the text.

        Args:
            text (str): The input text containing Persian/Arabic numbers.

        Returns:
            str: The text with Persian/Arabic numbers converted to English numbers.
        """
        table = {
            1776: 48,  # 0
            1777: 49,  # 1
            1778: 50,  # 2
            1779: 51,  # 3
            1780: 52,  # 4
            1781: 53,  # 5
            1782: 54,  # 6
            1783: 55,  # 7
            1784: 56,  # 8
            1785: 57,  # 9
            1632: 48,  # 0
            1633: 49,  # 1
            1634: 50,  # 2
            1635: 51,  # 3
            1636: 52,  # 4
            1637: 53,  # 5
            1638: 54,  # 6
            1639: 55,  # 7
            1640: 56,  # 8
            1641: 57,  # 9
        }
        return text.translate(table)

    @classmethod
    def convert_add_3digit_delimiter(cls, value: int) -> str:
        """Adds thousand separators to numbers.

        Args:
            value (int): The number to format.

        Returns:
            str: The formatted number with thousand separators.
        """
        return f"{value:,}" if isinstance(value, int) else value

    @classmethod
    def remove_emoji(cls, text: str) -> str:
        """Removes emoji characters from the text.

        Args:
            text (str): The input text containing emojis.

        Returns:
            str: The text with emojis removed.
        """
        emoji_pattern = re.compile(
            r"["
            r"\U0001F600-\U0001F64F"  # emoticons
            r"\U0001F300-\U0001F5FF"  # symbols & pictographs
            r"\U0001F680-\U0001F6FF"  # transport & map symbols
            r"\U0001F1E0-\U0001F1FF"  # flags
            r"\U0001F900-\U0001F9FF"  # supplemental symbols and pictographs
            r"\U0001FA00-\U0001FA6F"  # symbols and pictographs extended-A
            r"\U00002600-\U000026FF"  # miscellaneous symbols (some are emojis)
            r"\U00002700-\U000027BF"  # dingbats (some are emojis)
            r"\U00002190-\U000021FF"  # arrows (some are emojis)
            r"]+",
            re.UNICODE,
        )
        return emoji_pattern.sub(r"", text)

    @classmethod
    def replace_currencies_with_mask(cls, text: str, mask: str | None = None) -> str:
        """Masks currency symbols and amounts in the text.

        Args:
            text (str): The input text containing currency symbols and amounts.
            mask (str | None): The mask to replace currencies with. Defaults to "MASK_CURRENCIES".

        Returns:
            str: The text with currency symbols and amounts masked.
        """
        mask = mask or "MASK_CURRENCIES"
        currency_pattern = re_compile(r"(\\|zł|£|\$|₡|₦|¥|₩|₪|₫|€|₱|₲|₴|₹|﷼)+")
        return currency_pattern.sub(f" {mask} ", text)

    @classmethod
    def replace_numbers_with_mask(cls, text: str, mask: str | None = None) -> str:
        """Masks numbers in the text.

        Args:
            text (str): The input text containing numbers.
            mask (str | None): The mask to replace numbers with. Defaults to "MASK_NUMBERS".

        Returns:
            str: The text with numbers masked.
        """
        mask = mask or "MASK_NUMBERS"
        numbers = re.findall("[0-9]+", text)
        result: str = text
        for number in sorted(numbers, key=len, reverse=True):
            result = result.replace(number, f" {mask} ")  # type: ignore[arg-type]
        return result

    @classmethod
    def is_string_none_or_empty(cls, text: str) -> bool:
        """Checks if a string is `None` or empty (after stripping whitespace).

        Args:
            text (str): The input string to check.

        Returns:
            bool: `True` if the string is `None` or empty, `False` otherwise.
        """
        return text is None or (isinstance(text, str) and not text.strip())

    @classmethod
    def normalize_persian_text(
        cls,
        text: str,
        *,
        remove_vowels: bool = True,
        normalize_punctuation: bool = True,
        normalize_numbers: bool = True,
        normalize_persian_chars: bool = True,
        mask_urls: bool = False,
        mask_emails: bool = False,
        mask_phones: bool = False,
        mask_currencies: bool = False,
        mask_all_numbers: bool = False,
        remove_emojis: bool = False,
        url_mask: str | None = None,
        email_mask: str | None = None,
        phone_mask: str | None = None,
        currency_mask: str | None = None,
        number_mask: str | None = None,
        clean_spacing: bool = True,
        remove_punctuation: bool = False,
        normalize_punctuation_spacing: bool = False,
    ) -> str:
        """Normalizes Persian text with configurable options.

        Args:
            text (str): The input text to normalize.
            remove_vowels (bool): Whether to remove Arabic vowels. Defaults to `True`.
            normalize_punctuation (bool): Whether to normalize punctuation marks. Defaults to `True`.
            normalize_numbers (bool): Whether to normalize numbers to English format. Defaults to `True`.
            normalize_persian_chars (bool): Whether to normalize Persian characters. Defaults to `True`.
            mask_urls (bool): Whether to mask URLs. Defaults to `False`.
            mask_emails (bool): Whether to mask email addresses. Defaults to `False`.
            mask_phones (bool): Whether to mask phone numbers. Defaults to `False`.
            mask_currencies (bool): Whether to mask currency symbols and amounts. Defaults to `False`.
            mask_all_numbers (bool): Whether to mask all numbers. Defaults to `False`.
            remove_emojis (bool): Whether to remove emojis. Defaults to `False`.
            url_mask (str | None): The mask to replace URLs with. Defaults to `None`.
            email_mask (str | None): The mask to replace email addresses with. Defaults to `None`.
            phone_mask (str | None): The mask to replace phone numbers with. Defaults to `None`.
            currency_mask (str | None): The mask to replace currency symbols and amounts with. Defaults to `None`.
            number_mask (str | None): The mask to replace numbers with. Defaults to `None`.
            clean_spacing (bool): Whether to clean up spacing issues. Defaults to `True`.
            remove_punctuation (bool): Whether to remove punctuation marks. Defaults to `False`.
            normalize_punctuation_spacing (bool): Whether to apply proper spacing around punctuation marks. Defaults to `False`.

        Returns:
            str: The normalized text.
        """
        if not text:
            return text

        # Remove emojis if requested
        if remove_emojis:
            text = cls.remove_emoji(text)

        # Apply normalizations
        if remove_vowels:
            text = cls.remove_arabic_vowels(text)
        if normalize_persian_chars:
            text = cls.normalize_persian_chars(text)
        if normalize_punctuation:
            text = cls.normalize_punctuation(text)
        if remove_punctuation:
            text = cls.remove_punctuation_marks(text)
        if normalize_numbers:
            text = cls.normalize_numbers(text)

        # Apply masking
        if mask_urls:
            text = cls.mask_urls(text, mask=url_mask)
        if mask_emails:
            text = cls.mask_emails(text, mask=email_mask)
        if mask_phones:
            text = cls.mask_phones(text, mask=phone_mask)
        if mask_currencies:
            text = cls.replace_currencies_with_mask(text, mask=currency_mask)
        if mask_all_numbers:
            text = cls.replace_numbers_with_mask(text, mask=number_mask)

        if clean_spacing:
            text = cls.clean_spacing(text)
        if normalize_punctuation_spacing:
            text = cls.normalize_punctuation_spacing(text)

        return text.strip()

    @classmethod
    def snake_to_camel_case(cls, text: str) -> str:
        """Converts snake_case to camelCase.

        Args:
            text (str): The input text in snake_case format.

        Returns:
            str: The text converted to camelCase format.
        """
        if cls.is_string_none_or_empty(text):
            return text

        components = text.split("_")
        # First component remains lowercase, the rest get capitalized
        return components[0] + "".join(x.title() for x in components[1:])

    @classmethod
    def camel_to_snake_case(cls, text: str) -> str:
        """Converts camelCase to snake_case.

        Args:
            text (str): The input text in camelCase format.

        Returns:
            str: The text converted to snake_case format.
        """
        if cls.is_string_none_or_empty(text):
            return text

        # Add underscore before each capital letter and convert to lowercase
        s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", text)
        return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()

archipy.helpers.utils.string_utils.StringUtils.arabic_vowel_translate_table class-attribute instance-attribute 

arabic_vowel_translate_table = maketrans(fromkeys("ًٌَُِّْٓءٍٰۖۗۘۙۚۛ", ""))

archipy.helpers.utils.string_utils.StringUtils.alphabet_akoolad_alef_translate_table class-attribute instance-attribute 

alphabet_akoolad_alef_translate_table = maketrans(
    fromkeys("ﺁ", "آ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_alef_translate_table class-attribute instance-attribute 

alphabet_alef_translate_table = maketrans(
    fromkeys("ﺎٲٱإﺍأٵٳ", "ا")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_be_translate_table class-attribute instance-attribute 

alphabet_be_translate_table = maketrans(
    fromkeys("ﺐﺏﺑٻٮ", "ب")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_pe_translate_table class-attribute instance-attribute 

alphabet_pe_translate_table = maketrans(
    fromkeys("ﭖﭗﭙﺒﭘڀݐݒݕ", "پ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_te_translate_table class-attribute instance-attribute 

alphabet_te_translate_table = maketrans(
    fromkeys("ﭡٺٹﭞٿټﺕﺗﺖﺘݓ", "ت")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_se_translate_table class-attribute instance-attribute 

alphabet_se_translate_table = maketrans(
    fromkeys("ﺙﺛٽﺚﺜ", "ث")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_jim_translate_table class-attribute instance-attribute 

alphabet_jim_translate_table = maketrans(
    fromkeys("ﺝﺠﺟﺞۚ", "ج")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_che_translate_table class-attribute instance-attribute 

alphabet_che_translate_table = maketrans(
    fromkeys("ڃﭽﭼڇڄݘڿﭻ", "چ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_he_translate_table class-attribute instance-attribute 

alphabet_he_translate_table = maketrans(
    fromkeys("ﺢﺤڅځﺣﺡ", "ح")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_khe_translate_table class-attribute instance-attribute 

alphabet_khe_translate_table = maketrans(
    fromkeys("ﺥﺦﺨﺧڂݗ", "خ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_dal_translate_table class-attribute instance-attribute 

alphabet_dal_translate_table = maketrans(
    fromkeys("ډﺪﺩڊڈڍܥ", "د")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_zal_translate_table class-attribute instance-attribute 

alphabet_zal_translate_table = maketrans(
    fromkeys("ﺫﺬﻧڐڏڎڌ", "ذ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_re_translate_table class-attribute instance-attribute 

alphabet_re_translate_table = maketrans(
    fromkeys("ڗڒڑڕﺭﺮږڔړڒڑۯ", "ر")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_ze_translate_table class-attribute instance-attribute 

alphabet_ze_translate_table = maketrans(fromkeys("ﺰﺯ", "ز"))

archipy.helpers.utils.string_utils.StringUtils.alphabet_zhe_translate_table class-attribute instance-attribute 

alphabet_zhe_translate_table = maketrans(
    fromkeys("ﮊڙﮋ", "ژ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_sin_translate_table class-attribute instance-attribute 

alphabet_sin_translate_table = maketrans(
    fromkeys("ݭݜﺱﺲﺴﺳڛښۣݾݽ", "س")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_shin_translate_table class-attribute instance-attribute 

alphabet_shin_translate_table = maketrans(
    fromkeys("ﺵﺶﺸﺷڜۺ", "ش")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_sad_translate_table class-attribute instance-attribute 

alphabet_sad_translate_table = maketrans(
    fromkeys("ﺹﺺﺼﺻڝ", "ص")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_zad_translate_table class-attribute instance-attribute 

alphabet_zad_translate_table = maketrans(
    fromkeys("ﺽﺾﺿﻀۻڞ", "ض")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_ta_translate_table class-attribute instance-attribute 

alphabet_ta_translate_table = maketrans(
    fromkeys("ﻁﻂﻃﻄ", "ط")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_za_translate_table class-attribute instance-attribute 

alphabet_za_translate_table = maketrans(
    fromkeys("ﻆﻇﻈڟﻅ", "ظ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_eyn_translate_table class-attribute instance-attribute 

alphabet_eyn_translate_table = maketrans(
    fromkeys("ڠﻉﻊﻋﻌ", "ع")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_gheyn_translate_table class-attribute instance-attribute 

alphabet_gheyn_translate_table = maketrans(
    fromkeys("ﻎۼﻍﻐﻏݝݞݟ", "غ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_fe_translate_table class-attribute instance-attribute 

alphabet_fe_translate_table = maketrans(
    fromkeys("ﻒﻑﻔﻓڡڥڦڤ\u0603ڣڢ", "ف")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_ghaf_translate_table class-attribute instance-attribute 

alphabet_ghaf_translate_table = maketrans(
    fromkeys("ﻕﻖﻗڧڨ؋ﻘ", "ق")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_kaf_translate_table class-attribute instance-attribute 

alphabet_kaf_translate_table = maketrans(
    fromkeys("ڭﻚﮎﻜﮏګﻛﮑﮐڪكݢݣݤڬڮݿﻙ", "ک")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_gaf_translate_table class-attribute instance-attribute 

alphabet_gaf_translate_table = maketrans(
    fromkeys("ﮚﮒﮓﮕﮔڱڰڲڳڴ", "گ")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_lam_translate_table class-attribute instance-attribute 

alphabet_lam_translate_table = maketrans(
    fromkeys("ﻟﻝﻞﻠݪڷڸڶڵ", "ل")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_mim_translate_table class-attribute instance-attribute 

alphabet_mim_translate_table = maketrans(
    fromkeys("ﻡﻤﻢﻣݦݥ", "م")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_nun_translate_table class-attribute instance-attribute 

alphabet_nun_translate_table = maketrans(
    fromkeys("ڼﻦﻥﻨݩݨݧڻڽںڹ", "ن")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_vav_translate_table class-attribute instance-attribute 

alphabet_vav_translate_table = maketrans(
    fromkeys("ވﯙۈۋﺆۊۇۏۅۉﻭﻮؤۆۄ", "و")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_ha_translate_table class-attribute instance-attribute 

alphabet_ha_translate_table = maketrans(
    fromkeys("ﺓﮭﺔﻬھﻩﻫﻪۀەةہܣܤܝ", "ه")
)

archipy.helpers.utils.string_utils.StringUtils.alphabet_ye_translate_table class-attribute instance-attribute 

alphabet_ye_translate_table = maketrans(
    fromkeys("ﯨﭛﻯۍﻰﻱﻲﻳﻴﯼېﯽﯾﯿێےىيٸۑؽؾؿﺉﺋﺌ", "ی")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table1 class-attribute instance-attribute 

punctuation_translate_table1 = maketrans(fromkeys("¬", " "))

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table2 class-attribute instance-attribute 

punctuation_translate_table2 = maketrans(
    fromkeys("•·●·・∙｡ⴰ", ".")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table3 class-attribute instance-attribute 

punctuation_translate_table3 = maketrans(
    fromkeys(",٬٫‚，", "،")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table4 class-attribute instance-attribute 

punctuation_translate_table4 = maketrans(
    fromkeys("ʕ?⁉�", "؟")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table5 class-attribute instance-attribute 

punctuation_translate_table5 = maketrans(
    fromkeys("‼❕", "!")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table6 class-attribute instance-attribute 

punctuation_translate_table6 = maketrans(fromkeys("_", "ـ"))

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table7 class-attribute instance-attribute 

punctuation_translate_table7 = maketrans(
    fromkeys("－━−‐‑–—─−ー⁃", "-")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table8 class-attribute instance-attribute 

punctuation_translate_table8 = maketrans(
    fromkeys("‹《﴾", "«")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table9 class-attribute instance-attribute 

punctuation_translate_table9 = maketrans(
    fromkeys("›》﴿", "»")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table10 class-attribute instance-attribute 

punctuation_translate_table10 = maketrans(
    fromkeys(";", "؛")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table11 class-attribute instance-attribute 

punctuation_translate_table11 = maketrans(
    fromkeys("%", "٪")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table12 class-attribute instance-attribute 

punctuation_translate_table12 = maketrans(
    fromkeys("ˈ‘’“”", "'")
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_translate_table13 class-attribute instance-attribute 

punctuation_translate_table13 = maketrans(
    fromkeys("：", ":")
)

archipy.helpers.utils.string_utils.StringUtils.character_refinement_patterns class-attribute instance-attribute 

character_refinement_patterns: list = compile_patterns(
    [(" +", " "), ("\\n\\n+", "\n"), (" ?\\.\\.\\.", " …")]
)

archipy.helpers.utils.string_utils.StringUtils.punctuation_after class-attribute instance-attribute 

punctuation_after = '\\.:!،؛؟»\\]\\)\\}'

archipy.helpers.utils.string_utils.StringUtils.punctuation_before class-attribute instance-attribute 

punctuation_before = '«\\[\\(\\{'

archipy.helpers.utils.string_utils.StringUtils.punctuation_spacing_patterns class-attribute instance-attribute 

punctuation_spacing_patterns = compile_patterns(
    [
        (f" ([{punctuation_after}])", "\\1"),
        (f"([{punctuation_before}]) ", "\\1"),
        (
            f"([{punctuation_after[:3]}])([^ {punctuation_after}"
            + "\\d])",
            "\\1 \\2",
        ),
        (
            f"([{punctuation_after[3:]}])([^ {punctuation_after}])",
            "\\1 \\2",
        ),
        (
            f"([^ {punctuation_before}])([{punctuation_before}])",
            "\\1 \\2",
        ),
    ]
)

archipy.helpers.utils.string_utils.StringUtils.number_zero_translate_table class-attribute instance-attribute 

number_zero_translate_table = maketrans(fromkeys("۰٠", "0"))

archipy.helpers.utils.string_utils.StringUtils.number_one_translate_table class-attribute instance-attribute 

number_one_translate_table = maketrans(fromkeys('۱١', '1'))

archipy.helpers.utils.string_utils.StringUtils.number_two_translate_table class-attribute instance-attribute 

number_two_translate_table = maketrans(fromkeys('۲٢', '2'))

archipy.helpers.utils.string_utils.StringUtils.number_three_translate_table class-attribute instance-attribute 

number_three_translate_table = maketrans(
    fromkeys("۳٣", "3")
)

archipy.helpers.utils.string_utils.StringUtils.number_four_translate_table class-attribute instance-attribute 

number_four_translate_table = maketrans(fromkeys("۴٤", "4"))

archipy.helpers.utils.string_utils.StringUtils.number_five_translate_table class-attribute instance-attribute 

number_five_translate_table = maketrans(fromkeys("۵٥", "5"))

archipy.helpers.utils.string_utils.StringUtils.number_six_translate_table class-attribute instance-attribute 

number_six_translate_table = maketrans(fromkeys('۶٦', '6'))

archipy.helpers.utils.string_utils.StringUtils.number_seven_translate_table class-attribute instance-attribute 

number_seven_translate_table = maketrans(
    fromkeys("۷٧", "7")
)

archipy.helpers.utils.string_utils.StringUtils.number_eight_translate_table class-attribute instance-attribute 

number_eight_translate_table = maketrans(
    fromkeys("۸٨", "8")
)

archipy.helpers.utils.string_utils.StringUtils.number_nine_translate_table class-attribute instance-attribute 

number_nine_translate_table = maketrans(fromkeys("۹٩", "9"))

archipy.helpers.utils.string_utils.StringUtils.punctuation_persian_marks_to_space_translate_table class-attribute instance-attribute 

punctuation_persian_marks_to_space_translate_table = (
    maketrans(fromkeys(".:!،؛؟»])}«[({-ـ٪!'\"#+/", " "))
)

archipy.helpers.utils.string_utils.StringUtils.remove_arabic_vowels classmethod 

remove_arabic_vowels(text: str) -> str

Removes Arabic vowels (tashkeel) from the text.

Parameters:

Name Type Description Default
text str

The input text containing Arabic vowels.

 required

Returns:

Name Type Description
str str

The text with Arabic vowels removed.
Source code in archipy/helpers/utils/string_utils.py 
15
16
17
18
19
20
21
22
23
24
25
@classmethod
def remove_arabic_vowels(cls, text: str) -> str:
    """Removes Arabic vowels (tashkeel) from the text.

    Args:
        text (str): The input text containing Arabic vowels.

    Returns:
        str: The text with Arabic vowels removed.
    """
    return text.translate(cls.arabic_vowel_translate_table)

archipy.helpers.utils.string_utils.StringUtils.normalize_persian_chars classmethod 

normalize_persian_chars(text: str) -> str

Normalizes Persian characters to their standard forms.

Parameters:

Name Type Description Default
text str

The input text containing Persian characters.

 required

Returns:

Name Type Description
str str

The text with Persian characters normalized.
Source code in archipy/helpers/utils/string_utils.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@classmethod
def normalize_persian_chars(cls, text: str) -> str:
    """Normalizes Persian characters to their standard forms.

    Args:
        text (str): The input text containing Persian characters.

    Returns:
        str: The text with Persian characters normalized.
    """
    text = text.translate(cls.alphabet_akoolad_alef_translate_table)
    text = text.translate(cls.alphabet_alef_translate_table)
    text = text.translate(cls.alphabet_be_translate_table)
    text = text.translate(cls.alphabet_pe_translate_table)
    text = text.translate(cls.alphabet_te_translate_table)
    text = text.translate(cls.alphabet_se_translate_table)
    text = text.translate(cls.alphabet_jim_translate_table)
    text = text.translate(cls.alphabet_che_translate_table)
    text = text.translate(cls.alphabet_he_translate_table)
    text = text.translate(cls.alphabet_khe_translate_table)
    text = text.translate(cls.alphabet_dal_translate_table)
    text = text.translate(cls.alphabet_zal_translate_table)
    text = text.translate(cls.alphabet_re_translate_table)
    text = text.translate(cls.alphabet_ze_translate_table)
    text = text.translate(cls.alphabet_zhe_translate_table)
    text = text.translate(cls.alphabet_sin_translate_table)
    text = text.translate(cls.alphabet_shin_translate_table)
    text = text.translate(cls.alphabet_sad_translate_table)
    text = text.translate(cls.alphabet_zad_translate_table)
    text = text.translate(cls.alphabet_ta_translate_table)
    text = text.translate(cls.alphabet_za_translate_table)
    text = text.translate(cls.alphabet_eyn_translate_table)
    text = text.translate(cls.alphabet_gheyn_translate_table)
    text = text.translate(cls.alphabet_fe_translate_table)
    text = text.translate(cls.alphabet_ghaf_translate_table)
    text = text.translate(cls.alphabet_kaf_translate_table)
    text = text.translate(cls.alphabet_gaf_translate_table)
    text = text.translate(cls.alphabet_lam_translate_table)
    text = text.translate(cls.alphabet_mim_translate_table)
    text = text.translate(cls.alphabet_nun_translate_table)
    text = text.translate(cls.alphabet_vav_translate_table)
    text = text.translate(cls.alphabet_ha_translate_table)
    return text.translate(cls.alphabet_ye_translate_table)

archipy.helpers.utils.string_utils.StringUtils.normalize_punctuation classmethod 

normalize_punctuation(text: str) -> str

Normalizes punctuation marks in the text.

Parameters:

Name Type Description Default
text str

The input text containing punctuation marks.

 required

Returns:

Name Type Description
str str

The text with punctuation marks normalized.
Source code in archipy/helpers/utils/string_utils.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
@classmethod
def normalize_punctuation(cls, text: str) -> str:
    """Normalizes punctuation marks in the text.

    Args:
        text (str): The input text containing punctuation marks.

    Returns:
        str: The text with punctuation marks normalized.
    """
    text = text.translate(cls.punctuation_translate_table1)
    text = text.translate(cls.punctuation_translate_table2)
    text = text.translate(cls.punctuation_translate_table3)
    text = text.translate(cls.punctuation_translate_table4)
    text = text.translate(cls.punctuation_translate_table5)
    text = text.translate(cls.punctuation_translate_table6)
    text = text.translate(cls.punctuation_translate_table7)
    text = text.translate(cls.punctuation_translate_table8)
    text = text.translate(cls.punctuation_translate_table9)
    text = text.translate(cls.punctuation_translate_table10)
    text = text.translate(cls.punctuation_translate_table11)
    text = text.translate(cls.punctuation_translate_table12)
    return text.translate(cls.punctuation_translate_table13)

archipy.helpers.utils.string_utils.StringUtils.normalize_numbers classmethod 

normalize_numbers(text: str) -> str

Normalizes numbers in the text to English format.

Parameters:

Name Type Description Default
text str

The input text containing numbers.

 required

Returns:

Name Type Description
str str

The text with numbers normalized to English format.
Source code in archipy/helpers/utils/string_utils.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
@classmethod
def normalize_numbers(cls, text: str) -> str:
    """Normalizes numbers in the text to English format.

    Args:
        text (str): The input text containing numbers.

    Returns:
        str: The text with numbers normalized to English format.
    """
    text = text.translate(cls.number_zero_translate_table)
    text = text.translate(cls.number_one_translate_table)
    text = text.translate(cls.number_two_translate_table)
    text = text.translate(cls.number_three_translate_table)
    text = text.translate(cls.number_four_translate_table)
    text = text.translate(cls.number_five_translate_table)
    text = text.translate(cls.number_six_translate_table)
    text = text.translate(cls.number_seven_translate_table)
    text = text.translate(cls.number_eight_translate_table)
    return text.translate(cls.number_nine_translate_table)

archipy.helpers.utils.string_utils.StringUtils.clean_spacing classmethod 

clean_spacing(text: str) -> str

Cleans up spacing issues in the text, such as non-breaking spaces and zero-width non-joiners.

Parameters:

Name Type Description Default
text str

The input text with spacing issues.

 required

Returns:

Name Type Description
str str

The text with spacing cleaned up.
Source code in archipy/helpers/utils/string_utils.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@classmethod
def clean_spacing(cls, text: str) -> str:
    """Cleans up spacing issues in the text, such as non-breaking spaces and zero-width non-joiners.

    Args:
        text (str): The input text with spacing issues.

    Returns:
        str: The text with spacing cleaned up.
    """
    text = text.replace("\u200c", " ")  # ZWNJ
    text = text.replace("\xa0", " ")  # NBSP

    for pattern, repl in cls.character_refinement_patterns:
        text = pattern.sub(repl, text)

    return text

archipy.helpers.utils.string_utils.StringUtils.normalize_punctuation_spacing classmethod 

normalize_punctuation_spacing(text: str) -> str

Applies proper spacing around punctuation marks.

Parameters:

Name Type Description Default
text str

The input text with punctuation spacing issues.

 required

Returns:

Name Type Description
str str

The text with proper spacing around punctuation marks.
Source code in archipy/helpers/utils/string_utils.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
@classmethod
def normalize_punctuation_spacing(cls, text: str) -> str:
    """Applies proper spacing around punctuation marks.

    Args:
        text (str): The input text with punctuation spacing issues.

    Returns:
        str: The text with proper spacing around punctuation marks.
    """
    for pattern, repl in cls.punctuation_spacing_patterns:
        text = pattern.sub(repl, text)
    return text

archipy.helpers.utils.string_utils.StringUtils.remove_punctuation_marks classmethod 

remove_punctuation_marks(text: str) -> str

Removes punctuation marks from the text.

Parameters:

Name Type Description Default
text str

The input text containing punctuation marks.

 required

Returns:

Name Type Description
str str

The text with punctuation marks removed.
Source code in archipy/helpers/utils/string_utils.py 
148
149
150
151
152
153
154
155
156
157
158
@classmethod
def remove_punctuation_marks(cls, text: str) -> str:
    """Removes punctuation marks from the text.

    Args:
        text (str): The input text containing punctuation marks.

    Returns:
        str: The text with punctuation marks removed.
    """
    return text.translate(cls.punctuation_persian_marks_to_space_translate_table)

archipy.helpers.utils.string_utils.StringUtils.mask_urls classmethod 

mask_urls(text: str, mask: str | None = None) -> str

Masks URLs in the text with a specified mask.

Parameters:

Name Type Description Default
text str

The input text containing URLs.

 required
mask str | None

The mask to replace URLs with. Defaults to "MASK_URL".

 None

Returns:

Name Type Description
str str

The text with URLs masked.
Source code in archipy/helpers/utils/string_utils.py 
160
161
162
163
164
165
166
167
168
169
170
171
172
@classmethod
def mask_urls(cls, text: str, mask: str | None = None) -> str:
    """Masks URLs in the text with a specified mask.

    Args:
        text (str): The input text containing URLs.
        mask (str | None): The mask to replace URLs with. Defaults to "MASK_URL".

    Returns:
        str: The text with URLs masked.
    """
    mask = mask or "MASK_URL"
    return re_compile(r"https?://\S+|www\.\S+").sub(f" {mask} ", text)

archipy.helpers.utils.string_utils.StringUtils.mask_emails classmethod 

mask_emails(text: str, mask: str | None = None) -> str

Masks email addresses in the text with a specified mask.

Parameters:

Name Type Description Default
text str

The input text containing email addresses.

 required
mask str | None

The mask to replace emails with. Defaults to "MASK_EMAIL".

 None

Returns:

Name Type Description
str str

The text with email addresses masked.
Source code in archipy/helpers/utils/string_utils.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
@classmethod
def mask_emails(cls, text: str, mask: str | None = None) -> str:
    """Masks email addresses in the text with a specified mask.

    Args:
        text (str): The input text containing email addresses.
        mask (str | None): The mask to replace emails with. Defaults to "MASK_EMAIL".

    Returns:
        str: The text with email addresses masked.
    """
    mask = mask or "MASK_EMAIL"
    return re_compile(r"\S+@\S+\.\S+").sub(f" {mask} ", text)

archipy.helpers.utils.string_utils.StringUtils.mask_phones classmethod 

mask_phones(text: str, mask: str | None = None) -> str

Masks phone numbers in the text with a specified mask.

Parameters:

Name Type Description Default
text str

The input text containing phone numbers.

 required
mask str | None

The mask to replace phone numbers with. Defaults to "MASK_PHONE".

 None

Returns:

Name Type Description
str str

The text with phone numbers masked.
Source code in archipy/helpers/utils/string_utils.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
@classmethod
def mask_phones(cls, text: str, mask: str | None = None) -> str:
    """Masks phone numbers in the text with a specified mask.

    Args:
        text (str): The input text containing phone numbers.
        mask (str | None): The mask to replace phone numbers with. Defaults to "MASK_PHONE".

    Returns:
        str: The text with phone numbers masked.
    """
    mask = mask or "MASK_PHONE"
    return re_compile(r"(?:\+98|0)?(?:\d{3}\s*?\d{3}\s*?\d{4})").sub(f" {mask} ", text)

archipy.helpers.utils.string_utils.StringUtils.convert_english_number_to_persian classmethod 

convert_english_number_to_persian(text: str) -> str

Converts English numbers to Persian numbers in the text.

Parameters:

Name Type Description Default
text str

The input text containing English numbers.

 required

Returns:

Name Type Description
str str

The text with English numbers converted to Persian numbers.
Source code in archipy/helpers/utils/string_utils.py 
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
@classmethod
def convert_english_number_to_persian(cls, text: str) -> str:
    """Converts English numbers to Persian numbers in the text.

    Args:
        text (str): The input text containing English numbers.

    Returns:
        str: The text with English numbers converted to Persian numbers.
    """
    table = {
        48: 1776,  # 0
        49: 1777,  # 1
        50: 1778,  # 2
        51: 1779,  # 3
        52: 1780,  # 4
        53: 1781,  # 5
        54: 1782,  # 6
        55: 1783,  # 7
        56: 1784,  # 8
        57: 1785,  # 9
        44: 1548,  # ,
    }
    return text.translate(table)

archipy.helpers.utils.string_utils.StringUtils.convert_numbers_to_english classmethod 

convert_numbers_to_english(text: str) -> str

Converts Persian/Arabic numbers to English numbers in the text.

Parameters:

Name Type Description Default
text str

The input text containing Persian/Arabic numbers.

 required

Returns:

Name Type Description
str str

The text with Persian/Arabic numbers converted to English numbers.
Source code in archipy/helpers/utils/string_utils.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
@classmethod
def convert_numbers_to_english(cls, text: str) -> str:
    """Converts Persian/Arabic numbers to English numbers in the text.

    Args:
        text (str): The input text containing Persian/Arabic numbers.

    Returns:
        str: The text with Persian/Arabic numbers converted to English numbers.
    """
    table = {
        1776: 48,  # 0
        1777: 49,  # 1
        1778: 50,  # 2
        1779: 51,  # 3
        1780: 52,  # 4
        1781: 53,  # 5
        1782: 54,  # 6
        1783: 55,  # 7
        1784: 56,  # 8
        1785: 57,  # 9
        1632: 48,  # 0
        1633: 49,  # 1
        1634: 50,  # 2
        1635: 51,  # 3
        1636: 52,  # 4
        1637: 53,  # 5
        1638: 54,  # 6
        1639: 55,  # 7
        1640: 56,  # 8
        1641: 57,  # 9
    }
    return text.translate(table)

archipy.helpers.utils.string_utils.StringUtils.convert_add_3digit_delimiter classmethod 

convert_add_3digit_delimiter(value: int) -> str

Adds thousand separators to numbers.

Parameters:

Name Type Description Default
value int

The number to format.

 required

Returns:

Name Type Description
str str

The formatted number with thousand separators.
Source code in archipy/helpers/utils/string_utils.py 
261
262
263
264
265
266
267
268
269
270
271
@classmethod
def convert_add_3digit_delimiter(cls, value: int) -> str:
    """Adds thousand separators to numbers.

    Args:
        value (int): The number to format.

    Returns:
        str: The formatted number with thousand separators.
    """
    return f"{value:,}" if isinstance(value, int) else value

archipy.helpers.utils.string_utils.StringUtils.remove_emoji classmethod 

remove_emoji(text: str) -> str

Removes emoji characters from the text.

Parameters:

Name Type Description Default
text str

The input text containing emojis.

 required

Returns:

Name Type Description
str str

The text with emojis removed.
Source code in archipy/helpers/utils/string_utils.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
@classmethod
def remove_emoji(cls, text: str) -> str:
    """Removes emoji characters from the text.

    Args:
        text (str): The input text containing emojis.

    Returns:
        str: The text with emojis removed.
    """
    emoji_pattern = re.compile(
        r"["
        r"\U0001F600-\U0001F64F"  # emoticons
        r"\U0001F300-\U0001F5FF"  # symbols & pictographs
        r"\U0001F680-\U0001F6FF"  # transport & map symbols
        r"\U0001F1E0-\U0001F1FF"  # flags
        r"\U0001F900-\U0001F9FF"  # supplemental symbols and pictographs
        r"\U0001FA00-\U0001FA6F"  # symbols and pictographs extended-A
        r"\U00002600-\U000026FF"  # miscellaneous symbols (some are emojis)
        r"\U00002700-\U000027BF"  # dingbats (some are emojis)
        r"\U00002190-\U000021FF"  # arrows (some are emojis)
        r"]+",
        re.UNICODE,
    )
    return emoji_pattern.sub(r"", text)

archipy.helpers.utils.string_utils.StringUtils.replace_currencies_with_mask classmethod 

replace_currencies_with_mask(
    text: str, mask: str | None = None
) -> str

Masks currency symbols and amounts in the text.

Parameters:

Name Type Description Default
text str

The input text containing currency symbols and amounts.

 required
mask str | None

The mask to replace currencies with. Defaults to "MASK_CURRENCIES".

 None

Returns:

Name Type Description
str str

The text with currency symbols and amounts masked.
Source code in archipy/helpers/utils/string_utils.py 
299
300
301
302
303
304
305
306
307
308
309
310
311
312
@classmethod
def replace_currencies_with_mask(cls, text: str, mask: str | None = None) -> str:
    """Masks currency symbols and amounts in the text.

    Args:
        text (str): The input text containing currency symbols and amounts.
        mask (str | None): The mask to replace currencies with. Defaults to "MASK_CURRENCIES".

    Returns:
        str: The text with currency symbols and amounts masked.
    """
    mask = mask or "MASK_CURRENCIES"
    currency_pattern = re_compile(r"(\\|zł|£|\$|₡|₦|¥|₩|₪|₫|€|₱|₲|₴|₹|﷼)+")
    return currency_pattern.sub(f" {mask} ", text)

archipy.helpers.utils.string_utils.StringUtils.replace_numbers_with_mask classmethod 

replace_numbers_with_mask(
    text: str, mask: str | None = None
) -> str

Masks numbers in the text.

Parameters:

Name Type Description Default
text str

The input text containing numbers.

 required
mask str | None

The mask to replace numbers with. Defaults to "MASK_NUMBERS".

 None

Returns:

Name Type Description
str str

The text with numbers masked.
Source code in archipy/helpers/utils/string_utils.py 
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
@classmethod
def replace_numbers_with_mask(cls, text: str, mask: str | None = None) -> str:
    """Masks numbers in the text.

    Args:
        text (str): The input text containing numbers.
        mask (str | None): The mask to replace numbers with. Defaults to "MASK_NUMBERS".

    Returns:
        str: The text with numbers masked.
    """
    mask = mask or "MASK_NUMBERS"
    numbers = re.findall("[0-9]+", text)
    result: str = text
    for number in sorted(numbers, key=len, reverse=True):
        result = result.replace(number, f" {mask} ")  # type: ignore[arg-type]
    return result

archipy.helpers.utils.string_utils.StringUtils.is_string_none_or_empty classmethod 

is_string_none_or_empty(text: str) -> bool

Checks if a string is None or empty (after stripping whitespace).

Parameters:

Name Type Description Default
text str

The input string to check.

 required

Returns:

Name Type Description
bool bool

True if the string is None or empty, False otherwise.
Source code in archipy/helpers/utils/string_utils.py 
332
333
334
335
336
337
338
339
340
341
342
@classmethod
def is_string_none_or_empty(cls, text: str) -> bool:
    """Checks if a string is `None` or empty (after stripping whitespace).

    Args:
        text (str): The input string to check.

    Returns:
        bool: `True` if the string is `None` or empty, `False` otherwise.
    """
    return text is None or (isinstance(text, str) and not text.strip())

archipy.helpers.utils.string_utils.StringUtils.normalize_persian_text classmethod 

normalize_persian_text(
    text: str,
    *,
    remove_vowels: bool = True,
    normalize_punctuation: bool = True,
    normalize_numbers: bool = True,
    normalize_persian_chars: bool = True,
    mask_urls: bool = False,
    mask_emails: bool = False,
    mask_phones: bool = False,
    mask_currencies: bool = False,
    mask_all_numbers: bool = False,
    remove_emojis: bool = False,
    url_mask: str | None = None,
    email_mask: str | None = None,
    phone_mask: str | None = None,
    currency_mask: str | None = None,
    number_mask: str | None = None,
    clean_spacing: bool = True,
    remove_punctuation: bool = False,
    normalize_punctuation_spacing: bool = False,
) -> str

Normalizes Persian text with configurable options.

Parameters:

Name Type Description Default
text str

The input text to normalize.

 required
remove_vowels bool

Whether to remove Arabic vowels. Defaults to True.

 True
normalize_punctuation bool

Whether to normalize punctuation marks. Defaults to True.

 True
normalize_numbers bool

Whether to normalize numbers to English format. Defaults to True.

 True
normalize_persian_chars bool

Whether to normalize Persian characters. Defaults to True.

 True
mask_urls bool

Whether to mask URLs. Defaults to False.

 False
mask_emails bool

Whether to mask email addresses. Defaults to False.

 False
mask_phones bool

Whether to mask phone numbers. Defaults to False.

 False
mask_currencies bool

Whether to mask currency symbols and amounts. Defaults to False.

 False
mask_all_numbers bool

Whether to mask all numbers. Defaults to False.

 False
remove_emojis bool

Whether to remove emojis. Defaults to False.

 False
url_mask str | None

The mask to replace URLs with. Defaults to None.

 None
email_mask str | None

The mask to replace email addresses with. Defaults to None.

 None
phone_mask str | None

The mask to replace phone numbers with. Defaults to None.

 None
currency_mask str | None

The mask to replace currency symbols and amounts with. Defaults to None.

 None
number_mask str | None

The mask to replace numbers with. Defaults to None.

 None
clean_spacing bool

Whether to clean up spacing issues. Defaults to True.

 True
remove_punctuation bool

Whether to remove punctuation marks. Defaults to False.

 False
normalize_punctuation_spacing bool

Whether to apply proper spacing around punctuation marks. Defaults to False.

 False

Returns:

Name Type Description
str str

The normalized text.
Source code in archipy/helpers/utils/string_utils.py 
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
@classmethod
def normalize_persian_text(
    cls,
    text: str,
    *,
    remove_vowels: bool = True,
    normalize_punctuation: bool = True,
    normalize_numbers: bool = True,
    normalize_persian_chars: bool = True,
    mask_urls: bool = False,
    mask_emails: bool = False,
    mask_phones: bool = False,
    mask_currencies: bool = False,
    mask_all_numbers: bool = False,
    remove_emojis: bool = False,
    url_mask: str | None = None,
    email_mask: str | None = None,
    phone_mask: str | None = None,
    currency_mask: str | None = None,
    number_mask: str | None = None,
    clean_spacing: bool = True,
    remove_punctuation: bool = False,
    normalize_punctuation_spacing: bool = False,
) -> str:
    """Normalizes Persian text with configurable options.

    Args:
        text (str): The input text to normalize.
        remove_vowels (bool): Whether to remove Arabic vowels. Defaults to `True`.
        normalize_punctuation (bool): Whether to normalize punctuation marks. Defaults to `True`.
        normalize_numbers (bool): Whether to normalize numbers to English format. Defaults to `True`.
        normalize_persian_chars (bool): Whether to normalize Persian characters. Defaults to `True`.
        mask_urls (bool): Whether to mask URLs. Defaults to `False`.
        mask_emails (bool): Whether to mask email addresses. Defaults to `False`.
        mask_phones (bool): Whether to mask phone numbers. Defaults to `False`.
        mask_currencies (bool): Whether to mask currency symbols and amounts. Defaults to `False`.
        mask_all_numbers (bool): Whether to mask all numbers. Defaults to `False`.
        remove_emojis (bool): Whether to remove emojis. Defaults to `False`.
        url_mask (str | None): The mask to replace URLs with. Defaults to `None`.
        email_mask (str | None): The mask to replace email addresses with. Defaults to `None`.
        phone_mask (str | None): The mask to replace phone numbers with. Defaults to `None`.
        currency_mask (str | None): The mask to replace currency symbols and amounts with. Defaults to `None`.
        number_mask (str | None): The mask to replace numbers with. Defaults to `None`.
        clean_spacing (bool): Whether to clean up spacing issues. Defaults to `True`.
        remove_punctuation (bool): Whether to remove punctuation marks. Defaults to `False`.
        normalize_punctuation_spacing (bool): Whether to apply proper spacing around punctuation marks. Defaults to `False`.

    Returns:
        str: The normalized text.
    """
    if not text:
        return text

    # Remove emojis if requested
    if remove_emojis:
        text = cls.remove_emoji(text)

    # Apply normalizations
    if remove_vowels:
        text = cls.remove_arabic_vowels(text)
    if normalize_persian_chars:
        text = cls.normalize_persian_chars(text)
    if normalize_punctuation:
        text = cls.normalize_punctuation(text)
    if remove_punctuation:
        text = cls.remove_punctuation_marks(text)
    if normalize_numbers:
        text = cls.normalize_numbers(text)

    # Apply masking
    if mask_urls:
        text = cls.mask_urls(text, mask=url_mask)
    if mask_emails:
        text = cls.mask_emails(text, mask=email_mask)
    if mask_phones:
        text = cls.mask_phones(text, mask=phone_mask)
    if mask_currencies:
        text = cls.replace_currencies_with_mask(text, mask=currency_mask)
    if mask_all_numbers:
        text = cls.replace_numbers_with_mask(text, mask=number_mask)

    if clean_spacing:
        text = cls.clean_spacing(text)
    if normalize_punctuation_spacing:
        text = cls.normalize_punctuation_spacing(text)

    return text.strip()

archipy.helpers.utils.string_utils.StringUtils.snake_to_camel_case classmethod 

snake_to_camel_case(text: str) -> str

Converts snake_case to camelCase.

Parameters:

Name Type Description Default
text str

The input text in snake_case format.

 required

Returns:

Name Type Description
str str

The text converted to camelCase format.
Source code in archipy/helpers/utils/string_utils.py 
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
@classmethod
def snake_to_camel_case(cls, text: str) -> str:
    """Converts snake_case to camelCase.

    Args:
        text (str): The input text in snake_case format.

    Returns:
        str: The text converted to camelCase format.
    """
    if cls.is_string_none_or_empty(text):
        return text

    components = text.split("_")
    # First component remains lowercase, the rest get capitalized
    return components[0] + "".join(x.title() for x in components[1:])

archipy.helpers.utils.string_utils.StringUtils.camel_to_snake_case classmethod 

camel_to_snake_case(text: str) -> str

Converts camelCase to snake_case.

Parameters:

Name Type Description Default
text str

The input text in camelCase format.

 required

Returns:

Name Type Description
str str

The text converted to snake_case format.
Source code in archipy/helpers/utils/string_utils.py 
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
@classmethod
def camel_to_snake_case(cls, text: str) -> str:
    """Converts camelCase to snake_case.

    Args:
        text (str): The input text in camelCase format.

    Returns:
        str: The text converted to snake_case format.
    """
    if cls.is_string_none_or_empty(text):
        return text

    # Add underscore before each capital letter and convert to lowercase
    s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", text)
    return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()

options: show_root_toc_entry: false heading_level: 3

String Utils Constants

Constants used by string_utils for character sets, patterns, and limits.

archipy.helpers.utils.string_utils_constants.StringUtilsConstants

Constants for string utility operations including translation tables and regex patterns.

Source code in archipy/helpers/utils/string_utils_constants.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
class StringUtilsConstants:
    """Constants for string utility operations including translation tables and regex patterns."""

    arabic_vowel_translate_table = str.maketrans(
        dict.fromkeys(
            "\u064e\u064f\u0650\u0652\u0651\u0653\u064b\u064c\u0621\u064d\u0670"  # Normal vowels (Fatha, Damma, Kasra, etc)
            "\u06d6\u06d7\u06d8\u06d9\u06da\u06db",  # Quranic marks
            "",
        ),
    )

    # replace 'آ|ﺁ' with 'آ'
    alphabet_akoolad_alef_translate_table = str.maketrans(dict.fromkeys("\ufe81", "\u0622"))

    # replace 'ٳ|ٲ|ٱ|إ|ﺍ|أ|ٵ | ﺎ' with 'ا'
    alphabet_alef_translate_table = str.maketrans(
        dict.fromkeys("\ufe8e\u0672\u0671\u0625\ufe8d\u0623\u0675\u0673", "\u0627"),
    )

    # replace 'ٮ|ݕ|ٻ|ﺐ|ﺏ|ﺑ' with "ب"
    alphabet_be_translate_table = str.maketrans(dict.fromkeys("\ufe90\ufe8f\ufe91\u067b\u066e", "\u0628"))

    # replace 'ݕ|ݒ|ݐ|ڀ|ﭖ|ﭗ|ﭙ|ﺒ|ﭘ' with "پ"
    alphabet_pe_translate_table = str.maketrans(
        dict.fromkeys("\ufb56\ufb57\ufb59\ufe92\ufb58\u0680\u0750\u0752\u0755", "\u067e"),
    )

    # replace 'ﭡ|ٺ|ٹ|ﭞ|ٿ|ټ|ﺕ|ﺗ|ﺖ|ﺘ|ݓ' with "ت"
    alphabet_te_translate_table = str.maketrans(
        dict.fromkeys("\ufb61\u067a\u0679\ufb5e\u067f\u067c\ufe95\ufe97\ufe96\ufe98\u0753", "\u062a"),
    )
    # replace ﺙ|ﺛ|ٽ|ﺚ|ﺜ with "ث"
    alphabet_se_translate_table = str.maketrans(dict.fromkeys("\ufe99\ufe9b\u067d\ufe9a\ufe9c", "\u062b"))

    # replace "ﺞ|ﺝ|ﺠ|ﺟ| " with "ج"
    alphabet_jim_translate_table = str.maketrans(dict.fromkeys("\ufe9d\ufea0\ufe9f\ufe9e\u06da", "\u062c"))

    # replace "ﭻ|ڿ|ݘ|ڄ|ڇ|ڃ|ﭽ|ﭼ" with "چ"
    alphabet_che_translate_table = str.maketrans(
        dict.fromkeys("\u0683\ufb7d\ufb7c\u0687\u0684\u0758\u06bf\ufb7b", "\u0686"),
    )

    # replace "ﺡ|ﺢ|ﺤ|څ|ځ|ﺣ" with "ح"
    alphabet_he_translate_table = str.maketrans(dict.fromkeys("\ufea2\ufea4\u0685\u0681\ufea3\ufea1", "\u062d"))

    # replace "ݗ|څ|ڂ|ﺥ|ﺦ|ﺨ|ﺧ" with "خ"
    alphabet_khe_translate_table = str.maketrans(dict.fromkeys("\ufea5\ufea6\ufea8\ufea7\u0682\u0757", "\u062e"))

    # replace "ܥ|ڍ|ڈ|ڊ|ﺪ|ﺩ|ډ" with "د"
    alphabet_dal_translate_table = str.maketrans(dict.fromkeys("\u0689\ufeaa\ufea9\u068a\u0688\u068d\u0725", "\u062f"))

    # replace "ڌ|ڎ|ڏ|ڐ|ﺫ|ﺬ|ﻧ" with "ذ"
    alphabet_zal_translate_table = str.maketrans(dict.fromkeys("\ufeab\ufeac\ufee7\u0690\u068f\u068e\u068c", "\u0630"))

    # replace "ۯ|ڑ|ڒ|ړ|ڔ|ڕ|ږ|ڒ|ڑ|ڕ|ﺭ|ﺮ|ڗ" with "ر"
    alphabet_re_translate_table = str.maketrans(
        dict.fromkeys("\u0697\u0692\u0691\u0695\ufead\ufeae\u0696\u0694\u0693\u0692\u0691\u06ef", "\u0631"),
    )

    # replace "ﺰ|ﺯ" with "ز"
    alphabet_ze_translate_table = str.maketrans(dict.fromkeys("\ufeb0\ufeaf", "\u0632"))

    # replace "ﮋ|ڙ|ﮊ" with "ژ"
    alphabet_zhe_translate_table = str.maketrans(dict.fromkeys("\ufb8a\u0699\ufb8b", "\u0698"))

    # replace  r"ۣښ|ݭ|ݜ|ﺱ|ﺲ|ښ|ﺴ|ﺳ|ڛ|ۣ	"ݽ|ݾ|with r "س"
    alphabet_sin_translate_table = str.maketrans(
        dict.fromkeys("\u076d\u075c\ufeb1\ufeb2\ufeb4\ufeb3\u069b\u069a\u06e3\u077e\u077d", "\u0633"),
    )

    # replace "ۺ|ڜ|ﺵ|ﺶ|ﺸ|ﺷ" with "ش"
    alphabet_shin_translate_table = str.maketrans(dict.fromkeys("\ufeb5\ufeb6\ufeb8\ufeb7\u069c\u06fa", "\u0634"))

    # replace "ڝ|ﺺ|ﺼ|ﺻ |ﺹ" with "ص"
    alphabet_sad_translate_table = str.maketrans(dict.fromkeys("\ufeb9\ufeba\ufebc\ufebb\u069d", "\u0635"))

    # replace "ڞ|ۻ|ﺽ|ﺾ|ﺿ|ﻀ"  with "ض"
    alphabet_zad_translate_table = str.maketrans(dict.fromkeys("\ufebd\ufebe\ufebf\ufec0\u06fb\u069e", "\u0636"))

    # replace "ﻁ|ﻂ|ﻃ|ﻄ" with "ط"
    alphabet_ta_translate_table = str.maketrans(dict.fromkeys("\ufec1\ufec2\ufec3\ufec4", "\u0637"))

    # replace "ڟ|ﻆ|ﻇ|ﻈ|ﻅ" with "ظ"
    alphabet_za_translate_table = str.maketrans(dict.fromkeys("\ufec6\ufec7\ufec8\u069f\ufec5", "\u0638"))

    # replace "ڠ|ﻉ|ﻊ|ﻋ|ﻌ" with "ع"
    alphabet_eyn_translate_table = str.maketrans(dict.fromkeys("\u06a0\ufec9\ufeca\ufecb\ufecc", "\u0639"))

    # replace "ݞ|ݝ|ﻎ|ۼ|ﻍ|ﻐ|ﻏ|ݟ" with "غ"
    alphabet_gheyn_translate_table = str.maketrans(
        dict.fromkeys("\ufece\u06fc\ufecd\ufed0\ufecf\u075d\u075e\u075f", "\u063a"),
    )

    # replace "ڢ|ڣ|ڢ|ڣ|ڤ|ڦ|ڥ|ڡ|ﻒ|ﻑ|ﻔ|ﻓ" with "ف"
    alphabet_fe_translate_table = str.maketrans(
        dict.fromkeys("\ufed2\ufed1\ufed4\ufed3\u06a1\u06a5\u06a6\u06a4\u0603\u06a3\u06a2", "\u0641"),
    )

    # replace "؋|ڧ|ڨ|ﻕ|ﻖ|ﻗ|ﻘ" with "ق"
    alphabet_ghaf_translate_table = str.maketrans(dict.fromkeys("\ufed5\ufed6\ufed7\u06a7\u06a8\u060b\ufed8", "\u0642"))

    # replace "ݿ|ڮ|ڬ|ݤ|ݣ|ݢ|ڭ|ﻚ|ﮎ|ﻜ|ﮏ|ګ|ﻛ|ﮑ|ﮐ|ڪ|ك|ﻙ" with "ک"
    alphabet_kaf_translate_table = str.maketrans(
        dict.fromkeys(
            "\u06ad\ufeda\ufb8e\ufedc\ufb8f\u06ab\ufedb"
            "\ufb91\ufb90\u06aa\u0643\u0762\u0763\u0764"
            "\u06ac\u06ae\u077f\ufed9",
            "\u06a9",
        ),
    )
    # replace  "ڴ|ڳ|ڲ|ڰ|ڱ|ﮚ|ﮒ|ﮓ|ﮕ|ﮔ" with "گ"
    alphabet_gaf_translate_table = str.maketrans(
        dict.fromkeys("\ufb9a\ufb92\ufb93\ufb95\ufb94\u06b1\u06b0\u06b2\u06b3\u06b4", "\u06af"),
    )

    # replace "ڵ|ڶ|ڸ|ڷ|ݪ|ﻝ|ﻞ|ﻠ|ڵ | ﻟ" with "ل"
    alphabet_lam_translate_table = str.maketrans(
        dict.fromkeys("\ufedf\ufedd\ufede\ufee0\u076a\u06b7\u06b8\u06b6\u06b5", "\u0644"),
    )

    # replace "ݥ|ݦ|ﻡ|ﻤ|ﻢ|ﻣ" with "م"
    alphabet_mim_translate_table = str.maketrans(dict.fromkeys("\ufee1\ufee4\ufee2\ufee3\u0766\u0765", "\u0645"))

    # replace "ڹ|ں|ڽ|ڻ|ݧ|ݨ|ݩ|ڼ|ﻦ|ﻥ|ﻨ" with "ن"
    alphabet_nun_translate_table = str.maketrans(
        dict.fromkeys("\u06bc\ufee6\ufee5\ufee8\u0769\u0768\u0767\u06bb\u06bd\u06ba\u06b9", "\u0646"),
    )

    # replace "ۄ|ۆ|ۊ|ވ|ﯙ|ۈ|ۋ|ﺆ|ۊ|ۇ|ۏ|ۅ|ۉ|ﻭ|ﻮ|ؤ" with "و"
    alphabet_vav_translate_table = str.maketrans(
        dict.fromkeys(
            "\u0788\ufbd9\u06c8\u06cb\ufe86\u06ca\u06c7\u06cf\u06c5\u06c9\ufeed\ufeee\u0624\u06c6\u06c4",
            "\u0648",
        ),
    )
    # replace "ܝ|ܤ|ܣ|ﺔ|ﻬ|ھ|ﻩ|ﻫ|ﻪ|ۀ|ە|ة|ہ|ﮭ|ﺓ" with "ه"
    alphabet_ha_translate_table = str.maketrans(
        dict.fromkeys(
            "\ufe93\ufbad\ufe94\ufeec\u06be\ufee9\ufeeb\ufeea\u06c0\u06d5\u0629\u06c1\u0723\u0724\u071d",
            "\u0647",
        ),
    )

    # replace "ﺋ|ؿ|ؾ|ؽ|ۑ|ٸ|ﭛ|ﻯ|ۍ|ﻰ|ﻱ|ﻲ|ﻳ|ﻴ|ﯼ|ې|ﯽ|ﯾ|ﯿ|ێ|ے|ى|ي|ﺉ|ﺌ |ﯨ" with "ی"
    alphabet_ye_translate_table = str.maketrans(
        dict.fromkeys(
            "\ufbe8\ufb5b\ufeef\u06cd\ufef0\ufef1\ufef2\ufef3\ufef4\ufbfc"
            "\u06d0\ufbfd\ufbfe\ufbff\u06ce\u06d2\u0649\u064a\u0678"
            "\u06d1\u063d\u063e\u063f\ufe89\ufe8b\ufe8c",
            "\u06cc",
        ),
    )
    # replace '¬' with ' '
    punctuation_translate_table1 = str.maketrans(dict.fromkeys("\u00ac", "\u0020"))

    # replace '•|·|●|·|・|∙|｡|ⴰ' with '.'
    punctuation_translate_table2 = str.maketrans(
        dict.fromkeys("\u2022\u00b7\u25cf\u0387\u30fb\u2219\uff61\u2d30", "\u002e"),
    )

    # replace ',|٬|٫|‚|，' with '،'
    punctuation_translate_table3 = str.maketrans(dict.fromkeys("\u002c\u066c\u066b\u201a\uff0c", "\u060c"))

    # replace 'ʕ | ? | ⁉ | � ' with '؟'
    punctuation_translate_table4 = str.maketrans(dict.fromkeys("\u0295\u003f\u2049\ufffd", "\u061f"))

    # replace '‼ | ❕ ' with '!'
    punctuation_translate_table5 = str.maketrans(dict.fromkeys("\u203c\u2755", "\u0021"))

    # replace '_ ' with 'ـ'
    punctuation_translate_table6 = str.maketrans(dict.fromkeys("\u005f", "\u0640"))

    # replace ' － | ━ | − | ‐ | ‑ | – | — | ─ | − | ー | ⁃ (hyphen bullet : not supported by pycharm) |  ' with '-'
    punctuation_translate_table7 = str.maketrans(
        dict.fromkeys("\uff0d\u2501\u2212\u2010\u2011\u2013\u2014\u2500\u2212\u30fc\u2043", "\u002d"),
    )

    # replace '‹ |《 | ﴾ ' with '«'
    punctuation_translate_table8 = str.maketrans(dict.fromkeys("\u2039\u300a\ufd3e", "\u00ab"))

    # replace '› | 》| ﴿ ' with '»'
    punctuation_translate_table9 = str.maketrans(dict.fromkeys("\u203a\u300b\ufd3f", "\u00bb"))

    # replace ';' with '؛'
    punctuation_translate_table10 = str.maketrans(dict.fromkeys("\u003b", "\u061b"))

    # replace '%' with '٪'
    punctuation_translate_table11 = str.maketrans(dict.fromkeys("\u0025", "\u066a"))

    # replace "  ˈ | ‘ | ’ | “ | ”  " with " ' "
    punctuation_translate_table12 = str.maketrans(dict.fromkeys("\u02c8\u2018\u2019\u201c\u201d", "\u0027"))

    # replace '：' with ': '
    punctuation_translate_table13 = str.maketrans(dict.fromkeys("\uff1a", "\u003a"))

    character_refinement_patterns: list = compile_patterns(
        [
            (r" +", " "),  # remove extra spaces
            (r"\n\n+", "\n"),  # remove extra newlines
            (r" ?\.\.\.", " …"),  # replace 3 dots
        ],
    )

    punctuation_after = r"\.:!،؛؟»\]\)\}"
    punctuation_before = r"«\[\(\{"

    punctuation_spacing_patterns = compile_patterns(
        [
            (f" ([{punctuation_after}])", r"\1"),
            (f"([{punctuation_before}]) ", r"\1"),
            (
                f"([{punctuation_after[:3]}])([^ {punctuation_after}" + r"\d])",
                r"\1 \2",
            ),
            (
                f"([{punctuation_after[3:]}])([^ {punctuation_after}])",
                r"\1 \2",
            ),
            (f"([^ {punctuation_before}])([{punctuation_before}])", r"\1 \2"),
        ],
    )

    # replace '۰|٠' with '0'
    number_zero_translate_table = str.maketrans(dict.fromkeys("\u06f0\u0660", "\u0030"))

    # replace '۱|١' with '1'
    number_one_translate_table = str.maketrans(dict.fromkeys("\u06f1\u0661", "\u0031"))

    # replace '۲|٢' with '2'
    number_two_translate_table = str.maketrans(dict.fromkeys("\u06f2\u0662", "\u0032"))

    # replace '۳|٣' with '3'
    number_three_translate_table = str.maketrans(dict.fromkeys("\u06f3\u0663", "\u0033"))

    # replace '۴|٤' with '4'
    number_four_translate_table = str.maketrans(dict.fromkeys("\u06f4\u0664", "\u0034"))

    # replace '۵|٥' with '5'
    number_five_translate_table = str.maketrans(dict.fromkeys("\u06f5\u0665", "\u0035"))

    # replace '۶|٦' with '6'
    number_six_translate_table = str.maketrans(dict.fromkeys("\u06f6\u0666", "\u0036"))

    # replace '۷|٧' with '7'
    number_seven_translate_table = str.maketrans(dict.fromkeys("\u06f7\u0667", "\u0037"))

    # replace '۸|٨' with '8'
    number_eight_translate_table = str.maketrans(dict.fromkeys("\u06f8\u0668", "\u0038"))

    # replace '۹|٩' with '9'
    number_nine_translate_table = str.maketrans(dict.fromkeys("\u06f9\u0669", "\u0039"))

    # replace ' «|» | . | : | ، | ؛ | ؟ | [|] | (|) | {|} | - | ـ | ٪ | ! | ' | " | # | + | / |' with ' '
    punctuation_persian_marks_to_space_translate_table = str.maketrans(
        dict.fromkeys(
            "\u002e\u003a\u0021\u060c\u061b\u061f\u00bb\u005d"
            "\u0029\u007d\u00ab\u005b\u0028\u007b\u002d\u0640\u066a\u0021\u0027\u0022\u0023"
            "\u002b\u002f",
            "\u0020",
        ),
    )

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.arabic_vowel_translate_table class-attribute instance-attribute 

arabic_vowel_translate_table = maketrans(fromkeys("ًٌَُِّْٓءٍٰۖۗۘۙۚۛ", ""))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_akoolad_alef_translate_table class-attribute instance-attribute 

alphabet_akoolad_alef_translate_table = maketrans(
    fromkeys("ﺁ", "آ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_alef_translate_table class-attribute instance-attribute 

alphabet_alef_translate_table = maketrans(
    fromkeys("ﺎٲٱإﺍأٵٳ", "ا")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_be_translate_table class-attribute instance-attribute 

alphabet_be_translate_table = maketrans(
    fromkeys("ﺐﺏﺑٻٮ", "ب")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_pe_translate_table class-attribute instance-attribute 

alphabet_pe_translate_table = maketrans(
    fromkeys("ﭖﭗﭙﺒﭘڀݐݒݕ", "پ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_te_translate_table class-attribute instance-attribute 

alphabet_te_translate_table = maketrans(
    fromkeys("ﭡٺٹﭞٿټﺕﺗﺖﺘݓ", "ت")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_se_translate_table class-attribute instance-attribute 

alphabet_se_translate_table = maketrans(
    fromkeys("ﺙﺛٽﺚﺜ", "ث")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_jim_translate_table class-attribute instance-attribute 

alphabet_jim_translate_table = maketrans(
    fromkeys("ﺝﺠﺟﺞۚ", "ج")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_che_translate_table class-attribute instance-attribute 

alphabet_che_translate_table = maketrans(
    fromkeys("ڃﭽﭼڇڄݘڿﭻ", "چ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_he_translate_table class-attribute instance-attribute 

alphabet_he_translate_table = maketrans(
    fromkeys("ﺢﺤڅځﺣﺡ", "ح")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_khe_translate_table class-attribute instance-attribute 

alphabet_khe_translate_table = maketrans(
    fromkeys("ﺥﺦﺨﺧڂݗ", "خ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_dal_translate_table class-attribute instance-attribute 

alphabet_dal_translate_table = maketrans(
    fromkeys("ډﺪﺩڊڈڍܥ", "د")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_zal_translate_table class-attribute instance-attribute 

alphabet_zal_translate_table = maketrans(
    fromkeys("ﺫﺬﻧڐڏڎڌ", "ذ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_re_translate_table class-attribute instance-attribute 

alphabet_re_translate_table = maketrans(
    fromkeys("ڗڒڑڕﺭﺮږڔړڒڑۯ", "ر")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_ze_translate_table class-attribute instance-attribute 

alphabet_ze_translate_table = maketrans(fromkeys("ﺰﺯ", "ز"))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_zhe_translate_table class-attribute instance-attribute 

alphabet_zhe_translate_table = maketrans(
    fromkeys("ﮊڙﮋ", "ژ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_sin_translate_table class-attribute instance-attribute 

alphabet_sin_translate_table = maketrans(
    fromkeys("ݭݜﺱﺲﺴﺳڛښۣݾݽ", "س")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_shin_translate_table class-attribute instance-attribute 

alphabet_shin_translate_table = maketrans(
    fromkeys("ﺵﺶﺸﺷڜۺ", "ش")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_sad_translate_table class-attribute instance-attribute 

alphabet_sad_translate_table = maketrans(
    fromkeys("ﺹﺺﺼﺻڝ", "ص")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_zad_translate_table class-attribute instance-attribute 

alphabet_zad_translate_table = maketrans(
    fromkeys("ﺽﺾﺿﻀۻڞ", "ض")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_ta_translate_table class-attribute instance-attribute 

alphabet_ta_translate_table = maketrans(
    fromkeys("ﻁﻂﻃﻄ", "ط")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_za_translate_table class-attribute instance-attribute 

alphabet_za_translate_table = maketrans(
    fromkeys("ﻆﻇﻈڟﻅ", "ظ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_eyn_translate_table class-attribute instance-attribute 

alphabet_eyn_translate_table = maketrans(
    fromkeys("ڠﻉﻊﻋﻌ", "ع")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_gheyn_translate_table class-attribute instance-attribute 

alphabet_gheyn_translate_table = maketrans(
    fromkeys("ﻎۼﻍﻐﻏݝݞݟ", "غ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_fe_translate_table class-attribute instance-attribute 

alphabet_fe_translate_table = maketrans(
    fromkeys("ﻒﻑﻔﻓڡڥڦڤ\u0603ڣڢ", "ف")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_ghaf_translate_table class-attribute instance-attribute 

alphabet_ghaf_translate_table = maketrans(
    fromkeys("ﻕﻖﻗڧڨ؋ﻘ", "ق")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_kaf_translate_table class-attribute instance-attribute 

alphabet_kaf_translate_table = maketrans(
    fromkeys("ڭﻚﮎﻜﮏګﻛﮑﮐڪكݢݣݤڬڮݿﻙ", "ک")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_gaf_translate_table class-attribute instance-attribute 

alphabet_gaf_translate_table = maketrans(
    fromkeys("ﮚﮒﮓﮕﮔڱڰڲڳڴ", "گ")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_lam_translate_table class-attribute instance-attribute 

alphabet_lam_translate_table = maketrans(
    fromkeys("ﻟﻝﻞﻠݪڷڸڶڵ", "ل")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_mim_translate_table class-attribute instance-attribute 

alphabet_mim_translate_table = maketrans(
    fromkeys("ﻡﻤﻢﻣݦݥ", "م")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_nun_translate_table class-attribute instance-attribute 

alphabet_nun_translate_table = maketrans(
    fromkeys("ڼﻦﻥﻨݩݨݧڻڽںڹ", "ن")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_vav_translate_table class-attribute instance-attribute 

alphabet_vav_translate_table = maketrans(
    fromkeys("ވﯙۈۋﺆۊۇۏۅۉﻭﻮؤۆۄ", "و")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_ha_translate_table class-attribute instance-attribute 

alphabet_ha_translate_table = maketrans(
    fromkeys("ﺓﮭﺔﻬھﻩﻫﻪۀەةہܣܤܝ", "ه")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.alphabet_ye_translate_table class-attribute instance-attribute 

alphabet_ye_translate_table = maketrans(
    fromkeys("ﯨﭛﻯۍﻰﻱﻲﻳﻴﯼېﯽﯾﯿێےىيٸۑؽؾؿﺉﺋﺌ", "ی")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table1 class-attribute instance-attribute 

punctuation_translate_table1 = maketrans(fromkeys("¬", " "))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table2 class-attribute instance-attribute 

punctuation_translate_table2 = maketrans(
    fromkeys("•·●·・∙｡ⴰ", ".")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table3 class-attribute instance-attribute 

punctuation_translate_table3 = maketrans(
    fromkeys(",٬٫‚，", "،")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table4 class-attribute instance-attribute 

punctuation_translate_table4 = maketrans(
    fromkeys("ʕ?⁉�", "؟")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table5 class-attribute instance-attribute 

punctuation_translate_table5 = maketrans(
    fromkeys("‼❕", "!")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table6 class-attribute instance-attribute 

punctuation_translate_table6 = maketrans(fromkeys("_", "ـ"))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table7 class-attribute instance-attribute 

punctuation_translate_table7 = maketrans(
    fromkeys("－━−‐‑–—─−ー⁃", "-")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table8 class-attribute instance-attribute 

punctuation_translate_table8 = maketrans(
    fromkeys("‹《﴾", "«")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table9 class-attribute instance-attribute 

punctuation_translate_table9 = maketrans(
    fromkeys("›》﴿", "»")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table10 class-attribute instance-attribute 

punctuation_translate_table10 = maketrans(
    fromkeys(";", "؛")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table11 class-attribute instance-attribute 

punctuation_translate_table11 = maketrans(
    fromkeys("%", "٪")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table12 class-attribute instance-attribute 

punctuation_translate_table12 = maketrans(
    fromkeys("ˈ‘’“”", "'")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_translate_table13 class-attribute instance-attribute 

punctuation_translate_table13 = maketrans(
    fromkeys("：", ":")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.character_refinement_patterns class-attribute instance-attribute 

character_refinement_patterns: list = compile_patterns(
    [(" +", " "), ("\\n\\n+", "\n"), (" ?\\.\\.\\.", " …")]
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_after class-attribute instance-attribute 

punctuation_after = '\\.:!،؛؟»\\]\\)\\}'

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_before class-attribute instance-attribute 

punctuation_before = '«\\[\\(\\{'

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_spacing_patterns class-attribute instance-attribute 

punctuation_spacing_patterns = compile_patterns(
    [
        (f" ([{punctuation_after}])", "\\1"),
        (f"([{punctuation_before}]) ", "\\1"),
        (
            f"([{punctuation_after[:3]}])([^ {punctuation_after}"
            + "\\d])",
            "\\1 \\2",
        ),
        (
            f"([{punctuation_after[3:]}])([^ {punctuation_after}])",
            "\\1 \\2",
        ),
        (
            f"([^ {punctuation_before}])([{punctuation_before}])",
            "\\1 \\2",
        ),
    ]
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_zero_translate_table class-attribute instance-attribute 

number_zero_translate_table = maketrans(fromkeys("۰٠", "0"))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_one_translate_table class-attribute instance-attribute 

number_one_translate_table = maketrans(fromkeys('۱١', '1'))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_two_translate_table class-attribute instance-attribute 

number_two_translate_table = maketrans(fromkeys('۲٢', '2'))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_three_translate_table class-attribute instance-attribute 

number_three_translate_table = maketrans(
    fromkeys("۳٣", "3")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_four_translate_table class-attribute instance-attribute 

number_four_translate_table = maketrans(fromkeys("۴٤", "4"))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_five_translate_table class-attribute instance-attribute 

number_five_translate_table = maketrans(fromkeys("۵٥", "5"))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_six_translate_table class-attribute instance-attribute 

number_six_translate_table = maketrans(fromkeys('۶٦', '6'))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_seven_translate_table class-attribute instance-attribute 

number_seven_translate_table = maketrans(
    fromkeys("۷٧", "7")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_eight_translate_table class-attribute instance-attribute 

number_eight_translate_table = maketrans(
    fromkeys("۸٨", "8")
)

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.number_nine_translate_table class-attribute instance-attribute 

number_nine_translate_table = maketrans(fromkeys("۹٩", "9"))

archipy.helpers.utils.string_utils_constants.StringUtilsConstants.punctuation_persian_marks_to_space_translate_table class-attribute instance-attribute 

punctuation_persian_marks_to_space_translate_table = (
    maketrans(fromkeys(".:!،؛؟»])}«[({-ـ٪!'\"#+/", " "))
)

archipy.helpers.utils.string_utils_constants.compile_patterns 

compile_patterns(
    patterns: list[tuple[str, str]],
) -> list[tuple[re.Pattern[str], str]]

Compile regex patterns with their replacement strings.

Parameters:

Name Type Description Default
patterns list[tuple[str, str]]

List of tuples containing (pattern, replacement) pairs.

 required

Returns:

Type Description
list[tuple[Pattern[str], str]]

List of tuples containing (compiled_pattern, replacement) pairs.
Source code in archipy/helpers/utils/string_utils_constants.py 
 5
 6
 7
 8
 9
10
11
12
13
14
def compile_patterns(patterns: list[tuple[str, str]]) -> list[tuple[re.Pattern[str], str]]:
    """Compile regex patterns with their replacement strings.

    Args:
        patterns: List of tuples containing (pattern, replacement) pairs.

    Returns:
        List of tuples containing (compiled_pattern, replacement) pairs.
    """
    return [(re_compile(pattern), repl) for pattern, repl in patterns]

options: show_root_toc_entry: false heading_level: 3

File Utils

Utilities for file operations including reading, writing, hashing, and type validation.

archipy.helpers.utils.file_utils.FileUtils

A utility class for handling file-related operations, such as creating secure links and validating file names.

Source code in archipy/helpers/utils/file_utils.py 
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
class FileUtils:
    """A utility class for handling file-related operations, such as creating secure links and validating file names."""

    @staticmethod
    def _create_secure_link_hash(path: str, expires_at: float, file_config: FileConfig | None = None) -> str:
        """Generates a secure hash for a file link based on the file path, expiration timestamp, and secret key.

        Args:
            path (str): The file path to generate the hash for.
            expires_at (float): The expiration timestamp for the link.
            file_config (FileConfig | None): Optional file configuration object. If not provided, uses the global config.

        Returns:
            str: A base64-encoded secure hash for the file link.

        Raises:
            InvalidArgumentError: If the `SECRET_KEY` in the configuration is `None`.
        """
        configs: FileConfig = file_config or BaseConfig.global_config().FILE
        secret: str | None = configs.SECRET_KEY
        if secret is None:
            raise InvalidArgumentError(argument_name="SECRET_KEY")
        _input = f"{expires_at}{path} {secret}"
        # nginx secure_link requires MD5; keep for compatibility (not used for cryptographic security)
        hash_object = hashlib.md5(_input.encode("utf8"))
        return base64.urlsafe_b64encode(hash_object.digest()).decode("utf-8").rstrip("=")

    @classmethod
    def create_secure_link(
        cls,
        path: str,
        minutes: int | None = None,
        file_config: FileConfig | None = None,
    ) -> str:
        """Creates a secure link with expiration for file access.

        Args:
            path (str): The file path to create a secure link for.
            minutes (int | None): Number of minutes until link expiration. Defaults to the config's `DEFAULT_EXPIRY_MINUTES`.
            file_config (FileConfig | None): Optional file configuration object. If not provided, uses the global config.

        Returns:
            str: A secure link with a hash and expiration timestamp.

        Raises:
            InvalidArgumentError: If the `path` is empty.
            OutOfRangeError: If `minutes` is less than 1.
        """
        if not path:
            raise InvalidArgumentError(argument_name="path")

        configs: FileConfig = file_config or BaseConfig.global_config().FILE
        expiry_minutes: int = minutes if minutes is not None else configs.DEFAULT_EXPIRY_MINUTES

        if expiry_minutes < 1:
            raise OutOfRangeError(field_name="minutes")

        expires_at = int(DatetimeUtils.get_datetime_after_given_datetime_or_now(minutes=expiry_minutes).timestamp())
        secure_link_hash = cls._create_secure_link_hash(path, expires_at, file_config)

        return f"{path}?md5={secure_link_hash}&expires_at={expires_at}"

    @classmethod
    def validate_file_name(
        cls,
        file_name: str,
        file_config: FileConfig | None = None,
    ) -> bool:
        """Validates a file name based on allowed extensions.

        Args:
            file_name (str): The file name to validate.
            file_config (FileConfig | None): Optional file configuration object. If not provided, uses the global config.

        Returns:
            bool: `True` if the file name has an allowed extension, `False` otherwise.

        Raises:
            InvalidArgumentError: If `file_name` is not a string or `allowed_extensions` is not a list.
        """
        configs: FileConfig = file_config or BaseConfig.global_config().FILE
        allowed_extensions: list[str] = configs.ALLOWED_EXTENSIONS

        if not isinstance(file_name, str):
            raise InvalidArgumentError(argument_name="file_name")

        if not allowed_extensions:
            raise InvalidArgumentError(argument_name="allowed_extensions")

        file_path = Path(file_name)
        ext = file_path.suffix[1:].lower()
        return ext in allowed_extensions and bool(ext)

create_secure_link(
    path: str,
    minutes: int | None = None,
    file_config: FileConfig | None = None,
) -> str

Creates a secure link with expiration for file access.

Parameters:

Name Type Description Default
path str

The file path to create a secure link for.

 required
minutes int | None

Number of minutes until link expiration. Defaults to the config's DEFAULT_EXPIRY_MINUTES.

 None
file_config FileConfig | None

Optional file configuration object. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

A secure link with a hash and expiration timestamp.

Raises:

Type Description
InvalidArgumentError

If the path is empty.
OutOfRangeError

If minutes is less than 1.
Source code in archipy/helpers/utils/file_utils.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
@classmethod
def create_secure_link(
    cls,
    path: str,
    minutes: int | None = None,
    file_config: FileConfig | None = None,
) -> str:
    """Creates a secure link with expiration for file access.

    Args:
        path (str): The file path to create a secure link for.
        minutes (int | None): Number of minutes until link expiration. Defaults to the config's `DEFAULT_EXPIRY_MINUTES`.
        file_config (FileConfig | None): Optional file configuration object. If not provided, uses the global config.

    Returns:
        str: A secure link with a hash and expiration timestamp.

    Raises:
        InvalidArgumentError: If the `path` is empty.
        OutOfRangeError: If `minutes` is less than 1.
    """
    if not path:
        raise InvalidArgumentError(argument_name="path")

    configs: FileConfig = file_config or BaseConfig.global_config().FILE
    expiry_minutes: int = minutes if minutes is not None else configs.DEFAULT_EXPIRY_MINUTES

    if expiry_minutes < 1:
        raise OutOfRangeError(field_name="minutes")

    expires_at = int(DatetimeUtils.get_datetime_after_given_datetime_or_now(minutes=expiry_minutes).timestamp())
    secure_link_hash = cls._create_secure_link_hash(path, expires_at, file_config)

    return f"{path}?md5={secure_link_hash}&expires_at={expires_at}"

archipy.helpers.utils.file_utils.FileUtils.validate_file_name classmethod 

validate_file_name(
    file_name: str, file_config: FileConfig | None = None
) -> bool

Validates a file name based on allowed extensions.

Parameters:

Name Type Description Default
file_name str

The file name to validate.

 required
file_config FileConfig | None

Optional file configuration object. If not provided, uses the global config.

 None

Returns:

Name Type Description
bool bool

True if the file name has an allowed extension, False otherwise.

Raises:

Type Description
InvalidArgumentError

If file_name is not a string or allowed_extensions is not a list.
Source code in archipy/helpers/utils/file_utils.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
@classmethod
def validate_file_name(
    cls,
    file_name: str,
    file_config: FileConfig | None = None,
) -> bool:
    """Validates a file name based on allowed extensions.

    Args:
        file_name (str): The file name to validate.
        file_config (FileConfig | None): Optional file configuration object. If not provided, uses the global config.

    Returns:
        bool: `True` if the file name has an allowed extension, `False` otherwise.

    Raises:
        InvalidArgumentError: If `file_name` is not a string or `allowed_extensions` is not a list.
    """
    configs: FileConfig = file_config or BaseConfig.global_config().FILE
    allowed_extensions: list[str] = configs.ALLOWED_EXTENSIONS

    if not isinstance(file_name, str):
        raise InvalidArgumentError(argument_name="file_name")

    if not allowed_extensions:
        raise InvalidArgumentError(argument_name="allowed_extensions")

    file_path = Path(file_name)
    ext = file_path.suffix[1:].lower()
    return ext in allowed_extensions and bool(ext)

options: show_root_toc_entry: false heading_level: 3

Error Utils

Utilities for error formatting, context enrichment, and error chain inspection.

archipy.helpers.utils.error_utils.logger module-attribute 

logger = getLogger(__name__)

archipy.helpers.utils.error_utils.HTTP_AVAILABLE module-attribute 

HTTP_AVAILABLE = True

archipy.helpers.utils.error_utils.GRPC_AVAILABLE module-attribute 

GRPC_AVAILABLE = True

archipy.helpers.utils.error_utils.RequestProtocol

Bases: Protocol

Protocol for FastAPI Request objects.

Source code in archipy/helpers/utils/error_utils.py 
17
18
class RequestProtocol(Protocol):
    """Protocol for FastAPI Request objects."""

archipy.helpers.utils.error_utils.JSONResponseProtocol

Bases: Protocol

Protocol for FastAPI JSONResponse objects.

Source code in archipy/helpers/utils/error_utils.py 
21
22
class JSONResponseProtocol(Protocol):
    """Protocol for FastAPI JSONResponse objects."""

archipy.helpers.utils.error_utils.ErrorUtils

A utility class for handling errors, including capturing, reporting, and generating responses.

Source code in archipy/helpers/utils/error_utils.py 
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
class ErrorUtils:
    """A utility class for handling errors, including capturing, reporting, and generating responses."""

    @staticmethod
    def format_validation_errors(
        validation_error: ValidationError,
        *,
        include_type: bool = False,
    ) -> list[dict[str, str]]:
        """Formats Pydantic validation errors into a structured format.

        Args:
            validation_error (ValidationError): The validation error to format.
            include_type (bool): Whether to include the error type in the output. Defaults to False.

        Returns:
            list[dict[str, str]]: A list of formatted validation error details.
        """
        formatted_errors = []
        for error in validation_error.errors():
            error_dict = {
                "field": ".".join(str(x) for x in error["loc"]),
                "message": error["msg"],
                "value": str(error.get("input", "")),
            }
            if include_type:
                error_dict["type"] = error["type"]
            formatted_errors.append(error_dict)

        return formatted_errors

    @staticmethod
    def capture_exception(exception: BaseException) -> None:
        """Captures an exception and reports it to configured external services.

        This method logs the exception locally and optionally reports it to Sentry and Elastic APM,
        depending on the configuration.

        Args:
            exception (BaseException): The exception to capture and report.
        """
        # Always log the exception locally
        logger.exception("An exception occurred")
        config: Any = BaseConfig.global_config()

        # Report exception to Sentry if enabled
        if config.SENTRY.IS_ENABLED:
            try:
                import sentry_sdk

                sentry_sdk.capture_exception(exception)
            except ImportError:
                logger.exception("sentry_sdk is not installed, cannot capture exception in Sentry.")

        # Report exception to Elastic APM if enabled
        if config.ELASTIC_APM.IS_ENABLED:
            try:
                import elasticapm

                # Type ignoring elasticapm.get_client() as it's a third-party function
                client = elasticapm.get_client()
                client.capture_exception()
            except ImportError:
                logger.exception("elasticapm is not installed, cannot capture exception in Elastic APM.")

    @staticmethod
    async def async_handle_fastapi_exception(_request: RequestProtocol, exception: BaseError) -> JSONResponseProtocol:
        """Handles a FastAPI exception and returns a JSON response.

        Args:
            _request (Request): The incoming FastAPI request.
            exception (BaseError): The exception to handle.

        Returns:
            JSONResponse: A JSON response containing the exception details.

        Raises:
            NotImplementedError: If FastAPI is not available.
        """
        if not HTTP_AVAILABLE:
            raise NotImplementedError
        return JSONResponse(
            status_code=exception.http_status or HTTPStatus.INTERNAL_SERVER_ERROR,
            content=exception.to_dict(),
        )

    @staticmethod
    def handle_grpc_exception(exception: BaseError) -> tuple[int, str]:
        """Handles a gRPC exception and returns a tuple of status code and message.

        Args:
            exception (BaseError): The exception to handle.

        Returns:
            tuple[int, str]: A tuple containing the gRPC status code and error message.

        Raises:
            NotImplementedError: If gRPC is not available.
        """
        if not GRPC_AVAILABLE:
            raise NotImplementedError
        return exception.grpc_status or StatusCode.UNKNOWN.value[0], exception.get_message()

    @staticmethod
    def get_fastapi_exception_responses(exceptions: list[type[BaseError]]) -> dict[int, dict[str, Any]]:
        """Generates OpenAPI response documentation for the given errors.

        This method creates OpenAPI-compatible response schemas for FastAPI errors,
        including validation errors and custom errors.

        Args:
            exceptions (list[type[BaseError]]): A list of exception types to generate responses for.

        Returns:
            dict[int, dict[str, Any]]: A dictionary mapping HTTP status codes to their corresponding response schemas.
        """
        responses: dict[int, dict[str, Any]] = {}

        # Add validation error response by default
        validation_error_response = ValidationErrorResponseDTO()
        if validation_error_response.status_code is not None:
            responses[validation_error_response.status_code] = validation_error_response.model

        exception_schemas = {
            "InvalidPhoneNumberError": {
                "phone_number": {"type": "string", "example": "1234567890", "description": "The invalid phone number"},
            },
            "InvalidLandlineNumberError": {
                "landline_number": {
                    "type": "string",
                    "example": "02112345678",
                    "description": "The invalid landline number",
                },
            },
            "NotFoundError": {
                "resource_type": {
                    "type": "string",
                    "example": "user",
                    "description": "Type of resource that was not found",
                },
            },
            "AlreadyExistsError": {
                "resource_type": {
                    "type": "string",
                    "example": "user",
                    "description": "Type of resource that was not found",
                },
            },
            "InvalidNationalCodeError": {
                "national_code": {
                    "type": "string",
                    "example": "1234567890",
                    "description": "The invalid national code",
                },
            },
            "InvalidArgumentError": {
                "argument": {
                    "type": "string",
                    "example": "mobile_number",
                    "description": "Argument that was invalid",
                },
            },
        }

        for exc in exceptions:
            # Use exception class directly (error details are now class attributes)
            if exc.http_status:
                additional_properties = exception_schemas.get(exc.__name__)
                response = FastAPIErrorResponseDTO(exc, additional_properties)
                if response.status_code is not None:
                    responses[response.status_code] = response.model

        return responses

archipy.helpers.utils.error_utils.ErrorUtils.format_validation_errors staticmethod 

format_validation_errors(
    validation_error: ValidationError,
    *,
    include_type: bool = False,
) -> list[dict[str, str]]

Formats Pydantic validation errors into a structured format.

Parameters:

Name Type Description Default
validation_error ValidationError

The validation error to format.

 required
include_type bool

Whether to include the error type in the output. Defaults to False.

 False

Returns:

Type Description
list[dict[str, str]]

list[dict[str, str]]: A list of formatted validation error details.
Source code in archipy/helpers/utils/error_utils.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@staticmethod
def format_validation_errors(
    validation_error: ValidationError,
    *,
    include_type: bool = False,
) -> list[dict[str, str]]:
    """Formats Pydantic validation errors into a structured format.

    Args:
        validation_error (ValidationError): The validation error to format.
        include_type (bool): Whether to include the error type in the output. Defaults to False.

    Returns:
        list[dict[str, str]]: A list of formatted validation error details.
    """
    formatted_errors = []
    for error in validation_error.errors():
        error_dict = {
            "field": ".".join(str(x) for x in error["loc"]),
            "message": error["msg"],
            "value": str(error.get("input", "")),
        }
        if include_type:
            error_dict["type"] = error["type"]
        formatted_errors.append(error_dict)

    return formatted_errors

archipy.helpers.utils.error_utils.ErrorUtils.capture_exception staticmethod 

capture_exception(exception: BaseException) -> None

Captures an exception and reports it to configured external services.

This method logs the exception locally and optionally reports it to Sentry and Elastic APM, depending on the configuration.

Parameters:

Name Type Description Default
exception BaseException

The exception to capture and report.

 required
Source code in archipy/helpers/utils/error_utils.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
@staticmethod
def capture_exception(exception: BaseException) -> None:
    """Captures an exception and reports it to configured external services.

    This method logs the exception locally and optionally reports it to Sentry and Elastic APM,
    depending on the configuration.

    Args:
        exception (BaseException): The exception to capture and report.
    """
    # Always log the exception locally
    logger.exception("An exception occurred")
    config: Any = BaseConfig.global_config()

    # Report exception to Sentry if enabled
    if config.SENTRY.IS_ENABLED:
        try:
            import sentry_sdk

            sentry_sdk.capture_exception(exception)
        except ImportError:
            logger.exception("sentry_sdk is not installed, cannot capture exception in Sentry.")

    # Report exception to Elastic APM if enabled
    if config.ELASTIC_APM.IS_ENABLED:
        try:
            import elasticapm

            # Type ignoring elasticapm.get_client() as it's a third-party function
            client = elasticapm.get_client()
            client.capture_exception()
        except ImportError:
            logger.exception("elasticapm is not installed, cannot capture exception in Elastic APM.")

archipy.helpers.utils.error_utils.ErrorUtils.async_handle_fastapi_exception async staticmethod 

async_handle_fastapi_exception(
    _request: RequestProtocol, exception: BaseError
) -> JSONResponseProtocol

Handles a FastAPI exception and returns a JSON response.

Parameters:

Name Type Description Default
_request Request

The incoming FastAPI request.

 required
exception BaseError

The exception to handle.

 required

Returns:

Name Type Description
JSONResponse JSONResponseProtocol

A JSON response containing the exception details.

Raises:

Type Description
NotImplementedError

If FastAPI is not available.
Source code in archipy/helpers/utils/error_utils.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
@staticmethod
async def async_handle_fastapi_exception(_request: RequestProtocol, exception: BaseError) -> JSONResponseProtocol:
    """Handles a FastAPI exception and returns a JSON response.

    Args:
        _request (Request): The incoming FastAPI request.
        exception (BaseError): The exception to handle.

    Returns:
        JSONResponse: A JSON response containing the exception details.

    Raises:
        NotImplementedError: If FastAPI is not available.
    """
    if not HTTP_AVAILABLE:
        raise NotImplementedError
    return JSONResponse(
        status_code=exception.http_status or HTTPStatus.INTERNAL_SERVER_ERROR,
        content=exception.to_dict(),
    )

archipy.helpers.utils.error_utils.ErrorUtils.handle_grpc_exception staticmethod 

handle_grpc_exception(
    exception: BaseError,
) -> tuple[int, str]

Handles a gRPC exception and returns a tuple of status code and message.

Parameters:

Name Type Description Default
exception BaseError

The exception to handle.

 required

Returns:

Type Description
tuple[int, str]

tuple[int, str]: A tuple containing the gRPC status code and error message.

Raises:

Type Description
NotImplementedError

If gRPC is not available.
Source code in archipy/helpers/utils/error_utils.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
@staticmethod
def handle_grpc_exception(exception: BaseError) -> tuple[int, str]:
    """Handles a gRPC exception and returns a tuple of status code and message.

    Args:
        exception (BaseError): The exception to handle.

    Returns:
        tuple[int, str]: A tuple containing the gRPC status code and error message.

    Raises:
        NotImplementedError: If gRPC is not available.
    """
    if not GRPC_AVAILABLE:
        raise NotImplementedError
    return exception.grpc_status or StatusCode.UNKNOWN.value[0], exception.get_message()

archipy.helpers.utils.error_utils.ErrorUtils.get_fastapi_exception_responses staticmethod 

get_fastapi_exception_responses(
    exceptions: list[type[BaseError]],
) -> dict[int, dict[str, Any]]

Generates OpenAPI response documentation for the given errors.

This method creates OpenAPI-compatible response schemas for FastAPI errors, including validation errors and custom errors.

Parameters:

Name Type Description Default
exceptions list[type[BaseError]]

A list of exception types to generate responses for.

 required

Returns:

Type Description
dict[int, dict[str, Any]]

dict[int, dict[str, Any]]: A dictionary mapping HTTP status codes to their corresponding response schemas.
Source code in archipy/helpers/utils/error_utils.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
@staticmethod
def get_fastapi_exception_responses(exceptions: list[type[BaseError]]) -> dict[int, dict[str, Any]]:
    """Generates OpenAPI response documentation for the given errors.

    This method creates OpenAPI-compatible response schemas for FastAPI errors,
    including validation errors and custom errors.

    Args:
        exceptions (list[type[BaseError]]): A list of exception types to generate responses for.

    Returns:
        dict[int, dict[str, Any]]: A dictionary mapping HTTP status codes to their corresponding response schemas.
    """
    responses: dict[int, dict[str, Any]] = {}

    # Add validation error response by default
    validation_error_response = ValidationErrorResponseDTO()
    if validation_error_response.status_code is not None:
        responses[validation_error_response.status_code] = validation_error_response.model

    exception_schemas = {
        "InvalidPhoneNumberError": {
            "phone_number": {"type": "string", "example": "1234567890", "description": "The invalid phone number"},
        },
        "InvalidLandlineNumberError": {
            "landline_number": {
                "type": "string",
                "example": "02112345678",
                "description": "The invalid landline number",
            },
        },
        "NotFoundError": {
            "resource_type": {
                "type": "string",
                "example": "user",
                "description": "Type of resource that was not found",
            },
        },
        "AlreadyExistsError": {
            "resource_type": {
                "type": "string",
                "example": "user",
                "description": "Type of resource that was not found",
            },
        },
        "InvalidNationalCodeError": {
            "national_code": {
                "type": "string",
                "example": "1234567890",
                "description": "The invalid national code",
            },
        },
        "InvalidArgumentError": {
            "argument": {
                "type": "string",
                "example": "mobile_number",
                "description": "Argument that was invalid",
            },
        },
    }

    for exc in exceptions:
        # Use exception class directly (error details are now class attributes)
        if exc.http_status:
            additional_properties = exception_schemas.get(exc.__name__)
            response = FastAPIErrorResponseDTO(exc, additional_properties)
            if response.status_code is not None:
                responses[response.status_code] = response.model

    return responses

options: show_root_toc_entry: false heading_level: 3

JWT Utils

Utilities for JWT generation, verification, and decoding with configurable signing algorithms and expiration.

Utility module for JWT token operations with enhanced security and datetime handling.

This module provides a robust JWT handling implementation with support for access and refresh tokens, cryptographic security, token validation, and comprehensive error handling.

archipy.helpers.utils.jwt_utils.JWTUtils

Utility class for JWT token operations with enhanced security and datetime handling.

Source code in archipy/helpers/utils/jwt_utils.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
class JWTUtils:
    """Utility class for JWT token operations with enhanced security and datetime handling."""

    @classmethod
    def create_token(
        cls,
        data: dict[str, Any],
        expires_in: int,
        additional_claims: dict[str, Any] | None = None,
        auth_config: AuthConfig | None = None,
    ) -> str:
        """Creates a JWT token with enhanced security features.

        Args:
            data (dict[str, Any]): Base claims data to include in the token.
            expires_in (int): Token expiration time in seconds.
            additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
            auth_config (AuthConfig | None): Optional auth configuration override.
                If not provided, uses the global config.

        Returns:
            str: The encoded JWT token.

        Raises:
            ValueError: If data is empty or expiration is invalid
        """
        import jwt

        configs = auth_config or BaseConfig.global_config().AUTH
        current_time = DatetimeUtils.get_datetime_utc_now()

        # Define argument names
        arg_data = "data"
        arg_expires_in = "expires_in"

        if not data:
            raise InvalidArgumentError(arg_data)
        if expires_in <= 0:
            raise InvalidArgumentError(arg_expires_in)

        to_encode = data.copy()
        expire = DatetimeUtils.get_datetime_after_given_datetime_or_now(seconds=expires_in, datetime_given=current_time)

        # Add standard claims
        to_encode.update(
            {
                # Registered claims (RFC 7519)
                "iss": configs.JWT_ISSUER,
                "aud": configs.JWT_AUDIENCE,
                "exp": expire,
                "iat": current_time,
                "nbf": current_time,
            },
        )

        # Add JWT ID if enabled
        if configs.ENABLE_JTI_CLAIM:
            to_encode["jti"] = str(uuid4())

        # Add additional claims
        if additional_claims:
            to_encode.update(additional_claims)

        # Validate SECRET_KEY
        secret_key = configs.SECRET_KEY
        if secret_key is None:
            raise InvalidArgumentError("SECRET_KEY")
        return jwt.encode(to_encode, secret_key.get_secret_value(), algorithm=configs.HASH_ALGORITHM)

    @classmethod
    def create_access_token(
        cls,
        user_uuid: UUID,
        additional_claims: dict[str, Any] | None = None,
        auth_config: AuthConfig | None = None,
    ) -> str:
        """Creates an access token for a user.

        Args:
            user_uuid (UUID): The user's UUID to include in the token.
            additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
            auth_config (AuthConfig | None): Optional auth configuration override.
                If not provided, uses the global config.

        Returns:
            str: The encoded access token.
        """
        configs = auth_config or BaseConfig.global_config().AUTH

        return cls.create_token(
            data={
                "sub": str(user_uuid),
                "type": "access",
                "token_version": configs.TOKEN_VERSION,
            },
            expires_in=configs.ACCESS_TOKEN_EXPIRES_IN,
            additional_claims=additional_claims,
            auth_config=configs,
        )

    @classmethod
    def create_refresh_token(
        cls,
        user_uuid: UUID,
        additional_claims: dict[str, Any] | None = None,
        auth_config: AuthConfig | None = None,
    ) -> str:
        """Creates a refresh token for a user.

        Args:
            user_uuid (UUID): The user's UUID to include in the token.
            additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
            auth_config (AuthConfig | None): Optional auth configuration override.
                If not provided, uses the global config.

        Returns:
            str: The encoded refresh token.
        """
        configs = auth_config or BaseConfig.global_config().AUTH

        return cls.create_token(
            data={
                "sub": str(user_uuid),
                "type": "refresh",
                "token_version": configs.TOKEN_VERSION,
            },
            expires_in=configs.REFRESH_TOKEN_EXPIRES_IN,
            additional_claims=additional_claims,
            auth_config=configs,
        )

    @classmethod
    def decode_token(
        cls,
        token: str,
        verify_type: str | None = None,
        auth_config: AuthConfig | None = None,
    ) -> dict[str, Any]:
        """Decodes and verifies a JWT token with enhanced security checks.

        Args:
            token (str): The JWT token to decode.
            verify_type (str | None): Optional token type to verify (e.g., "access" or "refresh").
            auth_config (AuthConfig | None): Optional auth configuration override.
                If not provided, uses the global config.

        Returns:
            dict[str, Any]: The decoded token payload.

        Raises:
            TokenExpiredError: If the token has expired.
            InvalidTokenError: If the token is invalid (e.g., invalid signature, audience, issuer, or type).
        """
        import jwt
        from jwt.exceptions import (
            ExpiredSignatureError,
            InvalidAudienceError,
            InvalidIssuerError,
            InvalidSignatureError,
            InvalidTokenError as JWTInvalidTokenError,
        )

        configs = auth_config or BaseConfig.global_config().AUTH
        required_claims = ["exp", "iat", "nbf", "aud", "iss", "sub", "type", "token_version"]
        if configs.ENABLE_JTI_CLAIM:
            required_claims.append("jti")

        try:
            # Validate SECRET_KEY
            secret_key = configs.SECRET_KEY
            if secret_key is None:
                raise InvalidArgumentError("SECRET_KEY")

            payload = jwt.decode(
                token,
                secret_key.get_secret_value(),
                algorithms=[configs.HASH_ALGORITHM],
                options={
                    "verify_signature": True,
                    "verify_exp": True,
                    "verify_nbf": True,
                    "verify_iat": True,
                    "verify_aud": True,
                    "verify_iss": True,
                    "require": required_claims,
                },
                audience=configs.JWT_AUDIENCE,
                issuer=configs.JWT_ISSUER,
            )

            # Verify token type
            if verify_type and payload.get("type") != verify_type:
                raise InvalidTokenError

            # Verify token version
            if payload.get("token_version") != configs.TOKEN_VERSION:
                raise InvalidTokenError

            # Ensure the return type is dict[str, Any] as declared
            return dict(payload)

        except ExpiredSignatureError as exception:
            raise TokenExpiredError from exception
        except InvalidSignatureError as exception:
            raise InvalidTokenError from exception
        except InvalidAudienceError as exception:
            raise InvalidTokenError from exception
        except InvalidIssuerError as exception:
            raise InvalidTokenError from exception
        except JWTInvalidTokenError as exception:
            raise InvalidTokenError from exception

    @classmethod
    def verify_access_token(cls, token: str, auth_config: AuthConfig | None = None) -> dict[str, Any]:
        """Verifies an access token.

        Args:
            token (str): The access token to verify.
            auth_config (AuthConfig | None): Optional auth configuration override.
                If not provided, uses the global config.

        Returns:
            dict[str, Any]: The decoded access token payload.

        Raises:
            InvalidTokenException: If the token is invalid or not an access token.
            TokenExpiredException: If the token has expired.
        """
        configs = auth_config or BaseConfig.global_config().AUTH
        return cls.decode_token(token, verify_type="access", auth_config=configs)

    @classmethod
    def verify_refresh_token(cls, token: str, auth_config: AuthConfig | None = None) -> dict[str, Any]:
        """Verifies a refresh token.

        Args:
            token (str): The refresh token to verify.
            auth_config (AuthConfig | None): Optional auth configuration override.
                If not provided, uses the global config.

        Returns:
            dict[str, Any]: The decoded refresh token payload.

        Raises:
            InvalidTokenException: If the token is invalid or not a refresh token.
            TokenExpiredException: If the token has expired.
        """
        configs = auth_config or BaseConfig.global_config().AUTH
        return cls.decode_token(token, verify_type="refresh", auth_config=configs)

    @staticmethod
    def extract_user_uuid(payload: dict[str, Any]) -> UUID:
        """Extracts the user UUID from the token payload.

        Args:
            payload (dict[str, Any]): The decoded token payload.

        Returns:
            UUID: The user's UUID.

        Raises:
            InvalidTokenException: If the user identifier is invalid or missing.
        """
        try:
            return UUID(payload["sub"])
        except (KeyError, ValueError) as exception:
            raise InvalidTokenError from exception

    @classmethod
    def get_token_expiry(cls, token: str, auth_config: AuthConfig | None = None) -> int:
        """Gets the token expiry timestamp.

        Args:
            token (str): The JWT token.
            auth_config (AuthConfig | None): Optional auth configuration override.
                If not provided, uses the global config.

        Returns:
            int: The token expiry timestamp in seconds.

        Raises:
            InvalidTokenException: If the token is invalid.
        """
        payload = cls.decode_token(token, auth_config=auth_config)
        return int(payload["exp"])

archipy.helpers.utils.jwt_utils.JWTUtils.create_token classmethod 

create_token(
    data: dict[str, Any],
    expires_in: int,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str

Creates a JWT token with enhanced security features.

Parameters:

Name Type Description Default
data dict[str, Any]

Base claims data to include in the token.

 required
expires_in int

Token expiration time in seconds.

 required
additional_claims dict[str, Any] | None

Optional additional claims to include in the token.

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

The encoded JWT token.

Raises:

Type Description
ValueError

If data is empty or expiration is invalid
Source code in archipy/helpers/utils/jwt_utils.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@classmethod
def create_token(
    cls,
    data: dict[str, Any],
    expires_in: int,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str:
    """Creates a JWT token with enhanced security features.

    Args:
        data (dict[str, Any]): Base claims data to include in the token.
        expires_in (int): Token expiration time in seconds.
        additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        str: The encoded JWT token.

    Raises:
        ValueError: If data is empty or expiration is invalid
    """
    import jwt

    configs = auth_config or BaseConfig.global_config().AUTH
    current_time = DatetimeUtils.get_datetime_utc_now()

    # Define argument names
    arg_data = "data"
    arg_expires_in = "expires_in"

    if not data:
        raise InvalidArgumentError(arg_data)
    if expires_in <= 0:
        raise InvalidArgumentError(arg_expires_in)

    to_encode = data.copy()
    expire = DatetimeUtils.get_datetime_after_given_datetime_or_now(seconds=expires_in, datetime_given=current_time)

    # Add standard claims
    to_encode.update(
        {
            # Registered claims (RFC 7519)
            "iss": configs.JWT_ISSUER,
            "aud": configs.JWT_AUDIENCE,
            "exp": expire,
            "iat": current_time,
            "nbf": current_time,
        },
    )

    # Add JWT ID if enabled
    if configs.ENABLE_JTI_CLAIM:
        to_encode["jti"] = str(uuid4())

    # Add additional claims
    if additional_claims:
        to_encode.update(additional_claims)

    # Validate SECRET_KEY
    secret_key = configs.SECRET_KEY
    if secret_key is None:
        raise InvalidArgumentError("SECRET_KEY")
    return jwt.encode(to_encode, secret_key.get_secret_value(), algorithm=configs.HASH_ALGORITHM)

archipy.helpers.utils.jwt_utils.JWTUtils.create_access_token classmethod 

create_access_token(
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str

Creates an access token for a user.

Parameters:

Name Type Description Default
user_uuid UUID

The user's UUID to include in the token.

 required
additional_claims dict[str, Any] | None

Optional additional claims to include in the token.

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

The encoded access token.
Source code in archipy/helpers/utils/jwt_utils.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
@classmethod
def create_access_token(
    cls,
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str:
    """Creates an access token for a user.

    Args:
        user_uuid (UUID): The user's UUID to include in the token.
        additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        str: The encoded access token.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    return cls.create_token(
        data={
            "sub": str(user_uuid),
            "type": "access",
            "token_version": configs.TOKEN_VERSION,
        },
        expires_in=configs.ACCESS_TOKEN_EXPIRES_IN,
        additional_claims=additional_claims,
        auth_config=configs,
    )

archipy.helpers.utils.jwt_utils.JWTUtils.create_refresh_token classmethod 

create_refresh_token(
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str

Creates a refresh token for a user.

Parameters:

Name Type Description Default
user_uuid UUID

The user's UUID to include in the token.

 required
additional_claims dict[str, Any] | None

Optional additional claims to include in the token.

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

The encoded refresh token.
Source code in archipy/helpers/utils/jwt_utils.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
@classmethod
def create_refresh_token(
    cls,
    user_uuid: UUID,
    additional_claims: dict[str, Any] | None = None,
    auth_config: AuthConfig | None = None,
) -> str:
    """Creates a refresh token for a user.

    Args:
        user_uuid (UUID): The user's UUID to include in the token.
        additional_claims (dict[str, Any] | None): Optional additional claims to include in the token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        str: The encoded refresh token.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    return cls.create_token(
        data={
            "sub": str(user_uuid),
            "type": "refresh",
            "token_version": configs.TOKEN_VERSION,
        },
        expires_in=configs.REFRESH_TOKEN_EXPIRES_IN,
        additional_claims=additional_claims,
        auth_config=configs,
    )

archipy.helpers.utils.jwt_utils.JWTUtils.decode_token classmethod 

decode_token(
    token: str,
    verify_type: str | None = None,
    auth_config: AuthConfig | None = None,
) -> dict[str, Any]

Decodes and verifies a JWT token with enhanced security checks.

Parameters:

Name Type Description Default
token str

The JWT token to decode.

 required
verify_type str | None

Optional token type to verify (e.g., "access" or "refresh").

 None
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
dict[str, Any]

dict[str, Any]: The decoded token payload.

Raises:

Type Description
TokenExpiredError

If the token has expired.
InvalidTokenError

If the token is invalid (e.g., invalid signature, audience, issuer, or type).
Source code in archipy/helpers/utils/jwt_utils.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
@classmethod
def decode_token(
    cls,
    token: str,
    verify_type: str | None = None,
    auth_config: AuthConfig | None = None,
) -> dict[str, Any]:
    """Decodes and verifies a JWT token with enhanced security checks.

    Args:
        token (str): The JWT token to decode.
        verify_type (str | None): Optional token type to verify (e.g., "access" or "refresh").
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        dict[str, Any]: The decoded token payload.

    Raises:
        TokenExpiredError: If the token has expired.
        InvalidTokenError: If the token is invalid (e.g., invalid signature, audience, issuer, or type).
    """
    import jwt
    from jwt.exceptions import (
        ExpiredSignatureError,
        InvalidAudienceError,
        InvalidIssuerError,
        InvalidSignatureError,
        InvalidTokenError as JWTInvalidTokenError,
    )

    configs = auth_config or BaseConfig.global_config().AUTH
    required_claims = ["exp", "iat", "nbf", "aud", "iss", "sub", "type", "token_version"]
    if configs.ENABLE_JTI_CLAIM:
        required_claims.append("jti")

    try:
        # Validate SECRET_KEY
        secret_key = configs.SECRET_KEY
        if secret_key is None:
            raise InvalidArgumentError("SECRET_KEY")

        payload = jwt.decode(
            token,
            secret_key.get_secret_value(),
            algorithms=[configs.HASH_ALGORITHM],
            options={
                "verify_signature": True,
                "verify_exp": True,
                "verify_nbf": True,
                "verify_iat": True,
                "verify_aud": True,
                "verify_iss": True,
                "require": required_claims,
            },
            audience=configs.JWT_AUDIENCE,
            issuer=configs.JWT_ISSUER,
        )

        # Verify token type
        if verify_type and payload.get("type") != verify_type:
            raise InvalidTokenError

        # Verify token version
        if payload.get("token_version") != configs.TOKEN_VERSION:
            raise InvalidTokenError

        # Ensure the return type is dict[str, Any] as declared
        return dict(payload)

    except ExpiredSignatureError as exception:
        raise TokenExpiredError from exception
    except InvalidSignatureError as exception:
        raise InvalidTokenError from exception
    except InvalidAudienceError as exception:
        raise InvalidTokenError from exception
    except InvalidIssuerError as exception:
        raise InvalidTokenError from exception
    except JWTInvalidTokenError as exception:
        raise InvalidTokenError from exception

archipy.helpers.utils.jwt_utils.JWTUtils.verify_access_token classmethod 

verify_access_token(
    token: str, auth_config: AuthConfig | None = None
) -> dict[str, Any]

Verifies an access token.

Parameters:

Name Type Description Default
token str

The access token to verify.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
dict[str, Any]

dict[str, Any]: The decoded access token payload.

Raises:

Type Description
InvalidTokenException

If the token is invalid or not an access token.
TokenExpiredException

If the token has expired.
Source code in archipy/helpers/utils/jwt_utils.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
@classmethod
def verify_access_token(cls, token: str, auth_config: AuthConfig | None = None) -> dict[str, Any]:
    """Verifies an access token.

    Args:
        token (str): The access token to verify.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        dict[str, Any]: The decoded access token payload.

    Raises:
        InvalidTokenException: If the token is invalid or not an access token.
        TokenExpiredException: If the token has expired.
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    return cls.decode_token(token, verify_type="access", auth_config=configs)

archipy.helpers.utils.jwt_utils.JWTUtils.verify_refresh_token classmethod 

verify_refresh_token(
    token: str, auth_config: AuthConfig | None = None
) -> dict[str, Any]

Verifies a refresh token.

Parameters:

Name Type Description Default
token str

The refresh token to verify.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
dict[str, Any]

dict[str, Any]: The decoded refresh token payload.

Raises:

Type Description
InvalidTokenException

If the token is invalid or not a refresh token.
TokenExpiredException

If the token has expired.
Source code in archipy/helpers/utils/jwt_utils.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
@classmethod
def verify_refresh_token(cls, token: str, auth_config: AuthConfig | None = None) -> dict[str, Any]:
    """Verifies a refresh token.

    Args:
        token (str): The refresh token to verify.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        dict[str, Any]: The decoded refresh token payload.

    Raises:
        InvalidTokenException: If the token is invalid or not a refresh token.
        TokenExpiredException: If the token has expired.
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    return cls.decode_token(token, verify_type="refresh", auth_config=configs)

archipy.helpers.utils.jwt_utils.JWTUtils.extract_user_uuid staticmethod 

extract_user_uuid(payload: dict[str, Any]) -> UUID

Extracts the user UUID from the token payload.

Parameters:

Name Type Description Default
payload dict[str, Any]

The decoded token payload.

 required

Returns:

Name Type Description
UUID UUID

The user's UUID.

Raises:

Type Description
InvalidTokenException

If the user identifier is invalid or missing.
Source code in archipy/helpers/utils/jwt_utils.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
@staticmethod
def extract_user_uuid(payload: dict[str, Any]) -> UUID:
    """Extracts the user UUID from the token payload.

    Args:
        payload (dict[str, Any]): The decoded token payload.

    Returns:
        UUID: The user's UUID.

    Raises:
        InvalidTokenException: If the user identifier is invalid or missing.
    """
    try:
        return UUID(payload["sub"])
    except (KeyError, ValueError) as exception:
        raise InvalidTokenError from exception

archipy.helpers.utils.jwt_utils.JWTUtils.get_token_expiry classmethod 

get_token_expiry(
    token: str, auth_config: AuthConfig | None = None
) -> int

Gets the token expiry timestamp.

Parameters:

Name Type Description Default
token str

The JWT token.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
int int

The token expiry timestamp in seconds.

Raises:

Type Description
InvalidTokenException

If the token is invalid.
Source code in archipy/helpers/utils/jwt_utils.py 
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@classmethod
def get_token_expiry(cls, token: str, auth_config: AuthConfig | None = None) -> int:
    """Gets the token expiry timestamp.

    Args:
        token (str): The JWT token.
        auth_config (AuthConfig | None): Optional auth configuration override.
            If not provided, uses the global config.

    Returns:
        int: The token expiry timestamp in seconds.

    Raises:
        InvalidTokenException: If the token is invalid.
    """
    payload = cls.decode_token(token, auth_config=auth_config)
    return int(payload["exp"])

options: show_root_toc_entry: false heading_level: 3

Password Utils

Utilities for secure password hashing, verification, generation, and strength validation with timing-attack protection.

archipy.helpers.utils.password_utils.PasswordUtils

A utility class for handling password-related operations, such as hashing, verification, and validation.

Source code in archipy/helpers/utils/password_utils.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
class PasswordUtils:
    """A utility class for handling password-related operations, such as hashing, verification, and validation."""

    @staticmethod
    def hash_password(password: str, auth_config: AuthConfig | None = None) -> str:
        """Hashes a password using PBKDF2 with SHA256.

        Args:
            password (str): The password to hash.
            auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

        Returns:
            str: A base64-encoded string containing the salt and hash in the format "salt:hash".
        """
        configs = auth_config or BaseConfig.global_config().AUTH
        salt = os.urandom(configs.SALT_LENGTH)
        pw_hash = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, configs.HASH_ITERATIONS)

        # Combine salt and hash, encode in base64
        return b64encode(salt + pw_hash).decode("utf-8")

    @staticmethod
    def verify_password(password: str, stored_password: str, auth_config: AuthConfig | None = None) -> bool:
        """Verifies a password against a stored hash.

        Args:
            password (str): The password to verify.
            stored_password (str): The stored password hash to compare against.
            auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

        Returns:
            bool: True if the password matches the stored hash, False otherwise.
        """
        try:
            configs = auth_config or BaseConfig.global_config().AUTH

            # Decode the stored password
            decoded = b64decode(stored_password.encode("utf-8"))
            salt = decoded[: configs.SALT_LENGTH]
            stored_hash = decoded[configs.SALT_LENGTH :]

            # Hash the provided password with the same salt
            pw_hash = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, configs.HASH_ITERATIONS)

            # Compare in constant time to prevent timing attacks
            return hmac.compare_digest(pw_hash, stored_hash)
        except ValueError, TypeError, IndexError:
            # Catch specific exceptions that could occur during decoding or comparison
            return False

    @staticmethod
    def validate_password(
        password: str,
        auth_config: AuthConfig | None = None,
    ) -> None:
        """Validates a password against the password policy.

        Args:
            password (str): The password to validate.
            auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

        Raises:
            InvalidPasswordError: If the password does not meet the policy requirements.
        """
        configs = auth_config or BaseConfig.global_config().AUTH
        errors = []

        if len(password) < configs.MIN_LENGTH:
            errors.append(f"Password must be at least {configs.MIN_LENGTH} characters long.")

        if configs.REQUIRE_DIGIT and not any(char.isdigit() for char in password):
            errors.append("Password must contain at least one digit.")

        if configs.REQUIRE_LOWERCASE and not any(char.islower() for char in password):
            errors.append("Password must contain at least one lowercase letter.")

        if configs.REQUIRE_UPPERCASE and not any(char.isupper() for char in password):
            errors.append("Password must contain at least one uppercase letter.")

        if configs.REQUIRE_SPECIAL and not any(char in configs.SPECIAL_CHARACTERS for char in password):
            errors.append(f"Password must contain at least one special character: {configs.SPECIAL_CHARACTERS}")

        if errors:
            raise InvalidPasswordError(requirements=errors)

    @staticmethod
    def generate_password(auth_config: AuthConfig | None = None) -> str:
        """Generates a random password that meets the policy requirements.

        Args:
            auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

        Returns:
            str: A randomly generated password that meets the policy requirements.
        """
        configs = auth_config or BaseConfig.global_config().AUTH

        lowercase_chars = string.ascii_lowercase
        uppercase_chars = string.ascii_uppercase
        digit_chars = string.digits
        special_chars = "".join(configs.SPECIAL_CHARACTERS)

        # Initialize with required characters
        password_chars = []
        if configs.REQUIRE_LOWERCASE:
            password_chars.append(secrets.choice(lowercase_chars))
        if configs.REQUIRE_UPPERCASE:
            password_chars.append(secrets.choice(uppercase_chars))
        if configs.REQUIRE_DIGIT:
            password_chars.append(secrets.choice(digit_chars))
        if configs.REQUIRE_SPECIAL:
            password_chars.append(secrets.choice(special_chars))

        # Calculate remaining length
        remaining_length = max(0, configs.MIN_LENGTH - len(password_chars))

        # Add random characters to meet minimum length
        all_chars = lowercase_chars + uppercase_chars + digit_chars + special_chars
        password_chars.extend(secrets.choice(all_chars) for _ in range(remaining_length))

        # Shuffle the password characters
        shuffled = list(password_chars)
        secrets.SystemRandom().shuffle(shuffled)

        return "".join(shuffled)

    @classmethod
    def validate_password_history(
        cls,
        new_password: str,
        password_history: list[str],
        auth_config: AuthConfig | None = None,
        lang: LanguageType | None = None,
    ) -> None:
        """Validates a new password against the password history.

        Args:
            new_password (str): The new password to validate.
            password_history (list[str]): A list of previous password hashes.
            auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.
            lang (LanguageType): The language to use for error messages. Defaults to Persian.

        Raises:
            InvalidPasswordError: If the new password has been used recently or does not meet the policy requirements.
        """
        configs = auth_config or BaseConfig.global_config().AUTH

        # First validate against password policy
        cls.validate_password(new_password, configs)

        # Check password history
        if any(
            cls.verify_password(new_password, old_password, configs)
            for old_password in password_history[-configs.PASSWORD_HISTORY_SIZE :]
        ):
            raise InvalidPasswordError(requirements=["Password has been used recently"], lang=lang)

archipy.helpers.utils.password_utils.PasswordUtils.hash_password staticmethod 

hash_password(
    password: str, auth_config: AuthConfig | None = None
) -> str

Hashes a password using PBKDF2 with SHA256.

Parameters:

Name Type Description Default
password str

The password to hash.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

A base64-encoded string containing the salt and hash in the format "salt:hash".
Source code in archipy/helpers/utils/password_utils.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@staticmethod
def hash_password(password: str, auth_config: AuthConfig | None = None) -> str:
    """Hashes a password using PBKDF2 with SHA256.

    Args:
        password (str): The password to hash.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Returns:
        str: A base64-encoded string containing the salt and hash in the format "salt:hash".
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    salt = os.urandom(configs.SALT_LENGTH)
    pw_hash = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, configs.HASH_ITERATIONS)

    # Combine salt and hash, encode in base64
    return b64encode(salt + pw_hash).decode("utf-8")

archipy.helpers.utils.password_utils.PasswordUtils.verify_password staticmethod 

verify_password(
    password: str,
    stored_password: str,
    auth_config: AuthConfig | None = None,
) -> bool

Verifies a password against a stored hash.

Parameters:

Name Type Description Default
password str

The password to verify.

 required
stored_password str

The stored password hash to compare against.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
bool bool

True if the password matches the stored hash, False otherwise.
Source code in archipy/helpers/utils/password_utils.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@staticmethod
def verify_password(password: str, stored_password: str, auth_config: AuthConfig | None = None) -> bool:
    """Verifies a password against a stored hash.

    Args:
        password (str): The password to verify.
        stored_password (str): The stored password hash to compare against.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Returns:
        bool: True if the password matches the stored hash, False otherwise.
    """
    try:
        configs = auth_config or BaseConfig.global_config().AUTH

        # Decode the stored password
        decoded = b64decode(stored_password.encode("utf-8"))
        salt = decoded[: configs.SALT_LENGTH]
        stored_hash = decoded[configs.SALT_LENGTH :]

        # Hash the provided password with the same salt
        pw_hash = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, configs.HASH_ITERATIONS)

        # Compare in constant time to prevent timing attacks
        return hmac.compare_digest(pw_hash, stored_hash)
    except ValueError, TypeError, IndexError:
        # Catch specific exceptions that could occur during decoding or comparison
        return False

archipy.helpers.utils.password_utils.PasswordUtils.validate_password staticmethod 

validate_password(
    password: str, auth_config: AuthConfig | None = None
) -> None

Validates a password against the password policy.

Parameters:

Name Type Description Default
password str

The password to validate.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Raises:

Type Description
InvalidPasswordError

If the password does not meet the policy requirements.
Source code in archipy/helpers/utils/password_utils.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
@staticmethod
def validate_password(
    password: str,
    auth_config: AuthConfig | None = None,
) -> None:
    """Validates a password against the password policy.

    Args:
        password (str): The password to validate.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Raises:
        InvalidPasswordError: If the password does not meet the policy requirements.
    """
    configs = auth_config or BaseConfig.global_config().AUTH
    errors = []

    if len(password) < configs.MIN_LENGTH:
        errors.append(f"Password must be at least {configs.MIN_LENGTH} characters long.")

    if configs.REQUIRE_DIGIT and not any(char.isdigit() for char in password):
        errors.append("Password must contain at least one digit.")

    if configs.REQUIRE_LOWERCASE and not any(char.islower() for char in password):
        errors.append("Password must contain at least one lowercase letter.")

    if configs.REQUIRE_UPPERCASE and not any(char.isupper() for char in password):
        errors.append("Password must contain at least one uppercase letter.")

    if configs.REQUIRE_SPECIAL and not any(char in configs.SPECIAL_CHARACTERS for char in password):
        errors.append(f"Password must contain at least one special character: {configs.SPECIAL_CHARACTERS}")

    if errors:
        raise InvalidPasswordError(requirements=errors)

archipy.helpers.utils.password_utils.PasswordUtils.generate_password staticmethod 

generate_password(
    auth_config: AuthConfig | None = None,
) -> str

Generates a random password that meets the policy requirements.

Parameters:

Name Type Description Default
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Name Type Description
str str

A randomly generated password that meets the policy requirements.
Source code in archipy/helpers/utils/password_utils.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@staticmethod
def generate_password(auth_config: AuthConfig | None = None) -> str:
    """Generates a random password that meets the policy requirements.

    Args:
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.

    Returns:
        str: A randomly generated password that meets the policy requirements.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    lowercase_chars = string.ascii_lowercase
    uppercase_chars = string.ascii_uppercase
    digit_chars = string.digits
    special_chars = "".join(configs.SPECIAL_CHARACTERS)

    # Initialize with required characters
    password_chars = []
    if configs.REQUIRE_LOWERCASE:
        password_chars.append(secrets.choice(lowercase_chars))
    if configs.REQUIRE_UPPERCASE:
        password_chars.append(secrets.choice(uppercase_chars))
    if configs.REQUIRE_DIGIT:
        password_chars.append(secrets.choice(digit_chars))
    if configs.REQUIRE_SPECIAL:
        password_chars.append(secrets.choice(special_chars))

    # Calculate remaining length
    remaining_length = max(0, configs.MIN_LENGTH - len(password_chars))

    # Add random characters to meet minimum length
    all_chars = lowercase_chars + uppercase_chars + digit_chars + special_chars
    password_chars.extend(secrets.choice(all_chars) for _ in range(remaining_length))

    # Shuffle the password characters
    shuffled = list(password_chars)
    secrets.SystemRandom().shuffle(shuffled)

    return "".join(shuffled)

archipy.helpers.utils.password_utils.PasswordUtils.validate_password_history classmethod 

validate_password_history(
    new_password: str,
    password_history: list[str],
    auth_config: AuthConfig | None = None,
    lang: LanguageType | None = None,
) -> None

Validates a new password against the password history.

Parameters:

Name Type Description Default
new_password str

The new password to validate.

 required
password_history list[str]

A list of previous password hashes.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None
lang LanguageType

The language to use for error messages. Defaults to Persian.

 None

Raises:

Type Description
InvalidPasswordError

If the new password has been used recently or does not meet the policy requirements.
Source code in archipy/helpers/utils/password_utils.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
@classmethod
def validate_password_history(
    cls,
    new_password: str,
    password_history: list[str],
    auth_config: AuthConfig | None = None,
    lang: LanguageType | None = None,
) -> None:
    """Validates a new password against the password history.

    Args:
        new_password (str): The new password to validate.
        password_history (list[str]): A list of previous password hashes.
        auth_config (AuthConfig | None): Optional auth configuration override. If not provided, uses the global config.
        lang (LanguageType): The language to use for error messages. Defaults to Persian.

    Raises:
        InvalidPasswordError: If the new password has been used recently or does not meet the policy requirements.
    """
    configs = auth_config or BaseConfig.global_config().AUTH

    # First validate against password policy
    cls.validate_password(new_password, configs)

    # Check password history
    if any(
        cls.verify_password(new_password, old_password, configs)
        for old_password in password_history[-configs.PASSWORD_HISTORY_SIZE :]
    ):
        raise InvalidPasswordError(requirements=["Password has been used recently"], lang=lang)

options: show_root_toc_entry: false heading_level: 3

TOTP Utils

Utilities for TOTP (Time-based One-Time Password) generation, verification, and QR code URI construction.

Utility module for TOTP (Time-based One-Time Password) operations.

This module provides functionality for generating and verifying TOTP codes that are commonly used for multi-factor authentication.

archipy.helpers.utils.totp_utils.TOTPUtils

Utility class for TOTP (Time-based One-Time Password) operations.

This class provides methods for generating and verifying TOTP codes, as well as generating secure secret keys for TOTP initialization.

Uses the following configuration parameters from AuthConfig: - TOTP_SECRET_KEY: Master secret key for generating TOTP secrets - TOTP_HASH_ALGORITHM: Hash algorithm used for TOTP generation (default: SHA1) - TOTP_LENGTH: Number of digits in generated TOTP codes - TOTP_TIME_STEP: Time step in seconds between TOTP code changes - TOTP_EXPIRES_IN: TOTP validity period in seconds - TOTP_VERIFICATION_WINDOW: Number of time steps to check before/after - SALT_LENGTH: Length of random bytes for secure key generation

Source code in archipy/helpers/utils/totp_utils.py 
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
class TOTPUtils:
    """Utility class for TOTP (Time-based One-Time Password) operations.

    This class provides methods for generating and verifying TOTP codes, as well as generating
    secure secret keys for TOTP initialization.

    Uses the following configuration parameters from AuthConfig:
    - TOTP_SECRET_KEY: Master secret key for generating TOTP secrets
    - TOTP_HASH_ALGORITHM: Hash algorithm used for TOTP generation (default: SHA1)
    - TOTP_LENGTH: Number of digits in generated TOTP codes
    - TOTP_TIME_STEP: Time step in seconds between TOTP code changes
    - TOTP_EXPIRES_IN: TOTP validity period in seconds
    - TOTP_VERIFICATION_WINDOW: Number of time steps to check before/after
    - SALT_LENGTH: Length of random bytes for secure key generation
    """

    @classmethod
    def generate_totp(cls, secret: str | UUID, auth_config: AuthConfig | None = None) -> tuple[str, datetime]:
        """Generates a TOTP code using the configured hash algorithm.

        Args:
            secret: The secret key used to generate the TOTP code.
            auth_config: Optional auth configuration override. If not provided, uses the global config.

        Returns:
            A tuple containing the generated TOTP code and its expiration time.

        Raises:
            InvalidArgumentError: If the secret is invalid or empty.
        """
        if not secret:
            raise InvalidArgumentError(
                argument_name="secret",
            )

        configs = auth_config or BaseConfig.global_config().AUTH

        # Convert secret to bytes if it's UUID
        if isinstance(secret, UUID):
            secret = str(secret)

        # Get current timestamp and calculate time step
        current_time = DatetimeUtils.get_epoch_time_now()
        time_step_counter = int(current_time / configs.TOTP_TIME_STEP)

        # Generate HMAC hash
        secret_bytes = str(secret).encode("utf-8")
        time_bytes = struct.pack(">Q", time_step_counter)

        # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
        hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

        hmac_obj = hmac.new(secret_bytes, time_bytes, hash_algo)
        hmac_result = hmac_obj.digest()

        # Get offset and truncate
        offset = hmac_result[-1] & 0xF
        truncated_hash = (
            ((hmac_result[offset] & 0x7F) << 24)
            | ((hmac_result[offset + 1] & 0xFF) << 16)
            | ((hmac_result[offset + 2] & 0xFF) << 8)
            | (hmac_result[offset + 3] & 0xFF)
        )

        # Generate TOTP code
        totp_code = str(truncated_hash % (10**configs.TOTP_LENGTH)).zfill(configs.TOTP_LENGTH)

        # Calculate expiration time
        expires_in = DatetimeUtils.get_datetime_after_given_datetime_or_now(seconds=configs.TOTP_EXPIRES_IN)

        return totp_code, expires_in

    @classmethod
    def verify_totp(cls, secret: str | UUID, totp_code: str, auth_config: AuthConfig | None = None) -> bool:
        """Verifies a TOTP code against the provided secret.

        Args:
            secret: The secret key used to generate the TOTP code.
            totp_code: The TOTP code to verify.
            auth_config: Optional auth configuration override. If not provided, uses the global config.

        Returns:
            `True` if the TOTP code is valid, `False` otherwise.

        Raises:
            InvalidArgumentError: If the secret is invalid or empty.
            InvalidTokenError: If the TOTP code format is invalid.
        """
        if not secret:
            raise InvalidArgumentError(
                argument_name="secret",
            )

        if not totp_code:
            raise InvalidArgumentError(
                argument_name="totp_code",
            )

        if not totp_code.isdigit():
            raise InvalidTokenError

        configs = auth_config or BaseConfig.global_config().AUTH

        current_time = DatetimeUtils.get_epoch_time_now()

        # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
        hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

        # Check codes within verification window
        for i in range(-configs.TOTP_VERIFICATION_WINDOW, configs.TOTP_VERIFICATION_WINDOW + 1):
            time_step_counter = int(current_time / configs.TOTP_TIME_STEP) + i

            secret_bytes = str(secret).encode("utf-8")
            time_bytes = struct.pack(">Q", time_step_counter)
            hmac_obj = hmac.new(secret_bytes, time_bytes, hash_algo)
            hmac_result = hmac_obj.digest()

            offset = hmac_result[-1] & 0xF
            truncated_hash = (
                ((hmac_result[offset] & 0x7F) << 24)
                | ((hmac_result[offset + 1] & 0xFF) << 16)
                | ((hmac_result[offset + 2] & 0xFF) << 8)
                | (hmac_result[offset + 3] & 0xFF)
            )

            computed_totp = str(truncated_hash % (10 ** len(totp_code))).zfill(len(totp_code))

            if hmac.compare_digest(totp_code, computed_totp):
                return True

        return False

    @staticmethod
    def generate_secret_key_for_totp(auth_config: AuthConfig | None = None) -> str:
        """Generates a random secret key for TOTP initialization.

        Args:
            auth_config: Optional auth configuration override. If not provided, uses the global config.

        Returns:
            A base32-encoded secret key for TOTP initialization.

        Raises:
            InvalidArgumentError: If the TOTP_SECRET_KEY is not configured.
            InternalError: If there is an error generating the secret key.
        """
        try:
            configs = auth_config or BaseConfig.global_config().AUTH

            # Use secrets module instead of random for better security
            random_bytes = secrets.token_bytes(configs.SALT_LENGTH)

            # Check if TOTP secret key is configured
            if not configs.TOTP_SECRET_KEY:
                # Disable linter for this specific case since we're already in a try-except block
                # and creating nested functions would reduce code readability
                raise InvalidArgumentError(
                    argument_name="TOTP_SECRET_KEY",
                )

            master_key = configs.TOTP_SECRET_KEY.get_secret_value().encode("utf-8")

            # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
            hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

            # Use HMAC with master key for additional security
            hmac_obj = hmac.new(master_key, random_bytes, hash_algo)
            return base64.b32encode(hmac_obj.digest()).decode("utf-8")
        except Exception as e:
            # Convert any errors to our custom errors
            raise InternalError() from e

archipy.helpers.utils.totp_utils.TOTPUtils.generate_totp classmethod 

generate_totp(
    secret: str | UUID,
    auth_config: AuthConfig | None = None,
) -> tuple[str, datetime]

Generates a TOTP code using the configured hash algorithm.

Parameters:

Name Type Description Default
secret str | UUID

The secret key used to generate the TOTP code.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
tuple[str, datetime]

A tuple containing the generated TOTP code and its expiration time.

Raises:

Type Description
InvalidArgumentError

If the secret is invalid or empty.
Source code in archipy/helpers/utils/totp_utils.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
@classmethod
def generate_totp(cls, secret: str | UUID, auth_config: AuthConfig | None = None) -> tuple[str, datetime]:
    """Generates a TOTP code using the configured hash algorithm.

    Args:
        secret: The secret key used to generate the TOTP code.
        auth_config: Optional auth configuration override. If not provided, uses the global config.

    Returns:
        A tuple containing the generated TOTP code and its expiration time.

    Raises:
        InvalidArgumentError: If the secret is invalid or empty.
    """
    if not secret:
        raise InvalidArgumentError(
            argument_name="secret",
        )

    configs = auth_config or BaseConfig.global_config().AUTH

    # Convert secret to bytes if it's UUID
    if isinstance(secret, UUID):
        secret = str(secret)

    # Get current timestamp and calculate time step
    current_time = DatetimeUtils.get_epoch_time_now()
    time_step_counter = int(current_time / configs.TOTP_TIME_STEP)

    # Generate HMAC hash
    secret_bytes = str(secret).encode("utf-8")
    time_bytes = struct.pack(">Q", time_step_counter)

    # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
    hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

    hmac_obj = hmac.new(secret_bytes, time_bytes, hash_algo)
    hmac_result = hmac_obj.digest()

    # Get offset and truncate
    offset = hmac_result[-1] & 0xF
    truncated_hash = (
        ((hmac_result[offset] & 0x7F) << 24)
        | ((hmac_result[offset + 1] & 0xFF) << 16)
        | ((hmac_result[offset + 2] & 0xFF) << 8)
        | (hmac_result[offset + 3] & 0xFF)
    )

    # Generate TOTP code
    totp_code = str(truncated_hash % (10**configs.TOTP_LENGTH)).zfill(configs.TOTP_LENGTH)

    # Calculate expiration time
    expires_in = DatetimeUtils.get_datetime_after_given_datetime_or_now(seconds=configs.TOTP_EXPIRES_IN)

    return totp_code, expires_in

archipy.helpers.utils.totp_utils.TOTPUtils.verify_totp classmethod 

verify_totp(
    secret: str | UUID,
    totp_code: str,
    auth_config: AuthConfig | None = None,
) -> bool

Verifies a TOTP code against the provided secret.

Parameters:

Name Type Description Default
secret str | UUID

The secret key used to generate the TOTP code.

 required
totp_code str

The TOTP code to verify.

 required
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
bool

True if the TOTP code is valid, False otherwise.

Raises:

Type Description
InvalidArgumentError

If the secret is invalid or empty.
InvalidTokenError

If the TOTP code format is invalid.
Source code in archipy/helpers/utils/totp_utils.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
@classmethod
def verify_totp(cls, secret: str | UUID, totp_code: str, auth_config: AuthConfig | None = None) -> bool:
    """Verifies a TOTP code against the provided secret.

    Args:
        secret: The secret key used to generate the TOTP code.
        totp_code: The TOTP code to verify.
        auth_config: Optional auth configuration override. If not provided, uses the global config.

    Returns:
        `True` if the TOTP code is valid, `False` otherwise.

    Raises:
        InvalidArgumentError: If the secret is invalid or empty.
        InvalidTokenError: If the TOTP code format is invalid.
    """
    if not secret:
        raise InvalidArgumentError(
            argument_name="secret",
        )

    if not totp_code:
        raise InvalidArgumentError(
            argument_name="totp_code",
        )

    if not totp_code.isdigit():
        raise InvalidTokenError

    configs = auth_config or BaseConfig.global_config().AUTH

    current_time = DatetimeUtils.get_epoch_time_now()

    # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
    hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

    # Check codes within verification window
    for i in range(-configs.TOTP_VERIFICATION_WINDOW, configs.TOTP_VERIFICATION_WINDOW + 1):
        time_step_counter = int(current_time / configs.TOTP_TIME_STEP) + i

        secret_bytes = str(secret).encode("utf-8")
        time_bytes = struct.pack(">Q", time_step_counter)
        hmac_obj = hmac.new(secret_bytes, time_bytes, hash_algo)
        hmac_result = hmac_obj.digest()

        offset = hmac_result[-1] & 0xF
        truncated_hash = (
            ((hmac_result[offset] & 0x7F) << 24)
            | ((hmac_result[offset + 1] & 0xFF) << 16)
            | ((hmac_result[offset + 2] & 0xFF) << 8)
            | (hmac_result[offset + 3] & 0xFF)
        )

        computed_totp = str(truncated_hash % (10 ** len(totp_code))).zfill(len(totp_code))

        if hmac.compare_digest(totp_code, computed_totp):
            return True

    return False

archipy.helpers.utils.totp_utils.TOTPUtils.generate_secret_key_for_totp staticmethod 

generate_secret_key_for_totp(
    auth_config: AuthConfig | None = None,
) -> str

Generates a random secret key for TOTP initialization.

Parameters:

Name Type Description Default
auth_config AuthConfig | None

Optional auth configuration override. If not provided, uses the global config.

 None

Returns:

Type Description
str

A base32-encoded secret key for TOTP initialization.

Raises:

Type Description
InvalidArgumentError

If the TOTP_SECRET_KEY is not configured.
InternalError

If there is an error generating the secret key.
Source code in archipy/helpers/utils/totp_utils.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
@staticmethod
def generate_secret_key_for_totp(auth_config: AuthConfig | None = None) -> str:
    """Generates a random secret key for TOTP initialization.

    Args:
        auth_config: Optional auth configuration override. If not provided, uses the global config.

    Returns:
        A base32-encoded secret key for TOTP initialization.

    Raises:
        InvalidArgumentError: If the TOTP_SECRET_KEY is not configured.
        InternalError: If there is an error generating the secret key.
    """
    try:
        configs = auth_config or BaseConfig.global_config().AUTH

        # Use secrets module instead of random for better security
        random_bytes = secrets.token_bytes(configs.SALT_LENGTH)

        # Check if TOTP secret key is configured
        if not configs.TOTP_SECRET_KEY:
            # Disable linter for this specific case since we're already in a try-except block
            # and creating nested functions would reduce code readability
            raise InvalidArgumentError(
                argument_name="TOTP_SECRET_KEY",
            )

        master_key = configs.TOTP_SECRET_KEY.get_secret_value().encode("utf-8")

        # Use the dedicated TOTP hash algorithm from config, with fallback to SHA1
        hash_algo = getattr(configs, "TOTP_HASH_ALGORITHM", "SHA1")

        # Use HMAC with master key for additional security
        hmac_obj = hmac.new(master_key, random_bytes, hash_algo)
        return base64.b32encode(hmac_obj.digest()).decode("utf-8")
    except Exception as e:
        # Convert any errors to our custom errors
        raise InternalError() from e

options: show_root_toc_entry: false heading_level: 3

Keycloak Utils

Utilities for Keycloak token acquisition, validation, user info retrieval, and role checking.

archipy.helpers.utils.keycloak_utils.GRPC_AVAILABLE module-attribute 

GRPC_AVAILABLE = True

archipy.helpers.utils.keycloak_utils.GrpcContextType module-attribute 

GrpcContextType = ServicerContext

archipy.helpers.utils.keycloak_utils.AsyncGrpcContextType module-attribute 

AsyncGrpcContextType = ServicerContext

archipy.helpers.utils.keycloak_utils.security module-attribute 

security = HTTPBearer(
    scheme_name="OAuth2",
    description="OAuth2 Access Token",
    auto_error=False,
)

archipy.helpers.utils.keycloak_utils.DEFAULT_LANG module-attribute 

DEFAULT_LANG = FA

archipy.helpers.utils.keycloak_utils.logger module-attribute 

logger = getLogger(__name__)

archipy.helpers.utils.keycloak_utils.AuthContext

Bases: BaseModel

Authentication context passed to business logic.

Source code in archipy/helpers/utils/keycloak_utils.py 
50
51
52
53
54
55
56
57
58
class AuthContext(BaseModel):
    """Authentication context passed to business logic."""

    user_id: str
    username: str
    email: str
    roles: list[str]
    token: str
    raw_user_info: dict[str, Any]

archipy.helpers.utils.keycloak_utils.AuthContext.user_id instance-attribute 

user_id: str

archipy.helpers.utils.keycloak_utils.AuthContext.username instance-attribute 

username: str

archipy.helpers.utils.keycloak_utils.AuthContext.email instance-attribute 

email: str

archipy.helpers.utils.keycloak_utils.AuthContext.roles instance-attribute 

roles: list[str]

archipy.helpers.utils.keycloak_utils.AuthContext.token instance-attribute 

token: str

archipy.helpers.utils.keycloak_utils.AuthContext.raw_user_info instance-attribute 

raw_user_info: dict[str, Any]

archipy.helpers.utils.keycloak_utils.AuthContextManager

Manager for handling auth context in gRPC services.

Source code in archipy/helpers/utils/keycloak_utils.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class AuthContextManager:
    """Manager for handling auth context in gRPC services."""

    @staticmethod
    def set_auth_context(auth_context: AuthContext) -> None:
        """Set the auth context for the current request."""
        _auth_context_var.set(auth_context)

    @staticmethod
    def get_auth_context() -> AuthContext | None:
        """Get the auth context for the current request."""
        return _auth_context_var.get()

    @staticmethod
    def clear_auth_context() -> None:
        """Clear the auth context for the current request."""
        _auth_context_var.set(None)

archipy.helpers.utils.keycloak_utils.AuthContextManager.set_auth_context staticmethod 

set_auth_context(auth_context: AuthContext) -> None

Set the auth context for the current request.

Source code in archipy/helpers/utils/keycloak_utils.py 
68
69
70
71
@staticmethod
def set_auth_context(auth_context: AuthContext) -> None:
    """Set the auth context for the current request."""
    _auth_context_var.set(auth_context)

archipy.helpers.utils.keycloak_utils.AuthContextManager.get_auth_context staticmethod 

get_auth_context() -> AuthContext | None

Get the auth context for the current request.

Source code in archipy/helpers/utils/keycloak_utils.py 
73
74
75
76
@staticmethod
def get_auth_context() -> AuthContext | None:
    """Get the auth context for the current request."""
    return _auth_context_var.get()

archipy.helpers.utils.keycloak_utils.AuthContextManager.clear_auth_context staticmethod 

clear_auth_context() -> None

Clear the auth context for the current request.

Source code in archipy/helpers/utils/keycloak_utils.py 
78
79
80
81
@staticmethod
def clear_auth_context() -> None:
    """Clear the auth context for the current request."""
    _auth_context_var.set(None)

archipy.helpers.utils.keycloak_utils.KeycloakUtils

Utility class for Keycloak authentication and authorization in FastAPI applications.

Source code in archipy/helpers/utils/keycloak_utils.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
class KeycloakUtils:
    """Utility class for Keycloak authentication and authorization in FastAPI applications."""

    @staticmethod
    def _get_keycloak_adapter() -> KeycloakAdapter:
        return KeycloakAdapter()

    @staticmethod
    def _get_async_keycloak_adapter() -> AsyncKeycloakAdapter:
        return AsyncKeycloakAdapter()

    @classmethod
    # Synchronous decorator
    def fastapi_auth(
        cls,
        resource_type_param: str | None = None,
        resource_type: str | None = None,
        required_roles: frozenset[str] | None = None,
        all_roles_required: bool = False,
        required_permissions: tuple[tuple[str, str], ...] | None = None,
        admin_roles: frozenset[str] | None = None,
        lang: LanguageType = DEFAULT_LANG,
    ) -> Callable:
        """FastAPI decorator for Keycloak authentication and resource-based authorization.

        Args:
            resource_type_param: The parameter name in the path (e.g., 'user_uuid', 'employee_uuid')
            resource_type: The type of resource being accessed (e.g., 'users', 'employees')
            required_roles: Set of role names that the user must have
            all_roles_required: If True, user must have all specified roles; if False, any role is sufficient
            required_permissions: List of (resource, scope) tuples to check
            admin_roles: Set of roles that grant administrative access to all resources
            lang: Language for error messages
        Raises:
            UnauthenticatedError: If no valid Authorization header is provided
            InvalidTokenError: If token is invalid
            TokenExpiredError: If token is expired
            PermissionDeniedError: If user lacks required roles, permissions, or resource access
            InvalidArgumentError: If resource_type_param is missing when resource_type is provided
        """

        def dependency(
            request: Request,
            token: HTTPAuthorizationCredentials = Security(security),
            keycloak: KeycloakAdapter = Depends(cls._get_keycloak_adapter),
        ) -> dict[str, Any]:
            if token is None:
                raise UnauthenticatedError(lang=lang)
            token_str = token.credentials  # Extract the token string
            # Validate token
            if not keycloak.validate_token(token_str):
                token_info = keycloak.introspect_token(token_str)
                if not token_info or not token_info.get("active", False):
                    raise TokenExpiredError(lang=lang)

            # Get user info from token
            user_info = keycloak.get_userinfo(token_str)
            if not user_info:
                raise UnauthenticatedError(lang=lang)

            token_info = keycloak.get_token_info(token_str)

            # Resource-based authorization if resource type is provided
            if resource_type and resource_type_param:
                # Extract resource UUID from path parameters
                resource_uuid = request.path_params.get(resource_type_param)
                if not resource_uuid:
                    raise InvalidArgumentError(argument_name=resource_type_param, lang=lang)

                # Verify resource exists and user has access
                user_uuid = user_info.get("sub")

                # Check if resource exists
                resource_user = keycloak.get_user_by_id(resource_uuid)
                if not resource_user:
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                    )

                # Authorization check: either owns the resource or has admin privileges
                has_admin_privileges = admin_roles and keycloak.has_any_of_roles(token_str, admin_roles)
                if user_uuid != resource_uuid and not has_admin_privileges:
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                    )

            # Check additional roles if specified
            if required_roles:
                if all_roles_required:
                    if not keycloak.has_all_roles(token_str, required_roles):
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"required_roles": required_roles},
                        )
                elif not keycloak.has_any_of_roles(token_str, required_roles):
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"required_roles": required_roles},
                    )

            # Check permissions if specified
            if required_permissions:
                for resource, scope in required_permissions:
                    if not keycloak.check_permissions(token_str, resource, scope):
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"required_permission": f"{resource}#{scope}"},
                        )

            # Add user info to request state
            request.state.user_info = user_info
            request.state.token_info = token_info
            return user_info

        return dependency

    @classmethod
    def async_fastapi_auth(
        cls,
        resource_type_param: str | None = None,
        resource_type: str | None = None,
        required_roles: frozenset[str] | None = None,
        all_roles_required: bool = False,
        required_permissions: tuple[tuple[str, str], ...] | None = None,
        admin_roles: frozenset[str] | None = None,
        lang: LanguageType = DEFAULT_LANG,
    ) -> Callable:
        """FastAPI async decorator for Keycloak authentication and resource-based authorization.

        Args:
            resource_type_param: The parameter name in the path (e.g., 'user_uuid', 'employee_uuid')
            resource_type: The type of resource being accessed (e.g., 'users', 'employees')
            required_roles: Set of role names that the user must have
            all_roles_required: If True, user must have all specified roles; if False, any role is sufficient
            required_permissions: List of (resource, scope) tuples to check
            admin_roles: Set of roles that grant administrative access to all resources
            lang: Language for error messages
        Raises:
            UnauthenticatedError: If no valid Authorization header is provided
            InvalidTokenError: If token is invalid
            TokenExpiredError: If token is expired
            PermissionDeniedError: If user lacks required roles, permissions, or resource access
            InvalidArgumentError: If resource_type_param is missing when resource_type is provided
        """

        async def dependency(
            request: Request,
            token: HTTPAuthorizationCredentials = Security(security),
            keycloak: AsyncKeycloakAdapter = Depends(cls._get_async_keycloak_adapter),
        ) -> dict[str, Any]:
            if token is None:
                raise UnauthenticatedError(lang=lang)
            token_str = token.credentials  # Extract the token string

            # Validate token
            if not await keycloak.validate_token(token_str):
                # Handle token validation error
                token_info = await keycloak.introspect_token(token_str)
                if not token_info or not token_info.get("active", False):
                    raise TokenExpiredError(lang=lang)

            # Get user info from token
            user_info = await keycloak.get_userinfo(token_str)
            if not user_info:
                raise UnauthenticatedError(lang=lang)

            token_info = await keycloak.get_token_info(token_str)

            # Resource-based authorization if resource type is provided
            if resource_type and resource_type_param:
                # Extract resource UUID from path parameters
                resource_uuid = request.path_params.get(resource_type_param)
                if not resource_uuid:
                    raise InvalidArgumentError(argument_name=resource_type_param, lang=lang)

                # Verify resource exists and user has access
                user_uuid = user_info.get("sub")

                # Check if resource exists
                resource_user = await keycloak.get_user_by_id(resource_uuid)
                if not resource_user:
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                    )

                # Authorization check: either owns the resource or has admin privileges
                has_admin_privileges = admin_roles and await keycloak.has_any_of_roles(token_str, admin_roles)
                if user_uuid != resource_uuid and not has_admin_privileges:
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                    )

            # Check additional roles if specified
            if required_roles:
                if all_roles_required:
                    if not await keycloak.has_all_roles(token_str, required_roles):
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"required_roles": required_roles},
                        )
                elif not await keycloak.has_any_of_roles(token_str, required_roles):
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"required_roles": required_roles},
                    )

            # Check permissions if specified
            if required_permissions:
                for resource, scope in required_permissions:
                    if not await keycloak.check_permissions(token_str, resource, scope):
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"required_permission": f"{resource}#{scope}"},
                        )

            # Add user info to request state
            request.state.user_info = user_info
            request.state.token_info = token_info
            if not user_info:
                raise UnauthenticatedError(lang=lang)
            return user_info

        return dependency

    @staticmethod
    def _extract_token_from_metadata(context: object) -> str | None:
        """Extract Bearer token from gRPC metadata."""
        if not hasattr(context, "invocation_metadata") or not callable(context.invocation_metadata):
            return None
        invocation_metadata_method = cast("Callable[[], Any]", context.invocation_metadata)
        invocation_metadata_result = invocation_metadata_method()
        if invocation_metadata_result is None:
            return None
        # Convert metadata tuples to dict, handling both str and bytes keys
        # invocation_metadata_result is an iterable of tuples at runtime
        metadata: dict[str, str] = {}
        try:
            for key, value in invocation_metadata_result:
                # Normalize key to string
                key_str = key.decode("utf-8") if isinstance(key, bytes) else str(key)
                # Normalize value to string
                value_str = value.decode("utf-8") if isinstance(value, bytes) else str(value)
                metadata[key_str] = value_str
        except TypeError, ValueError:
            # If iteration fails, return None
            return None

        auth_keys = ["authorization", "Authorization", "auth", "token"]

        for key in auth_keys:
            if key in metadata:
                auth_value = metadata[key]
                # Handle both bytes and string values
                if isinstance(auth_value, bytes):
                    auth_value_str = auth_value.decode("utf-8")
                else:
                    auth_value_str = str(auth_value)

                if auth_value_str.startswith(("Bearer ", "bearer ")):
                    return auth_value_str[7:]
                else:
                    return auth_value_str

        return None

    @classmethod
    def grpc_auth(
        cls,
        required_roles: frozenset[str] | None = None,
        all_roles_required: bool = False,
        required_permissions: tuple[tuple[str, str], ...] | None = None,
        resource_attribute_name: str | None = None,
        admin_roles: frozenset[str] | None = None,
        lang: LanguageType = DEFAULT_LANG,
    ) -> Callable[[Callable], Callable]:
        """Synchronous gRPC decorator for authentication and authorization.

        This decorator handles:
        1. Token validation
        2. Role/permission checking
        3. Passing auth context to business logic

        Resource ownership is handled in the business logic layer.

        Args:
            required_roles: Set of roles, user must have at least one (or all if all_roles_required=True)
            all_roles_required: If True, user must have all required_roles; if False, any one role is sufficient
            required_permissions: Tuple of (resource, scope) pairs that must be satisfied
            resource_attribute_name: Attribute name to extract resource UUID from context for ownership checking
            admin_roles: Set of admin roles that bypass resource ownership checks
            lang: Language for error messages

        Returns:
            Decorated function with authentication and authorization
        """

        def decorator(func: Callable) -> Callable:
            @functools.wraps(func)
            def wrapper(self: object, request: object, context: object) -> object:
                try:
                    # 1. Extract and validate token
                    token_str = cls._extract_token_from_metadata(context)
                    if not token_str:
                        raise UnauthenticatedError(lang=lang)

                    # 2. Get Keycloak adapter (synchronous)
                    keycloak: KeycloakAdapter = cls._get_keycloak_adapter()

                    # 3. Validate token
                    if not keycloak.validate_token(token_str):
                        token_info = keycloak.introspect_token(token_str)
                        if not token_info or not token_info.get("active", False):
                            raise TokenExpiredError(lang=lang)

                    # 4. Get user info from token
                    user_info = keycloak.get_userinfo(token_str)
                    if not user_info:
                        raise UnauthenticatedError(lang=lang)

                    # 5. Resource-based authorization if resource_attribute_name is provided
                    if resource_attribute_name:
                        # Extract resource UUID from context
                        resource_uuid = getattr(request, resource_attribute_name)
                        if not resource_uuid:
                            raise InvalidArgumentError(argument_name=resource_attribute_name, lang=lang)

                        # Verify resource exists and user has access
                        user_uuid = user_info.get("sub")

                        # Check if resource exists
                        resource_user = keycloak.get_user_by_id(resource_uuid)
                        if not resource_user:
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={"resource_id": resource_uuid},
                            )

                        # Authorization check: either owns the resource or has admin privileges
                        has_admin_privileges = admin_roles and keycloak.has_any_of_roles(token_str, admin_roles)
                        if user_uuid != resource_uuid and not has_admin_privileges:
                            raise PermissionDeniedError(lang=lang, additional_data={"resource_id": resource_uuid})

                    # 6. Check roles if specified
                    if required_roles:
                        if all_roles_required:
                            if not keycloak.has_all_roles(token_str, required_roles):
                                raise PermissionDeniedError(
                                    lang=lang,
                                    additional_data={
                                        "required_roles": list(required_roles),
                                        "check_type": "all_required",
                                    },
                                )

                        elif not keycloak.has_any_of_roles(token_str, required_roles):
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={"required_roles": list(required_roles), "check_type": "any_required"},
                            )

                    # 7. Check permissions if specified
                    if required_permissions:
                        for resource, scope in required_permissions:
                            if not keycloak.check_permissions(token_str, resource, scope):
                                raise PermissionDeniedError(
                                    lang=lang,
                                    additional_data={
                                        "required_permission": f"{resource}#{scope}",
                                        "resource": resource,
                                        "scope": scope,
                                    },
                                )

                    # 8. Create auth context for business logic
                    user_id = user_info.get("sub")
                    if not user_id:
                        raise UnauthenticatedError(lang=lang)
                    auth_context = AuthContext(
                        user_id=user_id,
                        username=user_info.get("preferred_username", ""),
                        email=user_info.get("email", ""),
                        roles=user_info.get("realm_access", {}).get("roles", []),
                        token=token_str,
                        raw_user_info=user_info,
                    )

                    # 9. Set auth context using contextvars
                    AuthContextManager.set_auth_context(auth_context)

                    # 10. Call the original method - business logic handles ownership
                    return func(self, request, context)

                except Exception as e:
                    if isinstance(e, BaseError) and hasattr(e, "abort_grpc_sync") and GRPC_AVAILABLE:
                        # Only call abort if context is actually a ServicerContext
                        if hasattr(context, "abort"):
                            e.abort_grpc_sync(context)  # type: ignore[arg-type]
                    raise InternalError(
                        lang=lang,
                        additional_data={"original_error": str(e), "error_type": type(e).__name__},
                    ) from e

                finally:
                    # Clean up auth context
                    AuthContextManager.clear_auth_context()

            return wrapper

        return decorator

    @classmethod
    def async_grpc_auth(
        cls,
        required_roles: frozenset[str] | None = None,
        all_roles_required: bool = False,
        required_permissions: tuple[tuple[str, str], ...] | None = None,
        resource_attribute_name: str | None = None,
        admin_roles: frozenset[str] | None = None,
        lang: LanguageType = DEFAULT_LANG,
    ) -> Callable[[Callable], Callable]:
        """Simplified gRPC decorator for authentication and authorization.

        This decorator handles:
        1. Token validation
        2. Role/permission checking
        3. Passing auth context to business logic

        Resource ownership is handled in the business logic layer.

        Args:
            required_roles: Set of roles, user must have at least one (or all if all_roles_required=True)
            all_roles_required: If True, user must have all required_roles; if False, any one role is sufficient
            required_permissions: Tuple of (resource, scope) pairs that must be satisfied
            resource_attribute_name: Attribute name to extract resource UUID from context for ownership checking
            admin_roles: Set of admin roles that bypass resource ownership checks
            lang: Language for error messages

        Returns:
            Decorated function with authentication and authorization
        """

        def decorator(func: Callable) -> Callable:
            @functools.wraps(func)
            async def wrapper(self: object, request: object, context: object) -> object:
                try:
                    # 1. Extract and validate token
                    token_str = cls._extract_token_from_metadata(context)
                    if not token_str:
                        raise UnauthenticatedError(lang=lang)

                    # 2. Get Keycloak adapter
                    keycloak: AsyncKeycloakAdapter = cls._get_async_keycloak_adapter()

                    # 3. Validate token
                    if not await keycloak.validate_token(token_str):
                        token_info = await keycloak.introspect_token(token_str)
                        if not token_info or not token_info.get("active", False):
                            raise TokenExpiredError(lang=lang)

                    # 4. Get user info from token
                    user_info = await keycloak.get_userinfo(token_str)
                    if not user_info:
                        raise UnauthenticatedError(lang=lang)

                    # 5. Resource-based authorization if resource_attribute_name is provided
                    if resource_attribute_name:
                        # Extract resource UUID from context
                        resource_uuid = getattr(request, resource_attribute_name)
                        if not resource_uuid:
                            raise InvalidArgumentError(argument_name=resource_attribute_name, lang=lang)

                        # Verify resource exists and user has access
                        user_uuid = user_info.get("sub")

                        # Check if resource exists
                        resource_user = await keycloak.get_user_by_id(resource_uuid)
                        if not resource_user:
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={"resource_id": resource_uuid},
                            )

                        # Authorization check: either owns the resource or has admin privileges
                        has_admin_privileges = admin_roles and await keycloak.has_any_of_roles(token_str, admin_roles)
                        if user_uuid != resource_uuid and not has_admin_privileges:
                            raise PermissionDeniedError(lang=lang, additional_data={"resource_id": resource_uuid})

                    # 6. Check roles if specified
                    if required_roles:
                        if all_roles_required:
                            if not await keycloak.has_all_roles(token_str, required_roles):
                                raise PermissionDeniedError(
                                    lang=lang,
                                    additional_data={
                                        "required_roles": list(required_roles),
                                        "check_type": "all_required",
                                    },
                                )

                        elif not await keycloak.has_any_of_roles(token_str, required_roles):
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={"required_roles": list(required_roles), "check_type": "any_required"},
                            )

                    # 7. Check permissions if specified
                    if required_permissions:
                        for resource, scope in required_permissions:
                            if not await keycloak.check_permissions(token_str, resource, scope):
                                raise PermissionDeniedError(
                                    lang=lang,
                                    additional_data={
                                        "required_permission": f"{resource}#{scope}",
                                        "resource": resource,
                                        "scope": scope,
                                    },
                                )

                    # 8. Create auth context for business logic
                    user_id = user_info.get("sub")
                    if not user_id:
                        raise UnauthenticatedError(lang=lang)
                    auth_context = AuthContext(
                        user_id=user_id,
                        username=user_info.get("preferred_username", ""),
                        email=user_info.get("email", ""),
                        roles=user_info.get("realm_access", {}).get("roles", []),
                        token=token_str,
                        raw_user_info=user_info,
                    )

                    # 9. Set auth context using contextvars
                    AuthContextManager.set_auth_context(auth_context)

                    # 10. Call the original method - business logic handles ownership
                    return await func(self, request, context)

                except Exception as e:
                    if context is None:
                        raise
                    if isinstance(e, BaseError) and GRPC_AVAILABLE:
                        if isinstance(context, AsyncServicerContext):
                            await e.abort_grpc_async(context)  # type: ignore[arg-type]
                            return None  # abort_grpc_async will terminate, but satisfy type checker
                    if GRPC_AVAILABLE and isinstance(context, AsyncServicerContext):
                        # False positive: isinstance narrows type at runtime
                        error_instance = InternalError(
                            lang=lang,
                            additional_data={"original_error": str(e), "error_type": type(e).__name__},
                        )
                        await error_instance.abort_grpc_async(context)  # type: ignore[arg-type]
                        return None  # abort_grpc_async will terminate, but satisfy type checker
                    raise

                finally:
                    # Clean up auth context
                    AuthContextManager.clear_auth_context()

            return wrapper

        return decorator

archipy.helpers.utils.keycloak_utils.KeycloakUtils.fastapi_auth classmethod 

fastapi_auth(
    resource_type_param: str | None = None,
    resource_type: str | None = None,
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...]
    | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable

FastAPI decorator for Keycloak authentication and resource-based authorization.

Parameters:

Name Type Description Default
resource_type_param str | None

The parameter name in the path (e.g., 'user_uuid', 'employee_uuid')

 None
resource_type str | None

The type of resource being accessed (e.g., 'users', 'employees')

 None
required_roles frozenset[str] | None

Set of role names that the user must have

 None
all_roles_required bool

If True, user must have all specified roles; if False, any role is sufficient

 False
required_permissions tuple[tuple[str, str], ...] | None

List of (resource, scope) tuples to check

 None
admin_roles frozenset[str] | None

Set of roles that grant administrative access to all resources

 None
lang LanguageType

Language for error messages

 DEFAULT_LANG

Raises: UnauthenticatedError: If no valid Authorization header is provided InvalidTokenError: If token is invalid TokenExpiredError: If token is expired PermissionDeniedError: If user lacks required roles, permissions, or resource access InvalidArgumentError: If resource_type_param is missing when resource_type is provided

Source code in archipy/helpers/utils/keycloak_utils.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
@classmethod
# Synchronous decorator
def fastapi_auth(
    cls,
    resource_type_param: str | None = None,
    resource_type: str | None = None,
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...] | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable:
    """FastAPI decorator for Keycloak authentication and resource-based authorization.

    Args:
        resource_type_param: The parameter name in the path (e.g., 'user_uuid', 'employee_uuid')
        resource_type: The type of resource being accessed (e.g., 'users', 'employees')
        required_roles: Set of role names that the user must have
        all_roles_required: If True, user must have all specified roles; if False, any role is sufficient
        required_permissions: List of (resource, scope) tuples to check
        admin_roles: Set of roles that grant administrative access to all resources
        lang: Language for error messages
    Raises:
        UnauthenticatedError: If no valid Authorization header is provided
        InvalidTokenError: If token is invalid
        TokenExpiredError: If token is expired
        PermissionDeniedError: If user lacks required roles, permissions, or resource access
        InvalidArgumentError: If resource_type_param is missing when resource_type is provided
    """

    def dependency(
        request: Request,
        token: HTTPAuthorizationCredentials = Security(security),
        keycloak: KeycloakAdapter = Depends(cls._get_keycloak_adapter),
    ) -> dict[str, Any]:
        if token is None:
            raise UnauthenticatedError(lang=lang)
        token_str = token.credentials  # Extract the token string
        # Validate token
        if not keycloak.validate_token(token_str):
            token_info = keycloak.introspect_token(token_str)
            if not token_info or not token_info.get("active", False):
                raise TokenExpiredError(lang=lang)

        # Get user info from token
        user_info = keycloak.get_userinfo(token_str)
        if not user_info:
            raise UnauthenticatedError(lang=lang)

        token_info = keycloak.get_token_info(token_str)

        # Resource-based authorization if resource type is provided
        if resource_type and resource_type_param:
            # Extract resource UUID from path parameters
            resource_uuid = request.path_params.get(resource_type_param)
            if not resource_uuid:
                raise InvalidArgumentError(argument_name=resource_type_param, lang=lang)

            # Verify resource exists and user has access
            user_uuid = user_info.get("sub")

            # Check if resource exists
            resource_user = keycloak.get_user_by_id(resource_uuid)
            if not resource_user:
                raise PermissionDeniedError(
                    lang=lang,
                    additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                )

            # Authorization check: either owns the resource or has admin privileges
            has_admin_privileges = admin_roles and keycloak.has_any_of_roles(token_str, admin_roles)
            if user_uuid != resource_uuid and not has_admin_privileges:
                raise PermissionDeniedError(
                    lang=lang,
                    additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                )

        # Check additional roles if specified
        if required_roles:
            if all_roles_required:
                if not keycloak.has_all_roles(token_str, required_roles):
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"required_roles": required_roles},
                    )
            elif not keycloak.has_any_of_roles(token_str, required_roles):
                raise PermissionDeniedError(
                    lang=lang,
                    additional_data={"required_roles": required_roles},
                )

        # Check permissions if specified
        if required_permissions:
            for resource, scope in required_permissions:
                if not keycloak.check_permissions(token_str, resource, scope):
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"required_permission": f"{resource}#{scope}"},
                    )

        # Add user info to request state
        request.state.user_info = user_info
        request.state.token_info = token_info
        return user_info

    return dependency

archipy.helpers.utils.keycloak_utils.KeycloakUtils.async_fastapi_auth classmethod 

async_fastapi_auth(
    resource_type_param: str | None = None,
    resource_type: str | None = None,
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...]
    | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable

FastAPI async decorator for Keycloak authentication and resource-based authorization.

Parameters:

Name Type Description Default
resource_type_param str | None

The parameter name in the path (e.g., 'user_uuid', 'employee_uuid')

 None
resource_type str | None

The type of resource being accessed (e.g., 'users', 'employees')

 None
required_roles frozenset[str] | None

Set of role names that the user must have

 None
all_roles_required bool

If True, user must have all specified roles; if False, any role is sufficient

 False
required_permissions tuple[tuple[str, str], ...] | None

List of (resource, scope) tuples to check

 None
admin_roles frozenset[str] | None

Set of roles that grant administrative access to all resources

 None
lang LanguageType

Language for error messages

 DEFAULT_LANG

Raises: UnauthenticatedError: If no valid Authorization header is provided InvalidTokenError: If token is invalid TokenExpiredError: If token is expired PermissionDeniedError: If user lacks required roles, permissions, or resource access InvalidArgumentError: If resource_type_param is missing when resource_type is provided

Source code in archipy/helpers/utils/keycloak_utils.py 
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
@classmethod
def async_fastapi_auth(
    cls,
    resource_type_param: str | None = None,
    resource_type: str | None = None,
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...] | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable:
    """FastAPI async decorator for Keycloak authentication and resource-based authorization.

    Args:
        resource_type_param: The parameter name in the path (e.g., 'user_uuid', 'employee_uuid')
        resource_type: The type of resource being accessed (e.g., 'users', 'employees')
        required_roles: Set of role names that the user must have
        all_roles_required: If True, user must have all specified roles; if False, any role is sufficient
        required_permissions: List of (resource, scope) tuples to check
        admin_roles: Set of roles that grant administrative access to all resources
        lang: Language for error messages
    Raises:
        UnauthenticatedError: If no valid Authorization header is provided
        InvalidTokenError: If token is invalid
        TokenExpiredError: If token is expired
        PermissionDeniedError: If user lacks required roles, permissions, or resource access
        InvalidArgumentError: If resource_type_param is missing when resource_type is provided
    """

    async def dependency(
        request: Request,
        token: HTTPAuthorizationCredentials = Security(security),
        keycloak: AsyncKeycloakAdapter = Depends(cls._get_async_keycloak_adapter),
    ) -> dict[str, Any]:
        if token is None:
            raise UnauthenticatedError(lang=lang)
        token_str = token.credentials  # Extract the token string

        # Validate token
        if not await keycloak.validate_token(token_str):
            # Handle token validation error
            token_info = await keycloak.introspect_token(token_str)
            if not token_info or not token_info.get("active", False):
                raise TokenExpiredError(lang=lang)

        # Get user info from token
        user_info = await keycloak.get_userinfo(token_str)
        if not user_info:
            raise UnauthenticatedError(lang=lang)

        token_info = await keycloak.get_token_info(token_str)

        # Resource-based authorization if resource type is provided
        if resource_type and resource_type_param:
            # Extract resource UUID from path parameters
            resource_uuid = request.path_params.get(resource_type_param)
            if not resource_uuid:
                raise InvalidArgumentError(argument_name=resource_type_param, lang=lang)

            # Verify resource exists and user has access
            user_uuid = user_info.get("sub")

            # Check if resource exists
            resource_user = await keycloak.get_user_by_id(resource_uuid)
            if not resource_user:
                raise PermissionDeniedError(
                    lang=lang,
                    additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                )

            # Authorization check: either owns the resource or has admin privileges
            has_admin_privileges = admin_roles and await keycloak.has_any_of_roles(token_str, admin_roles)
            if user_uuid != resource_uuid and not has_admin_privileges:
                raise PermissionDeniedError(
                    lang=lang,
                    additional_data={"resource_type": resource_type, "resource_id": resource_uuid},
                )

        # Check additional roles if specified
        if required_roles:
            if all_roles_required:
                if not await keycloak.has_all_roles(token_str, required_roles):
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"required_roles": required_roles},
                    )
            elif not await keycloak.has_any_of_roles(token_str, required_roles):
                raise PermissionDeniedError(
                    lang=lang,
                    additional_data={"required_roles": required_roles},
                )

        # Check permissions if specified
        if required_permissions:
            for resource, scope in required_permissions:
                if not await keycloak.check_permissions(token_str, resource, scope):
                    raise PermissionDeniedError(
                        lang=lang,
                        additional_data={"required_permission": f"{resource}#{scope}"},
                    )

        # Add user info to request state
        request.state.user_info = user_info
        request.state.token_info = token_info
        if not user_info:
            raise UnauthenticatedError(lang=lang)
        return user_info

    return dependency

archipy.helpers.utils.keycloak_utils.KeycloakUtils.grpc_auth classmethod 

grpc_auth(
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...]
    | None = None,
    resource_attribute_name: str | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable[[Callable], Callable]

Synchronous gRPC decorator for authentication and authorization.

This decorator handles: 1. Token validation 2. Role/permission checking 3. Passing auth context to business logic

Resource ownership is handled in the business logic layer.

Parameters:

Name Type Description Default
required_roles frozenset[str] | None

Set of roles, user must have at least one (or all if all_roles_required=True)

 None
all_roles_required bool

If True, user must have all required_roles; if False, any one role is sufficient

 False
required_permissions tuple[tuple[str, str], ...] | None

Tuple of (resource, scope) pairs that must be satisfied

 None
resource_attribute_name str | None

Attribute name to extract resource UUID from context for ownership checking

 None
admin_roles frozenset[str] | None

Set of admin roles that bypass resource ownership checks

 None
lang LanguageType

Language for error messages

 DEFAULT_LANG

Returns:

Type Description
Callable[[Callable], Callable]

Decorated function with authentication and authorization
Source code in archipy/helpers/utils/keycloak_utils.py 
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
@classmethod
def grpc_auth(
    cls,
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...] | None = None,
    resource_attribute_name: str | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable[[Callable], Callable]:
    """Synchronous gRPC decorator for authentication and authorization.

    This decorator handles:
    1. Token validation
    2. Role/permission checking
    3. Passing auth context to business logic

    Resource ownership is handled in the business logic layer.

    Args:
        required_roles: Set of roles, user must have at least one (or all if all_roles_required=True)
        all_roles_required: If True, user must have all required_roles; if False, any one role is sufficient
        required_permissions: Tuple of (resource, scope) pairs that must be satisfied
        resource_attribute_name: Attribute name to extract resource UUID from context for ownership checking
        admin_roles: Set of admin roles that bypass resource ownership checks
        lang: Language for error messages

    Returns:
        Decorated function with authentication and authorization
    """

    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        def wrapper(self: object, request: object, context: object) -> object:
            try:
                # 1. Extract and validate token
                token_str = cls._extract_token_from_metadata(context)
                if not token_str:
                    raise UnauthenticatedError(lang=lang)

                # 2. Get Keycloak adapter (synchronous)
                keycloak: KeycloakAdapter = cls._get_keycloak_adapter()

                # 3. Validate token
                if not keycloak.validate_token(token_str):
                    token_info = keycloak.introspect_token(token_str)
                    if not token_info or not token_info.get("active", False):
                        raise TokenExpiredError(lang=lang)

                # 4. Get user info from token
                user_info = keycloak.get_userinfo(token_str)
                if not user_info:
                    raise UnauthenticatedError(lang=lang)

                # 5. Resource-based authorization if resource_attribute_name is provided
                if resource_attribute_name:
                    # Extract resource UUID from context
                    resource_uuid = getattr(request, resource_attribute_name)
                    if not resource_uuid:
                        raise InvalidArgumentError(argument_name=resource_attribute_name, lang=lang)

                    # Verify resource exists and user has access
                    user_uuid = user_info.get("sub")

                    # Check if resource exists
                    resource_user = keycloak.get_user_by_id(resource_uuid)
                    if not resource_user:
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"resource_id": resource_uuid},
                        )

                    # Authorization check: either owns the resource or has admin privileges
                    has_admin_privileges = admin_roles and keycloak.has_any_of_roles(token_str, admin_roles)
                    if user_uuid != resource_uuid and not has_admin_privileges:
                        raise PermissionDeniedError(lang=lang, additional_data={"resource_id": resource_uuid})

                # 6. Check roles if specified
                if required_roles:
                    if all_roles_required:
                        if not keycloak.has_all_roles(token_str, required_roles):
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={
                                    "required_roles": list(required_roles),
                                    "check_type": "all_required",
                                },
                            )

                    elif not keycloak.has_any_of_roles(token_str, required_roles):
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"required_roles": list(required_roles), "check_type": "any_required"},
                        )

                # 7. Check permissions if specified
                if required_permissions:
                    for resource, scope in required_permissions:
                        if not keycloak.check_permissions(token_str, resource, scope):
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={
                                    "required_permission": f"{resource}#{scope}",
                                    "resource": resource,
                                    "scope": scope,
                                },
                            )

                # 8. Create auth context for business logic
                user_id = user_info.get("sub")
                if not user_id:
                    raise UnauthenticatedError(lang=lang)
                auth_context = AuthContext(
                    user_id=user_id,
                    username=user_info.get("preferred_username", ""),
                    email=user_info.get("email", ""),
                    roles=user_info.get("realm_access", {}).get("roles", []),
                    token=token_str,
                    raw_user_info=user_info,
                )

                # 9. Set auth context using contextvars
                AuthContextManager.set_auth_context(auth_context)

                # 10. Call the original method - business logic handles ownership
                return func(self, request, context)

            except Exception as e:
                if isinstance(e, BaseError) and hasattr(e, "abort_grpc_sync") and GRPC_AVAILABLE:
                    # Only call abort if context is actually a ServicerContext
                    if hasattr(context, "abort"):
                        e.abort_grpc_sync(context)  # type: ignore[arg-type]
                raise InternalError(
                    lang=lang,
                    additional_data={"original_error": str(e), "error_type": type(e).__name__},
                ) from e

            finally:
                # Clean up auth context
                AuthContextManager.clear_auth_context()

        return wrapper

    return decorator

archipy.helpers.utils.keycloak_utils.KeycloakUtils.async_grpc_auth classmethod 

async_grpc_auth(
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...]
    | None = None,
    resource_attribute_name: str | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable[[Callable], Callable]

Simplified gRPC decorator for authentication and authorization.

This decorator handles: 1. Token validation 2. Role/permission checking 3. Passing auth context to business logic

Resource ownership is handled in the business logic layer.

Parameters:

Name Type Description Default
required_roles frozenset[str] | None

Set of roles, user must have at least one (or all if all_roles_required=True)

 None
all_roles_required bool

If True, user must have all required_roles; if False, any one role is sufficient

 False
required_permissions tuple[tuple[str, str], ...] | None

Tuple of (resource, scope) pairs that must be satisfied

 None
resource_attribute_name str | None

Attribute name to extract resource UUID from context for ownership checking

 None
admin_roles frozenset[str] | None

Set of admin roles that bypass resource ownership checks

 None
lang LanguageType

Language for error messages

 DEFAULT_LANG

Returns:

Type Description
Callable[[Callable], Callable]

Decorated function with authentication and authorization
Source code in archipy/helpers/utils/keycloak_utils.py 
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
@classmethod
def async_grpc_auth(
    cls,
    required_roles: frozenset[str] | None = None,
    all_roles_required: bool = False,
    required_permissions: tuple[tuple[str, str], ...] | None = None,
    resource_attribute_name: str | None = None,
    admin_roles: frozenset[str] | None = None,
    lang: LanguageType = DEFAULT_LANG,
) -> Callable[[Callable], Callable]:
    """Simplified gRPC decorator for authentication and authorization.

    This decorator handles:
    1. Token validation
    2. Role/permission checking
    3. Passing auth context to business logic

    Resource ownership is handled in the business logic layer.

    Args:
        required_roles: Set of roles, user must have at least one (or all if all_roles_required=True)
        all_roles_required: If True, user must have all required_roles; if False, any one role is sufficient
        required_permissions: Tuple of (resource, scope) pairs that must be satisfied
        resource_attribute_name: Attribute name to extract resource UUID from context for ownership checking
        admin_roles: Set of admin roles that bypass resource ownership checks
        lang: Language for error messages

    Returns:
        Decorated function with authentication and authorization
    """

    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        async def wrapper(self: object, request: object, context: object) -> object:
            try:
                # 1. Extract and validate token
                token_str = cls._extract_token_from_metadata(context)
                if not token_str:
                    raise UnauthenticatedError(lang=lang)

                # 2. Get Keycloak adapter
                keycloak: AsyncKeycloakAdapter = cls._get_async_keycloak_adapter()

                # 3. Validate token
                if not await keycloak.validate_token(token_str):
                    token_info = await keycloak.introspect_token(token_str)
                    if not token_info or not token_info.get("active", False):
                        raise TokenExpiredError(lang=lang)

                # 4. Get user info from token
                user_info = await keycloak.get_userinfo(token_str)
                if not user_info:
                    raise UnauthenticatedError(lang=lang)

                # 5. Resource-based authorization if resource_attribute_name is provided
                if resource_attribute_name:
                    # Extract resource UUID from context
                    resource_uuid = getattr(request, resource_attribute_name)
                    if not resource_uuid:
                        raise InvalidArgumentError(argument_name=resource_attribute_name, lang=lang)

                    # Verify resource exists and user has access
                    user_uuid = user_info.get("sub")

                    # Check if resource exists
                    resource_user = await keycloak.get_user_by_id(resource_uuid)
                    if not resource_user:
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"resource_id": resource_uuid},
                        )

                    # Authorization check: either owns the resource or has admin privileges
                    has_admin_privileges = admin_roles and await keycloak.has_any_of_roles(token_str, admin_roles)
                    if user_uuid != resource_uuid and not has_admin_privileges:
                        raise PermissionDeniedError(lang=lang, additional_data={"resource_id": resource_uuid})

                # 6. Check roles if specified
                if required_roles:
                    if all_roles_required:
                        if not await keycloak.has_all_roles(token_str, required_roles):
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={
                                    "required_roles": list(required_roles),
                                    "check_type": "all_required",
                                },
                            )

                    elif not await keycloak.has_any_of_roles(token_str, required_roles):
                        raise PermissionDeniedError(
                            lang=lang,
                            additional_data={"required_roles": list(required_roles), "check_type": "any_required"},
                        )

                # 7. Check permissions if specified
                if required_permissions:
                    for resource, scope in required_permissions:
                        if not await keycloak.check_permissions(token_str, resource, scope):
                            raise PermissionDeniedError(
                                lang=lang,
                                additional_data={
                                    "required_permission": f"{resource}#{scope}",
                                    "resource": resource,
                                    "scope": scope,
                                },
                            )

                # 8. Create auth context for business logic
                user_id = user_info.get("sub")
                if not user_id:
                    raise UnauthenticatedError(lang=lang)
                auth_context = AuthContext(
                    user_id=user_id,
                    username=user_info.get("preferred_username", ""),
                    email=user_info.get("email", ""),
                    roles=user_info.get("realm_access", {}).get("roles", []),
                    token=token_str,
                    raw_user_info=user_info,
                )

                # 9. Set auth context using contextvars
                AuthContextManager.set_auth_context(auth_context)

                # 10. Call the original method - business logic handles ownership
                return await func(self, request, context)

            except Exception as e:
                if context is None:
                    raise
                if isinstance(e, BaseError) and GRPC_AVAILABLE:
                    if isinstance(context, AsyncServicerContext):
                        await e.abort_grpc_async(context)  # type: ignore[arg-type]
                        return None  # abort_grpc_async will terminate, but satisfy type checker
                if GRPC_AVAILABLE and isinstance(context, AsyncServicerContext):
                    # False positive: isinstance narrows type at runtime
                    error_instance = InternalError(
                        lang=lang,
                        additional_data={"original_error": str(e), "error_type": type(e).__name__},
                    )
                    await error_instance.abort_grpc_async(context)  # type: ignore[arg-type]
                    return None  # abort_grpc_async will terminate, but satisfy type checker
                raise

            finally:
                # Clean up auth context
                AuthContextManager.clear_auth_context()

        return wrapper

    return decorator

options: show_root_toc_entry: false heading_level: 3

Prometheus Utils

Utilities for registering and exposing Prometheus metrics within ArchiPy applications.

Prometheus utilities for managing Prometheus HTTP server and metrics.

This module provides utilities for Prometheus metrics server management that can be shared across FastAPI, gRPC, and Temporal adapters.

archipy.helpers.utils.prometheus_utils.logger module-attribute 

logger = getLogger(__name__)

archipy.helpers.utils.prometheus_utils.is_prometheus_server_running 

is_prometheus_server_running(port: int) -> bool

Check if Prometheus server is already running on the specified port.

Parameters:

Name Type Description Default
port int

The port number to check.

 required

Returns:

Name Type Description
bool bool

True if server is running, False otherwise.
Example 
from archipy.helpers.utils.prometheus_utils import is_prometheus_server_running

if not is_prometheus_server_running(8200):
    from prometheus_client import start_http_server

    start_http_server(8200)
Source code in archipy/helpers/utils/prometheus_utils.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
def is_prometheus_server_running(port: int) -> bool:
    """Check if Prometheus server is already running on the specified port.

    Args:
        port (int): The port number to check.

    Returns:
        bool: True if server is running, False otherwise.

    Example:
        ```python
        from archipy.helpers.utils.prometheus_utils import is_prometheus_server_running

        if not is_prometheus_server_running(8200):
            from prometheus_client import start_http_server

            start_http_server(8200)
        ```
    """
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    result = sock.connect_ex(("localhost", port))
    sock.close()
    return result == 0

archipy.helpers.utils.prometheus_utils.start_prometheus_server_if_needed 

start_prometheus_server_if_needed(port: int) -> None

Start Prometheus HTTP server if not already running on the specified port.

Parameters:

Name Type Description Default
port int

The port number for the Prometheus metrics endpoint.

 required
Example 
from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

# This will start the server only if it's not already running
start_prometheus_server_if_needed(8200)
Source code in archipy/helpers/utils/prometheus_utils.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def start_prometheus_server_if_needed(port: int) -> None:
    """Start Prometheus HTTP server if not already running on the specified port.

    Args:
        port (int): The port number for the Prometheus metrics endpoint.

    Example:
        ```python
        from archipy.helpers.utils.prometheus_utils import start_prometheus_server_if_needed

        # This will start the server only if it's not already running
        start_prometheus_server_if_needed(8200)
        ```
    """
    if not is_prometheus_server_running(port):
        try:
            start_http_server(port)
            logger.info(f"Started Prometheus HTTP server on port {port}")
        except Exception as error:
            logger.exception(
                "Failed to start Prometheus HTTP server",
                extra={
                    "port": port,
                    "error": str(error),
                },
            )
            raise
    else:
        logger.debug(f"Prometheus HTTP server already running on port {port}")

options: show_root_toc_entry: false heading_level: 3