Skip to content

operations

Utility functions for generating a UUID.

Can generate a UUID as a uuid.UUID, str, or hex (UUID without '-' characters).

Allows trimming a number of characters from the end of a UUID string, as well as returning the first n number of characters.

Note

A UUID string is 36 characters (32 characters as hex).

first_n_chars(first_n=36, in_uuid=uuid.uuid4(), as_hex=False)

Return first n characters of UUID string (where n is first_n).

Parameters:

Name Type Description Default
first_n int

trim (int): Number of characters to remove from beginning of UUID string.

 36
in_uuid str

in_uuid (str): An existing UUID str to be trimmed/converted to hex.

 uuid4()
as_hex bool

as_hex (bool): If True, returns a UUID hex (UUID str without the - characters).

 False

Returns

(str): A 36 character UUID string
(str): A 32 character UUID hex string (a UUID minus the `-` characters)

Raises:

Type Description
ValueError

If input first_n is an invalid number of characters to return, less than 0 or greater than predefined max value (32 for hex, 36 for standard).
Source code in src/red_utils/std/uuid_utils/operations.py 
 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
def first_n_chars(first_n: int = 36, in_uuid: str = uuid.uuid4(), as_hex: bool = False):
    """Return first n characters of UUID string (where n is first_n).

    Params:
        first_n (int): trim (int): Number of characters to remove from beginning of UUID string.
        in_uuid (str): in_uuid (str): An existing UUID `str` to be trimmed/converted to hex.
        as_hex (bool): as_hex (bool): If `True`, returns a UUID hex (UUID `str` without the `-` characters).

    Returns
    -------
        (str): A 36 character UUID string
        (str): A 32 character UUID hex string (a UUID minus the `-` characters)

    Raises:
        ValueError: If input `first_n` is an invalid number of characters to return, less than 0 or greater than predefined max value (32 for hex, 36 for standard).

    """
    if not isinstance(first_n, int):
        first_n = int(first_n)

    if as_hex:
        _max = glob_uuid_lens.hex - 1
    else:
        _max = glob_uuid_lens.standard - 1

    if first_n < 0 or first_n > _max:
        raise ValueError(
            f"Invalid number of UUID characters requested: {first_n}. Must be greater than 0 and less than or equal to {_max}."
        )

    ## Return first n characters from beginning of string
    _uuid: str = str(in_uuid)[0:first_n]

    return _uuid

gen_uuid(as_hex=False)

Return a UUID.

Nested function to simply return a UUID object.

Parameters:

Name Type Description Default
as_hex bool

If True, returns a UUID hex (a UUID without the '-' characters, which is 32 characters instead of 36).

 False

Returns

(str): A 36 character UUID string
(str): A 32 character UUID hex string (a UUID minus the `-` characters)
Source code in src/red_utils/std/uuid_utils/operations.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def gen_uuid(as_hex: bool = False) -> Union[str, uuid.UUID]:
    """Return a UUID.

    Nested function to simply return a UUID object.

    Params:
        as_hex (bool): If True, returns a UUID hex (a UUID without the '-' characters, which is 32 characters instead of 36).

    Returns
    -------
        (str): A 36 character UUID string
        (str): A 32 character UUID hex string (a UUID minus the `-` characters)

    """
    if as_hex:
        hex_uuid = uuid.uuid4().hex

        ## Returns a str
        return hex_uuid

    _uuid: uuid.UUID = uuid.uuid4()

    ## Returns a UUID
    return _uuid

get_rand_uuid(trim=0, characters=0, as_str=True, as_hex=False)

Return a UUID.

Parameters:

Name Type Description Default
trim int

Remove n characters from end of string.

 0
characters(int)

Return first n characters from beginning of string.

 required
as_str bool
True
as_hex bool

Return UUID as a hexadecimal (32 chars, UUID without - characters).

 False

Returns

(str): A 36 character UUID string
(str): A 32 character UUID hex string (a UUID minus the `-` characters)

