Contribute#
Overall guidance on contributing to a PyAnsys library appears in Contributing in the PyAnsys Developer’s Guide. Ensure that you are thoroughly familiar with this guide before attempting to contribute to PyMechanical.
The following contribution information is specific to PyMechanical.
Clone the repository and install project dependencies#
To clone and install the latest PyMechanical release in development mode, run these commands:
Clone the repository and create a virtual environment:
# Clone the repository
git clone https://github.com/ansys/pymechanical
cd pymechanical
# Create a virtual environment
python -m venv .venv
Activate the virtual environment:
.venv\Scripts\activate.bat
.venv\Scripts\Activate.ps1
source .venv/bin/activate
Install tools and dependencies:
# Install build system tools
python -m pip install --upgrade pip tox flit twine
# Install the project, documentation, and test dependencies in editable mode
python -m pip install -e .[doc,tests]
Test PyMechanical#
PyMechanical uses PyTest and tox for unit testing. Prior to running the tests, ensure Mechanical is installed on your system with a valid license and the test dependencies are installed. Run this command to install the test dependencies:
pip install -e .[tests]
Using pytest
#
To run the tests, navigate to the root directory of the repository and run this command:
pytest
The pytest
command runs all of the tests in the tests
folder. After pytest
is
done running, it shows the test coverage of each of the files in the repository. To run
specific tests, run these commands:
# Run tests for embedded instances
pytest -m embedding
# Run tests for embedded instances that use subprocess
pytest -m embedding_scripts
# Run tests that launch Mechanical and work with the gRPC server inside of it
pytest -m remote_session_launch
# Run tests that connect to Mechanical and work with the gRPC server inside of it
pytest -m remote_session_connect
See the pyproject.toml
file for a full list of markers (-m) and their descriptions.
To run specific tests based on a keyword, use the -k
argument:
# Run all tests containing the word ``appdata``
# This would run ``test_private_appdata`` and ``test_normal_appdata`` only
pytest -k appdata
Using tox
#
This project takes advantage of tox. This tool automates common development
tasks (similar to Makefile
), but it is oriented towards Python development.
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.
The following 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 documentation-building process.
Remote testing#
If you do not have a licensed copy of Mechanical installed locally but want to run PyMechanical unit tests on a remote instance, you must set up environment variables.
On Linux
export PYMECHANICAL_START_INSTANCE=False
export PYMECHANICAL_PORT=<MECHANICAL Port> (default 10000)
export PYMECHANICAL_IP=<MECHANICAL IP> (default 127.0.0.1)
On Windows
SET PYMECHANICAL_START_INSTANCE=False
SET PYMECHANICAL_PORT=<MECHANICAL Port> (default 10000)
SET PYMECHANICAL_IP=<MECHANICAL IP> (default 127.0.0.1)
The environment variables for your operating system tell PyMechanical
to attempt to connect to the existing Mechanical service by default
when you use the launch_mechanical()
method.
Adhere to coding style#
As indicated in Coding style in the PyAnsys Developer’s Guide, PyMechanical follows PEP8 guidelines. PyMechanical implements pre-commit for style checking.
To ensure your code meets minimum code styling standards, run these commands:
pip install pre-commit
pre-commit run --all-files
You can also install this as a pre-commit hook by running this command:
pre-commit install
This way, it’s not possible for you to push code that fails the style checks:
$ pre-commit install
$ git commit -am "added my cool feature"
check pre-commit.ci config...............................................Passed
black....................................................................Passed
blacken-docs.............................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
codespell................................................................Passed
Add License Headers......................................................Passed
Ansys Technical Review...................................................Passed
pydocstyle...............................................................Passed
check for merge conflicts................................................Passed
debug statements (python)................................................Passed
check yaml...............................................................Passed
trim trailing whitespace.................................................Passed
check for added large files..............................................Passed
Validate GitHub Workflows................................................Passed
Documentation#
For building documentation, you can run the usual rules provided in the
Sphinx make
file:
# build and view the doc from the POSIX system
make -C doc html && your_browser_name doc/html/index.html
# build and view the doc from a Windows environment
make -C doc clean
make -C doc html
start .\doc\_build\html\index.html
However, the recommended way of checking documentation integrity is to use
tox
:
tox -e doc && your_browser_name .tox/doc_out/index.html
View documentation#
Documentation for the latest stable release of PyMechanical is hosted at PyMechanical Documentation.
In the upper right corner of the documentation’s title bar, there is an option for switching from viewing the documentation for the latest stable release to viewing the documentation for the development version or previously released versions.
Post issues#
Use the PyMechanical Issues page to submit questions, report bugs, and request new features. When possible, use these templates:
If your issue does not fit into one of these template categories, create your own issue.