Metadata-Version: 2.4
Name: asciilint
Version: 0.2.0
Summary: ASCII and character policy checks for text files
Project-URL: Homepage, https://nanx.me/asciilint/
Project-URL: Documentation, https://nanx.me/asciilint/
Project-URL: Repository, https://github.com/nanxstats/asciilint
Project-URL: Issues, https://github.com/nanxstats/asciilint/issues
Project-URL: Changelog, https://github.com/nanxstats/asciilint/blob/main/CHANGELOG.md
Author-email: Nan Xiao <me@nanx.me>
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.4.2
Requires-Dist: pathspec>=1.1.1
Description-Content-Type: text/markdown

# asciilint

[![PyPI version](https://img.shields.io/pypi/v/asciilint)](https://pypi.org/project/asciilint/)
![Python versions](https://img.shields.io/pypi/pyversions/asciilint)
[![CI tests](https://github.com/nanxstats/asciilint/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/ci-tests.yml)
[![Mypy check](https://github.com/nanxstats/asciilint/actions/workflows/mypy.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/mypy.yml)
[![Ruff check](https://github.com/nanxstats/asciilint/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/nanxstats/asciilint/actions/workflows/ruff-check.yml)
[![Documentation](https://github.com/nanxstats/asciilint/actions/workflows/docs.yml/badge.svg)](https://nanx.me/asciilint/)
![License](https://img.shields.io/pypi/l/asciilint)

Minimal, configurable, CI-friendly character policy checks for text files.

By default, `asciilint` recursively scans a project and fails when UTF-8
text files contain non-ASCII characters. It can also enforce arbitrary Unicode
allowlists and denylists, so it is useful for broader character policy checks.

## Installation

Install `asciilint` from PyPI:

```bash
pip install asciilint
```

For an isolated, global CLI installation, use
[`pipx`](https://packaging.python.org/en/latest/guides/installing-stand-alone-command-line-tools/):

```bash
pipx install asciilint
```

To run it once without adding it to your environment, use
[`uvx`](https://docs.astral.sh/uv/guides/tools/):

```bash
uvx asciilint --help
```

## Usage

```bash
asciilint .
```

Example failing output:

```text
> Checking characters in /path/to/project
Files found: 3, 2 to scan, 1 ignored
Checking text:
✓x
Files checked: 2 text, 0 binary skipped, 0 read error(s)

Issues :-(
> Disallowed characters
  1. docs/page.md
     1. [L012:C018] U+2014 "\u2014" not allowed by policy
Summary: 1 disallowed character(s), 0 read error(s)
```

Exit code `0` means no issues. Exit code `1` means disallowed characters or
read errors were found.

## Configuration

Create `asciilint.toml`:

```toml
[asciilint]
paths = ["."]
respect_gitignore = true
ignore_files = [".asciilintignore"]
allowed_ranges = ["U+0000-U+007F"]
allowed_chars = []
disallowed_ranges = []
disallowed_chars = []
max_issues_per_file = 5
```

Ignore files use gitignore syntax and are matched with `pathspec`.
`.gitignore` is respected by default.
You can add other ignore files, for example:

```bash
asciilint . --ignore-file .asciilintignore --ignore-file config/lint.ignore
```

Character ranges can be written as `U+0000-U+007F`, `0x20..0x7e`, `32-126`, or
single code points such as `U+00A9`. Deny rules take precedence over allow rules.

To allow any Unicode character except a small denylist:

```bash
asciilint . --allow-any --disallowed-char "→" --disallowed-range U+2000-U+206F
```

## UTF-8 and binary files

`asciilint` assumes text files are UTF-8. Files that are classified as text but
cannot be decoded as UTF-8 are reported explicitly and skipped. Binary files are
skipped automatically using the zlib `txtvsbin` heuristic.
