Metadata-Version: 2.4
Name: ansys-pre-commit-hooks
Version: 0.8.1
Home-page: https://github.com/ansys/pre-commit-hooks
Author: Synopsys, Inc. and ANSYS, Inc.
Author-email: "Synopsys, Inc. and ANSYS, Inc." <pyansys-core@synopsys.com>
Maintainer: Synopsys, Inc. and ANSYS, Inc.
Maintainer-email: "Synopsys, Inc. and ANSYS, Inc." <pyansys-core@synopsys.com>
License-Expression: MIT
Project-URL: Source, https://github.com/ansys/pre-commit-hooks/
Project-URL: Issues, https://github.com/ansys/pre-commit-hooks/issues
Project-URL: Discussions, https://github.com/ansys/pre-commit-hooks/discussions
Project-URL: Documentation, https://pre-commit-hooks.docs.pyansys.com
Project-URL: Releases, https://github.com/ansys/pre-commit-hooks/releases
Project-URL: Changelog, https://github.com/ansys/pre-commit-hooks/blob/main/doc/source/changelog.rst
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10,<4
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: click==8.5.0
Requires-Dist: GitPython==3.2.1
Requires-Dist: importlib-metadata==9.0.1
Requires-Dist: Jinja2==3.1.6
Requires-Dist: packaging==26.3
Requires-Dist: reuse==6.3.0
Requires-Dist: requests==2.34.2
Requires-Dist: semver==3.1.0
Requires-Dist: toml==0.10.2
Provides-Extra: doc
Requires-Dist: ansys-sphinx-theme[autoapi]==1.9.0; extra == "doc"
Requires-Dist: numpydoc==1.11.0; extra == "doc"
Requires-Dist: sphinx==8.2.3; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints==3.1.0; extra == "doc"
Requires-Dist: sphinx-copybutton==0.5.2; extra == "doc"
Provides-Extra: tests
Requires-Dist: pytest==9.1.1; extra == "tests"
Requires-Dist: pytest-cov==7.1.0; extra == "tests"
Dynamic: author
Dynamic: classifier
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: requires-python

Ansys pre-commit hooks
======================
|pyansys| |python| |pypi| |GH-CI| |MIT| |ruff| |pre-commit-ci|

.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC
   :target: https://docs.pyansys.com/
   :alt: PyAnsys

.. |python| image:: https://img.shields.io/pypi/pyversions/ansys-pre-commit-hooks?logo=pypi
   :target: https://pypi.org/project/ansys-pre-commit-hooks/
   :alt: Python

.. |pypi| image:: https://img.shields.io/pypi/v/ansys-pre-commit-hooks.svg?logo=python&logoColor=white
   :target: https://pypi.org/project/ansys-pre-commit-hooks
   :alt: PyPI

.. |GH-CI| image:: https://github.com/ansys/pre-commit-hooks/actions/workflows/ci_cd.yml/badge.svg
   :target: https://github.com/ansys/pre-commit-hooks/actions/workflows/ci_cd.yml
   :alt: GH-CI

.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT
   :alt: MIT

.. |ruff| image:: https://img.shields.io/badge/code%20style-ruff-D7FF64.svg?style=flat
   :target: https://github.com/astral-sh/ruff
   :alt: Ruff

.. |pre-commit-ci| image:: https://results.pre-commit.ci/badge/github/ansys/pre-commit-hooks/main.svg
   :target: https://results.pre-commit.ci/latest/github/ansys/pre-commit-hooks/main
   :alt: pre-commit.ci status

This Ansys repository contains `pre-commit`_ hooks for different purposes.
The following hooks are currently available:

* ``add-license-headers``: Add missing license headers to files by using
  `REUSE <https://reuse.software/>`_ . To use this hook, you must
  have ``REUSE`` implemented in your repository.
* ``tech-review``: Do a technical review of your repository according to
  `Ansys repository requirements <https://dev.docs.pyansys.com/packaging/structure.html>`_
* ``pyansys-quality-report``: Check PyAnsys quality
   with selectable rules and a machine-readable JSON report.

Configure the quality report in the ``.pre-commit-config.yaml`` file:

.. code:: yaml

   - repo: https://github.com/ansys/pre-commit-hooks
     rev: v0.8.1
     hooks:
     - id: pyansys-quality-report
       args: [--show-all]
       verbose: true

