feat: Add log21.helper_types module and FileSize type.

Author: MPCodeWriter21

CHANGELOG.md

@@ -6,14 +6,65 @@ Help this project by [Donation](DONATE.md)
 Changes
 -------
 
+### v3.3.0
+
+Add `log21.helper_types` module.
+
+This module contains a collection of useful types meant for using with argument parser
+to parse CLI arguments to more usable formats.
+
+- `FileSize`: Can take `str` and `int` values. Will convert human inputs such as "121 KB",
+  "21MiB", or "4.56 GB" to bytes. Can also be used to represent bytes value in more
+  human-readable formats.
+
+For even more control you can still define Logger, Handlers, and Formatters manually.
+
+#### Example of `FileSize` usage
+
+```python
+from pathlib import Path
+
+import log21
+from log21.helper_types import FileSize
+
+
+def main(path: Path, min_size: FileSize, max_size: FileSize, /):
+    log21.info(
+        "Files that are smaller than %s or bigger than %s will be ignored.",
+        args=(min_size, max_size),
+    )
+
+    for file in path.iterdir():
+        if not file.is_file():
+            continue
+        if min_size <= (size := file.stat().st_size) <= max_size:
+            log21.print(
+                "`%s` is %s.",
+                args=(file, FileSize(size).humanize(binary=False, fmt="%.4f")),
+            )
+
+
+if __name__ == "__main__":
+    log21.argumentify(main)
+```
+
+Example usage and output:
+
+```shell
+$ uv run test.py . "1.23MiB" "0.5 GB"
+[21:21:21] [INFO] Files that are smaller than 1.23 MiB or bigger than 476.84 MiB will be
+ignored.
+`myfile21.zip` is 35.1856 MB.
+```
+
 ### v3.2.0
 
 Add `file_mode` and `file_encoding` parameters to `get_logger` for finer control over
 the way a simple logger handles files.
 
 For even more control you can still define Logger, Handlers, and Formatters manually.
 
-#### Example
+#### Example of using `get_logger` with a file
 
 ```python
 import log21

README.md

@@ -69,24 +69,55 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.2.0
+### v3.3.0
 
-Add `file_mode` and `file_encoding` parameters to `get_logger` for finer control over
-the way a simple logger handles files.
+Add `log21.helper_types` module.
+
+This module contains a collection of useful types meant for using with argument parser
+to parse CLI arguments to more usable formats.
+
++ `FileSize`: Can take `str` and `int` values. Will convert human inputs such as "121 KB",
+  "21MiB", or "4.56 GB" to bytes. Can also be used to represent bytes value in more
+  human-readable formats.
 
 For even more control you can still define Logger, Handlers, and Formatters manually.
 
 #### Example
 
 ```python
+from pathlib import Path
+
 import log21
