.. module:: Tools =============================================================================== Tools =============================================================================== All tools below are installed automatically as dependencies of ``core-dev-tools``. They are grouped by purpose so you can quickly find what you need for a given CI/CD stage or development workflow. CLI Commands =============================================================================== ``core-dev-tools`` ships a small CLI of its own, exposed through your project's ``manager.py`` via ``cli_dev``. Wire it in once and every project gets the same commands: .. code-block:: python from click.core import CommandCollection from core_dev_tools.cli.runner import cli_dev CommandCollection(sources=[cli_dev])() run-linters ******************************************************************************* Runs all five linters and type checkers against a given package directory. All tools always run; failures are collected and reported together at the end. .. code-block:: bash python manager.py run-linters python manager.py run-linters --tool ruff # Single tool python manager.py run-linters --tool mypy --tool ty # Multiple tools Tools executed in order: ``ty check``, ``ruff check``, ``mypy --explicit-package-bases``, ``pyright``, ``pylint``. run-security ******************************************************************************* Runs security scanners against a given package directory. All tools always run; failures are collected and reported together at the end. .. code-block:: bash python manager.py run-security Tools executed in order: ``bandit -r ``, ``pip-audit``. Package & Environment Management =============================================================================== UV ******************************************************************************* An extremely fast Python package and project manager, written in Rust. More information: https://docs.astral.sh/uv/ .. code-block:: bash uv [OPTIONS] Linting & Formatting =============================================================================== Ruff Linter ******************************************************************************* The Ruff Linter is an extremely fast Python linter designed as a drop-in replacement for Flake8 (plus dozens of plugins), isort, pydocstyle, pyupgrade, autoflake, and more. More information: https://docs.astral.sh/ruff/linter/ .. code-block:: bash ruff check # Lint files in the current directory. ruff check --fix # Lint files in the current directory and fix any fixable errors. ruff check --watch # Lint files in the current directory and re-lint on change. ruff check path/to/code/ # Lint files in `path/to/code`. PyLint ******************************************************************************* Pylint is a tool that checks for errors in Python code, tries to enforce a coding standard (stricter/static code analyzer (if you want more opinions than ruff)) and looks for bad code smells. More information: https://docs.pylint.org/ .. code-block:: bash pylint Type Checking =============================================================================== Mypy ******************************************************************************* Mypy is an optional static type checker for Python that aims to combine the benefits of dynamic (or "duck") typing and static typing. More information: * https://mypy-lang.org/ * https://mypy.readthedocs.io/en/stable/ .. code-block:: bash mypy . Pyright ******************************************************************************* Pyright is a full-featured, standards-compliant static type checker for Python. It is designed for high performance and can be used with large Python source bases. More information: https://microsoft.github.io/pyright .. code-block:: bash pyright ty ******************************************************************************* ty is an extremely fast Python type checker and language server written in Rust, developed by Astral (the creators of Ruff and uv). It is designed to be a high-performance alternative to mypy and pyright. More information: https://docs.astral.sh/ty/ .. code-block:: bash ty check # Type-check the current project. ty check # Type-check a specific file or directory. Security & Compliance =============================================================================== Bandit ******************************************************************************* Bandit is a tool designed to find common security issues in Python code. To do this Bandit processes each file, builds an AST from it, and runs appropriate plugins against the AST nodes. Once Bandit has finished scanning all the files it generates a report. More information: https://pypi.org/project/bandit/ .. code-block:: bash bandit -r pip-audit ******************************************************************************* It is a tool for scanning Python environments for packages with known vulnerabilities. It uses the Python Packaging Advisory Database (https://github.com/pypa/advisory-database) via the PyPI JSON API as a source of vulnerability reports. More information: https://pypi.org/project/pip-audit/ .. code-block:: bash pip-audit Testing =============================================================================== pytest ******************************************************************************* pytest is a mature, full-featured Python testing framework. It makes it easy to write small, readable tests and scales to support complex functional testing for applications and libraries. More information: https://docs.pytest.org/ .. code-block:: bash pytest # Run all tests. pytest tests/test_foo.py # Run a single test file. pytest -k "test_name" # Run tests matching a keyword expression. pytest -v # Run with verbose output. pytest-cov ******************************************************************************* pytest-cov is a pytest plugin that measures code coverage during test runs. It integrates with the ``coverage`` package and supports parallel test execution via pytest-xdist. More information: https://pytest-cov.readthedocs.io/ .. code-block:: bash pytest --cov= # Run tests with coverage report. pytest --cov= --cov-report=html # Generate HTML coverage report. pytest --cov= --cov-report=term # Print coverage summary to terminal. pytest-xdist ******************************************************************************* pytest-xdist is a pytest plugin that extends pytest with distributed and parallel test execution modes. It allows tests to run across multiple CPUs or even remote machines. More information: https://pytest-xdist.readthedocs.io/ .. code-block:: bash pytest -n auto # Run tests in parallel using all available CPUs. pytest -n # Run tests in parallel using workers. coverage ******************************************************************************* `coverage` measures code coverage of Python programs. It monitors which lines of your program are executed and which are not, making it easy to identify untested code. More information: https://coverage.readthedocs.io/ .. code-block:: bash coverage run -m pytest # Run tests and measure coverage. coverage report # Print coverage summary to terminal. coverage html # Generate HTML coverage report. Tox ******************************************************************************* It aims to automate and standardize testing in Python. It is part of a larger vision of easing the packaging, testing and release process of Python software (alongside pytest and devpi). More information: * https://pypi.org/project/tox/ * https://tox.wiki .. code-block:: bash tox Git Hooks =============================================================================== pre-commit ******************************************************************************* pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. It integrates with git to automatically run checks (linters, formatters, security scanners) before each commit. More information: https://pre-commit.com/ .. code-block:: bash pre-commit install # Install hooks into the git repository. pre-commit run --all-files # Run all hooks against all files. pre-commit autoupdate # Update hook versions to latest. CLI & Configuration Utilities =============================================================================== click ******************************************************************************* Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It is highly configurable and comes with sensible defaults out of the box. More information: https://click.palletsprojects.com/ .. code-block:: python @click.command() @click.option("--name", prompt="Your name", help="The person to greet.") def hello(name): click.echo(f"Hello {name}!") environs ******************************************************************************* environs is a Python library for parsing environment variables. It makes it easy to define expected types, default values, and validation rules for environment-based configuration, with support for ``.env`` files. More information: https://github.com/sloria/environs .. code-block:: python from environs import Env env = Env() env.read_env() # Read .env file if it exists. DEBUG = env.bool("DEBUG") # Parse and cast to bool. PORT = env.int("PORT", 5000) # With a default value. Task Automation =============================================================================== taskipy ******************************************************************************* The complementary task runner for python. More information: https://pypi.org/project/taskipy/ .. code-block:: bash task Documentation =============================================================================== Sphinx ******************************************************************************* Sphinx makes it easy to create intelligent and beautiful documentation. More information: https://www.sphinx-doc.org/ .. code-block:: bash sphinx-quickstart docs cd docs make html Packaging & Publishing =============================================================================== Build ******************************************************************************* A simple, correct Python packaging build frontend. It manages pyproject.toml-based builds, invoking build-backend hooks as appropriate to build a distribution package. It is a simple build tool and does not perform any dependency management. More information: https://pypi.org/project/build/ .. code-block:: bash python -m build Twine ******************************************************************************* Twine is a utility for publishing Python packages to PyPI and other repositories. It provides build system independent uploads of source and binary distribution artifacts for both new and existing projects. More information: https://twine.readthedocs.io/en/stable/ .. code-block:: bash twine check dist/* twine upload -u USER -p PASSWORD dist/*