Metadata-Version: 2.4
Name: mermaid-ascii
Version: 0.7.0
Summary: Mermaid-ASCII (GoLang) wrapped in a Python Package
License-File: LICENSE
Author: Ivan Ogasawara
Author-email: ivan.ogasawara@gmail.com
Requires-Python: >=3.9,<4
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Description-Content-Type: text/markdown

# mermaid-ascii (PyPI packaging)

This repository rebundles the upstream
**[mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii)** (written
in Go) and publishes it to **PyPI** as a Python package. It exists to make
**Mermaid → ASCII** conversion trivial to install and use from Python and in CI,
without requiring Node, Graphviz, or a JVM.

> Upstream author: **Alexander Grooff** This repo is a packaging/redistribution
> project and is not affiliated with the upstream authors.

---

## What you get

- A **prebuilt `mermaid-ascii` binary** shipped inside the wheel.
- A tiny **Python wrapper** for programmatic use (`mermaid_to_ascii(...)`).
- Optional CLI access via your Python environment (see Usage).

This lets you:

- Convert Mermaid diagrams to **ASCII** in terminals and CI logs
- Call the converter **directly from Python**, Jupyter, or scripts

---

## Install

```bash
pip install mermaid-ascii
```

> We publish wheels for common platforms. If a wheel isn’t available for your
> platform yet, please open an issue.

---

## Quick start

### CLI

```bash
# From a file
mermaid-ascii -i diagram.mmd

# From stdin
echo 'flowchart LR; A-->B' | mermaid-ascii -i -
```

### Python API

```python
from mermaid_ascii import mermaid_to_ascii

src = """
flowchart TB
  A[Start] --> B{Question?}
  B -->|Yes| C[Go]
  B -->|No|  D[Stop]
"""
print(mermaid_to_ascii(src))
```

### Jupyter tip

JupyterLab ≥ 4.1 / Notebook ≥ 7.1 can render Mermaid natively for visual
preview:

````markdown
```mermaid
flowchart LR
  A --> B
```
````

Use this package when you specifically need **ASCII output** (for terminals,
logs, or text-only artifacts).

---

## Versioning

- The **Python package version matches the upstream `mermaid-ascii` tag**, with
  a leading `v` stripped if present (e.g., upstream `v0.6.1` → package `0.6.1`).
- Each release of this package corresponds to the latest upstream release at the
  time of packaging.

---

## How this repo works (release automation)

1. CI clones the upstream **AlexanderGrooff/mermaid-ascii** repo and detects its
   **latest tag**.
2. If that version differs from this package’s version in `pyproject.toml`
   (annotated with `# mermaid-ascii version`), CI:

   - Updates `pyproject.toml` to the new version
   - Builds the upstream Go binary
   - Bundles the binary into the Python wheel
   - Publishes to **PyPI**
   - Creates a GitHub **tag + release** in this repo

3. If nothing changed, CI exits without publishing.

This keeps the PyPI package in lockstep with upstream releases.

---

## Platforms

We aim to provide wheels for:

- Linux (x86_64, aarch64)
- macOS (arm64, x86_64)
- Windows (x86_64)

If your platform isn’t covered, please open an issue with details (OS,
architecture, Python version).

---

## Troubleshooting

- **`mermaid-ascii: command not found`** Ensure your Python environment’s
  `bin`/`Scripts` is on `PATH`. Alternatively, invoke via Python:

  ```bash
  python -m mermaid_ascii -i diagram.mmd
  ```

  (If unavailable, use the Python API example above.)

- **Non-ASCII terminals** Output uses Unicode box-drawing characters. If your
  terminal can’t display them, switch to a UTF-8–capable font/locale.

- **Diagram doesn’t render as expected** Please first confirm the diagram
  renders in a Mermaid viewer. If the ASCII rendering is the problem, open an
  issue here; if it’s Mermaid syntax/semantics, consider filing upstream.

---

## Contributing

- Packaging changes and Python wrapper issues → **this repo**
- Core ASCII rendering behavior → **upstream**:
  [https://github.com/AlexanderGrooff/mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii)

PRs are welcome for:

- Additional wheels/platforms
- CI improvements
- Small Python wrapper enhancements (docs, examples)

---

## License & attribution

- The included `mermaid-ascii` binary and its source are licensed by the
  [**upstream project**](https://github.com/AlexanderGrooff/mermaid-ascii/blob/master/LICENSE).
- The packaging code in this repository is licensed as stated in this repo’s
  [LICENSE](./LICENSE) file.
- © Respect to the upstream author(s). This project simply repackages their
  work for PyPI distribution.

---

## Maintainers

- Open Science Labs – **OSL Packages** Repo:
  [https://github.com/osl-packages/mermaid-ascii](https://github.com/osl-packages/mermaid-ascii)

If you rely on this package, consider starring both this repo and the upstream
to support the maintainers.

