log21 3.1.0__tar.gz → 3.3.0__tar.gz

{log21-3.1.0 → log21-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: log21
-Version: 3.1.0
+Version: 3.3.0
 Summary: A simple logging package
 Keywords: python,log,colorize,color,logging,Python3,CodeWriter21
 Author: CodeWriter21(Mehrad Pooryoussof)
@@ -94,140 +94,57 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.1.0
+### v3.3.0
 
-Change the way `argumentify` handles function parameters to argument-parser arguments
-conversion.
+Add `log21.helper_types` module.
 
-+ `POSITIONAL_ONLY` and `VAR_POSITIONAL` parameters will be positional arguments.
-+ `POSITIONAL_OR_KEYWORD` and `KEYWORD_ONLY` parameters have flags assigned to them.
-+ `POSITIONAL_OR_KEYWORD` parameters will be required if at least one `KEYWORD_ONLY`
-  parameter is there, otherwise they are optional.
-+ `VAR_KEYWORD` parameters are still not supported.
+This module contains a collection of useful types meant for using with argument parser
+to parse CLI arguments to more usable formats.
 
-#### Example 1
++ `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.
 
-```python
-def main(path: Path, /, output: Path, *, verbose: bool = False):
-    """Process a file.
-
-    :param path: The input file path
-    :param output: The output file
-    :param verbose: Write more logs to the standard output.
-    """
-    ...
-
-
-if __name__ == "__main__":
-    argumentify(main)
-```
-
-The help looks like this:
-
-```help
-usage: test.py [-h] --output OUTPUT [--verbose] path
-
-Process a file.
-
-positional arguments:
-  path              The input file path
-
-options:
-  -h, --help
-                        show this help message and exit
-  --output OUTPUT, -o OUTPUT
-                        The output file
-  --verbose, -v
-                        Write more logs to the standard output.
-
-```
+For even more control you can still define Logger, Handlers, and Formatters manually.
 
-_Note that `path` and `output` are required._
-
-#### Example 2
+#### Example
 
 ```python
-def main(output: Path, /, *inputs: Path):
-    """Process multiple files into one.
-
-    :param output: The output file
-    :param inputs: The path to the input files
-    """
-    # Since `inputs` is a VAR_POSITIONAL, while being a positional argument, it can have
-    # zero length which is in many cases not intended.
-    # You might want to add a check for its length and raise an ArgumentError if it does
-    # not match your needs
-
-    # Check if at least one input has been passed and mark the argument as required
-    # if len(inputs) < 1:
-    #     raise RequiredArgumentError("inputs")
-
-    # Raise an error unless at least two inputs are present
-    if len(inputs) < 2:
-        raise ArgumentError(message="You need to pass at least two files as input.")
-    ...
-```
+from pathlib import Path
 
-The help looks like this:
+import log21
+from log21.helper_types import FileSize
 
-```help
-usage: test.py [-h] output [inputs ...]
 
-Process multiple files into one.
+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),
+    )
 
