Metadata-Version: 2.5
Name: unifont-utils
Version: 0.8.0
Summary: Unifont Utilities, but rewritten in Python.
Project-URL: Homepage, https://unifont-utils.readthedocs.io/
Project-URL: Documentation, https://unifont-utils.readthedocs.io/
Project-URL: Repository, https://github.com/SkyEye-FAST/unifont_utils
Project-URL: Issues, https://github.com/SkyEye-FAST/unifont_utils/issues
Author-email: SkyEye_FAST <skyeyefast@foxmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: unifont
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Natural Language :: English
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
Classifier: Topic :: Text Processing :: Fonts
Classifier: Topic :: Utilities
Requires-Python: <4.0,>=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: fonttools>=4.60
Requires-Dist: pillow>=10.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.9
Description-Content-Type: text/markdown

# Unifont Utils

[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

[![CI](https://github.com/SkyEye-FAST/unifont_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/SkyEye-FAST/unifont_utils/actions/workflows/ci.yml)
![PyPI - Version](https://img.shields.io/pypi/v/unifont_utils) ![GitHub Release](https://img.shields.io/github/v/release/SkyEye-FAST/unifont_utils)

- **[English](README.md) | [中文](README_zh.md)**

This project provides a set of tools for working with the GNU Unifont.

**See the documentation at [Read the Docs](https://unifont-utils.readthedocs.io/latest/en/)
for more information.**

## Installation

Install the package from PyPI using the following command:

``` shell
pip install unifont-utils
```

## Quick start

Load a GNU Unifont `.hex` file, edit a glyph and save the file:

```python
from unifont_utils import Glyph, GlyphSet, print_glyph

glyphs = GlyphSet.load_hex_file("unifont.hex")
glyph = glyphs["0041"]
print(glyph.hex_str, glyph.width, glyph.unicode_name)
print_glyph(glyph)

glyphs.set_glyph(Glyph("E000", "00" * 16))
glyphs.save_hex_file("edited.hex")
```

The package is organized in layers:

| Module | Contents |
| --- | --- |
| `unifont_utils` | Core model: `Glyph`, `GlyphSet`, `ColorScheme`, patterns, `print_glyph`, `print_diff` |
| `unifont_utils.operations` | Merging, range and Hangul selection, statistics, diffs, rotation, combining circles |
| `unifont_utils.generators` | Code point boxes, Braille and Kinya glyphs, matching the GNU Unifont programs |
| `unifont_utils.formats` | Glyph and page images, BDF, GNU hexdraw text, TrueType/CFF OpenType, `.hex` checks |
| `unifont_utils.downloader` | Downloading official Unifont releases |
| `unifont_utils.cli` | The `unifont-utils` command |

```python
from unifont_utils.formats import save_opentype, save_page_image
from unifont_utils.operations import select_range

latin = select_range(glyphs, "0020", "007E")
save_page_image(glyphs, "4E", "page.png")
save_opentype(latin, "latin.otf", font_format="otf")
```

Interactive terminal editing lives in the independent **UniPie** (`unipie`) project.

## Command line

```shell
unifont-utils --help
unifont-utils download  # The latest official release
unifont-utils hex query --path unifont.hex --code_point 0041 --pure
unifont-utils hex merge base.hex overrides.hex --output merged.hex
unifont-utils hex subset --path merged.hex --start 0020 --end 007E --output latin.hex
unifont-utils convert page hex2img --path unifont.hex --page 4E --output page.png
unifont-utils convert font export --path latin.hex --format otf --output latin.otf
unifont-utils generate filler --range E000 E0FF --output filler.hex
```

The `hex` group queries, edits, checks and processes `.hex` files. The `convert` group
handles images, unihex2bmp pages, BDF, hexdraw text and OpenType fonts. The `generate`
group creates glyphs by algorithm.

## Development

The repository uses [uv](https://docs.astral.sh/uv/) for locked environments and Ruff for linting
and formatting:

```shell
uv sync --locked
uv run --locked pytest
uv run --locked ruff check .
uv run --locked ruff format --check .
```

The documentation lives in `docs/`, with Chinese pages in `docs/zh` and English pages in
`docs/en`. Preview both languages with:

```shell
uv sync --locked --group docs
uv run --locked mkdocs serve
```

## License

The project is released under the [GPL v3 License](LICENSE).

``` text
    Unifont Utils
    Copyright (C) 2024-2026 SkyEye_FAST

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.
```

## Feedback

Please feel free to raise issues for any problems encountered or feature suggestions.

Pull requests are welcome.
