nyxcore 0.1.0__tar.gz

nyxcore-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.3
+Name: nyxcore
+Version: 0.1.0
+Summary: nyx's utility library
+Author: verticalsync
+Author-email: verticalsync <nightly@riseup.net>
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/verticalsync/nyxcore
+Project-URL: Source, https://github.com/verticalsync/nyxcore
+Description-Content-Type: text/markdown
+
+# nyxcore
+
+personal utility library
+
+## modules
+
+| module | description |
+|---|---|
+| [`nyxcore.color`](#nyxcorecolor) | ANSI color support — named colors, 256-color, true color, Windows compat, auto-strip |
+| [`nyxcore.logger`](#nyxcorelogger) | Configurable logger with colored console output, file logging, custom formats |
+
+---
+
+## `nyxcore.color`
+
+ANSI escape code helpers. Zero dependencies.
+
+### colors
+
+| code | `fg` | `bg` |
+|---|---|---|
+| 30/40 | `fg.black` | `bg.black` |
+| 31/41 | `fg.red` | `bg.red` |
+| 32/42 | `fg.green` | `bg.green` |
+| 33/43 | `fg.yellow` | `bg.yellow` |
+| 34/44 | `fg.blue` | `bg.blue` |
+| 35/45 | `fg.magenta` | `bg.magenta` |
+| 36/46 | `fg.cyan` | `bg.cyan` |
+| 37/47 | `fg.white` | `bg.white` |
+| 90/100 | `fg.gray` | `bg.gray` |
+| 91/101 | `fg.bright_red` | `bg.bright_red` |
+| 92/102 | `fg.bright_green` | `bg.bright_green` |
+| 93/103 | `fg.bright_yellow` | `bg.bright_yellow` |
+| 94/104 | `fg.bright_blue` | `bg.bright_blue` |
+| 95/105 | `fg.bright_magenta` | `bg.bright_magenta` |
+| 96/106 | `fg.bright_cyan` | `bg.bright_cyan` |
+| 97/107 | `fg.bright_white` | `bg.bright_white` |
+| 39/49 | `fg.reset` | `bg.reset` |
+
+```python
+print(f"{fg.cyan}hello{fg.reset}")
+```
+
+### `attr` — text styles
+
+`attr.bold`, `attr.dim`, `attr.italic`, `attr.underline`, `attr.blink`, `attr.reverse`, `attr.hidden`, `attr.strikethrough`, `attr.reset`
+
+```python
+print(f"{attr.bold}{fg.red}bold red{attr.reset}")
+```
+
+### extended colors
+
+| function | description |
+|---|---|
+| `fg256(code)` | 256-color foreground (0–255) |
+| `bg256(code)` | 256-color background |
+| `fgrgb(r, g, b)` | 24-bit true color foreground |
+| `bgrgb(r, g, b)` | 24-bit true color background |
+
+```python
+print(f"{fg256(196)}bright red{fg.reset}")
+print(f"{fgrgb(255, 100, 50)}orange{fg.reset}")
+```
+
+### `strip(text)`
+
+Remove all ANSI escape sequences.
+
+```python
+clean = strip("\x1b[31mhello\x1b[0m")  # "hello"
+```
+
+### `init(strip_auto=True)`
+
+Enable Windows console ANSI support. Call once at startup.
+
+On Windows: enables virtual terminal processing via Win32 API.  
+When `strip_auto=True`: non-TTY streams (piped/redirected) are wrapped to strip ANSI codes automatically.
+
+```python
+from nyxcore.color import init
+init()
+```
+
+---
+
+## `nyxcore.logger`
+
+Configurable logger on top of stdlib `logging`. Supports colored console output, file output, custom formats.
+
+### `Logger(name, level, *, colorize, fmt, file)`
+
+| param | type | default | description |
+|---|---|---|---|
+| `name` | `str` | `"nyxcore"` | logger name |
+| `level` | `str` or `int` | `"INFO"` | `DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` or a `logging` constant |
+| `colorize` | `bool` or `None` | auto | `True` = colors on, `False` = plain, `None` = TTY-detect |
+| `fmt` | `str` or `None` | default | see [format](#format) |
+| `file` | `str` or `Path` | `None` | path to a log file (appends) |
+
+```python
+from nyxcore.logger import Logger
+
+log = Logger("myapp")
+log.info("hello")
+log.warning("careful")
+log.error("oops")
+```
+
+### `set_level(level)`
+
+Change minimum log level at runtime.
+
+```python
+log.set_level("DEBUG")
+```
+
+### `add_file(path, level=None)`
+
+Add a file handler after construction. File output is never colorized.
+
+```python
+log.add_file("app.log")
+log.add_file("errors.log", level="ERROR")
+```
+
+### format
+
+Placeholders: `{time}`, `{level}`, `{name}`, `{message}`. Python format specifiers work (`{level:^8}` centers in 8 chars).
+
+Default:
+
+```
+[{time}] {level:^8} | {name} | {message}
+```
+
+Custom:
+
+```python
+log = Logger("app", fmt="{level} | {message}")
+```

nyxcore-0.1.0/README.md

@@ -0,0 +1,142 @@
+# nyxcore
+
+personal utility library
+
+## modules
+
+| module | description |
+|---|---|
+| [`nyxcore.color`](#nyxcorecolor) | ANSI color support — named colors, 256-color, true color, Windows compat, auto-strip |
+| [`nyxcore.logger`](#nyxcorelogger) | Configurable logger with colored console output, file logging, custom formats |
+
+---
+
+## `nyxcore.color`
+
+ANSI escape code helpers. Zero dependencies.
+
+### colors
+
+| code | `fg` | `bg` |
+|---|---|---|
+| 30/40 | `fg.black` | `bg.black` |
+| 31/41 | `fg.red` | `bg.red` |
+| 32/42 | `fg.green` | `bg.green` |
+| 33/43 | `fg.yellow` | `bg.yellow` |
+| 34/44 | `fg.blue` | `bg.blue` |
+| 35/45 | `fg.magenta` | `bg.magenta` |
+| 36/46 | `fg.cyan` | `bg.cyan` |
+| 37/47 | `fg.white` | `bg.white` |
+| 90/100 | `fg.gray` | `bg.gray` |
+| 91/101 | `fg.bright_red` | `bg.bright_red` |
+| 92/102 | `fg.bright_green` | `bg.bright_green` |
+| 93/103 | `fg.bright_yellow` | `bg.bright_yellow` |
+| 94/104 | `fg.bright_blue` | `bg.bright_blue` |
+| 95/105 | `fg.bright_magenta` | `bg.bright_magenta` |
+| 96/106 | `fg.bright_cyan` | `bg.bright_cyan` |
+| 97/107 | `fg.bright_white` | `bg.bright_white` |
+| 39/49 | `fg.reset` | `bg.reset` |
+
+```python
+print(f"{fg.cyan}hello{fg.reset}")
+```
+
+### `attr` — text styles
+
+`attr.bold`, `attr.dim`, `attr.italic`, `attr.underline`, `attr.blink`, `attr.reverse`, `attr.hidden`, `attr.strikethrough`, `attr.reset`
+
+```python
+print(f"{attr.bold}{fg.red}bold red{attr.reset}")
+```
+
+### extended colors
+
+| function | description |
+|---|---|
+| `fg256(code)` | 256-color foreground (0–255) |
+| `bg256(code)` | 256-color background |
+| `fgrgb(r, g, b)` | 24-bit true color foreground |
+| `bgrgb(r, g, b)` | 24-bit true color background |
+
+```python
+print(f"{fg256(196)}bright red{fg.reset}")
+print(f"{fgrgb(255, 100, 50)}orange{fg.reset}")
+```
+
+### `strip(text)`
+
+Remove all ANSI escape sequences.
+
+```python
+clean = strip("\x1b[31mhello\x1b[0m")  # "hello"
+```
+
+### `init(strip_auto=True)`
+
+Enable Windows console ANSI support. Call once at startup.
+
+On Windows: enables virtual terminal processing via Win32 API.  
+When `strip_auto=True`: non-TTY streams (piped/redirected) are wrapped to strip ANSI codes automatically.
+
+```python
+from nyxcore.color import init
+init()
+```
+
+---
+
+## `nyxcore.logger`
+
+Configurable logger on top of stdlib `logging`. Supports colored console output, file output, custom formats.
+
+### `Logger(name, level, *, colorize, fmt, file)`
+
+| param | type | default | description |
+|---|---|---|---|
+| `name` | `str` | `"nyxcore"` | logger name |
+| `level` | `str` or `int` | `"INFO"` | `DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL` or a `logging` constant |
+| `colorize` | `bool` or `None` | auto | `True` = colors on, `False` = plain, `None` = TTY-detect |
+| `fmt` | `str` or `None` | default | see [format](#format) |
+| `file` | `str` or `Path` | `None` | path to a log file (appends) |
+
+```python
+from nyxcore.logger import Logger
+
+log = Logger("myapp")
+log.info("hello")
+log.warning("careful")
+log.error("oops")
+```
+
+### `set_level(level)`
+
+Change minimum log level at runtime.
+
+```python
+log.set_level("DEBUG")
+```
+
+### `add_file(path, level=None)`
+
+Add a file handler after construction. File output is never colorized.
+
+```python
+log.add_file("app.log")
+log.add_file("errors.log", level="ERROR")
+```
+
+### format
+
+Placeholders: `{time}`, `{level}`, `{name}`, `{message}`. Python format specifiers work (`{level:^8}` centers in 8 chars).
+
+Default:
+
+```
+[{time}] {level:^8} | {name} | {message}
+```
+
+Custom:
+
+```python
+log = Logger("app", fmt="{level} | {message}")
+```

nyxcore-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "nyxcore"
+version = "0.1.0"
+description = "nyx's utility library"
+readme = "README.md"
+authors = [{ name = "verticalsync", email = "nightly@riseup.net" }]
+requires-python = ">=3.14"
+urls = { Homepage = "https://github.com/verticalsync/nyxcore", Source = "https://github.com/verticalsync/nyxcore" }
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["isort>=8.0.1", "mypy>=1.15.0", "pytest>=8.0.0", "ruff>=0.15.22"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+ignore_missing_imports = true

nyxcore-0.1.0/src/nyxcore/color.py

@@ -0,0 +1,160 @@
+from __future__ import annotations  # noqa: I001
+
+import os
+import re
+import sys
+from typing import Any
+
+_ANSIRE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+
+class fg:
+    """Foreground color escape codes."""
+
+    black = "\x1b[30m"
+    red = "\x1b[31m"
+    green = "\x1b[32m"
+    yellow = "\x1b[33m"
+    blue = "\x1b[34m"
+    magenta = "\x1b[35m"
+    cyan = "\x1b[36m"
+    white = "\x1b[37m"
+    gray = "\x1b[90m"
+    bright_red = "\x1b[91m"
+    bright_green = "\x1b[92m"
+    bright_yellow = "\x1b[93m"
+    bright_blue = "\x1b[94m"
+    bright_magenta = "\x1b[95m"
+    bright_cyan = "\x1b[96m"
+    bright_white = "\x1b[97m"
+    reset = "\x1b[39m"
+
+
+class bg:
+    """Background color escape codes."""
+
+    black = "\x1b[40m"
+    red = "\x1b[41m"
+    green = "\x1b[42m"
+    yellow = "\x1b[43m"
+    blue = "\x1b[44m"
+    magenta = "\x1b[45m"
+    cyan = "\x1b[46m"
+    white = "\x1b[47m"
+    gray = "\x1b[100m"
+    bright_red = "\x1b[101m"
+    bright_green = "\x1b[102m"
+    bright_yellow = "\x1b[103m"
+    bright_blue = "\x1b[104m"
+    bright_magenta = "\x1b[105m"
+    bright_cyan = "\x1b[106m"
+    bright_white = "\x1b[107m"
+    reset = "\x1b[49m"
+
+
+class attr:
+    """Text attribute/style escape codes."""
+
+    bold = "\x1b[1m"
+    dim = "\x1b[2m"
+    italic = "\x1b[3m"
+    underline = "\x1b[4m"
+    blink = "\x1b[5m"
+    reverse = "\x1b[7m"
+    hidden = "\x1b[8m"
+    strikethrough = "\x1b[9m"
+    reset = "\x1b[0m"
+    reset_bold = "\x1b[22m"
+    reset_italic = "\x1b[23m"
+    reset_underline = "\x1b[24m"
+    reset_blink = "\x1b[25m"
+    reset_reverse = "\x1b[27m"
+
+
+def fg256(code: int) -> str:
+    """Generate a 256-color foreground escape sequence."""
+    return f"\x1b[38;5;{code}m"
+
+
+def bg256(code: int) -> str:
+    """Generate a 256-color background escape sequence."""
+    return f"\x1b[48;5;{code}m"
+
+
+def fgrgb(r: int, g: int, b: int) -> str:
+    """Generate a 24-bit true-color foreground escape sequence."""
+    return f"\x1b[38;2;{r};{g};{b}m"
+
+
+def bgrgb(r: int, g: int, b: int) -> str:
+    """Generate a 24-bit true-color background escape sequence."""
+    return f"\x1b[48;2;{r};{g};{b}m"
+
+
+def strip(text: str) -> str:
+    """Remove all ANSI escape sequences from *text*."""
+    return _ANSIRE.sub("", text)
+
+
+def _init_windows() -> bool:
+    """Enable virtual terminal processing on the Windows console."""
+    import ctypes
+    from ctypes import wintypes
+
+    STD_OUTPUT_HANDLE = -11
+    STD_ERROR_HANDLE = -12
+    ENABLE_VIRTUAL_TERMINAL_PROCESSING = 4
+    DISABLE_NEWLINE_AUTO_RETURN = 8
+
+    kernel32 = ctypes.windll.kernel32
+
+    for handle in (STD_OUTPUT_HANDLE, STD_ERROR_HANDLE):
+        h = kernel32.GetStdHandle(handle)
+        if h == wintypes.HANDLE(-1).value or h is None:
+            continue
+        mode = wintypes.DWORD()
+        if not kernel32.GetConsoleMode(h, ctypes.byref(mode)):
+            continue
+        mode.value |= ENABLE_VIRTUAL_TERMINAL_PROCESSING
+        mode.value |= DISABLE_NEWLINE_AUTO_RETURN
+        kernel32.SetConsoleMode(h, mode)
+
+    return True
+
+
+class _StreamWrapper:
+    """Wraps a stream to strip ANSI codes on write."""
+
+    def __init__(self, stream: Any) -> None:
+        self._stream = stream
+
+    def write(self, text: str) -> None:
+        """Write *text* with ANSI codes stripped."""
+        self._stream.write(strip(text))
+
+    def flush(self) -> None:
+        """Flush the underlying stream."""
+        self._stream.flush()
+
+    def __getattr__(self, name: str):  # type: ignore[no-untyped-def]
+        return getattr(self._stream, name)
+
+
+def init(*, strip_auto: bool = True) -> None:
+    """Enable ANSI color support and configure auto-stripping.
+
+    On Windows this enables virtual terminal processing via the Win32 API.
+    When *strip_auto* is ``True`` (the default), non-TTY output streams
+    are wrapped to automatically strip ANSI codes so they don't appear
+    in redirected or file output.
+    """
+    if os.name != "nt":
+        return
+    try:
+        _init_windows()
+    except Exception:
+        pass
+    if strip_auto:
+        if not sys.stdout.isatty():
+            sys.stdout = _StreamWrapper(sys.stdout)
+        if not sys.stderr.isatty():
+            sys.stderr = _StreamWrapper(sys.stderr)

nyxcore-0.1.0/src/nyxcore/logger/__init__.py

@@ -0,0 +1,106 @@
+from __future__ import annotations  # noqa: I001
+
+import logging
+import re
+import sys
+from pathlib import Path
+from typing import Literal
+
+from nyxcore import color
+
+Level = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+_LEVELS = {"DEBUG": logging.DEBUG, "INFO": logging.INFO, "WARNING": logging.WARNING, "ERROR": logging.ERROR, "CRITICAL": logging.CRITICAL}
+
+_COLORS: dict[int, str] = {
+    logging.DEBUG: color.fg256(244),
+    logging.INFO: color.fg256(39),
+    logging.WARNING: color.fg256(220),
+    logging.ERROR: color.fg256(196),
+    logging.CRITICAL: f"{color.fg256(196)}{color.attr.bold}",
+}
+
+
+def _levelno(name: str) -> int:
+    """Convert a level string (case-insensitive) to a logging level constant."""
+    return _LEVELS[name.upper()]
+
+
+class _Formatter(logging.Formatter):
+    """Custom formatter that optionally wraps level/msg in ANSI color codes."""
+
+    def __init__(self, fmt: str, colorize: bool) -> None:
+        super().__init__(fmt)
+        self.colorize = colorize
+
+    def format(self, record: logging.LogRecord) -> str:
+        if self.colorize:
+            c = _COLORS.get(record.levelno, color.attr.reset)
+            record.msg = f"{c}{record.msg}{color.attr.reset}"
+            record.levelname = f"{c}{record.levelname}{color.attr.reset}"
+        return super().format(record)
+
+
+_TO_LOGGING = {"time": "asctime", "level": "levelname", "name": "name", "message": "message"}
+_FMT_PATTERN = re.compile(r"\{(\w+)(?::[^}]*)?\}")
+
+class Logger:
+    """Configurable logger with optional color and file output.
+
+    Wraps the stdlib ``logging`` module. Output can go to the terminal,
+    a file, or both simultaneously.
+    """
+
+    def __init__(
+        self,
+        name: str = "nyxcore",
+        level: Level | int = "INFO",
+        *,
+        colorize: bool | None = None,
+        fmt: str | None = None,
+        file: str | Path | None = None,
+    ) -> None:
+        if isinstance(level, str):
+            level = _levelno(level)
+        _use_color = sys.stdout.isatty() if colorize is None else colorize
+
+        if fmt is None:
+            fmt = "[{time}] {level:^8} | {name} | {message}"
+        self._fmt = _FMT_PATTERN.sub(lambda m: f"%({_TO_LOGGING[m.group(1)]})s", fmt)
+
+        self._logger = logging.getLogger(name)
+        self._logger.setLevel(level)
+        self._logger.handlers.clear()
+
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setLevel(level)
+        handler.setFormatter(_Formatter(self._fmt, _use_color))
+        self._logger.addHandler(handler)
+
+        if file is not None:
+            self.add_file(file, level)
+
+    def __getattr__(self, name: str):  # type: ignore[no-untyped-def]
+        """Delegate attribute access to the underlying logger."""
+        return getattr(self._logger, name)
+
+    def set_level(self, level: Level | int) -> None:
+        """Change the minimum log level at runtime."""
+        if isinstance(level, str):
+            level = _levelno(level)
+        self._logger.setLevel(level)
+        for h in self._logger.handlers:
+            h.setLevel(level)
+
+    def add_file(self, path: str | Path, level: Level | int | None = None) -> None:
+        """Add a file handler for persistent logging."""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if isinstance(level, str):
+            level = _levelno(level)
+        if level is None:
+            level = self._logger.level
+        fh = logging.FileHandler(str(path), encoding="utf-8")
+        fh.setLevel(level)
+        fh.setFormatter(logging.Formatter(self._fmt))
+        self._logger.addHandler(fh)