-positional arguments:
-  output            The output file
-  inputs            The path to the input files
-
-options:
-  -h, --help
-                        show this help message and exit
-
-```
-
-#### Example 3
-
-```python
-def main(first_name: str, last_name: str, output: Path, verbose: bool = False):
-    """Write a greeting message.
-
-    :param first_name: The first name of the user to greet (optional)
-    :param last_name: The last name of the user to greet (optional)
-    :param output: The output file (stdout if none is provided)
-    :param verbose: If provided, will write the debug logs to stdout
-    """
-    ...
+    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__":
-    argumentify(main)
+    log21.argumentify(main)
 ```
 
-The help looks like this:
-
-```help
-usage: test.py [-h] [--first-name FIRST_NAME] [--last-name LAST_NAME] [--output OUTPUT]
-               [--verbose]
-
-Write a greeting message.
-
-options:
-  -h, --help
-                        show this help message and exit
-  --first-name FIRST_NAME, -f FIRST_NAME
-                        The first name of the user to greet (optional)
-  --last-name LAST_NAME, -l LAST_NAME
-                        The last name of the user to greet (optional)
-  --output OUTPUT, -o OUTPUT
-                        The output file (stdout if none is provided)
-  --verbose, -v
-                        If provided, will write the debug logs to stdout
+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.
 ```
 
-_Note that all the options are optional and default to None. `verbose` is False by
-default since a default value is provided for it in function definition._
-
 [Full CHANGELOG](https://github.com/MPCodeWriter21/log21/blob/master/CHANGELOG.md)
 
 Usage Examples

{log21-3.1.0 → log21-3.3.0}/README.md

@@ -69,140 +69,57 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.1.0
+### v3.3.0
 
-Change the way `argumentify` handles function parameters to argument-parser arguments
-conversion.
+Add `log21.helper_types` module.
 
-+ `POSITIONAL_ONLY` and `VAR_POSITIONAL` parameters will be positional arguments.
-+ `POSITIONAL_OR_KEYWORD` and `KEYWORD_ONLY` parameters have flags assigned to them.
-+ `POSITIONAL_OR_KEYWORD` parameters will be required if at least one `KEYWORD_ONLY`
-  parameter is there, otherwise they are optional.
-+ `VAR_KEYWORD` parameters are still not supported.
+This module contains a collection of useful types meant for using with argument parser
+to parse CLI arguments to more usable formats.
 
-#### Example 1
++ `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.
 
-```python
-def main(path: Path, /, output: Path, *, verbose: bool = False):
-    """Process a file.
-
-    :param path: The input file path
-    :param output: The output file
-    :param verbose: Write more logs to the standard output.
-    """
-    ...
-
-
-if __name__ == "__main__":
-    argumentify(main)
-```
-
-The help looks like this:
-
-```help
-usage: test.py [-h] --output OUTPUT [--verbose] path
-
-Process a file.
-
-positional arguments:
-  path              The input file path
-
-options:
-  -h, --help
-                        show this help message and exit
-  --output OUTPUT, -o OUTPUT
-                        The output file
-  --verbose, -v
-                        Write more logs to the standard output.
-
-```
+For even more control you can still define Logger, Handlers, and Formatters manually.
 
-_Note that `path` and `output` are required._
-
-#### Example 2
+#### Example
 
 ```python
-def main(output: Path, /, *inputs: Path):
-    """Process multiple files into one.
-
-    :param output: The output file
-    :param inputs: The path to the input files
-    """
-    # Since `inputs` is a VAR_POSITIONAL, while being a positional argument, it can have
-    # zero length which is in many cases not intended.
-    # You might want to add a check for its length and raise an ArgumentError if it does
-    # not match your needs
-
-    # Check if at least one input has been passed and mark the argument as required
-    # if len(inputs) < 1:
-    #     raise RequiredArgumentError("inputs")
-
-    # Raise an error unless at least two inputs are present
-    if len(inputs) < 2:
-        raise ArgumentError(message="You need to pass at least two files as input.")
-    ...
-```
+from pathlib import Path
 
-The help looks like this:
+import log21
+from log21.helper_types import FileSize
 
-```help
-usage: test.py [-h] output [inputs ...]
 
-Process multiple files into one.
+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),
+    )
 
-positional arguments:
-  output            The output file
-  inputs            The path to the input files
-
-options:
-  -h, --help
-                        show this help message and exit
-
-```
-
-#### Example 3
-
-```python
-def main(first_name: str, last_name: str, output: Path, verbose: bool = False):
-    """Write a greeting message.
-
-    :param first_name: The first name of the user to greet (optional)
-    :param last_name: The last name of the user to greet (optional)
-    :param output: The output file (stdout if none is provided)
-    :param verbose: If provided, will write the debug logs to stdout
-    """
-    ...
+    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__":
-    argumentify(main)
+    log21.argumentify(main)
 ```
 
