colorful-log 0.4.0__tar.gz

colorful_log-0.4.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.3
+Name: colorful-log
+Version: 0.4.0
+Summary: tools that allow you to manipulate the style of the string
+Author: Finsa-SC
+Author-email: Finsa-SC <finsakusumaputra@gmail.com>
+Requires-Dist: typing-extensions>=4.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# colorful-log
+
+[![PyPI version](https://img.shields.io/pypi/v/colorful-log)](https://pypi.org/project/colorful-log/)
+[![Python versions](https://img.shields.io/pypi/pyversions/colorful-log)](https://pypi.org/project/colorful-log/)
+[![License](https://img.shields.io/github/license/Finsa-SC/colorfull-log)](LICENSE)
+
+A small Python library for coloring and styling terminal text, without writing raw ANSI escape codes by hand.
+
+```python
+from colorful_log import PrintLog, Colors
+
+print(PrintLog("Build succeeded").color(Colors.GREEN).bold())
+```
+
+## Why colorful-log?
+
+Terminal colors are done with escape sequences like `\033[1;32m`, which are hard to read, easy to get wrong, and easy to forget to reset. colorful-log wraps them in a small, readable API:
+
+- **Readable code.** `PrintLog("Done").color(Colors.GREEN).bold()` says what it does. No escape codes to memorize.
+- **Hex colors out of the box.** Use `"#6381f6"` directly, for both text and background.
+- **Reusable styles.** Build a template once (for example an "error" style) and reuse it for any text.
+- **Lightweight.** One small dependency (`typing-extensions`), fully typed, and works on Python 3.10+.
+
+## Installation
+
+```bash
+pip install colorful-log
+```
+
+Requires Python 3.10 or newer.
+
+## Features
+
+- Foreground and background colors from built-in colors, hex codes, or your own registered colors
+- Text styles: bold, dim, italic, underline, reverse, and strikethrough
+- Method chaining and a short `|` operator for setting the text color
+- Reusable templates with `copy()`, and an easy way to swap the text with a call
+- Custom color registry, which can also override built-in colors
+- `plain` property to get the text without any formatting
+- Separate resets for colors (`reset()`) and styles (`reset_style()`)
+- Clear `ValueError` for invalid hex colors
+
+## Usage
+
+### Basic
+
+```python
+from colorful_log import PrintLog, Colors
+
+print(PrintLog("Hello, World!").color(Colors.CYAN))
+print(PrintLog("Hello, World!").color("#6381f6").background("#1e1e2e"))
+```
+
+Built-in colors: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, `MAGENTA`, `CYAN`, `WHITE`.
+
+### Text styles
+
+Styles can be chained in any order.
+
+```python
+PrintLog("Important").bold().underline()
+PrintLog("Deprecated").dim().strikethrough()
+```
+
+Available styles: `bold()`, `dim()`, `italic()`, `underline()`, `revert()` (reverse video), `strikethrough()`.
+
+### Setting the color with `|`
+
+The `|` operator is a shortcut for setting the text color.
+
+```python
+print(PrintLog("Warning: disk almost full") | Colors.YELLOW)
+print(PrintLog("Custom") | "#ff8800")
+```
+
+### Custom colors
+
+Register a color once and use it anywhere.
+
+```python
+Colors.register("brand", "#6381f6")
+
+print(PrintLog("Brand color") | Colors.brand)
+```
+
+Registering a name that already exists replaces it, including the built-in colors:
+
+```python
+Colors.register("RED", "#ff5555")   # Colors.RED is now #ff5555
+```
+
+This is global, so it affects every use of `Colors.RED` in your program.
+`RESET`, `register`, and names starting with `_` are reserved and raise a `ValueError`.
+
+### Templates
+
+Calling a `PrintLog` instance replaces its text and keeps its formatting, so you can define a style once and reuse it.
+
+```python
+error = PrintLog().color(Colors.WHITE).background(Colors.RED).bold()
+
+print(error("Something went wrong"))
+print(error("Another error"))
+```
+
+> Calling an instance (and using `+`) modifies that same object and returns it.
+> If you need independent results, use `copy()`:
+>
+> ```python
+> a = error.copy()("First")
+> b = error.copy()("Second")
+> ```
+
+### Appending text
+
+```python
+msg = PrintLog("Hello")
+print(msg + ", World!")      # appends to the existing text
+```
+
+### Plain text
+
+`plain` returns the text without any color or style codes, which is useful for logs or files.
+
+```python
+error("Disk full").plain     # "Disk full"
+```
+
+### Resetting
+
+```python
+style = PrintLog("text").bold().color(Colors.RED)
+
+style.reset()          # clears foreground and background colors, keeps styles
+style.reset_style()    # clears text styles, keeps colors
+```
+
+### Invalid colors
+
+Invalid hex values raise a `ValueError` with a clear message.
+
+```python
+PrintLog("x") | "#GGGGGG"
+# ValueError: Invalid HEX color: '#GGGGGG'. Expected format: '#RRGGBB'.
+```
+
+Only the `#RRGGBB` format is supported.
+
+## Notes
+
+- Hex colors use 24-bit ("truecolor") ANSI codes. Most modern terminals support them, but some older ones do not.
+- Output contains ANSI escape codes. Use `.plain` if you need clean text, for example when writing to a file.
+
+## License
+
+Released under the [MIT License](LICENSE).
+
+## Author
+
+Finsa Kusuma Putra ([@Finsa-SC](https://github.com/Finsa-SC))

colorful_log-0.4.0/README.md

@@ -0,0 +1,160 @@
+# colorful-log
+
+[![PyPI version](https://img.shields.io/pypi/v/colorful-log)](https://pypi.org/project/colorful-log/)
+[![Python versions](https://img.shields.io/pypi/pyversions/colorful-log)](https://pypi.org/project/colorful-log/)
+[![License](https://img.shields.io/github/license/Finsa-SC/colorfull-log)](LICENSE)
+
+A small Python library for coloring and styling terminal text, without writing raw ANSI escape codes by hand.
+
+```python
+from colorful_log import PrintLog, Colors
+
+print(PrintLog("Build succeeded").color(Colors.GREEN).bold())
+```
+
+## Why colorful-log?
+
+Terminal colors are done with escape sequences like `\033[1;32m`, which are hard to read, easy to get wrong, and easy to forget to reset. colorful-log wraps them in a small, readable API:
+
+- **Readable code.** `PrintLog("Done").color(Colors.GREEN).bold()` says what it does. No escape codes to memorize.
+- **Hex colors out of the box.** Use `"#6381f6"` directly, for both text and background.
+- **Reusable styles.** Build a template once (for example an "error" style) and reuse it for any text.
+- **Lightweight.** One small dependency (`typing-extensions`), fully typed, and works on Python 3.10+.
+
+## Installation
+
+```bash
+pip install colorful-log
+```
+
+Requires Python 3.10 or newer.
+
+## Features
+
+- Foreground and background colors from built-in colors, hex codes, or your own registered colors
+- Text styles: bold, dim, italic, underline, reverse, and strikethrough
+- Method chaining and a short `|` operator for setting the text color
+- Reusable templates with `copy()`, and an easy way to swap the text with a call
+- Custom color registry, which can also override built-in colors
+- `plain` property to get the text without any formatting
+- Separate resets for colors (`reset()`) and styles (`reset_style()`)
+- Clear `ValueError` for invalid hex colors
+
+## Usage
+
+### Basic
+
+```python
+from colorful_log import PrintLog, Colors
+
+print(PrintLog("Hello, World!").color(Colors.CYAN))
+print(PrintLog("Hello, World!").color("#6381f6").background("#1e1e2e"))
+```
+
+Built-in colors: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, `MAGENTA`, `CYAN`, `WHITE`.
+
+### Text styles
+
+Styles can be chained in any order.
+
+```python
+PrintLog("Important").bold().underline()
+PrintLog("Deprecated").dim().strikethrough()
+```
+
+Available styles: `bold()`, `dim()`, `italic()`, `underline()`, `revert()` (reverse video), `strikethrough()`.
+
+### Setting the color with `|`
+
+The `|` operator is a shortcut for setting the text color.
+
+```python
+print(PrintLog("Warning: disk almost full") | Colors.YELLOW)
+print(PrintLog("Custom") | "#ff8800")
+```
+
+### Custom colors
+
+Register a color once and use it anywhere.
+
+```python
+Colors.register("brand", "#6381f6")
+
+print(PrintLog("Brand color") | Colors.brand)
+```
+
+Registering a name that already exists replaces it, including the built-in colors:
+
+```python
+Colors.register("RED", "#ff5555")   # Colors.RED is now #ff5555
+```
+
+This is global, so it affects every use of `Colors.RED` in your program.
+`RESET`, `register`, and names starting with `_` are reserved and raise a `ValueError`.
+
+### Templates
+
+Calling a `PrintLog` instance replaces its text and keeps its formatting, so you can define a style once and reuse it.
+
+```python
+error = PrintLog().color(Colors.WHITE).background(Colors.RED).bold()
+
+print(error("Something went wrong"))
+print(error("Another error"))
+```
+
+> Calling an instance (and using `+`) modifies that same object and returns it.
+> If you need independent results, use `copy()`:
+>
+> ```python
+> a = error.copy()("First")
+> b = error.copy()("Second")
+> ```
+
+### Appending text
+
+```python
+msg = PrintLog("Hello")
+print(msg + ", World!")      # appends to the existing text
+```
+
+### Plain text
+
+`plain` returns the text without any color or style codes, which is useful for logs or files.
+
+```python
+error("Disk full").plain     # "Disk full"
+```
+
+### Resetting
+
+```python
+style = PrintLog("text").bold().color(Colors.RED)
+
+style.reset()          # clears foreground and background colors, keeps styles
+style.reset_style()    # clears text styles, keeps colors
+```
+
+### Invalid colors
+
+Invalid hex values raise a `ValueError` with a clear message.
+
+```python
+PrintLog("x") | "#GGGGGG"
+# ValueError: Invalid HEX color: '#GGGGGG'. Expected format: '#RRGGBB'.
+```
+
+Only the `#RRGGBB` format is supported.
+
+## Notes
+
+- Hex colors use 24-bit ("truecolor") ANSI codes. Most modern terminals support them, but some older ones do not.
+- Output contains ANSI escape codes. Use `.plain` if you need clean text, for example when writing to a file.
+
+## License
+
+Released under the [MIT License](LICENSE).
+
+## Author
+
+Finsa Kusuma Putra ([@Finsa-SC](https://github.com/Finsa-SC))

colorful_log-0.4.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "colorful-log"
+version = "0.4.0"
+description = "tools that allow you to manipulate the style of the string"
+readme = "README.md"
+authors = [
+    { name = "Finsa-SC", email = "finsakusumaputra@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "typing-extensions>=4.10",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.18,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

colorful_log-0.4.0/src/colorful_log/__init__.py

@@ -0,0 +1,3 @@
+from colorful_log.logger import PrintLog
+from colorful_log.colors import Colors
+from colorful_log.styles import Styles

colorful_log-0.4.0/src/colorful_log/colors.py

@@ -0,0 +1,34 @@
+class ColorsMeta(type):
+    def __getattribute__(cls, name: str):
+        if not name.startswith("_"):
+            custom = type.__getattribute__(cls, "_custom_colors")
+            if name in custom:
+                return custom[name]
+
+        try:
+            return type.__getattribute__(cls, name)
+        except AttributeError as e:
+            raise AttributeError(
+                f"Colors has no attribute {name!r}"
+            ) from e
+
+class Colors(metaclass=ColorsMeta):
+    _custom_colors: dict[str, str] = {}
+    _reserved = {"RESET", "register"}
+
+    @classmethod
+    def register(cls, name: str, value: str):
+        if name in cls._reserved or name.startswith("_"):
+            raise ValueError(f"{name!r} is reserved and cannot be registered")
+
+        cls._custom_colors[name] = value
+
+    BLACK = "0"
+    RED = "1"
+    GREEN = "2"
+    YELLOW = "3"
+    BLUE = "4"
+    MAGENTA = "5"
+    CYAN = "6"
+    WHITE = "7"
+    RESET = "9"

colorful_log-0.4.0/src/colorful_log/engine.py

@@ -0,0 +1,36 @@
+import re
+
+
+class PrintLogEngine:
+    @staticmethod
+    def _set_text(num: str) -> str:
+        if num.startswith("\033"):
+            return num
+        return f"\033[3{num}m"
+
+    @staticmethod
+    def _set_back(num: str) -> str:
+        if num.startswith("\033"):
+            return num
+        return f"\033[4{num}m"
+
+    @staticmethod
+    def hex_to_rgb(hex_color: str, background: bool = False) -> str:
+        if not re.fullmatch(r"#[0-9a-fA-F]{6}", hex_color):
+            raise ValueError(
+                f"Invalid HEX color: {hex_color!r}. "
+                "Expected format: '#RRGGBB'."
+            )
+
+        hex_color = hex_color.lstrip('#')
+
+        if len(hex_color) != 6:
+            raise ValueError("HEX color must contain 6 digits.")
+
+        r = int(hex_color[0:2], 16)
+        g = int(hex_color[2:4], 16)
+        b = int(hex_color[4:6], 16)
+
+        code = "4" if background else "3"
+
+        return f"\033[{code}8;2;{r};{g};{b}m"

colorful_log-0.4.0/src/colorful_log/logger.py

@@ -0,0 +1,67 @@
+from colorful_log.engine import PrintLogEngine
+from colorful_log.colors import Colors
+from colorful_log.styles import StylesAPI
+from copy import copy
+
+class PrintLog(PrintLogEngine, StylesAPI):
+    def __init__(self, text: str = ""):
+        super().__init__("")
+        self._palette          = Colors
+        self.text               = text
+        self._text_color       = ""
+        self._background_color = ""
+        self._text_style       = ""
+
+    """Dunder"""
+    def __str__(self) -> str:
+        return (
+            f"{self._background_color}"
+            f"{self._text_color}"
+            f"{self._text_style}"
+            f"{self.text}"
+            f"\033[0m"
+        )
+
+    def __or__(self, other: str) -> "PrintLog":
+        if other.startswith('#'):
+            self._text_color = self.hex_to_rgb(other)
+        else:
+            self._text_color = self._set_text(other)
+        return self
+
+    def __add__(self, other) -> "PrintLog":
+        self.text += other
+        return self
+
+    def __call__(self, text: str):
+        self.text = text
+        return self
+
+    """API"""
+    ## Foreground and Background colors
+    def color(self, color: str) -> "PrintLog":
+        if color.startswith("#"):
+            self._text_color = self.hex_to_rgb(color)
+        else:
+            self._text_color = self._set_text(color)
+
+        return self
+
+    def background(self, color: str) -> "PrintLog":
+        if color.startswith("#"):
+            self._background_color = self.hex_to_rgb(color, background=True)
+        else:
+            self._background_color = self._set_back(color)
+        return self
+
+    def reset(self) -> "PrintLog":
+        self._text_color = self._set_text(self._palette.RESET)
+        self._background_color = self._set_back(self._palette.RESET)
+        return self
+
+    @property
+    def plain(self) -> str:
+        return self.text
+
+    def copy(self) -> "PrintLog":
+        return copy(self)

colorful_log-0.4.0/src/colorful_log/styles.py

@@ -0,0 +1,43 @@
+from typing_extensions import Self
+
+class Styles:
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    ITALIC = "\033[3m"
+    UNDERLINE = "\033[4m"
+    REVERSE = "\033[7m"
+    STRIKETHROUGH = "\033[9m"
+    RESET = "\033[22m\033[23m\033[24m\033[27m\033[29m"
+
+class StylesAPI:
+    def __init__(self, text_style: str):
+        self._text_style = text_style
+        self._styles = Styles()
+
+    def bold(self) -> Self:
+        self._text_style += self._styles.BOLD
+        return self
+
+    def italic(self) -> Self:
+        self._text_style += self._styles.ITALIC
+        return self
+
+    def underline(self) -> Self:
+        self._text_style += self._styles.UNDERLINE
+        return self
+
+    def revert(self) -> Self:
+        self._text_style += self._styles.REVERSE
+        return self
+
+    def dim(self) -> Self:
+        self._text_style += self._styles.DIM
+        return self
+
+    def strikethrough(self) -> Self:
+        self._text_style += self._styles.STRIKETHROUGH
+        return self
+
+    def reset_style(self) -> Self:
+        self._text_style = self._styles.RESET
+        return self