Contribute

Overall guidance on contributing to a PyAnsys library appears in the Contributing topic in the PyAnsys developer’s guide. Ensure that you are thoroughly familiar with this guide before attempting to contribute to PyEDB-Core.

The following contribution information is specific to PyEDB-Core.

Developer installation

Installing the ansys-edb package in developer mode allows you to modify the source and enhance it.

This package supports Python 3.9 through 3.12 on Windows, Linux, and MacOS.

1. Clone the repository:

   git clone https://github.com/ansys/pyedb-core
   

2. Create a fresh-clean Python virtual environment and activate it:

   # Create a virtual environment
   python -m venv .venv
   
   # Activate it in a Linux environment
   source .venv/bin/activate
   
   # Activate it in a Windows CMD environment
   .venv\Scripts\activate.bat
   
   # Activate it in a Windows Powershell environment
   .venv\Scripts\Activate.ps1
   

3. Make sure you have the latest required build system and documentation, testing, and CI tools:

   python -m pip install -U pip
   
   python -m pip install .[tests]
   

4. Verify your development installation:

   tox
   

Testing

This project takes advantage of tox. Similar to Makefile, this tool allows you to automate common tasks, but it is oriented towards Python development.

Using tox

While Makefile has rules, tox has environments. In fact, the tool creates its own virtual environment so anything being tested is isolated from the project to guarantee the project’s integrity. The following environments commands are provided:

• tox -e style: Checks for coding style quality.

• tox -e test: Checks for unit tests. Pass pytest flags after the -- portion of the command. For example, use this pytest command to show the standard output, replacing X with the minor version of your Python environment: tox -e py3X -- -s.

• tox -e coverage: Checks for code coverage.

• tox -e doc: Checks for documentation building.

Raw testing

If required, you can always call code style tools, such as black, isort, and flake8, or unit testing tools, such as pytest from the command line. However, using these tools do not guarantee that your project is being tested in an isolated environment, which is the reason why a tool like tox exists.

Adhere to code style

PyEDB-Core follows the PEP8 standard as indicated in PEP 8 in the PyAnsys developer’s guide. It also implements style checking using pre-commit.

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 code style checks:

$ git commit -am "added my cool feature"
black....................................................................Passed
blacken-docs.............................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
docformatter.............................................................Passed
codespell................................................................Passed
check for merge conflicts................................................Passed
debug statements (python)................................................Passed
check yaml...............................................................Passed
trim trailing whitespace.................................................Passed
Add License Headers......................................................Passed
Validate GitHub Workflows................................................Passed

Documentation

To install the required dependencies for the documentation, run this command:

pip install .[doc]

To build the documentation, run the usual rules provided in the Sphinx Makefile for your operating system.

On Windows:

.\doc\make.bat html
.\doc\build\html\index.html

On Linux and MacOS:

make -C doc/ html && your_browser_name 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/html/index.html

Distributing

If you would like to create either source or wheel files, run these commands:

flit build
python -m twine check dist/*