Run ``pre-commit run pyansys-quality-report --all-files`` (or ``prek run
pyansys-quality-report --all-files``) to show warnings and errors.
Use ``--show-all`` to include passing checks, ``--check RM003`` to select a
rule, ``--ignore RM004`` to omit one, ``--color never`` for plain output, or
``--json`` for JSON output. Colors are enabled by default, including for
captured output. The current rules and options are documented in the
`quality report guide <https://pre-commit-hooks.docs.ansys.com/version/stable/getting-started/pyansys-quality-report/index.html>`_.

How to install
--------------

The following sections provide instructions for installing the ``ansys-pre-commit-hooks``
package in two installation modes: user and developer.

For users
^^^^^^^^^

Before installing the package, to ensure that you
have the latest version of `pip`_, run this command:

.. code:: bash

    python -m pip install -U pip

Then, to install the package, run this command:

.. code:: bash

    python -m pip install ansys-pre-commit-hooks

For developers
^^^^^^^^^^^^^^

Installing the package in developer mode allows you to modify and
enhance the source code.

Before contributing to the project, ensure that you are familiar with
the `PyAnsys Developer's Guide`_.

For a developer installation, you must follow these steps:

#. Clone the repository with this command:

   .. code:: bash

      git clone https://github.com/ansys/pre-commit-hooks

#. Create a fresh-clean Python environment and activate it with these commands:

   .. code:: bash

      # Create a virtual environment
      python -m venv .venv

      # Activate it in a POSIX system
      source .venv/bin/activate

      # Activate it in Windows CMD environment
      .venv\Scripts\activate.bat

      # Activate it in Windows Powershell
      .venv\Scripts\Activate.ps1

#. Ensure that you have the latest required build system tools by
   running this command:

   .. code:: bash

      python -m pip install -U pip flit tox twine


#. Install the project in editable mode by running one of these commands:

   .. code:: bash

      # Install the minimum requirements
      python -m pip install -e .

      # Install the minimum + tests requirements
      python -m pip install -e .[tests]

      # Install the minimum + doc requirements
      python -m pip install -e .[doc]

      # Install all requirements
      python -m pip install -e .[tests,doc]

#. Verify your development installation by running this command:

   .. code:: bash

      tox


How to test it
--------------

This project takes advantage of `tox`_. This tool automates common
development tasks (similar to Makefile), but it is oriented towards
Python development.

Using ``tox``
^^^^^^^^^^^^^

While Makefile has rules, ``tox`` has environments. In fact, ``tox`` creates its
own virtual environment so that anything being tested is isolated from the project
to guarantee the project's integrity.

These environment commands are provided:

- **tox -e style**: Checks for coding style quality.
- **tox -e py**: Checks for unit tests.
- **tox -e py-coverage**: Checks for unit testing and code coverage.
- **tox -e doc**: Checks for successfully building the documentation.


Raw testing
^^^^^^^^^^^

If required, you can call ``ruff check --fix .`` and ``ruff format .`` with
`Ruff`_, or unit testing commands, such as `pytest`_, from the command line.
However, calling these commands does not guarantee that your project is
being tested in an isolated environment, which is the reason why tools like
``tox`` exist.


A note on ``pre-commit``
^^^^^^^^^^^^^^^^^^^^^^^^

The style checks take advantage of `pre-commit`_. Developers are not forced but
encouraged to install this tool by running this command:

.. code:: bash

    python -m pip install pre-commit && pre-commit install


Documentation
-------------

For building documentation, you can run the usual rules provided in the
`Sphinx`_ Makefile with a command that is formatted like this:

.. code:: bash

    make -C doc/ html && your_browser_name doc/html/index.html

However, the recommended way of checking documentation integrity is by
running ``tox`` with a command that is formatted like this:

.. code:: bash

    tox -e doc && your_browser_name .tox/doc_out/index.html


Distributing
------------

If you would like to create either source or wheel files, install
the building requirements and then execute the build module with these commands:

.. code:: bash

    python -m pip install .
    python -m build
    python -m twine check dist/*


.. LINKS AND REFERENCES
.. _Ruff: https://docs.astral.sh/ruff/
.. _pip: https://pypi.org/project/pip/
.. _pre-commit: https://pre-commit.com/
.. _PyAnsys Developer's Guide: https://dev.docs.pyansys.com/
.. _pytest: https://docs.pytest.org/en/stable/
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _tox: https://tox.wiki/
