Package: ansys-pre-commit-hooks
This Ansys repository containspre-commithooks for different purposes.
Currently, these hooks are available:add-license-headers: Add missing license headers to files by usingREUSE. To use this hook, you must
haveREUSEimplemented in your repository.add-license-headerssetupAdd required directoriesIf 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
namedLICENSESin the root of your repository. The custom template cannot be namedansys.jinja2, otherwise it will be removed
after the hook is done running. The custom license cannot be namedMIT.txtfor the same reason. The.reuseand/orLICENSESdirectories 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.tomlWherelicense_nameis the name of the license that is being used, for example, MIT.txt, andtemplate_nameis 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 byREUSEcan be found in thespdx/license-list-datarepository.
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-hooksrev:v0.2.9hooks:-id:add-license-headersargs:["--custom_copyright","customcopyrightphrase","--custom_template","template_name","--custom_license","license_name","--ignore_license_check","--start_year","2023"]argscan also be formatted as follows:args:---custom_copyright=custom copyright phrase---custom_template=template_name---custom_license=license_name---ignore_license_check---start_year=2023custom copyright phraseis the copyright line you want to include in the license
header. By default, it uses"ANSYS, Inc. and/or its affiliates.".template_nameis the name of the .jinja2 file located in.reuse/templates/.
By default, it usesansys.license_nameis the name of the license being used. For example, MIT, ECL-1.0, etc.
To view a list of licenses that are supported byREUSE, seehttps://github.com/spdx/license-list-data/tree/main/text. By default it usesMIT.ignore_license_checkis 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_checkto ignore checking for licensing information
in the files.start_yearis the start year of the copyright statement. By default, thestart_yearis
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_yearargument with the year your
package was released. For example, ifstart_yearis 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 onBy default, the hook will run on proto files in any directory, as well as python files within
directories namedsrc,examples, andtests. To specify additional files and/or directories
the hook should run on, add the necessary regex to thefilesline in your
.pre-commit-config.yaml file:-repo:https://github.com/ansys/pre-commit-hooksrev:v0.2.9hooks:-id:add-license-headersfiles:'(src|examples|tests|newFolder)/.*\.(py|newExtension)|\.(proto|newExtension)'Ignore specific files or file typesIn .pre-commit-config.yaml:-repo:https://github.com/ansys/pre-commit-hooksrev:v0.2.9hooks:-id:add-license-headersexclude:|(?x)^(path/to/file1.py |path/to/.*\.(ts|cpp) |(.folder1|folder2)/.* |.*\.js |\..* |)$path/to/file1.pyexcludes the stated file.path/to/.*\.(ts|cpp)excludes all .ts and .cpp files within thepath/todirectory.(.folder1|folder2)/.*excludes directories named .folder1 and folder2..*\.jsexcludes all .js files in all directories.\..*excludes all hidden files.How to installThe following sections provide instructions for installing theansys-pre-commit-hookspackage in two installation modes: user and developer.For usersBefore installing the package, to ensure that you
have the latest version ofpip, run this command:python-mpipinstall-UpipThen, to install the package, run this command:python-mpipinstallansys-pre-commit-hooksFor developersInstalling 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
thePyAnsys Developer’s Guide.For a developer installation, you must follow these steps:Clone the repository with this command:gitclonehttps://github.com/ansys/pre-commit-hooksCreate a fresh-clean Python environment and activate it with these commands:# Create a virtual environmentpython-mvenv.venv# Activate it in a POSIX systemsource.venv/bin/activate# Activate it in Windows CMD environment.venv\Scripts\activate.bat# Activate it in Windows Powershell.venv\Scripts\Activate.ps1Ensure that you have the latest required build system tools by
running this command:python-mpipinstall-UpipflittoxtwineInstall the project in editable mode by running one of these commands:# Install the minimum requirementspython-mpipinstall-e.# Install the minimum + tests requirementspython-mpipinstall-e.[tests]# Install the minimum + doc requirementspython-mpipinstall-e.[doc]# Install all requirementspython-mpipinstall-e.[tests,doc]Verify your development installation by running this command:toxHow to test itThis project takes advantage oftox. This tool automates common
development tasks (similar to Makefile), but it is oriented towards
Python development.UsingtoxWhile Makefile has rules,toxhas environments. In fact,toxcreates 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 testingIf required, you can always call style commands, such asblack,isort,
andflake8, or unit testing commands, such aspytest, 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 liketoxexist.A note onpre-commitThe style checks take advantage ofpre-commit. Developers are not forced but
encouraged to install this tool by running this command:python-mpipinstallpre-commit&&pre-commitinstallDocumentationFor building documentation, you can run the usual rules provided in theSphinxMakefile with a command that is formatted like this:make-Cdoc/html&&your_browser_namedoc/html/index.htmlHowever, the recommended way of checking documentation integrity is by
runningtoxwith a command that is formatted like this:tox-edoc&&your_browser_name.tox/doc_out/index.htmlDistributingIf you would like to create either source or wheel files, install
the building requirements and then execute the build module with these commands:python-mpipinstall.python-mbuildpython-mtwinecheckdist/*