Merge pull request #143 from jakob-bagterp/documentation/add-hex-colo…

…r-options-to-readme

Documentation: Add Hex color options and examples of ColorHex and BgColorHex

README.md

@@ -110,8 +110,8 @@ Both options appear the same in the terminal:
 
 ![Example of terminal message with red text color](/assets/images/examples/color_custom_text_red.png)
 
-### Print RGB and HSL Colors
-Note that not all terminals support RGB or HSL colors. If your terminal does support such advanced colors, read on.
+### Print RGB, HSL and Hex Colors
+Note that not all terminals support RGB, HSL or Hex colors. If your terminal does support such advanced colors, read on.
 
 #### RGB Colors
 Try the `rgb` and `bg_rgb` methods for a full line of colored text. The values for red, green, blue can be an integer between `0-255`.
@@ -171,6 +171,35 @@ How it appears in the terminal:
 
 ![Another example of text in HSL colors printed in a terminal window](/assets/images/examples/hsl_custom_text.png)
 
+#### Hex Colors
+Try the `hex` and `bg_hex` methods for a full line of colored text. Allowed Hex values are, for instance, `#00aaff` or `#0af`, alternatively without the hash sign as `00aaff` or `0af`.
+
+```python
+from colorist import hex, bg_hex
+
+hex("I want this text in coral Hex colors", "#ff7f50")
+bg_hex("I want this background in coral Hex colors", "#ff7f50")
+```
+
+How it appears in the terminal:
+
+![Example of text in Hex colors printed in a terminal window](/assets/images/examples/hex_full_text.png)
+
+Or customize the styling of text and background with the `ColorHex` and `BgColorHex` classes:
+
+```python
+from colorist import ColorHex, BgColorHex
+
+watermelon_red = ColorHex("#ff5733")
+bg_mint_green = BgColorHex("#99ff99")
+
+print(f"I want to use {watermelon_red}watermelon pink{watermelon_red.OFF} and {bg_mint_green}mint green{bg_mint_green.OFF} colors inside this paragraph")
+```
+
+How it appears in the terminal:
+
+![Another example of text in Hex colors printed in a terminal window](/assets/images/examples/hex_custom_text.png)
+
 ### Print Effects and Other Styles
 In addition to colors, Colorist can also add effects when you print text in the terminal. How to print a full line of text with effects:
 
@@ -227,11 +256,11 @@ Similar to `Color.OFF`, remember to turn off an effect with the relevant reset o
 # Supported Colors and Styles
 Colorist is based on [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code), a standard that defines colors, styling and effects for text in terminal windows. Note that most terminals support all color options, but not all:
 
-| Category                                               | Color Options                                      |
-| ------------------------------------------------------ | -------------------------------------------------- |
-| Standard ANSI colors supported by almost all terminals | `Color`, `BgColor`, `Effect`                       |
-| Non-standard ANSI colors supported by most terminals   | `BrightColor`, `BgBrightColor`                     |
-| Advanced ANSI colors only supported by some terminals  | `ColorRGB`, `BgColorRGB`, `ColorHSL`, `BgColorHSL` |
+| Category                                               | Color Options                                                                |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Standard ANSI colors supported by almost all terminals | `Color`, `BgColor`, `Effect`                                                 |
+| Non-standard ANSI colors supported by most terminals   | `BrightColor`, `BgBrightColor`                                               |
+| Advanced ANSI colors only supported by some terminals  | `ColorRGB`, `BgColorRGB`, `ColorHSL`, `BgColorHSL`, `ColorHex`, `BgColorHex` |
 
 ## Foreground Text
 | Color | Full Text Function | Custom | Example |

src/colorist/helper/convert.py

