escansi 0.1.0__tar.gz

escansi-0.1.0/.gitignore

@@ -0,0 +1 @@
+**/__pycache__

escansi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo JRSM Vieira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

escansi-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: escansi
+Version: 0.1.0
+Summary: Python library to easily create ANSI escape codes and add them to your text.
+Project-URL: Homepage, https://github.com/ricardojrsmvieira/escansi
+Project-URL: Issues, https://github.com/ricardojrsmvieira/escansi/issues
+Author-email: Ricardo JRSM Vieira <ricardojrsmvieira@gmail.com>
+Maintainer-email: Ricardo JRSM Vieira <ricardojrsmvieira@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Printing
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: >=3.0
+Description-Content-Type: text/markdown
+
+# escansi
+Python library to easily create ANSI escape codes and add them to your text.

escansi-0.1.0/README.md

@@ -0,0 +1,2 @@
+# escansi
+Python library to easily create ANSI escape codes and add them to your text.

escansi-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "escansi"
+version = "0.1.0"
+authors = [
+  { name = "Ricardo JRSM Vieira", email = "ricardojrsmvieira@gmail.com" }
+]
+maintainers = [
+  { name = "Ricardo JRSM Vieira", email = "ricardojrsmvieira@gmail.com" }
+]
+description = "Python library to easily create ANSI escape codes and add them to your text."
+readme = "README.md"
+requires-python = ">=3.0"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Printing",
+    "Topic :: Terminals",
+    "Typing :: Typed"
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.urls]
+Homepage = "https://github.com/ricardojrsmvieira/escansi"
+Issues = "https://github.com/ricardojrsmvieira/escansi/issues"

escansi-0.1.0/src/escansi/__init__.py

@@ -0,0 +1,14 @@
+from .utils import (
+  BackColor as BackColor,
+  Clear as Clear,
+  Cursor as Cursor,
+  ForeColor as ForeColor,
+  Format as Format,
+  ResetFormat as ResetFormat
+)
+from .types import (
+  ColorNameType as ColorNameType,
+  ClearActionNameType as ClearActionNameType,
+  CursorActionNameType as CursorActionNameType,
+  FormatNameType as FormatNameType
+)

escansi-0.1.0/src/escansi/constants.py

