{"id":5046,"library":"rstcheck-core","title":"rstcheck-core","description":"rstcheck-core is the core library behind the rstcheck CLI application, used for checking the syntax of reStructuredText documents and code blocks embedded within them. It leverages docutils for parsing RST and reports found issues. The library follows semantic versioning, with bugfixes typically supported only for the current minor release. It has a regular release cadence, with updates often reflecting changes in the broader rstcheck ecosystem.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/rstcheck/rstcheck-core","tags":["reStructuredText","rst","linter","static-analysis","documentation"],"install":[{"cmd":"pip install rstcheck-core","lang":"bash","label":"Install core library"},{"cmd":"pip install rstcheck-core[sphinx,toml,yaml]","lang":"bash","label":"Install with optional extras"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false},{"reason":"Used internally for reStructuredText parsing.","package":"docutils","optional":false},{"reason":"Optional dependency for Sphinx integration (e.g., when installing `rstcheck[sphinx]`).","package":"sphinx","optional":true},{"reason":"Optional dependency for TOML configuration file support (e.g., when installing `rstcheck[toml]`).","package":"toml","optional":true},{"reason":"Optional dependency for YAML configuration file support (e.g., when installing `rstcheck[yaml]`).","package":"pyyaml","optional":true}],"imports":[{"note":"The `rstcheck.check` import is for the older, monolithic `rstcheck` package. `rstcheck-core` is the separated core library, requiring direct import from `rstcheck_core`.","wrong":"from rstcheck import check","symbol":"check","correct":"from rstcheck_core import check"}],"quickstart":{"code":"from rstcheck_core import check\n\nrst_content = '''\nExample\n=======\n\n.. code:: python\n    print(\"Hello, rstcheck!\")\n\n.. code:: badlang\n    This language does not exist.\n'''\n\nissues = list(check(rst_content))\nfor line, message in issues:\n    print(f\"Line {line}: {message}\")\n\n# Example with an actual error:\nerror_rst = '''\nBad RST\n=======\n\nThis title underline is too short.\n===\n'''\nissues_with_error = list(check(error_rst))\nfor line, message in issues_with_error:\n    print(f\"Line {line}: {message}\")","lang":"python","description":"This quickstart demonstrates how to use the `check` function from `rstcheck_core` to programmatically validate reStructuredText content. It will yield a series of (line_number, message) tuples for any detected issues."},"warnings":[{"fix":"Update import paths to use `rstcheck_core` where applicable. Review CLI options and configuration file keys as many were renamed or changed in `rstcheck` v6.","message":"The `rstcheck` project underwent a significant architectural change with version 6.0.0, where the core logic was extracted into the `rstcheck-core` library. Direct imports or interactions with internal `rstcheck` modules from versions 5.x or earlier will break when migrating to `rstcheck-core` or `rstcheck` v6+.","severity":"breaking","affected_versions":"rstcheck <6.0.0 (when migrating to rstcheck-core v1+)"},{"fix":"For critical usage, consider running `rstcheck-core` within a Linux environment (e.g., WSL, Docker) or use a CI/CD pipeline running on Linux. Monitor GitHub issues for updates on Windows stability.","message":"Windows support for `rstcheck-core` is explicitly stated as not stable. Tests can fail with incorrect positives and negatives for unknown reasons, which may lead to unreliable linting results on Windows systems.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be explicit with CLI options if overriding configuration is intended. If you need to debug which configuration file is being used, `rstcheck` (the CLI tool) has a `--log-level DEBUG` option that can help. Ensure your project structure and configuration file placement match the expected search behavior, or explicitly specify the config file path using `--config`.","message":"Configuration settings defined in files (e.g., `.rstcheck.cfg`, `pyproject.toml`, `setup.cfg`) can be completely overridden by command-line interface (CLI) options. Additionally, `rstcheck-core` searches for configuration files by traversing up the directory tree from the checked file, which might lead to unexpected configuration being applied if not carefully managed.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}