@@ -33,7 +33,7 @@ def hsl_to_rgb(hue: float, saturation: float, lightness: float) -> tuple[int, in
 
 
 def hex_to_rgb(hex: str) -> tuple[int, int, int]:
-    """Convert hex color to RGB. Expects valid hex value, for instance #B4FBB8 or B4FBB8, #B4F or B4F."""
+    """Convert Hex color to RGB. Expects valid Hex color value, for instance #B4FBB8 or B4FBB8, #B4F or B4F."""
 
     hex = hex.lstrip("#")
     if len(hex) == 3:

src/colorist/helper/error.py

@@ -13,4 +13,4 @@ def message_for_hsl_percentage_value_error(param: str, value: float) -> str:
 
 
 def message_for_hex_value_error(value: str) -> str:
-    return f"Value {value} isn't valid hex colour code, and should be for instance #B4FBB8 or B4FBB8, #B4F or B4F."
+    return f"Value {value} isn't valid Hex color code, and should be for instance #B4FBB8 or B4FBB8, #B4F or B4F."

src/colorist/model/abc/hex.py

@@ -11,7 +11,7 @@
 
 
 class Hex_ABC(ABC):
-    """Abstract base class for custom hex color instances."""
+    """Abstract base class for custom Hex color instances."""
 
     OFF = RESET_ALL
 
@@ -33,7 +33,7 @@ def __repr__(self) -> str:
         return f"Hex: #{self.hex.lstrip('#')}"
 
     def convert_hex_to_rgb(self) -> RGB_ABC:
-        """Method to convert hex to RGB color."""
+        """Method to convert Hex to RGB color."""
 
         red, green, blue = helper.convert.hex_to_rgb(self.hex)
         return ColorRGB(red, green, blue)

src/colorist/model/background/hex.py

@@ -6,7 +6,7 @@
 
 
 class BgColorHex(Hex_ABC):
-    """Class for custom background color defined as hex color."""
+    """Class for custom background defined in Hex color."""
 
     def generate_ansi_code(self) -> str:
         return helper.generate.ansi_rgb_color_sequence(AnsiRgbColorSelector.BACKGROUND, self._rgb)

src/colorist/model/foreground/hex.py

@@ -6,7 +6,7 @@
 
 
 class ColorHex(Hex_ABC):
-    """Class for custom foreground text color defined as hex color."""
+    """Class for custom foreground text defined in Hex color."""
 
     def generate_ansi_code(self) -> str:
         return helper.generate.ansi_rgb_color_sequence(AnsiRgbColorSelector.FOREGROUND, self._rgb)

src/colorist/print/background/hex.py

@@ -4,7 +4,7 @@
 
 
 def bg_hex(text: str, hex: str) -> None:
-    """Prints full line of text on colored background defined by hex colors. Expects valid hex value, for instance #B4FBB8 or B4FBB8, #B4F or B4F."""
+    """Prints full line of text on colored background defined in Hex color. Expects valid Hex color value, for instance #B4FBB8 or B4FBB8, #B4F or B4F."""
 
     red, green, blue = helper.convert.hex_to_rgb(hex)
     helper.print.bg_rgb(text, red, green, blue)

src/colorist/print/foreground/hex.py

@@ -4,7 +4,7 @@
 
 
 def hex(text: str, hex: str) -> None:
-    """Prints full line of colored text defined as hex colors. Expects valid hex value, for instance #B4FBB8 or B4FBB8, #B4F or B4F."""
+    """Prints full line of text in Hex color. Expects valid Hex color value, for instance #B4FBB8 or B4FBB8, #B4F or B4F."""
 
     red, green, blue = helper.convert.hex_to_rgb(hex)
     helper.print.rgb(text, red, green, blue)

test/_examples/hex/custom_text.py

@@ -0,0 +1,11 @@
+# Copyright 2022 – present, Jakob Bagterp. BSD 3-Clause license and refer to LICENSE file.
+
+from colorist import BgColorHex, ColorHex
+
+if __name__ == "__main__":
+    watermelon_red = ColorHex("#ff5733")
+    bg_mint_green = BgColorHex("#99ff99")
+
+    print("")
+    print(f"I want to use {watermelon_red}watermelon pink{watermelon_red.OFF} and {bg_mint_green}mint green{bg_mint_green.OFF} colors inside this paragraph")
+    print("")

test/_examples/hex/full_text.py

@@ -0,0 +1,9 @@
+# Copyright 2022 – present, Jakob Bagterp. BSD 3-Clause license and refer to LICENSE file.
+
+from colorist import bg_hex, hex
+
+if __name__ == "__main__":
+    print("")
+    hex("I want this text in coral Hex colors", "#ff7f50")
+    bg_hex("I want this background in coral Hex colors", "#ff7f50")
+    print("")

test/_examples/run_examples.py

@@ -33,9 +33,15 @@ def run_terminal_examples_for_hsl_color() -> None:
     subprocess.call("python3 ./hsl/custom_text.py".split())
 
 
+def run_terminal_examples_for_hex_color() -> None:
+    subprocess.call("python3 ./hex/full_text.py".split())
+    subprocess.call("python3 ./hex/custom_text.py".split())
+
+
 if __name__ == "__main__":
     run_terminal_examples_for_color()
     run_terminal_examples_for_bright_color()
     run_terminal_examples_for_effect()
     run_terminal_examples_for_rgb_color()
     run_terminal_examples_for_hsl_color()
+    run_terminal_examples_for_hex_color()