Skip to content

string

zettelkasten_id 

zettelkasten_id() -> str

Generate a Zettelkasten identifier.

This function creates a unique identifier suitable for a Zettelkasten note-taking system. It generates a UUID, then formats the hexadecimal string by taking the first 9 characters, appending a dot, and then the last 11 characters of the UUID.

Returns:

  • str ( str ) –

    A formatted unique identifier (e.g., "abc123def.ghi45678901").

Examples:

>>> id_str = zettelkasten_id()
>>> isinstance(id_str, str)
True
Source code in ures/string.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
def zettelkasten_id() -> str:
    """
    Generate a Zettelkasten identifier.

    This function creates a unique identifier suitable for a Zettelkasten note-taking system.
    It generates a UUID, then formats the hexadecimal string by taking the first 9 characters,
    appending a dot, and then the last 11 characters of the UUID.

    Returns:
            str: A formatted unique identifier (e.g., "abc123def.ghi45678901").

    Examples:
            >>> id_str = zettelkasten_id()
            >>> isinstance(id_str, str)
            True
    """
    _id = uuid.uuid4().hex
    return f"{_id[:9]}.{_id[-11:]}"

unique_id 

unique_id() -> str

Generate a unique identifier.

This function returns a unique identifier as a hexadecimal string generated from a UUID.

Returns:

  • str ( str ) –

    A unique hexadecimal identifier (e.g., "3f8a7c2d1e9b4a6f8d0e2c1b3a5f7e9d").

Examples:

>>> uid = unique_id()
>>> len(uid) == 32
True
Source code in ures/string.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def unique_id() -> str:
    """
    Generate a unique identifier.

    This function returns a unique identifier as a hexadecimal string generated from a UUID.

    Returns:
            str: A unique hexadecimal identifier (e.g., "3f8a7c2d1e9b4a6f8d0e2c1b3a5f7e9d").

    Examples:
            >>> uid = unique_id()
            >>> len(uid) == 32
            True
    """
    return uuid.uuid4().hex

format_memory 

format_memory(nbytes: int | None) -> str

Format a memory size into a human-readable string.

Converts a memory size in bytes into a formatted string using appropriate units (B, KB, MB, or GB) with two decimal places of precision. If the provided value is None, it returns "0 bytes".

Parameters:

  • nbytes (int | None) –

    The memory size in bytes, or None for "0 bytes".

Returns:

  • str ( str ) –

    The memory size in a human-readable format.

Examples:

>>> format_memory(1024)
'1.00 KB'
>>> format_memory(1048576)
'1.00 MB'
Source code in ures/string.py 
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
def format_memory(nbytes: int | None) -> str:
    """
    Format a memory size into a human-readable string.

    Converts a memory size in bytes into a formatted string using appropriate units (B, KB, MB, or GB)
    with two decimal places of precision. If the provided value is None, it returns "0 bytes".

    Args:
            nbytes (int | None): The memory size in bytes, or None for "0 bytes".

    Returns:
            str: The memory size in a human-readable format.

    Examples:
            >>> format_memory(1024)
            '1.00 KB'
            >>> format_memory(1048576)
            '1.00 MB'
    """
    if nbytes is None:
        return "0 bytes"

    KB = 1024
    MB = 1024 * KB
    GB = 1024 * MB
    if abs(nbytes) >= GB:
        return f"{nbytes * 1.0 / GB:.2f} GB"
    elif abs(nbytes) >= MB:
        return f"{nbytes * 1.0 / MB:.2f} MB"
    elif abs(nbytes) >= KB:
        return f"{nbytes * 1.0 / KB:.2f} KB"
    else:
        return str(nbytes) + " B"

capitalize_string 

capitalize_string(string: str, separator: str = ' ') -> str

Capitalize each word in a string using a specified separator.

Splits the input string by the given separator, capitalizes the first letter of each part, and then joins the parts back together using the same separator.

Parameters:

  • string (str) –

    The string to be capitalized.

  • separator (str, default: ' ' ) –

    The separator to use for splitting and joining the string. Defaults to " ".

Returns:

  • str ( str ) –

    The capitalized string.

Examples:

>>> capitalize_string("hello world")
'Hello World'
>>> capitalize_string("john-doe", separator="-")
'John-Doe'
Source code in ures/string.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
def capitalize_string(string: str, separator: str = " ") -> str:
    """
    Capitalize each word in a string using a specified separator.

    Splits the input string by the given separator, capitalizes the first letter of each part,
    and then joins the parts back together using the same separator.

    Args:
            string (str): The string to be capitalized.
            separator (str, optional): The separator to use for splitting and joining the string.
                                                               Defaults to " ".

    Returns:
            str: The capitalized string.

    Examples:
            >>> capitalize_string("hello world")
            'Hello World'
            >>> capitalize_string("john-doe", separator="-")
            'John-Doe'
    """
    return separator.join([item.capitalize() for item in string.split(separator)])

string2date 

string2date(date_string: str) -> dict[str, int | str | None]

Parses various date string formats ('YYYY', 'YYYY-MM', 'YYYY-MM-DD') and returns a dictionary with the month as a three-letter abbreviation.

Parameters:

  • date_string (str) –

    The input date string.

Returns:

  • dict[str, int | str | None] –

    dict[str, int | str | None]: Keys year, month, and day.

  • dict[str, int | str | None] –

    Missing parts are None.

Examples:

>>> parsed = string2date("2024-03-15")
>>> parsed["year"], parsed["day"]
(2024, 15)
>>> string2date("2024")["day"] is None
True
Source code in ures/string.py 
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
def string2date(date_string: str) -> dict[str, int | str | None]:
    """
    Parses various date string formats ('YYYY', 'YYYY-MM', 'YYYY-MM-DD')
    and returns a dictionary with the month as a three-letter abbreviation.

    Args:
      date_string: The input date string.

    Returns:
        dict[str, int | str | None]: Keys ``year``, ``month``, and ``day``.
        Missing parts are ``None``.

    Examples:
        >>> parsed = string2date("2024-03-15")
        >>> parsed["year"], parsed["day"]
        (2024, 15)
        >>> string2date("2024")["day"] is None
        True
    """
    # 1. Attempt to parse the most complete format: 'YYYY-MM-DD'
    try:
        dt_obj = datetime.strptime(date_string, "%Y-%m-%d")
        return {"year": dt_obj.year, "month": dt_obj.strftime("%b"), "day": dt_obj.day}
    except ValueError:
        pass  # If the format doesn't match, proceed to the next try block

    # 2. Attempt to parse the 'YYYY-MM' format
    try:
        dt_obj = datetime.strptime(date_string, "%Y-%m")
        return {"year": dt_obj.year, "month": dt_obj.strftime("%b"), "day": None}
    except ValueError:
        pass  # If the format doesn't match, proceed to the next try block

    # 3. Attempt to parse a year-only string 'YYYY'
    try:
        # strptime cannot parse a year alone, so we convert it manually
        year = int(date_string)
        # Add a simple validation for a reasonable 4-digit year
        if 1 <= year <= 9999 and len(date_string) == 4:
            return {"year": year, "month": None, "day": None}
    except (ValueError, TypeError):
        pass  # If the conversion fails

    # 4. If all parsing attempts fail
    return {"year": None, "month": None, "day": None}