@@ -0,0 +1,116 @@
+from typing import Literal, get_args
+
+from .types import (
+  ClearActionNameType,
+  ColorNameType,
+  CursorActionNameType,
+  CursorActionsThatHaveNoNumberParametersNameType,
+  CursorActionsThatHaveOneNumberParameterNameType,
+  CursorActionsThatHaveTwoNumberParametersNameType,
+  FormatNameType
+)
+
+
+COLOR_CODES: dict[Literal["foreground", "background"], dict[ColorNameType, int]] = {
+  "foreground": {
+    "black": 30,
+    "red": 31,
+    "green": 32,
+    "yellow": 33,
+    "blue": 34,
+    "magenta": 35,
+    "cyan": 36,
+    "white": 37,
+    "default": 39,
+    "bright_black": 90,
+    "bright_red": 91,
+    "bright_green": 92,
+    "bright_yellow": 93,
+    "bright_blue": 94,
+    "bright_magenta": 95,
+    "bright_cyan": 96,
+    "bright_white": 97
+  },
+  "background": {
+    "black": 40,
+    "red": 41,
+    "green": 42,
+    "yellow": 43,
+    "blue": 44,
+    "magenta": 45,
+    "cyan": 46,
+    "white": 47,
+    "default": 49,
+    "bright_black": 100,
+    "bright_red": 101,
+    "bright_green": 102,
+    "bright_yellow": 103,
+    "bright_blue": 104,
+    "bright_magenta": 105,
+    "bright_cyan": 106,
+    "bright_white": 107
+  }
+}
+
+
+FORMAT_CODES: dict[Literal["apply", "reset"], dict[FormatNameType, int]] = {
+  "apply": {
+    "bold": 1,
+    "dim": 2,
+    "italic": 3,
+    "underline": 4,
+    "blink": 5,
+    "swap_colors": 7,
+    "hidden": 8,
+    "strikethrough": 9
+  },
+  "reset": {
+    "bold": 21,
+    "dim": 22,
+    "italic": 23,
+    "underline": 24,
+    "blink": 25,
+    "swap_colors": 27,
+    "hidden": 28,
+    "strikethrough": 29
+  }
+}
+
+
+CURSOR_CODES: dict[CursorActionNameType, str] = {
+  "up": "A",                    "u": "A",
+  "down": "B",                  "d": "B",
+  "forward": "C",               "f": "C",
+  "backward": "D",              "b": "D",
+  "start_of_line_down": "E",    "sold": "E",
+  "start_of_line_up": "F",      "solu": "F",
+  "move_to_column": "G",        "mtc": "G",
+  "move_to_position": "H",      "mtp": "H",
+  "save_position": "s",         "sp": "s",
+  "restore_position": "u",      "rp": "u",
+  "hide": "?25l",               "h": "?25l",
+  "show": "?25h",               "s": "?25h"
+}
+
+
+CLEAR_CODES: dict[ClearActionNameType, str] = {
+  "all": "2J",                  "a": "2J",
+  "begin_to_cursor": "1J",      "btc": "1J",
+  "cursor_to_end": "0J",        "cte": "0J",
+  "line": "2K",                 "l": "2K",
+  "line_start_to_cursor": "1K", "lstc": "1K",
+  "cursor_to_line_end": "0K",   "ctle": "0K"
+}
+
+
+COLOR_NAMES: tuple[ColorNameType, ...] = get_args(ColorNameType.__value__)
+
+CURSOR_ACTIONS_THAT_HAVE_ONE_NUMBER_PARAMETER: tuple[CursorActionsThatHaveOneNumberParameterNameType, ...] = (
+  get_args(CursorActionsThatHaveOneNumberParameterNameType.__value__)
+)
+CURSOR_ACTIONS_THAT_HAVE_TWO_NUMBER_PARAMETERS: tuple[CursorActionsThatHaveTwoNumberParametersNameType, ...] = (
+  get_args(CursorActionsThatHaveTwoNumberParametersNameType.__value__)
+)
+CURSOR_ACTIONS_THAT_HAVE_NO_NUMBER_PARAMETERS: tuple[CursorActionsThatHaveNoNumberParametersNameType, ...] = (
+  get_args(CursorActionsThatHaveNoNumberParametersNameType.__value__)
+)

escansi-0.1.0/src/escansi/types.py

@@ -0,0 +1,88 @@
+from typing import Literal
+
+
+type ColorNameType = Literal[
+  "black",
+  "red",
+  "green",
+  "yellow",
+  "blue",
+  "magenta",
+  "cyan",
+  "white",
+  "default",
+  "bright_black",
+  "bright_red",
+  "bright_green",
+  "bright_yellow",
+  "bright_blue",
+  "bright_magenta",
+  "bright_cyan",
+  "bright_white"
+]
+
+
+type FormatNameType = Literal[
+  "bold",
+  "dim",
+  "italic",
+  "underline",
+  "blink",
+  "swap_colors",
+  "hidden",
+  "strikethrough"
+]
+
+
+# THIS TYPES ARE RELATED ->
+# If need to add/remove to the first one (main), consider where else it should be added/removed to keep the consistency.
+type CursorActionNameType = Literal[
+  # CursorActionsThatHaveOneNumberParameterNameType
+  "up",                   "u",
+  "down",                 "d",
+  "forward",              "f",
+  "backward",             "b",
+  "start_of_line_down",   "sold",
+  "start_of_line_up",     "solu",
+  "move_to_column",       "mtc",
+  # CursorActionsThatHaveTwoNumberParametersNameType
+  "move_to_position",     "mtp",
+  # CursorActionsThatHaveNoNumberParametersNameType
+  "save_position",        "sp",
+  "restore_position",     "rp",
+  "hide",                 "h",
+  "show",                 "s"
+]
+
+type CursorActionsThatHaveOneNumberParameterNameType = Literal[
+  "up",                   "u",
+  "down",                 "d",
+  "forward",              "f",
+  "backward",             "b",
+  "start_of_line_down",   "sold",
+  "start_of_line_up",     "solu",
+  "move_to_column",       "mtc"
+]
+
+type CursorActionsThatHaveTwoNumberParametersNameType = Literal[
+  "move_to_position",     "mtp"
+]
+
+type CursorActionsThatHaveNoNumberParametersNameType = Literal[
+  "save_position",        "sp",
+  "restore_position",     "rp",
+  "hide",                 "h",
+  "show",                 "s"
+]
+# If need to add/remove to the first one (main), consider where else it should be added/removed to keep the consistency.
+# <- THIS TYPES ARE RELATED
+
+
+type ClearActionNameType = Literal[
+  "all",                  "a",
+  "begin_to_cursor",      "btc",
+  "cursor_to_end",        "cte",
+  "line",                 "l",
+  "line_start_to_cursor", "lstc",
+  "cursor_to_line_end",   "ctle"
+]