+from log21.helper_types import FileSize
+
+
+def main(path: Path, min_size: FileSize, max_size: FileSize, /):
+    log21.info(
+        "Files that are smaller than %s or bigger than %s will be ignored.",
+        args=(min_size, max_size),
+    )
+
+    for file in path.iterdir():
+        if not file.is_file():
+            continue
+        if min_size <= (size := file.stat().st_size) <= max_size:
+            log21.print(
+                "`%s` is %s.",
+                args=(file, FileSize(size).humanize(binary=False, fmt="%.4f")),
+            )
+
+
+if __name__ == "__main__":
+    log21.argumentify(main)
+```
 
-logger = log21.get_logger(
-    "My File Logger", show_level=False, show_time=True, file="myapp.log", file_mode="a",
-    file_encoding="utf-8"
-)
+Example usage and output:
 
-logger.info("Hello World!")
+```shell
+$ uv run test.py . "1.23MiB" "0.5 GB"
+[21:21:21] [INFO] Files that are smaller than 1.23 MiB or bigger than 476.84 MiB will be
+ignored.
+`myfile21.zip` is 35.1856 MB.
 ```
 
 [Full CHANGELOG](https://github.com/MPCodeWriter21/log21/blob/master/CHANGELOG.md)

pyproject.toml

@@ -23,7 +23,7 @@ dependencies = [
     "webcolors",
     "docstring-parser"
 ]
-version = "3.2.0"
+version = "3.3.0"
 
 [build-system]
 requires = ["uv_build>=0.8.15,<0.9.0"]

src/log21/__init__.py

@@ -10,6 +10,8 @@
 from typing import (Type as _Type, Union as _Union, Literal as _Literal,
                     Mapping as _Mapping, Iterable as _Iterable, Optional as _Optional)
 
+import log21.helper_types
+
 from . import crash_reporter
 from .colors import (Colors, get_color, get_colors, ansi_escape, closest_color,
                      get_color_name)
@@ -31,7 +33,7 @@
 # yapf: enable
 
 __author__ = 'CodeWriter21 (Mehrad Pooryoussof)'
-__version__ = '3.2.0'
+__version__ = '3.3.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',
@@ -44,7 +46,7 @@
     'log', 'basic_config', 'basicConfig', 'ProgressBar', 'LoggingWindow',
     'LoggingWindowHandler', 'get_logging_window', 'crash_reporter', 'console_reporter',
     'file_reporter', 'argumentify', 'ArgumentError', 'IncompatibleArgumentsError',
-    'RequiredArgumentError', 'TooFewArgumentsError'
+    'RequiredArgumentError', 'TooFewArgumentsError', 'FileHandler'
 ]
 
 _manager = Manager()

src/log21/helper_types.py

@@ -0,0 +1,126 @@
+# log21.helper_types.py
+# CodeWriter21
+"""A collection of useful types meant for using with argument parser to parse CLI
+arguments to more usable formats.
+
++ FileSize: Can take `str` and `int` values. Will convert human inputs such as "121 KB",
+  "21MiB", or "4.56 GB" to bytes. Can also be used to represent bytes value in more
+  human-readable formats.
+"""
+
+# yapf: disable
+
+import re as _re
+from math import log as _log
+from typing import Union as _Union, SupportsInt as _SupportsInt
+
+# yapf: enable
+
+__all__ = ["FileSize"]
+
+POWERS = "KMGTPEZYRQ"
+FILE_SIZE_PATTERN = _re.compile(rf"^([+-]?[0-9]+(?:\.[0-9]+)?)\s*(|[{POWERS}])(i?)B$")
+
+
+class FileSize:
+
+    def __init__(self, value: _Union[int, str]) -> None:
+        """An interface for converting different inputs to file-size (bytes).
+
+        :param value: int value in bytes or a string such as "100 KB", "20MiB", or "1.23
+            GB"
+        :raises TypeError: If the value is not of type int or str
+        :raises ValueError: If the str value does not match the file-size pattern:
+            ^([+-]?[0-9]+(?:\\.[0-9]+)?)\\s*(|[KMGTPEZYRQ])(i?)B$
+        """
+        if isinstance(value, int):
+            self.bytes = value
+        elif isinstance(value, str):
+            match = FILE_SIZE_PATTERN.match(value)
+            if not match:
+                raise ValueError(f"Input does not match the file-size pattern: {value}")
+            val, prefix, binary = match.groups()
+            power = POWERS.index(prefix) + 1
+            assert power is not None
+            self.bytes = int(float(val) * (1024 if binary else 1000)**power)
+        else:
+            raise TypeError(f"Input to FileSize() can be int or str, not {type(value)}")
+
+    def humanize(
+        self,
+        binary: bool = False,
+        gnu: bool = False,
+        fmt: str = "%.2f",
+    ) -> str:
+        """Returns the size in a human readable way."""
+        base = 1024 if (gnu or binary) else 1000
+        abs_bytes = abs(self.bytes)
+
+        if abs_bytes == 1 and not gnu:
+            return f"{self.bytes} Byte"
+
+        if abs_bytes < base:
+            return f"{self.bytes}B" if gnu else f"{self.bytes} Bytes"
+
+        power = int(min(_log(abs_bytes, base), len(POWERS)))
+        result: str = fmt % (self.bytes / (base**power))
+        if gnu:
+            return result + POWERS[power - 1]
+        result += " " + POWERS[power - 1]
+        if binary:
+            result += "i"
+        result += "B"
+        return result
+
+    @property
+    def KB(self) -> float:
+        return self.bytes / 1000
+
+    @property
+    def MB(self) -> float:
+        return self.bytes / 1000_000
+
+    @property
+    def GB(self) -> float:
+        return self.bytes / 1000_000_000
+
+    @property
+    def KiB(self) -> float:
+        return self.bytes / 1024
+
+    @property
+    def MiB(self) -> float:
+        return self.bytes / 1048576
+
+    @property
+    def GiB(self) -> float:
+        return self.bytes / 1073741824
+
+    def __int__(self) -> int:
+        return self.bytes
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, _SupportsInt):
+            return False
+        return self.bytes == int(value)
+
+    def __lt__(self, value: _SupportsInt) -> bool:
+        return self.bytes < int(value)
+
+    def __le__(self, value: _SupportsInt) -> bool:
+        return self.bytes <= int(value)
+
+    def __gt__(self, value: _SupportsInt) -> bool:
+        return int(value) < self.bytes
+
+    def __ge__(self, value: _SupportsInt) -> bool:
+        return int(value) <= self.bytes
+
+    def __add__(self, value: _SupportsInt) -> "FileSize":
+        return FileSize(self.bytes + int(value))
+
+    def __str__(self) -> str:
+        return self.humanize(binary=True)
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: '{self!s}'>"