Metadata-Version: 2.4
Name: core-dev-tools
Version: 2.1.0
Summary: This library provides common tools used for development...
Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
Maintainer: Alejandro Cora González
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/bytecode-solutions/core/core-dev-tools
Project-URL: Repository, https://gitlab.com/bytecode-solutions/core/core-dev-tools
Project-URL: Documentation, https://core-dev-tools.readthedocs.io/en/latest/
Project-URL: Issues, https://gitlab.com/bytecode-solutions/core/core-dev-tools/-/issues
Project-URL: Changelog, https://gitlab.com/bytecode-solutions/core/core-dev-tools/-/blob/main/CHANGELOG.md
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: bandit>=1.8.6
Requires-Dist: build>=1.3.0
Requires-Dist: click>=8.1.8
Requires-Dist: coverage[toml]>=7.10.0
Requires-Dist: environs>=14.1.1
Requires-Dist: mypy>=1.17.1
Requires-Dist: pip-audit>=2.9.0
Requires-Dist: pre-commit>=3.8.0
Requires-Dist: pylint>=3.3.8
Requires-Dist: pytest>=8.4.0
Requires-Dist: pytest-cov>=7.0.0
Requires-Dist: pytest-xdist>=3.8.0
Requires-Dist: pyright>=1.1.404
Requires-Dist: ruff>=0.12.11
Requires-Dist: setuptools>=61.0.0
Requires-Dist: Sphinx>=7.4.7
Requires-Dist: types-setuptools>=62.6.1
Requires-Dist: taskipy>=1.14.1
Requires-Dist: tox>=4.29.0
Requires-Dist: twine>=6.1.0
Requires-Dist: ty>=0.0.18
Requires-Dist: uv>=0.8.14
Requires-Dist: wheel>=0.45.0
Dynamic: license-file

core-dev-tools
===============================================================================

``core-dev-tools`` is a Python meta-package that centralizes the standard
development toolchain for the entire ecosystem. Instead of each
project independently declaring and versioning its own development tools,
every project installs this single package and immediately has access to the
full, curated set of tools.

There is no Python source code, the value of this package is entirely in
its curated dependency list. A single ``pip install core-dev-tools`` is enough
to equip any project or CI/CD pipeline with tools for:

* **Testing** — pytest, pytest-cov, pytest-xdist, coverage, tox
* **Linting & formatting** — Ruff, Pylint
* **Type checking** — Mypy, Pyright, ty
* **Security & compliance** — Bandit (``bandit --check``), pip-audit
* **Packaging & publishing** — Build, Twine
* **Pre-commit hooks** — pre-commit
* **Documentation** — Sphinx
* **Task automation** — taskipy, UV
* **Configuration** — click, environs

This ensures consistent, version-controlled tooling across every project in
the ecosystem without any per-project duplication.

===============================================================================

.. image:: https://static.pepy.tech/personalized-badge/core-dev-tools?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads
    :target: https://pepy.tech/projects/core-dev-tools
    :alt: PyPI Downloads

.. image:: https://img.shields.io/pypi/pyversions/core-dev-tools.svg
    :target: https://pypi.org/project/core-dev-tools/
    :alt: Python Versions

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-dev-tools/-/blob/main/LICENSE
    :alt: License

.. image:: https://gitlab.com/bytecode-solutions/core/core-dev-tools/badges/release/pipeline.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-dev-tools/-/pipelines
    :alt: Pipeline Status

.. image:: https://readthedocs.org/projects/core-dev-tools/badge/?version=latest
    :target: https://readthedocs.org/projects/core-dev-tools/
    :alt: Docs Status

.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security

|


Installation
===============================================================================

Install from PyPI using pip:

.. code-block:: bash

    pip install core-dev-tools
    uv pip install core-dev-tools  # Or using UV...


Getting Started
===============================================================================

Install once per project or environment, all tools are immediately available
on the ``PATH``:

.. code-block:: bash

    ruff check .             # Lint
    mypy .                   # Type check
    bandit -r .              # Security scan
    pytest -n auto --cov=.   # Tests with parallel execution and coverage
    pip-audit                # Dependency vulnerability scan

For detailed documentation, visit: https://core-dev-tools.readthedocs.io/


Development
===============================================================================

**Run the test suite:**

.. code-block:: bash

    python -m unittest discover -v tests/unit

**Run tests with coverage report:**

.. code-block:: bash

    coverage run -m unittest discover tests/unit
    coverage report -m                                  # Terminal summary
    coverage html                                       # HTML report in htmlcov/

**Run linters against the package:**

.. code-block:: bash

    python manager.py run-linters core_dev_tools
    python manager.py run-linters core_dev_tools --tool ruff --tool mypy   # Specific tools only

**Run security scanners against the package:**

.. code-block:: bash

    python manager.py run-security core_dev_tools


CI/CD Usage
===============================================================================

The primary motivation for this package is CI/CD pipelines. Rather than
listing every tool in each project's pipeline configuration, simply install
``core-dev-tools`` at the start of the pipeline:

.. code-block:: yaml

    # Example GitLab CI / GitHub Actions step
    - pip install core-dev-tools

Then run the tools you need in subsequent steps:

.. code-block:: bash

    ruff check .                     # Enforce code style
    pylint src/                      # Static analysis
    mypy src/                        # Type checking
    bandit -r src/                   # Security compliance
    pip-audit                        # CVE scan on dependencies
    pytest -n auto --cov=src/        # Run test suite with coverage
    tox                              # Multi-environment testing

Updating tool versions for the entire ecosystem is a single change in
this package's ``pyproject.toml``, every downstream project picks it up
on their next install.


Available Tools
===============================================================================

UV
-------------------------------------------------------------------------------
An extremely fast Python package and project manager, written in Rust.

More information: https://docs.astral.sh/uv/

.. code-block:: bash

    uv [OPTIONS] <COMMAND>


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 <module_or_package>


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


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 <path>


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}!")


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.


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.


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


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.


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=<source>                       # Run tests with coverage report.
    pytest --cov=<source> --cov-report=html     # Generate HTML coverage report.
    pytest --cov=<source> --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 <num>         # Run tests in parallel using <num> workers.


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


taskipy
-------------------------------------------------------------------------------
The complementary task runner for python.

More information: https://pypi.org/project/taskipy/

.. code-block:: bash

    task <task-name>


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


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/*


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 <path>     # Type-check a specific file or directory.


Contributing
===============================================================================

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: ``pytest -n auto``
5. Run linting: ``pylint .``
6. Run security checks: ``bandit .``
7. Submit a pull request


License
===============================================================================

This project is licensed under the MIT License. See the LICENSE file for details.


Links
===============================================================================

* **Documentation:** https://core-dev-tools.readthedocs.io/en/latest/
* **Repository:** https://gitlab.com/bytecode-solutions/core/core-dev-tools
* **Issues:** https://gitlab.com/bytecode-solutions/core/core-dev-tools/-/issues
* **Changelog:** https://gitlab.com/bytecode-solutions/core/core-dev-tools/-/blob/main/CHANGELOG.md
* **PyPI:** https://pypi.org/project/core-dev-tools/


Support
===============================================================================

For questions or support, please open an issue on GitLab or contact the maintainers.


Authors
===============================================================================

* **Alejandro Cora González** - *Initial work* - alek.cora.glez@gmail.com