escansi-0.1.0/src/escansi/utils.py

@@ -0,0 +1,170 @@
+from typing import Literal, overload
+
+from .types import (
+  ClearActionNameType,
+  CursorActionNameType,
+  CursorActionsThatHaveNoNumberParametersNameType,
+  CursorActionsThatHaveOneNumberParameterNameType,
+  CursorActionsThatHaveTwoNumberParametersNameType,
+  FormatNameType,
+)
+from .constants import (
+  CLEAR_CODES,
+  COLOR_CODES,
+  COLOR_NAMES,
+  CURSOR_ACTIONS_THAT_HAVE_NO_NUMBER_PARAMETERS,
+  CURSOR_ACTIONS_THAT_HAVE_ONE_NUMBER_PARAMETER,
+  CURSOR_ACTIONS_THAT_HAVE_TWO_NUMBER_PARAMETERS,
+  CURSOR_CODES,
+  FORMAT_CODES,
+)
+
+
+#region overloads
+@overload
+def ForeColor(
+  color_or_grey_or_red: str | int | tuple[int, int, int],
+  green: None = None,
+  blue: None = None,
+  /
+) -> str: ...
+@overload
+def ForeColor(
+  color_or_grey_or_red: int,
+  green: int,
+  blue: int,
+  /
+) -> str: ...
+#endregion overloads
+def ForeColor(
+  color_or_grey_or_red: str | int | tuple[int, int, int],
+  green: int | None = None,
+  blue: int | None = None,
+  /
+) -> str:
+  if isinstance(color_or_grey_or_red, str):
+    if color_or_grey_or_red in COLOR_NAMES:
+      return f"\033[{COLOR_CODES['foreground'][color_or_grey_or_red]}m"
+    else:
+      if color_or_grey_or_red.startswith("#") and len(color_or_grey_or_red) == 7:
+        try:
+          r = int(color_or_grey_or_red[1:3], 16)
+          g = int(color_or_grey_or_red[3:5], 16)
+          b = int(color_or_grey_or_red[5:7], 16)
+          return f"\033[38;2;{r};{g};{b}m"
+        except ValueError:
+          raise ValueError(f"Invalid color code or name: '{color_or_grey_or_red}'")
+      else:
+        raise ValueError(f"Invalid color code or name: '{color_or_grey_or_red}'")
+  elif green is None or blue is None:
+    if isinstance(color_or_grey_or_red, tuple):
+      r, g, b = color_or_grey_or_red
+      return f"\033[38;2;{r};{g};{b}m"
+    else:
+      return f"\033[38;5;{color_or_grey_or_red}m"
+  else:
+    return f"\033[38;2;{color_or_grey_or_red};{green};{blue}m"
+
+
+#region overloads
+@overload
+def BackColor(
+  color_or_grey_or_red: str | int | tuple[int, int, int],
+  green: None = None,
+  blue: None = None,
+  /
+) -> str: ...
+@overload
+def BackColor(
+  color_or_grey_or_red: int,
+  green: int,
+  blue: int,
+  /
+) -> str: ...
+#endregion overloads
+def BackColor(
+  color_or_grey_or_red: str | int | tuple[int, int, int],
+  green: int | None = None,
+  blue: int | None = None,
+  /
+) -> str:
+  if isinstance(color_or_grey_or_red, str):
+    if color_or_grey_or_red in COLOR_NAMES:
+      return f"\033[{COLOR_CODES['background'][color_or_grey_or_red]}m"
+    else:
+      if color_or_grey_or_red.startswith("#") and len(color_or_grey_or_red) == 7:
+        try:
+          r = int(color_or_grey_or_red[1:3], 16)
+          g = int(color_or_grey_or_red[3:5], 16)
+          b = int(color_or_grey_or_red[5:7], 16)
+          return f"\033[48;2;{r};{g};{b}m"
+        except ValueError:
+          raise ValueError(f"Invalid color code or name: '{color_or_grey_or_red}'")
+      else:
+        raise ValueError(f"Invalid color code or name: '{color_or_grey_or_red}'")
+  elif green is None or blue is None:
+    if isinstance(color_or_grey_or_red, tuple):
+      r, g, b = color_or_grey_or_red
+      return f"\033[48;2;{r};{g};{b}m"
+    else:
+      return f"\033[48;5;{color_or_grey_or_red}m"
+  else:
+    return f"\033[48;2;{color_or_grey_or_red};{green};{blue}m"
+
+
+def Format(format: FormatNameType | tuple[FormatNameType, ...]) -> str:
+  if isinstance(format, tuple):
+    return "".join(f"\033[{FORMAT_CODES['apply'][f]}m" for f in format)
+  return f"\033[{FORMAT_CODES['apply'][format]}m"
+
+
+def ResetFormat(format: FormatNameType | tuple[FormatNameType, ...] | Literal["all"] = "all") -> str:
+  if format == "all":
+    return "\033[0m"
+  elif isinstance(format, tuple):
+    return "".join(f"\033[{FORMAT_CODES['reset'][f]}m" for f in format)
+  else:
+    return f"\033[{FORMAT_CODES['reset'][format]}m"
+
+
+#region overloads
+@overload
+def Cursor(
+action: CursorActionsThatHaveNoNumberParametersNameType,
+  n: None = None,
+  m: None = None,
+  /
+) -> str: ...
+@overload
+def Cursor(
+action: CursorActionsThatHaveOneNumberParameterNameType,
+  n: int,
+  m: None = None,
+  /
+) -> str: ...
+@overload
+def Cursor(
+action: CursorActionsThatHaveTwoNumberParametersNameType,
+  n: int,
+  m: int,
+  /
+) -> str: ...
+#endregion overloads
+def Cursor(
+  action: CursorActionNameType,
+  n: int | None = None,
+  m: int | None = None,
+  /
+) -> str:
+  if action in CURSOR_ACTIONS_THAT_HAVE_ONE_NUMBER_PARAMETER:
+    return f"\033[{n}{CURSOR_CODES[action]}"
+  elif action in CURSOR_ACTIONS_THAT_HAVE_TWO_NUMBER_PARAMETERS:
+    return f"\033[{n};{m}{CURSOR_CODES[action]}"
+  elif action in CURSOR_ACTIONS_THAT_HAVE_NO_NUMBER_PARAMETERS:
+    return f"\033[{CURSOR_CODES[action]}"
+  else:
+    raise ValueError(f"Invalid cursor action: '{action}'")
+
+
+def Clear(action: ClearActionNameType = "all") -> str:
+  return f"\033[{CLEAR_CODES[action]}"