Metadata-Version: 2.4
Name: nscolors
Version: 1.0.1
Summary: Lightweight cross-platform terminal coloring & utilities for Python
Author: NullSpecter404
License: MIT
Project-URL: Homepage, https://github.com/NullSpecter404/nscolors-project
Project-URL: Repository, https://github.com/NullSpecter404/nscolors-project
Project-URL: Issue Tracker, https://github.com/NullSpecter404/nscolors-project/issues
Keywords: terminal,color,ansi,theme,cli,text-style,printing,cross-platform
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Dynamic: license-file

# nscolors

Lightweight cross-platform terminal coloring & utilities for Python

nscolors is a compact package that provides ANSI/WinAPI-aware terminal coloring, simple RGB/256-color helpers, progress bars, cursor movement utilities, tables and more — all without external dependencies. This repository contains an early (v1.0.0) implementation designed for small CLI tools and scripts.

---

## Key features

- Foreground (FG) and background (BG) helpers and convenience functions
- direct color helpers (RGB, 256-color, random colors)
- Table builder with ANSI-safe width calculations
- Multiple progress-bar styles and a customizable progress method
- Cursor control helpers (move, goto, hide/show)
- Dual support: ANSI sequences and Windows WINAPI where available
- Palettes loaded from `nscolors/palettes/` (JSON/TXT)
- No external dependencies (pure Python)

---

## Quick install

This project is a global package. To install (optional):

```powershell
# from repository nscolors
python -m pip install nscolors
```

Or just import directly from the package folder in your project.

---

## Quick start

Preferred import styles (avoid `from nscolors import *` in your own projects):

```python
# explicit import (recommended)
from nscolors.colors import colors, ESC, CSI, SEP, RESET_STYLE
from nscolors.fg import FG
from nscolors.bg import BG
from nscolors.direct import DIRECT
from nscolors.cursor import CURSOR
from nscolors.progress import Progress
from nscolors.tables import Table

# or namespace import
import nscolors
nscolors.FG.red("hello")
```

Examples:

```python
from nscolors.fg import FG
from nscolors.bg import BG
from nscolors.direct import DIRECT

# simple foreground color
FG.red("This text is red")

# background and foreground
BG.blue("This has a blue background")
FG.white("White text")

# direct color (style + palette names)
DIRECT.color("Styled text", text_style="Normal", color="Green", bgcolor="Black")

# rgb
DIRECT.rgb("Truecolor text", R=200, G=100, B=50)

# progress bar
from nscolors.progress import Progress
for i in range(21):
    Progress.block(i, 20)

# cursor
from nscolors.cursor import CURSOR
CURSOR.goto(5, 10, "At row 5 col 10")

# table
from nscolors.tables import Table
from nscolors.fg import FG

t = Table(title="Sample")
t.add_column("Name", "Age")
t.add_row("Alice", "30")
t.add_row("Bob", "27")
t.print_table()
```

---

## API summary

Important modules / symbols exported by the package:

- `nscolors.colors`:
  - `ESC`, `CSI`, `SEP`, `RESET_STYLE` — low-level ANSI constants
  - `colors`, `BgColors`, `TextStyles`, `WinFGColors`, `WinBGColors` — color palettes (dicts)
- `nscolors.fg`:
  - `FG` class with static methods: `FG.red(text)`, `FG.green(text)`, etc.
- `nscolors.bg`:
  - `BG` class with static methods for backgrounds: `BG.blue(text)`, etc.
- `nscolors.direct`:
  - `DIRECT.color`, `DIRECT.rgb`, `DIRECT.color256`, `DIRECT.random_text_colored`, `DIRECT.animated_write`
- `nscolors.cursor`:
  - `CURSOR.goto`, `CURSOR.up`, `CURSOR.down`, `CURSOR.hide_cursor`, etc.
- `nscolors.progress`:
  - `Progress` with different predefined styles (`block`, `arabic`, `professional`, ...)
- `nscolors.tables`:
  - `Table` class that handles column widths while stripping ANSI sequences.
- `nscolors.core`:
  - `GetSystemInfo()`, `init()`, `LoadPalette()` and other helper utilities

---

## Notes & best practices

- Avoid `from nscolors import *` in your projects; prefer explicit imports or `import nscolors` to avoid namespace pollution.
- Currently `nscolors/__init__.py` calls `GetSystemInfo()` and `init()` and some modules load palettes at import time. That means importing the package may perform I/O and attempt Windows console setup immediately. This behavior is intentional in this version but consider the cost in short-running scripts.
- If you need to minimize import cost, import specific submodules only when required (e.g., only import `nscolors.tables` if you use tables).
- Palettes are stored in `nscolors/palettes/`. You can edit or extend those JSON/TXT files to customize available named colors.

---

## Compatibility

- Designed to work cross-platform with fallback to Windows WINAPI on older Windows releases.
- For modern rich rendering or advanced terminal features, consider using `rich` (which provides more features and polished output), but `nscolors` is intentionally dependency-free and lightweight.

---

## Contributing

Small, focused contributions are welcome. Suggested early PRs:

- Convert import-time palette loading to optional lazy-loading
- Replace `import *` usage across package with explicit exports (internal refactor)
- Add unit tests (pytest) for core functions like `LoadPalette`, `strip_ansi_codes` and color outputs
- Improve error messages and unify logging format

Please include a short description, test, and example for any new feature.

---

## License

As indicated in `pyproject.toml`, this project uses the MIT License. Include a `LICENSE` file in the repo if you plan to publish.

---

