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}")
```
