Jedutils 0.2.8__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
jedutils/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ __version__ = "0.2.8"
2
+ __copyright__ = "Copyright (c) 2023-2026 AYMENJD ~ https://github.com/AYMENJD"
3
+ __license__ = "MIT License"
@@ -0,0 +1,13 @@
1
+ __all__ = (
2
+ "AsyncRedisPipe",
3
+ "ConcurrencyManager",
4
+ "run_async",
5
+ "RWLock",
6
+ "download_file",
7
+ )
8
+
9
+ from ._async_redis_pipe import AsyncRedisPipe
10
+ from ._concurrency_manager import ConcurrencyManager
11
+ from ._run_async import run_async
12
+ from ._rwlock import RWLock
13
+ from .network._dl import download_file
@@ -0,0 +1,137 @@
1
+ import asyncio
2
+ import logging
3
+
4
+ try:
5
+ from redis import Redis
6
+ except ImportError:
7
+ Redis = None
8
+
9
+
10
+ class AsyncRedisPipe:
11
+ """
12
+ A utility class for executing Redis commands concurrently and efficiently using pipelines in the backend.
13
+
14
+ This class is designed for high-loaded applications that rely on Redis non-pipeline calls. By using pipelines to batch together multiple Redis commands, it can achieve significantly higher throughput than traditional non-pipeline Redis calls.
15
+
16
+ Example:
17
+ >>> redis = Redis()
18
+ >>> pipe = AsyncRedisPipe(redis)
19
+ >>> await pipe.set("key", "value")
20
+ >>> await pipe.get("key")
21
+ >>> redis_calls = [pipe.get("key") for i in range(100000)]
22
+ >>> await asyncio.gather(*redis_calls) # 100K Concurrent redis calls
23
+
24
+ Disclaimer:
25
+ This class is intended to be used with basic redis commands, other non redis commands (a.k.a client side commands) are not supported (eg. `redis.lock`) and such call can have unexpected behavior.
26
+ """
27
+
28
+ def __init__(
29
+ self,
30
+ redis: Redis,
31
+ pipe_max_size: int = 200,
32
+ workers: int = 8,
33
+ loop: asyncio.AbstractEventLoop = None,
34
+ debug: bool = False,
35
+ ) -> None:
36
+ """
37
+ Parameters:
38
+ redis (``Redis``):
39
+ The Redis client
40
+
41
+ pipe_max_size (``int``, *optional*):
42
+ The maximum number of commands in a single pipeline. Defaults to ``200``.
43
+
44
+ workers (``int``, *optional*):
45
+ The number of workers processing the pipeline. Defaults to ``8``.
46
+
47
+ loop (:py:class:`asyncio.AbstractEventLoop`, *optional*):
48
+ The event loop to use. Defaults to :py:class:`asyncio.get_event_loop()`.
49
+
50
+ debug (``bool``, *optional*):
51
+ Whether to enable debug logging. Defaults to ``False``.
52
+ """
53
+
54
+ if not Redis:
55
+ raise RuntimeError("Redis is not installed. Try pip install redis")
56
+
57
+ self.redis = redis
58
+ self.pipe_max_size = pipe_max_size
59
+ self.debug = debug
60
+ self.logger = logging.getLogger(__name__)
61
+
62
+ self.__queue = asyncio.Queue()
63
+ self.__loop = (
64
+ asyncio.get_event_loop()
65
+ if not isinstance(loop, asyncio.AbstractEventLoop)
66
+ else loop
67
+ )
68
+ self.is_running = True
69
+ self.__worker_tasks = [
70
+ self.__loop.create_task(self.__worker()) for _ in range(workers)
71
+ ]
72
+
73
+ async def __aenter__(self):
74
+ return self
75
+
76
+ async def __aexit__(self, exc_type, exc_val, exc_tb):
77
+ self.close()
78
+ return
79
+
80
+ async def __worker(self):
81
+ while self.is_running:
82
+ pipe = self.redis.pipeline(False)
83
+ futures = []
84
+ count = 0
85
+
86
+ while count <= self.pipe_max_size:
87
+ try:
88
+ if count == 0:
89
+ data = await self.__queue.get()
90
+ else:
91
+ data = self.__queue.get_nowait()
92
+ await asyncio.sleep(0)
93
+ except asyncio.QueueEmpty:
94
+ break
95
+ else:
96
+ if self.debug:
97
+ self.logger.debug(f"Executing command: {data[1]}")
98
+
99
+ try:
100
+ getattr(pipe, data[1])(*data[2], **data[3])
101
+ except Exception as e:
102
+ data[0].set_exception(e)
103
+ continue
104
+
105
+ futures.append(data[0])
106
+ count += 1
107
+
108
+ await self.__handle_pipe_line(futures, pipe)
109
+
110
+ async def __handle_pipe_line(self, futures: list, pipe):
111
+ for x, result in enumerate((await pipe.execute(False))):
112
+ if self.debug:
113
+ self.logger.debug(f"Result: {result}")
114
+
115
+ if isinstance(result, BaseException):
116
+ futures[x].set_exception(result)
117
+ else:
118
+ futures[x].set_result(result)
119
+
120
+ def __getattr__(self, name):
121
+ wrapper = self.__dict__.get(name)
122
+ if wrapper is None:
123
+ def wrapper(*args, **kwargs):
124
+ fut = asyncio.Future()
125
+ self.__queue.put_nowait((fut, name, args, kwargs))
126
+ return fut
127
+
128
+ # cache in the instance dict so later calls skip __getattr__
129
+ # and the per-call closure allocation
130
+ self.__dict__[name] = wrapper
131
+ return wrapper
132
+
133
+ def close(self):
134
+ """Close the AsyncRedisPipe instance"""
135
+ self.is_running = False
136
+ for worker in self.__worker_tasks:
137
+ worker.cancel()
@@ -0,0 +1,134 @@
1
+ import asyncio
2
+ from contextlib import asynccontextmanager
3
+
4
+
5
+ class ConcurrencyManager:
6
+ """A class for managing and tracking concurrent operations"""
7
+
8
+ def __init__(self):
9
+ """Initialize the ConcurrencyManager class with data and a lock"""
10
+
11
+ self.data = {}
12
+ self.lock = asyncio.Lock()
13
+
14
+ async def acquire(self, ID) -> None:
15
+ """
16
+ Acquire a lock for the specified ID
17
+
18
+ Parameters:
19
+ ID (``str``):
20
+ Identifier for the operation
21
+ """
22
+
23
+ async with self.lock:
24
+ self.data.setdefault(ID, 0)
25
+ self.data[ID] += 1
26
+
27
+ async def release(self, ID) -> bool:
28
+ """
29
+ Release a lock for the specified ID
30
+
31
+ Parameters:
32
+ ID (``str``):
33
+ Identifier for the operation
34
+
35
+ Returns:
36
+ ``bool``:
37
+ ``True`` if the lock was released, ``False`` if ID was not found
38
+ """
39
+
40
+ async with self.lock:
41
+ if ID in self.data:
42
+ self.data[ID] -= 1
43
+ if self.data[ID] == 0:
44
+ del self.data[ID]
45
+ return True
46
+ else:
47
+ return False
48
+
49
+ async def get_count(self, ID) -> int:
50
+ """
51
+ Get the current count of operations for the specified ID
52
+
53
+ Parameters:
54
+ ID (``str``):
55
+ Identifier for the operation
56
+
57
+ Returns:
58
+ ``int``:
59
+ Current count of operations for the ID
60
+ """
61
+
62
+ async with self.lock:
63
+ return self.data.get(ID, 0)
64
+
65
+ @asynccontextmanager
66
+ async def context(self, ID):
67
+ """
68
+ Create a context for the specified ID, acquiring and releasing a lock
69
+
70
+ Parameters:
71
+ ID (``str``):
72
+ Identifier for the operation
73
+ """
74
+
75
+ await self.acquire(ID)
76
+ try:
77
+ yield
78
+ finally:
79
+ await self.release(ID)
80
+
81
+ @asynccontextmanager
82
+ async def limit(self, ID, max_count):
83
+ """
84
+ Create a context with a limit on the number of concurrent operations.
85
+
86
+ Parameters:
87
+ ID (``str``):
88
+ Identifier for the operation.
89
+
90
+ max_count (``int``):
91
+ Maximum allowed concurrent operations for the ``ID``.
92
+
93
+ Raises:
94
+ ``ValueError``:
95
+ If the limit for the ``ID`` is exceeded
96
+ """
97
+
98
+ await self.acquire(ID)
99
+ try:
100
+ count = await self.get_count(ID)
101
+ if count <= max_count:
102
+ yield
103
+ else:
104
+ raise ValueError(f"Exceeded limit of {max_count} for {ID}")
105
+ finally:
106
+ await self.release(ID)
107
+
108
+ async def wait_until(self, ID, target_count, timeout=None):
109
+ """
110
+ Wait until the count for the specified ID reaches the target count
111
+
112
+ Parameters:
113
+ ID (``str``):
114
+ Identifier for the operation
115
+
116
+ target_count (``int``):
117
+ Target count to wait for
118
+
119
+ timeout (``float``):
120
+ Maximum time to wait in seconds. If ``None``, wait indefinitely
121
+
122
+ Raises:
123
+ ``TimeoutError``:
124
+ If the ``timeout`` is reached before the target count is achieved
125
+ """
126
+
127
+ while await self.get_count(ID) != target_count:
128
+ await asyncio.sleep(0.1)
129
+ if timeout is not None:
130
+ timeout -= 0.1
131
+ if timeout <= 0:
132
+ raise TimeoutError(
133
+ f"Timeout waiting for {ID} to reach {target_count}"
134
+ )
@@ -0,0 +1,10 @@
1
+ import asyncio
2
+ from typing import Any, Awaitable, Callable, TypeVar
3
+
4
+ T = TypeVar("T")
5
+
6
+
7
+ def run_async(func: Callable[..., Awaitable[T]], *args: Any, **kwargs: Any) -> T:
8
+ """Run an async function synchronously, blocking the event loop until it completes."""
9
+ loop = asyncio.get_event_loop()
10
+ return loop.run_until_complete(func(*args, **kwargs))
@@ -0,0 +1,64 @@
1
+ import asyncio
2
+ from contextlib import asynccontextmanager
3
+
4
+
5
+ class RWLock:
6
+ """Asynchronous Read-Write Lock (RWLock) implementation"""
7
+
8
+ def __init__(self):
9
+ """Initialize the RWLock"""
10
+
11
+ self.__readers = 0
12
+ self.__writers = 0
13
+ self.__write_lock = asyncio.Lock()
14
+ self.__read_lock = asyncio.Lock()
15
+
16
+ async def acquire_read(self):
17
+ async with self.__read_lock:
18
+ self.__readers += 1
19
+ if self.__readers == 1:
20
+ await self.__write_lock.acquire()
21
+
22
+ async def release_read(self):
23
+ async with self.__read_lock:
24
+ self.__readers -= 1
25
+ if self.__readers == 0:
26
+ self.__write_lock.release()
27
+
28
+ async def acquire_write(self):
29
+ await self.__write_lock.acquire()
30
+
31
+ def release_write(self):
32
+ self.__write_lock.release()
33
+
34
+ @property
35
+ def readers(self):
36
+ """Return the current count of active readers"""
37
+
38
+ return self.__readers
39
+
40
+ @property
41
+ def writers(self):
42
+ """Return the current count of active writers"""
43
+
44
+ return self.__writers
45
+
46
+ @asynccontextmanager
47
+ async def read(self):
48
+ """A context manager for acquiring a read lock"""
49
+
50
+ try:
51
+ await self.acquire_read()
52
+ yield
53
+ finally:
54
+ await self.release_read()
55
+
56
+ @asynccontextmanager
57
+ async def write(self):
58
+ """A context manager for acquiring a write lock"""
59
+
60
+ try:
61
+ await self.acquire_write()
62
+ yield
63
+ finally:
64
+ self.release_write()
@@ -0,0 +1,2 @@
1
+ __all__ = ("download_file",)
2
+ from ._dl import download_file
@@ -0,0 +1,96 @@
1
+ import asyncio
2
+
3
+ try:
4
+ import aiohttp
5
+ except ImportError:
6
+ aiohttp = None
7
+
8
+ import os
9
+
10
+
11
+ async def download_file(
12
+ url: str,
13
+ filename: str,
14
+ chunk_size: int = 8192,
15
+ ignore_status: bool = False,
16
+ progress_callback: callable = None,
17
+ thread_pool=None,
18
+ **kwargs,
19
+ ) -> None:
20
+ r"""
21
+ Asynchronously download a file from the given URL and saves it to the specified filename using chunked downloading
22
+
23
+ Example:
24
+ Download a large file asynchronously:
25
+
26
+ .. code-block:: python
27
+
28
+ async def my_callback(downloaded, expected_size):
29
+ print(f"Downloaded: {downloaded}/{expected_size}")
30
+
31
+ await download_file('https://example.com/large_file.zip', 'my_large_file.zip', progress_callback=my_callback)
32
+
33
+ Parameters:
34
+ url (``str``):
35
+ The URL of the file to download
36
+
37
+ filename (``str``, *optional*):
38
+ The filename to save the downloaded file as
39
+
40
+ chunk_size (``int``, *optional*):
41
+ The size of each chunk to download in bytes. Default is 8192 bytes (8 KB)
42
+
43
+ ignore_status (``bool``, *optional*):
44
+ Whether to ignore errors in the response from the server. Default is ``False``
45
+
46
+ progress_callback (``callable``, *optional*):
47
+ A callable function to be called with the download progress, in bytes
48
+
49
+ thread_pool:
50
+ A thread pool to use for blocking operations. Default is ``None``
51
+
52
+ \*\*kwargs:
53
+ Any additional keyword arguments to pass to the `aiohttp.get` call
54
+ Returns:
55
+ ``None``
56
+
57
+ Raises:
58
+ :py:class:`aiohttp.ClientResponseError`
59
+ """
60
+
61
+ if not aiohttp:
62
+ raise RuntimeError("aiohttp is not installed. Try pip install aiohttp")
63
+
64
+ async with aiohttp.ClientSession() as session:
65
+ async with session.get(url, **kwargs) as response:
66
+ if not ignore_status:
67
+ response.raise_for_status()
68
+
69
+ expected_size = int(response.headers.get("content-length", 0))
70
+ downloaded_size = 0
71
+ loop = asyncio.get_event_loop()
72
+
73
+ if progress_callback:
74
+ progress_callback(downloaded_size, expected_size)
75
+
76
+ if not filename:
77
+ filename = os.path.basename(url)
78
+ if not filename:
79
+ raise ValueError("Can't find filename")
80
+
81
+ f = None
82
+ try:
83
+ f = await loop.run_in_executor(thread_pool, open, filename, "wb")
84
+
85
+ async for chunk in response.content.iter_chunked(chunk_size):
86
+ await loop.run_in_executor(thread_pool, f.write, chunk)
87
+
88
+ downloaded_size += len(chunk)
89
+ if progress_callback:
90
+ progress_callback(downloaded_size, expected_size)
91
+
92
+ finally:
93
+ if f:
94
+ await loop.run_in_executor(thread_pool, f.close)
95
+
96
+ return None
@@ -0,0 +1,3 @@
1
+ from .b62 import BASE62_CHARS, b62encode, b62decode
2
+
3
+ __all__ = ["BASE62_CHARS", "b62encode", "b62decode"]
jedutils/base62/b62.py ADDED
@@ -0,0 +1,70 @@
1
+ from typing import Union
2
+
3
+ BASE62_CHARS = list("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
4
+ BASE62_LOOKUP = {char: index for index, char in enumerate(BASE62_CHARS)}
5
+
6
+
7
+ def b62encode(data: Union[bytes, int]) -> str:
8
+ r"""
9
+ Encodes the given data into a base62 string
10
+
11
+ \Example:
12
+ .. code-block:: python
13
+ >>> b62encode(b'hello world')
14
+ 'AAwf93rvy4aWQVw'
15
+ >>> b62encode(123456789)
16
+ '8M0kX'
17
+
18
+ \Parameters:
19
+ data (``bytes`` or ``int``):
20
+ The data to be encoded. It must be either bytes or an integer
21
+
22
+ \Returns:
23
+ ``str``: The base62 encoded string
24
+ """
25
+
26
+ if isinstance(data, bytes):
27
+ num = int.from_bytes(data, byteorder="big")
28
+ elif isinstance(data, int):
29
+ num = data
30
+ else:
31
+ raise TypeError("data must be bytes or int")
32
+
33
+ base62 = []
34
+
35
+ while num > 0:
36
+ num, remainder = divmod(num, 62)
37
+ base62.append(BASE62_CHARS[remainder])
38
+
39
+ return "".join(reversed(base62))
40
+
41
+
42
+ def b62decode(b62_string: str, as_int: bool = False) -> Union[bytes, int]:
43
+ r"""
44
+ Decodes a Base62 encoded string
45
+
46
+ \Example:
47
+ .. code-block:: python
48
+ >>> b62decode("AAwf93rvy4aWQVw")
49
+ b'hello world'
50
+ >>> b62decode("8M0kX", as_int=True)
51
+ 123456789
52
+
53
+ \Parameters:
54
+ b62_string (``str``):
55
+ The Base62 encoded string to decode
56
+
57
+ as_int (``bool``, *optional*):
58
+ Pass ``True`` to return the decoded value as an integer. Default is ``False``
59
+
60
+ \Returns:
61
+ ``bytes`` or ``int``: The decoded value as bytes if ``as_int`` is ``False``, otherwise as an integer.
62
+ """
63
+
64
+ num = 0
65
+ for char in b62_string:
66
+ num = num * 62 + BASE62_LOOKUP[char]
67
+
68
+ if as_int:
69
+ return num
70
+ return num.to_bytes(((num.bit_length() + 7) // 8), byteorder="big")
@@ -0,0 +1,2 @@
1
+ __all__ = ("InMemoryDB",)
2
+ from ._in_memory import InMemoryDB
@@ -0,0 +1,90 @@
1
+ from collections import OrderedDict
2
+
3
+
4
+ class InMemoryDB:
5
+ """
6
+ A simple key-value data store that stores data in memory
7
+
8
+ Example:
9
+ .. code-block:: python
10
+
11
+ # Create a new in-memory database with a maximum of 100 keys
12
+ db = InMemoryDB(max_keys=100)
13
+
14
+ # Set a key-value pair
15
+ db.set('key1', 'value1')
16
+
17
+ # Get the value for a key
18
+ value1 = db.get('key1')
19
+ print(value1) # Output: 'value1'
20
+
21
+ # Delete a key-value pair
22
+ db.delete('key1')
23
+
24
+ Parameters:
25
+ max_keys (``int``, *optional*):
26
+ The maximum number of keys that can be stored in the database
27
+ If None (default), there is no limit on the number of keys
28
+
29
+ """
30
+
31
+ def __init__(self, max_keys: int = 1000):
32
+ self.data = OrderedDict()
33
+ self.max_keys = max_keys
34
+
35
+ def set(self, key, value):
36
+ """
37
+ Sets the value associated with a key in the database
38
+
39
+ Parameters:
40
+ key (``str``):
41
+ The key to set the value for
42
+
43
+ value:
44
+ The value to associate with the key
45
+
46
+ Returns:
47
+ None
48
+ """
49
+ if self.max_keys is not None and len(self.data) >= self.max_keys:
50
+ self._remove_oldest_key()
51
+
52
+ self.data[key] = value
53
+
54
+ def get(self, key):
55
+ """
56
+ Gets the value associated with a key in the database
57
+
58
+ Parameters:
59
+ key (``str``):
60
+ The key to get the value for
61
+
62
+ Returns:
63
+ The value associated with the given key, or ``None`` if the key is not found
64
+ """
65
+ return self.data.get(key, None)
66
+
67
+ def delete(self, key):
68
+ """
69
+ Deletes the key-value pair with the given key from the database
70
+
71
+ Parameters:
72
+ key (``str``):
73
+ The key to delete
74
+
75
+ Returns:
76
+ None
77
+ """
78
+ del self.data[key]
79
+
80
+ def _remove_oldest_key(self):
81
+ self.data.popitem(last=False)
82
+
83
+ def __setitem__(self, key, value):
84
+ self.set(key, value)
85
+
86
+ def __getitem__(self, key):
87
+ return self.data[key]
88
+
89
+ def __delitem__(self, key):
90
+ self.delete(key)
@@ -0,0 +1,17 @@
1
+ __all__ = (
2
+ "format_bytes",
3
+ "parse_bytes",
4
+ "format_duration",
5
+ "format_number_short",
6
+ "convert_to_bytes",
7
+ "to_numeric",
8
+ )
9
+
10
+ from ._number_formatter import (
11
+ format_bytes,
12
+ parse_bytes,
13
+ format_duration,
14
+ format_number_short,
15
+ convert_to_bytes,
16
+ to_numeric,
17
+ )
@@ -0,0 +1,223 @@
1
+ def format_bytes(size: int) -> str:
2
+ """
3
+ Converts a size in bytes to a human-readable format
4
+
5
+ Parameters:
6
+ size (``int``):
7
+ The size in bytes
8
+
9
+ Returns:
10
+ ``str``:
11
+ The formatted size with the appropriate suffix
12
+
13
+ """
14
+
15
+ suffixes = ["B", "KB", "MB", "GB", "TB"]
16
+ i = 0
17
+ while size >= 1024 and i < len(suffixes) - 1:
18
+ size /= 1024
19
+ i += 1
20
+ return f"{size:.2f} {suffixes[i]}"
21
+
22
+
23
+ def parse_bytes(size_str: str) -> str:
24
+ """
25
+ Converts a size in a human-readable format to bytes
26
+
27
+ Parameters:
28
+ size_str (``str``):
29
+ The size in a human-readable format, e.g., ``2.00 KB``
30
+
31
+ Returns:
32
+ ``int``:
33
+ The size in bytes
34
+
35
+ Raises:
36
+ ``ValueError``:
37
+ If the input ``size_str`` is in an invalid format
38
+
39
+ """
40
+
41
+ suffixes = ["B", "KB", "MB", "GB", "TB"]
42
+ size_str = size_str.strip()
43
+ size, suffix = size_str[:-2], size_str[-2:].upper()
44
+
45
+ if suffix not in suffixes:
46
+ raise ValueError("Invalid size format")
47
+
48
+ try:
49
+ size = float(size)
50
+ except ValueError:
51
+ raise ValueError("Invalid size format")
52
+
53
+ power = suffixes.index(suffix)
54
+ size *= 1024**power
55
+ return int(size)
56
+
57
+
58
+ units = [
59
+ ("year", 365 * 24 * 60 * 60),
60
+ ("day", 24 * 60 * 60),
61
+ ("hour", 60 * 60),
62
+ ("minute", 60),
63
+ ("second", 1),
64
+ ]
65
+
66
+
67
+ def format_duration(seconds: int, format_option: str = "short") -> str:
68
+ """
69
+ Formats the given duration in seconds into a human-readable string representation
70
+
71
+ Parameters:
72
+ seconds (``int``):
73
+ The duration in seconds
74
+
75
+ format_option (``str``, *optional*):
76
+ The formatting option either ``long`` or ``short``. Default is "short"
77
+
78
+ Returns:
79
+ ``str``:
80
+ The formatted duration string
81
+
82
+ Raises:
83
+ ``ValueError``:
84
+ If the duration is a negative number
85
+ """
86
+
87
+ if seconds < 0:
88
+ raise ValueError("Duration must be a non-negative number")
89
+
90
+ parts = []
91
+ for unit, duration in units:
92
+ if seconds >= duration:
93
+ count = seconds // duration
94
+ seconds %= duration
95
+
96
+ if count > 1:
97
+ unit += "s"
98
+
99
+ parts.append(f"{count} {unit}")
100
+
101
+ if not parts:
102
+ return "0 seconds"
103
+
104
+ if format_option == "long":
105
+ if len(parts) == 1:
106
+ return parts[0]
107
+ last_part = parts.pop()
108
+ return ", ".join(parts) + " and " + last_part
109
+ elif format_option == "short":
110
+ hours = int(seconds // 3600)
111
+ minutes = int((seconds // 60) % 60)
112
+ seconds = int(seconds % 60)
113
+
114
+ time_parts = []
115
+ if hours > 0:
116
+ time_parts.append(str(hours))
117
+ time_parts.append(f"{minutes:02d}")
118
+ time_parts.append(f"{seconds:02d}")
119
+ return ":".join(time_parts)
120
+ else:
121
+ raise ValueError("Invalid format option. Available options: 'long', 'short'")
122
+
123
+
124
+ def format_number_short(number: int) -> str:
125
+ """
126
+ Convert a number to a short format with a specified number of decimal places
127
+
128
+ Parameters:
129
+ number (``float``):
130
+ The number to format
131
+
132
+ Returns:
133
+ ``str``:
134
+ The formatted number in short format
135
+ """
136
+
137
+ suffixes = {0: "", 3: "K", 6: "M", 9: "B", 12: "T", 15: "Q"}
138
+
139
+ order = 0
140
+ while number >= 10**3 and order < max(suffixes.keys()):
141
+ order += 3
142
+ number /= 10**3
143
+
144
+ if number.is_integer():
145
+ formatted_number = f"{int(number)}"
146
+ else:
147
+ formatted_number = f"{number:.1f}".rstrip("0").rstrip(".")
148
+
149
+ formatted_number += suffixes.get(order, "")
150
+
151
+ return formatted_number
152
+
153
+
154
+ def convert_to_bytes(value: int, unit: str) -> int:
155
+ """
156
+ Convert a number with a unit prefix into bytes
157
+
158
+ Parameters:
159
+ value (``int``):
160
+ The numerical value
161
+
162
+ unit (``str``):
163
+ The unit prefix (e.g., "B", "KB", "MB", "GB", "TB", "PB")
164
+
165
+ Returns:
166
+ ``int``:
167
+ The value converted to bytes
168
+ """
169
+
170
+ unit = unit.upper()
171
+ if unit == "B":
172
+ return value
173
+ elif unit == "KB":
174
+ return int(value * 1024)
175
+ elif unit == "MB":
176
+ return int(value * 1024 * 1024)
177
+ elif unit == "GB":
178
+ return int(value * 1024 * 1024 * 1024)
179
+ elif unit == "TB":
180
+ return int(value * 1024 * 1024 * 1024 * 1024)
181
+ elif unit == "PB":
182
+ return int(value * 1024 * 1024 * 1024 * 1024 * 1024)
183
+ else:
184
+ raise ValueError("Invalid unit. Use 'B', 'KB', 'MB', 'GB', 'TB', or 'PB'.")
185
+
186
+
187
+ def to_numeric(value: int, unit: str) -> int:
188
+ """
189
+ Convert a number with a unit prefix into its numerical value
190
+
191
+ Parameters:
192
+ value (``int``):
193
+ The numerical value
194
+
195
+ unit (``str``):
196
+ The unit prefix (e.g., "U" for "UNIT", "T" for "TEN", "H" for "HUNDRED", "K" for "THOUSAND",
197
+ "M" for "MILLION", "B" for "BILLION", "T" for "TRILLION")
198
+
199
+ Returns:
200
+ ``float``:
201
+ The value converted to its numerical value
202
+ """
203
+
204
+ unit = unit.upper()
205
+ if unit == "U":
206
+ return value
207
+ elif unit == "T":
208
+ return value * 10
209
+ elif unit == "H":
210
+ return value * 100
211
+ elif unit == "K":
212
+ return value * 1000
213
+ elif unit == "M":
214
+ return value * 1000000
215
+ elif unit == "B":
216
+ return value * 1000000000
217
+ elif unit == "T":
218
+ return value * 1000000000000
219
+ else:
220
+ raise ValueError(
221
+ "Invalid unit. Use 'U' for 'UNIT', 'T' for 'TEN', 'H' for 'HUNDRED', 'K' for 'THOUSAND', "
222
+ "'M' for 'MILLION', 'B' for 'BILLION', or 'T' for 'TRILLION'."
223
+ )
@@ -0,0 +1,12 @@
1
+ __all__ = (
2
+ "random_string",
3
+ "random_string_urandom",
4
+ "random_hex_string",
5
+ "split_text",
6
+ "to_arabic_nums",
7
+ "to_english_nums",
8
+ )
9
+
10
+ from ._random_string import random_string, random_string_urandom, random_hex_string
11
+ from ._chunked_text import split_text
12
+ from ._numerals import to_arabic_nums, to_english_nums
@@ -0,0 +1,37 @@
1
+ import textwrap
2
+
3
+
4
+ def split_text(text: str, chunk_size: int = 4096):
5
+ """
6
+ Splits a text into chunks of the specified size
7
+
8
+ Example:
9
+ .. code-block:: python
10
+
11
+ # Split a long text into chunks of 4096 characters
12
+ >>> long_text = "..." # The long text to split
13
+ >>> for chunk in split_text(long_text, 4096):
14
+ ... # Send each chunk as a separate message
15
+ ... send_message(chunk)
16
+
17
+ Parameters:
18
+ text (``str``):
19
+ The text to split
20
+
21
+ chunk_size (``int``, *optional*):
22
+ The maximum size of each chunk. Defaults to ``4096``
23
+
24
+ Returns:
25
+ ``list``:
26
+ A list of text chunks
27
+ """
28
+
29
+ if len(text) <= chunk_size:
30
+ return [text]
31
+ else:
32
+ chunks = []
33
+ wrapper = textwrap.TextWrapper(width=chunk_size, break_long_words=False)
34
+ lines = wrapper.wrap(text)
35
+ for line in lines:
36
+ chunks.extend(textwrap.wrap(line, width=chunk_size))
37
+ return chunks
@@ -0,0 +1,46 @@
1
+ arabic_indic_digits = str.maketrans(
2
+ "0123456789", "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669"
3
+ )
4
+ english_digits = str.maketrans(
5
+ "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669", "0123456789"
6
+ )
7
+
8
+
9
+ def to_arabic_nums(string: str):
10
+ """
11
+ Convert a string with english numerals to Arabic numerals
12
+
13
+ Example:
14
+ .. code-block:: python
15
+ >>> to_arabic_nums("1234")
16
+ '١٢٣٤'
17
+
18
+ Parameters:
19
+ string (``str`` || ``int``):
20
+ The string or integer containing English numerals to convert to Arabic numerals
21
+
22
+ Returns:
23
+ ``str``: The string with digits converted to Arabic numerals
24
+ """
25
+
26
+ return str(string).translate(arabic_indic_digits)
27
+
28
+
29
+ def to_english_nums(string: str):
30
+ """
31
+ Convert a string with Arabic numerals to English numerals
32
+
33
+ Example:
34
+ .. code-block:: python
35
+ >>> to_english_nums("١٢٣٤")
36
+ '1234'
37
+
38
+ Parameters:
39
+ string (``str`` || ``int``):
40
+ The string or integer containing Arabic numerals to convert to English numerals
41
+
42
+ Returns:
43
+ ``str``: The string with Arabic numerals converted to English numerals
44
+ """
45
+
46
+ return str(string).translate(english_digits)
@@ -0,0 +1,43 @@
1
+ __all__ = ("random_string", "random_string_urandom", "random_hex_string")
2
+
3
+ import binascii
4
+ import os
5
+ import string
6
+ import random
7
+
8
+
9
+ chars = list(string.digits + string.ascii_letters)
10
+ chars_len = len(chars)
11
+
12
+
13
+ def random_string(length: int):
14
+ r"""Generate a random string
15
+
16
+ Parameters:
17
+ length (``int``):
18
+ The length of the string
19
+ """
20
+
21
+ return "".join(random.choices(chars, k=length))
22
+
23
+
24
+ def random_string_urandom(length: int):
25
+ r"""Generate a random string using os.urandom
26
+
27
+ Parameters:
28
+ length (``int``):
29
+ The length of the string (in bytes)
30
+ """
31
+
32
+ return "".join(chars[b % chars_len] for b in os.urandom(length))
33
+
34
+
35
+ def random_hex_string(length):
36
+ r"""Generate a random hex string
37
+
38
+ Parameters:
39
+ length (``int``):
40
+ The length of the string (in bytes)
41
+ """
42
+
43
+ return binascii.hexlify(os.urandom(length)).decode()
@@ -0,0 +1,15 @@
1
+ from .arithmetic import (
2
+ as_tdlib_message_id,
3
+ as_server_message_id,
4
+ as_server_message_id_unchecked,
5
+ get_supergroup_chat_id,
6
+ get_supergroup_id,
7
+ )
8
+
9
+ __all__ = (
10
+ "as_tdlib_message_id",
11
+ "as_server_message_id",
12
+ "as_server_message_id_unchecked",
13
+ "get_supergroup_chat_id",
14
+ "get_supergroup_id",
15
+ )
@@ -0,0 +1,105 @@
1
+ def as_tdlib_message_id(message_id: int) -> int:
2
+ r"""
3
+ Convert server message ID to TDLib message ID
4
+
5
+ \Example:
6
+ .. code-block:: python
7
+
8
+ >>> as_tdlib_message_id(12345)
9
+ 12944670720
10
+
11
+ \Parameters:
12
+ message_id (``int``):
13
+ Server message ID
14
+
15
+ \Returns:
16
+ ``int``: TDLib message ID
17
+ """
18
+
19
+ return message_id << 20
20
+
21
+
22
+ def as_server_message_id(message_id: int) -> int:
23
+ r"""
24
+ Converts TDLib message ID to server message ID
25
+
26
+ \Example:
27
+ .. code-block:: python
28
+
29
+ >>> as_server_message_id(12944670720)
30
+ 12345
31
+
32
+ \Parameters:
33
+ message_id (``int``):
34
+ TDLib message ID
35
+
36
+ \Returns:
37
+ ``int``: The server message ID
38
+ """
39
+
40
+ result = message_id >> 20
41
+ assert as_tdlib_message_id(result) == message_id
42
+ return result
43
+
44
+
45
+ def as_server_message_id_unchecked(message_id: int) -> int:
46
+ r"""
47
+ Converts TDLib message ID to server message ID
48
+
49
+ \Example:
50
+ >>> as_server_message_id_unchecked(12944670720)
51
+ 12345
52
+ >>> as_server_message_id_unchecked(12944670721) # Invalid ID
53
+ 0
54
+
55
+ \Parameters:
56
+ message_id (``int``):
57
+ TDLib message ID
58
+
59
+ \Returns:
60
+ ``int``:
61
+ The server message ID or 0 if the conversion is invalid
62
+ """
63
+
64
+ result = message_id >> 20
65
+ if as_tdlib_message_id(result) != message_id:
66
+ return 0
67
+ return result
68
+
69
+
70
+ def get_supergroup_chat_id(supergroup_id: int) -> int:
71
+ r"""
72
+ Convert supergroup_id to chat_id
73
+
74
+ \Example:
75
+ >>> get_supergroup_chat_id(-123456789)
76
+ -1000123456789
77
+
78
+ \Parameters:
79
+ supergroup_id (``int``):
80
+ ID of the supergroup
81
+
82
+ \Returns:
83
+ ``int``: The chat ID of the supergroup
84
+ """
85
+
86
+ return -1000000000000 - (supergroup_id if supergroup_id > 0 else -supergroup_id)
87
+
88
+
89
+ def get_supergroup_id(chat_id: int) -> int:
90
+ r"""
91
+ Convert chat_id to supergroup_id
92
+
93
+ Example:
94
+ >>> get_supergroup_id(-1000123456789)
95
+ 123456789
96
+
97
+ Parameters:
98
+ chat_id (``int``):
99
+ The chat ID to convert to a supergroup ID
100
+
101
+ Returns:
102
+ ``int``: The supergroup ID
103
+ """
104
+
105
+ return -1000000000000 - chat_id
@@ -0,0 +1,51 @@
1
+ Metadata-Version: 2.4
2
+ Name: Jedutils
3
+ Version: 0.2.8
4
+ Summary: Jedutils is a Python utilities package that provides a collection of useful helper functions.
5
+ Author-email: AYMEN A <let.me.code.safe@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Source, https://github.com/AYMENJD/jedutils
8
+ Project-URL: Tracker, https://github.com/AYMENJD/jedutils/issues
9
+ Keywords: utilities,tools,library,helper,functions,development
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Programming Language :: Python :: 3.15
19
+ Classifier: Topic :: Software Development :: Libraries
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Provides-Extra: all
24
+ Requires-Dist: redis; extra == "all"
25
+ Requires-Dist: aiohttp; extra == "all"
26
+ Dynamic: license-file
27
+
28
+ # Jedutils [![Version](https://img.shields.io/pypi/v/jedutils?style=flat&logo=pypi)](https://pypi.org/project/jedutils) [![Downloads](https://static.pepy.tech/personalized-badge/jedutils?period=month&units=none&left_color=grey&right_color=brightgreen&left_text=Downloads)](https://pepy.tech/project/jedutils)
29
+
30
+ Jedutils is a Python utilities package that provides a collection of useful helper functions.
31
+
32
+ ## Installation
33
+
34
+ You can install Jedutils using `pip`:
35
+
36
+ ```bash
37
+ pip install jedutils
38
+ ```
39
+
40
+ To install all the dependencies for all utilities, use the following command:
41
+ ```bash
42
+ pip install jedutils[all]
43
+ ```
44
+
45
+ ## Contributing
46
+
47
+ Contributions to Jedutils are welcome! If you have an idea for a new utility or an improvement to an existing one, please open an issue or submit a pull request on GitHub.
48
+
49
+ ## License
50
+
51
+ Jedutils is licensed under the MIT License. See the `LICENSE` file for details.
@@ -0,0 +1,25 @@
1
+ jedutils/__init__.py,sha256=Wi1KFAWaDAGS-go93e7UddQr0sDrvexXWGGWA5c8z9g,129
2
+ jedutils/asyncio/__init__.py,sha256=dEEOfjpCv0nPcXEua7Ui_nhnojf82P4tRnjf5qJYH44,315
3
+ jedutils/asyncio/_async_redis_pipe.py,sha256=Qp8xviAcUXqotcNdGK4DkbVhOgoYtwjnulkF3xjgnak,4614
4
+ jedutils/asyncio/_concurrency_manager.py,sha256=UmmnziezRDMkWRLjvaaWeIX5sJ86c5mCik_ONbu126A,3615
5
+ jedutils/asyncio/_run_async.py,sha256=a7PspPauA_NwIURno6nOljFAI7IhYIWLxSVOIg28eWA,355
6
+ jedutils/asyncio/_rwlock.py,sha256=Pf4hNOr3yNYZgdvZS1o6Qt6BO8HDrUzW-ZZADcimkAg,1576
7
+ jedutils/asyncio/network/__init__.py,sha256=QHETCv5LCLcj6MPfFemtmn4SLXTuMheLCw1EGqsu32w,60
8
+ jedutils/asyncio/network/_dl.py,sha256=7PGlTWnI9C-j09fjLXhpuezyMo36xcxnfeLGuwSBlZ0,2935
9
+ jedutils/base62/__init__.py,sha256=VyGs2GaC2RD3PlQ3KKa-GmdqwQewndwf9YE82vWptzc,109
10
+ jedutils/base62/b62.py,sha256=i5OaUmfGERy8cqiapvLtJLoEOzVA6LhAbRCp0VTmm_0,1955
11
+ jedutils/databases/__init__.py,sha256=6JRAP-Foid63FcSuK3XMEnQcd1SRfxPS8606Cvq2fHY,61
12
+ jedutils/databases/_in_memory.py,sha256=OQxCs7IdededBKO4TNVlOLauh_6GRASqjbfQohUftSY,2216
13
+ jedutils/math/__init__.py,sha256=KLKEBEWW7hXhe495pa1Z8OOI4fEiGZ0INm8c9yMyG3c,300
14
+ jedutils/math/_number_formatter.py,sha256=LqUZbs7M3HtBK7zvnj9UJXI_j-PaGGOjnCLXACjgpjY,5634
15
+ jedutils/strings/__init__.py,sha256=AbNYFNrd5goifxXLEbOd3zyBkm2kStGiMSIldGW384g,330
16
+ jedutils/strings/_chunked_text.py,sha256=aRurZmUPXVPFxe6Xbu0hx441SUFnI5vqDs4FrDrFeLw,1024
17
+ jedutils/strings/_numerals.py,sha256=DxUgC0WJ0rzLBWWM33D6zHzARo7JGRaeX25Ad62t7iI,1296
18
+ jedutils/strings/_random_string.py,sha256=-tAZ2dcYwa4Qdypky58XLTmMiCKqasbzHFxj1S_Ds3Q,901
19
+ jedutils/tdlib/__init__.py,sha256=TM8HtFUYItvUqN6szqPKHmMg7f6hhsMhYRkaohnT5Zw,344
20
+ jedutils/tdlib/arithmetic.py,sha256=jFfcr2QPdqPlGeguc28Yf5EU7AUtz1gYMul7wvVriL8,2328
21
+ jedutils-0.2.8.dist-info/licenses/LICENSE,sha256=0UzMsgGnNG6Ne6ira7QmNUI-xvXxF6U1K7f_Pw0dzQs,1069
22
+ jedutils-0.2.8.dist-info/METADATA,sha256=iCVlVaHSqf7VYhgVAEQ5CBlj2sOM0Dbyc4UMGSrh5uQ,2010
23
+ jedutils-0.2.8.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
24
+ jedutils-0.2.8.dist-info/top_level.txt,sha256=tofN_XGFp4UH_NeVh1LdwEgp-tvJMxpWttn3KaVPY_0,9
25
+ jedutils-0.2.8.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023-2026 AYMENJD
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ jedutils