Ansys pre-commit hooks#
This Ansys repository contains pre-commit hooks for different purposes. Currently, these hooks are available:
add-license-headers
: Add missing license headers to files by using REUSE . To use this hook, you must haveREUSE
implemented in your repository.tech-review
: Do a technical review of your repository according to Ansys repository requirements
add-license-headers
setup#
Add required directories#
If you are using the ansys.jinja2 template and MIT.txt license, skip this step. By default, the hook will make symbolic links from its “assets” directory containing LICENSES/MIT.txt and .reuse/templates/ansys.jinja2 to your repository when the hook runs. The .reuse and LICENSES directories will be deleted once the hook is done running.
If you are using a custom template, create a directory named .reuse
, and if you are using a custom license, create a directory
named LICENSES
in the root of your repository. The custom template cannot be named ansys.jinja2
, otherwise it will be removed
after the hook is done running. The custom license cannot be named MIT.txt
for the same reason. The .reuse
and/or LICENSES
directories will have to be committed to your repository and will not be removed once the hook is done running as long as there
are custom templates or licenses in those directories. Your project should have the following layout:
project ├── LICENCES │ └── license_name.txt ├── .reuse │ └── templates │ └── template_name.jinja2 ├── src ├── examples ├── tests ├── .pre-commit-config.yaml ├── pyproject.toml
Where license_name
is the name of the license that is being used, for example, MIT.txt, and
template_name
is the name of the custom template being used. The jinja2 file contains the
template for the license headers that are added to the files.
Licenses that are supported by REUSE
can be found in the
spdx/license-list-data repository.
Please select a license text file from that repository, and copy it to the LICENSES directory.
Set custom arguments#
- repo: https://github.com/ansys/pre-commit-hooks
rev: v0.4.3
hooks:
- id: add-license-headers
args: ["--custom_copyright", "custom copyright phrase", "--custom_template", "template_name", "--custom_license", "license_name", "--ignore_license_check", "--start_year", "2023"]
args
can also be formatted as follows:
args:
- --custom_copyright=custom copyright phrase
- --custom_template=template_name
- --custom_license=license_name
- --ignore_license_check
- --start_year=2023
custom copyright phrase
is the copyright line you want to include in the license header. By default, it uses"ANSYS, Inc. and/or its affiliates."
.template_name
is the name of the .jinja2 file located in.reuse/templates/
. By default, it usesansys
.license_name
is the name of the license being used. For example, MIT, ECL-1.0, etc. To view a list of licenses that are supported byREUSE
, see spdx/license-list-data. By default it usesMIT
.ignore_license_check
is whether or not to check for the license in the header. By default, it isFalse
, meaning the files are checked for both the copyright and licensing information in the header. Add--ignore_license_check
to ignore checking for licensing information in the files.start_year
is the start year of the copyright statement. By default, thestart_year
is the current year, making the copyright statement “Copyright (C) 2024 ANSYS, Inc. and/or its affiliates.” If you are adding license headers to packages released before the current year, add thestart_year
argument with the year your package was released. For example, ifstart_year
is 2023, the copyright statement would be “Copyright (C) 2023 - 2024 ANSYS, Inc. and/or its affiliates.” assuming the current year is 2024.
Specify directories to run the hook on#
By default, the hook will run on proto files in any directory, as well as python files within
directories named src
, examples
, and tests
. To specify additional files and/or directories
the hook should run on, add the necessary regex to the files
line in your
.pre-commit-config.yaml file:
- repo: https://github.com/ansys/pre-commit-hooks
rev: v0.4.3
hooks:
- id: add-license-headers
files: '(src|examples|tests|newFolder)/.*\.(py|newExtension)|\.(proto|newExtension)'
Ignore specific files or file types#
In .pre-commit-config.yaml:
- repo: https://github.com/ansys/pre-commit-hooks
rev: v0.4.3
hooks:
- id: add-license-headers
exclude: |
(?x)^(
path/to/file1.py |
path/to/.*\.(ts|cpp) |
(.folder1|folder2)/.* |
.*\.js |
\..* |
)$
path/to/file1.py
excludes the stated file.path/to/.*\.(ts|cpp)
excludes all .ts and .cpp files within thepath/to
directory.(.folder1|folder2)/.*
excludes directories named .folder1 and folder2..*\.js
excludes all .js files in all directories.\..*
excludes all hidden files.
tech-review
setup#
These are the default values for the arguments of the tech-review hook:
--author_maint_name=ANSYS, Inc.
--author_maint_email=pyansys.core@ansys.com
--license=MIT
--url=https://github.com/ansys/{repo-name}
, replacingrepo-name
with the name of the repository
The --author_maint_name
is the name of the author and maintainer in the pyproject.toml
file.
By default, it is “Ansys, Inc.”.
The --author_maint_email
is the email of the author and maintainer in the pyproject.toml
file.
By default, it is “pyansys.core@ansys.com”.
The --license
argument is the license that is being used by your repository. By default, it is
MIT.
The --url
argument is automatically rendered based on the repository name. If your repository
is not in the Ansys organization, please add this argument to your configuration in
.pre-commit-config.yaml.
The --product
argument is required if a README.rst
or README.md
file does not
exist in your repository and you want the template to render correctly. The product
for PyMechanical
would be mechanical
, for example.
The --non_compliant_name
flag can be used if your repository does not follow the typical
naming convention of ansys-*-*
.
Technical review hook in ansys/pre-commit-hooks
’ .pre-commit-config.yaml file:
- repo: https://github.com/ansys/pre-commit-hooks
rev: v0.4.3
hooks:
- id: tech-review
args:
- --product=pre_commit_hooks
- --non_compliant_name
Technical review hook in PyMechanical
’s .pre-commit-config.yaml file:
- repo: https://github.com/ansys/pre-commit-hooks
rev: v0.4.3
hooks:
- id: tech-review
args:
- --product=mechanical
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:
python -m pip install -U pip
Then, to install the package, run this command:
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:
git clone https://github.com/ansys/pre-commit-hooks
Create a fresh-clean Python environment and activate it with these commands:
# 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:
python -m pip install -U pip flit tox twine
Install the project in editable mode by running one of these commands:
# 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:
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 always call style commands, such as black, isort,
and flake8, 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:
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:
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:
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:
python -m pip install .
python -m build
python -m twine check dist/*