Vale Python Package

3.13.0.0 · active · verified Thu Apr 16

The `vale` Python package provides a convenient way to install and use the Vale command-line grammar and style checking tool within Python environments. Vale itself is a static analysis tool for prose, written in Go. This Python package acts as a wrapper, automatically downloading the appropriate Vale binary on first execution. The package aims to simplify the inclusion of Vale as a dependency in Python applications or libraries, without requiring manual installation of the Vale CLI.

Common errors

```
ModuleNotFoundError: No module named 'vale'
```
cause The `vale` package was not installed or is not accessible in the current Python environment.

fix Ensure the package is installed using `pip install vale` within your active virtual environment.
```
FileNotFoundError: [Errno 2] No such file or directory: 'vale'
```
cause The Vale CLI executable, which the Python package wraps, could not be found. This often happens if the initial download failed or the system's PATH environment variable is not set correctly to include the downloaded binary's location.

fix Verify your internet connection for the initial download. Check the package's internal cache directory (typically `~/.cache/vale`) for the downloaded binary. If issues persist, try reinstalling the package or manually checking file permissions. This error can also occur if the `.vale.ini` or style files are missing or incorrectly configured.
```
Runtime error 'Apple Developer Program roles and permissions' not found Execution stopped with code 1.
```
cause This specific error (or similar 'Runtime error [...] not found') indicates an issue within the Vale CLI itself, often related to an invalid configuration file (`.vale.ini`) or missing/incorrectly referenced style guides. This can be caused by new breaking changes in Vale CLI versions interpreting rules differently.

fix Review your `.vale.ini` file and any custom style guide configurations. Ensure all paths are correct and that the configuration adheres to the Vale CLI version being used by the Python package. If recently updated, check for breaking changes in the Vale CLI's changelog. Pin your `vale` package version to a known working version if necessary.

Warnings

gotcha The Vale CLI binary is not bundled with the Python package. It is automatically downloaded and installed on the user's system the first time any method requiring the Vale CLI is executed. This means the first run might take longer due to the download.
Fix: Be aware that the first execution of a Vale operation will involve a download. Subsequent runs will use the cached binary.
breaking The versioning of the Python `vale` package (`X.Y.Z.P`) directly corresponds to the Vale CLI version (`X.Y.Z`). The fourth number (`P`) is specific to Python package fixes and is ignored when downloading the Vale CLI. Therefore, incrementing the fourth number does not update the underlying Vale CLI version.
Fix: To update the Vale CLI version, you must update the Python package to a version where the first three numbers (X.Y.Z) match the desired Vale CLI version. If only the Python wrapper needs fixing, increment the fourth number.
breaking Breaking changes in new versions of the underlying Vale CLI tool can silently alter linting behavior or cause errors, especially if not pinning the exact version. For example, Vale CLI v3.11.0 introduced changes to linting Front Matter fields that could break existing CI pipelines.
Fix: Always pin the exact version of the `vale` Python package in your `requirements.txt` or `pyproject.toml` to ensure consistent behavior across environments. For example, `vale==3.13.0`.

Install

pip install vale Install latest version
pip install vale==3.13.0.0 Install specific version (matching Vale CLI v3.13.0)

Imports

Vale
```
from vale import Vale
```

Quickstart

This quickstart demonstrates how to initialize the `Vale` object and lint a string. Note that Vale requires a `.vale.ini` configuration file and a `StylesPath` directory to operate correctly. This example creates minimal temporary configuration files. In a real application, you would manage these configuration files within your project structure. The Vale CLI binary is downloaded the first time `vale.lint()` is called, which might take a moment.

import os
from vale import Vale

# Vale requires a .vale.ini config file and a StylesPath directory.
# For a quickstart, we'll create minimal ones in a temporary directory.
# In a real project, these would be managed in your project structure.

config_content = """
StylesPath = styles
MinAlertLevel = warning

[*.md]
BasedOn = proselint
"""

style_content = """
# styles/proselint/SomeRule/Vocab.yml
# Minimal example rule (if you had a custom rule)
"""

# Create a temporary directory structure
# In a real application, you'd manage config_dir and style_dir appropriately
import tempfile
import shutil

try:
    with tempfile.TemporaryDirectory() as temp_dir:
        config_dir = os.path.join(temp_dir, ".vale")
        styles_dir = os.path.join(config_dir, "styles", "proselint")
        os.makedirs(styles_dir, exist_ok=True)

        with open(os.path.join(config_dir, ".vale.ini"), "w") as f:
            f.write(config_content)
        
        # You'd typically install actual styles here or reference system-wide ones
        # For this quickstart, we just need the directories to exist.

        vale_instance = Vale(config_path=os.path.join(config_dir, ".vale.ini"))

        text_to_lint = "This is a very simple test. I will be using bad grammar."

        # Lint the text. Output format is typically JSON.
        # The default output is a list of dictionaries, one for each alert.
        alerts = vale_instance.lint(text_to_lint, syntax='md')

        print(f"Found {len(alerts)} alerts:")
        for alert in alerts:
            print(f"  - [{alert['Severity']}] {alert['Message']} (Rule: {alert['Check']})")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure Vale CLI is successfully downloaded on first run and config is valid.")

view raw JSON →