Raises:

Type Description
ValueError

If inputs trim or characters are invalid. TODO: Add TypeErrors too
Source code in src/red_utils/std/uuid_utils/operations.py 
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
def get_rand_uuid(
    trim: int = 0, characters: int = 0, as_str: bool = True, as_hex: bool = False
) -> Union[str, uuid.UUID]:
    """Return a UUID.

    Params:
        trim (int): Remove `n` characters from end of string.
        characters(int): Return first `n` characters from beginning of string.
        as_str (bool):
        as_hex (bool): Return UUID as a hexadecimal (32 chars, UUID without `-` characters).

    Returns
    -------
        (str): A 36 character UUID string
        (str): A 32 character UUID hex string (a UUID minus the `-` characters)

    Raises:
        ValueError: If inputs `trim` or `characters` are invalid. TODO: Add `TypeErrors` too

    """
    if isinstance(trim, int) and isinstance(characters, int):
        if trim > 0 and characters > 0:
            raise ValueError(
                "Cannot pass both a trim value and a characters value, please use one or the other."
            )
    elif not isinstance(trim, int) and isinstance(characters, int):
        raise ValueError("Trim value must be an int")
    elif isinstance(trim, int) and not isinstance(characters, int):
        raise ValueError("Characters value must be an int")
    else:
        raise ValueError("Trim and Characters values must be int")

    ## Generate a UUID. Returns a 36 char string, or 32 char if as_hex is set
    _uuid: uuid.UUID = gen_uuid(as_hex=as_hex)

    # if as_hex:
    trim = validate_trim(trim_in=trim, as_hex=as_hex)

    if characters > 0:
        characters = validate_characters(characters_in=characters, as_hex=as_hex)

    if trim:
        _uuid: str = trim_uuid(trim=trim, in_uuid=_uuid, as_hex=as_hex)

    if characters:
        _uuid: str = first_n_chars(first_n=characters, in_uuid=_uuid, as_hex=as_hex)

    ## If as_str was passed, convert UUID to string
    if as_str:
        _uuid: str = str(_uuid)

    return _uuid

trim_uuid(trim=0, in_uuid=uuid.uuid4(), as_hex=False)

Trim UUID string, removing n characters from end of string (where n is value of trim).

Parameters:

Name Type Description Default
trim int

Number of characters to remove from end of UUID string.

 0
in_uuid str

An existing UUID str to be trimmed/converted to hex.

 uuid4()
as_hex bool

If True, returns a UUID hex (UUID str without the - characters).

 False

Returns

(str): A 36 character UUID string
(str): A 32 character UUID hex string (a UUID minus the `-` characters)
Source code in src/red_utils/std/uuid_utils/operations.py 
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
def trim_uuid(trim: int = 0, in_uuid: str = uuid.uuid4(), as_hex: bool = False) -> str:
    """Trim UUID string, removing n characters from end of string (where n is value of trim).

    Params:
        trim (int): Number of characters to remove from end of UUID string.
        in_uuid (str): An existing UUID `str` to be trimmed/converted to hex.
        as_hex (bool): If `True`, returns a UUID hex (UUID `str` without the `-` characters).

    Returns
    -------
        (str): A 36 character UUID string
        (str): A 32 character UUID hex string (a UUID minus the `-` characters)

    """
    ## Set max character count
    ## Attempt to convert inputs value to integer
    if not isinstance(trim, int):
        trim = int(trim)

    if as_hex:
        _max = glob_uuid_lens.hex - 1
    else:
        _max = glob_uuid_lens.standard - 1

    ## Validate trim/characters
    if trim < 0 or trim > _max:
        raise ValueError(
            f"Invalid trim length: {trim}. Must be greater than 0 and less than {_max} ({_max -1})."
        )

    ## Trim n characters from end of string
    _uuid: str = str(in_uuid)[:-trim]

    return _uuid