{"id":8757,"library":"vale","title":"Vale Python Package","description":"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.","status":"active","version":"3.13.0.0","language":"en","source_language":"en","source_url":"https://github.com/daniperez/vale-python-package","tags":["linter","grammar","style check","prose","cli wrapper","documentation"],"install":[{"cmd":"pip install vale","lang":"bash","label":"Install latest version"},{"cmd":"pip install vale==3.13.0.0","lang":"bash","label":"Install specific version (matching Vale CLI v3.13.0)"}],"dependencies":[],"imports":[{"symbol":"Vale","correct":"from vale import Vale"}],"quickstart":{"code":"import os\nfrom vale import Vale\n\n# Vale requires a .vale.ini config file and a StylesPath directory.\n# For a quickstart, we'll create minimal ones in a temporary directory.\n# In a real project, these would be managed in your project structure.\n\nconfig_content = \"\"\"\nStylesPath = styles\nMinAlertLevel = warning\n\n[*.md]\nBasedOn = proselint\n\"\"\"\n\nstyle_content = \"\"\"\n# styles/proselint/SomeRule/Vocab.yml\n# Minimal example rule (if you had a custom rule)\n\"\"\"\n\n# Create a temporary directory structure\n# In a real application, you'd manage config_dir and style_dir appropriately\nimport tempfile\nimport shutil\n\ntry:\n    with tempfile.TemporaryDirectory() as temp_dir:\n        config_dir = os.path.join(temp_dir, \".vale\")\n        styles_dir = os.path.join(config_dir, \"styles\", \"proselint\")\n        os.makedirs(styles_dir, exist_ok=True)\n\n        with open(os.path.join(config_dir, \".vale.ini\"), \"w\") as f:\n            f.write(config_content)\n        \n        # You'd typically install actual styles here or reference system-wide ones\n        # For this quickstart, we just need the directories to exist.\n\n        vale_instance = Vale(config_path=os.path.join(config_dir, \".vale.ini\"))\n\n        text_to_lint = \"This is a very simple test. I will be using bad grammar.\"\n\n        # Lint the text. Output format is typically JSON.\n        # The default output is a list of dictionaries, one for each alert.\n        alerts = vale_instance.lint(text_to_lint, syntax='md')\n\n        print(f\"Found {len(alerts)} alerts:\")\n        for alert in alerts:\n            print(f\"  - [{alert['Severity']}] {alert['Message']} (Rule: {alert['Check']})\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure Vale CLI is successfully downloaded on first run and config is valid.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Be aware that the first execution of a Vale operation will involve a download. Subsequent runs will use the cached binary.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":"Vale CLI v3.11.0 and later (as reflected in `vale` Python package versions)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed using `pip install vale` within your active virtual environment.","cause":"The `vale` package was not installed or is not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'vale'"},{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'vale'"},{"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.","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.","error":"Runtime error 'Apple Developer Program roles and permissions' not found Execution stopped with code 1."}]}