-The help looks like this:
-
-```help
-usage: test.py [-h] [--first-name FIRST_NAME] [--last-name LAST_NAME] [--output OUTPUT]
-               [--verbose]
-
-Write a greeting message.
-
-options:
-  -h, --help
-                        show this help message and exit
-  --first-name FIRST_NAME, -f FIRST_NAME
-                        The first name of the user to greet (optional)
-  --last-name LAST_NAME, -l LAST_NAME
-                        The last name of the user to greet (optional)
-  --output OUTPUT, -o OUTPUT
-                        The output file (stdout if none is provided)
-  --verbose, -v
-                        If provided, will write the debug logs to stdout
+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.
 ```
 
-_Note that all the options are optional and default to None. `verbose` is False by
-default since a default value is provided for it in function definition._
-
 [Full CHANGELOG](https://github.com/MPCodeWriter21/log21/blob/master/CHANGELOG.md)
 
 Usage Examples

{log21-3.1.0 → log21-3.3.0}/pyproject.toml

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

{log21-3.1.0 → log21-3.3.0}/src/log21/__init__.py

@@ -10,6 +10,8 @@ from types import ModuleType as _ModuleType
 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 @@ from .stream_handler import StreamHandler, ColorizingStreamHandler
 # yapf: enable
 
 __author__ = 'CodeWriter21 (Mehrad Pooryoussof)'
-__version__ = '3.1.0'
+__version__ = '3.3.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',
@@ -44,7 +46,7 @@ __all__ = [
     '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()
@@ -60,7 +62,8 @@ def _prepare_formatter(
     colorize_time_and_level: bool = True,
     level_names: _Optional[_Mapping[int, str]] = None,
     level_colors: _Optional[_Mapping[int, tuple[str, ...]]] = None,
-    formatter_class: _Type[_logging.Formatter] = ColorizingFormatter
+    formatter_class: _Type[_logging.Formatter] = ColorizingFormatter,
+    prefix_carriage_return: bool = True,
 ) -> _logging.Formatter:
     # Prepares a formatting if the fmt was None
     if not fmt:
@@ -70,7 +73,8 @@ def _prepare_formatter(
             fmt = '[%(levelname)s] ' + fmt
         if show_time:
             fmt = '[%(asctime)s] ' + fmt
-        fmt = '\r' + fmt
+        if prefix_carriage_return:
+            fmt = '\r' + fmt
 
     if level_colors and not issubclass(formatter_class, ColorizingFormatter):
         warning(
@@ -116,7 +120,10 @@ def get_logger(
     override: bool = False,
     level_names: _Optional[_Mapping[int, str]] = None,
     level_colors: _Optional[_Mapping[int, tuple[str, ...]]] = None,
-    file: _Optional[_Union[_os.PathLike, str]] = None
+    # TODO: Rename file to file_path in one future update
+    file: _Optional[_Union[_os.PathLike, str]] = None,
+    file_mode: _Optional[str] = None,
+    file_encoding: _Optional[str] = None,
 ) -> Logger:
     """Returns a logging.Logger with colorizing support.
 
@@ -182,7 +189,9 @@ def get_logger(
     :param level_names: Mapping[int, str] = None: You can specify custom level names.
     :param level_colors: Mapping[int, Tuple[str, ...]] = None: You can specify custom
         level colors.
-    :param file: Union[os.PathLike, str] = None: The file to log to
+    :param file: Union[os.PathLike, str] = None: The file path to log to
+    :param file_mode: str = None: The mode to open file at (Defaults to 'a')
+    :param file_encoding: str = None: The file encoding
     :return: log21.Logger
     """
     if not isinstance(name, str):
@@ -209,7 +218,9 @@ def get_logger(
         _manager.addLogger(name, logger)
 
         if file:
-            file_handler = FileHandler(file)
+            file_handler = DecolorizingFileHandler(
+                file, mode=file_mode or 'a', encoding=file_encoding
+            )
             file_formatter = _prepare_formatter(
                 fmt,
                 style,
@@ -218,7 +229,8 @@ def get_logger(
                 show_time,
                 False,
                 level_names,
-                formatter_class=DecolorizingFormatter
+                formatter_class=DecolorizingFormatter,
+                prefix_carriage_return=False,
             )
             file_handler.setFormatter(file_formatter)
             logger.addHandler(file_handler)

log21-3.3.0/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}'>"