richx 1.1.1
Extended Rich with CSS-Style Themes
License: Apache License 2.0

[![PyPI Version](https://img.shields.io/pypi/v/richx.svg)](https://pypi.org/project/richx/)
[![Python Versions](https://img.shields.io/pypi/pyversions/richx.svg)](https://pypi.org/project/richx/)
[![License](https://img.shields.io/pypi/l/richx.svg)](https://github.com/chingwon/richx/blob/main/LICENSE)

**RichX** is a fork of [Textualize/rich](https://github.com/Textualize/rich), enhanced with **CSS-like theming** using `.richstyle` files — with full support for both **normal files** and **zipped theme archives (`.zip`)**.

It retains all the power of Rich (colorful terminal formatting, progress bars, tracebacks, tables, etc.) and adds the ability to **define, package, and load themes** using a clean CSS-style syntax — including variables and reusable templates.

---

## Key Features

- **`.richstyle` Theme Loader**  
  Load themes written in a CSS-like format:

  ```css
  header {
      color: #00ffaa;
      bold: true;
  }

  warning {
      color: yellow;
      bold: true;
  }
  ```

* **Variables Support**
  Define reusable color variables:

  ```css
  --primary: #00ffaa;

  header {
      color: var(--primary);
      bold: true;
  }
  ```

* **Dual Format Support**
  RichX can load themes from either:

  * A single `.richstyle` file, or
  * A `.zip` archive containing one or more `.richstyle` files.

  ```python
  from richx.css_style import theme_from_stylesheet

  # Load from .richstyle file
  theme = theme_from_stylesheet("themes/dark.richstyle")

  # Or load from a zip archive
  theme = theme_from_stylesheet("themes/templates.zip")
  ```

  Zipped themes are automatically extracted, combined, and parsed — including safe handling for password-protected archives.

* **Built-in Template Themes**
  Predefined styles like `ARCTIC_THEME`, `SUNSET_THEME`, `NEBULA_THEME`, `MATRIX_THEME`, and `CLAY_THEME`.

* **Automatic Theme Loading**

  ```python
  from richx.console import Console

  console = Console(theme="ARCTIC_THEME")
  console.print("Hello styled world!", style="header")
  ```

* **Fully Compatible with Rich** — works with tables, panels, markdown, logs, tracebacks, etc.

* **Lightweight and Dependency-Free** — no extra packages required.

---

## Installation

```bash
pip install richx
```

---

## Using Template Themes

### 1. Import Console

```python
from richx.console import Console
```

### 2. Load a Predefined Theme

```python
console = Console(theme="ARCTIC_THEME")
console.print("Hello styled!", style="header")
```

### 3. List Available Themes

```python
print(Console.available_themes())
```

Example:

```
['ARCTIC_THEME', 'SUNSET_THEME', 'NEBULA_THEME', 'MATRIX_THEME', ...]
```

### 4. Apply Styles in Code

```python
console.print("Header text", style="header")
console.print("Warning!", style="warning")
console.print("Success!", style="success")
```

### 5. Use Variables in `.richstyle`

```css
--primary: #00ffaa;
--danger: #ff0055;

header {
    color: var(--primary);
    bold: true;
}

error {
    color: var(--danger);
    bold: true;
}
```

---

## Loading Themes from Zip Archives

RichX supports zipped theme bundles for cleaner packaging:

```python
from richx.css_style import theme_from_stylesheet
from richx.console import Console

# Automatically reads all `.richstyle` files inside the archive
theme = theme_from_stylesheet("themes/template.zip")

console = Console(theme=theme)
console.print("Loaded theme from ZIP!", style="header")
```

If multiple `.richstyle` files are present, they are automatically concatenated and parsed as a single stylesheet.

---

## Command-Line Tool

Preview or compile `.richstyle` or `.zip` themes:

```bash
python -m richx.css_style path/to/theme.richstyle --show
```

**Options:**

* `--json` → Print compiled theme as JSON
* `--show` → Display a live preview in the terminal

---

## Advanced Usage

Programmatically load and apply a theme:

```python
from richx.css_style import theme_from_stylesheet
from richx.console import Console

theme = theme_from_stylesheet("themes/theme.zip")  # or .richstyle
console = Console(theme=theme)
console.print("Styled text!", style="header")
```

---

## Example Project Layout

```
my_project/
├── themes/
│   ├── template.zip
│   └── custom.richstyle
├── main.py
└── requirements.txt
```

**main.py**

```python
from richx.console import Console

console = Console(theme="themes/template.zip")
console.print("Welcome!", style="header")
```

---

## Compatibility

* Python 3.8+
* Fully compatible with Rich APIs
* Works in Jupyter, Textual, and Rich logging environments

---

## License

MIT License © 2025

---

## Credits

Built upon the incredible work of [Will McGugan](https://github.com/willmcgugan) and the [Textualize](https://github.com/Textualize) team.
**RichX** extends Rich with **CSS-like theming and flexible `.richstyle` + `.zip` support**.

---

## Changelog

### v1.1.1

* Added support for **loading `.richstyle` themes from both normal files and `.zip` archives**
* Safely reads and merges multiple `.richstyle` files inside an archive
* Improved theme loader robustness and cross-platform compatibility

### v1.1.0

* Added full variable support with recursive substitution
* Added multiple built-in theme templates
* Improved CLI preview and compilation output
* Fully backward compatible with existing Rich features
* Minor stability and compatibility fixes

### v0.1.0

* Initial release with `.richstyle` CSS-style theme support
* Added CLI compiler and preview
* Fully compatible with Rich API