Contribute#

Thank you for considering contributing to PyPLUTO!

We welcome contributions of all kinds, including bug reports, feature requests, documentation improvements, and code contributions.

Getting Started#

To contribute:

  1. Fork the repository: GiMattia/PyPLUTO

  2. Create a feature branch:

$ git checkout -b feature/your-feature-name

  1. Make your changes and write tests.

  2. Ensure your code adheres to the project’s coding standards.

  3. Commit with a descriptive message.

  4. Push and open a pull request.

Installation guidelines#

In order to install the project, you can use the following command:

$ pip install -r requirements_dev.txt

In order to ensure that the pre-commit hooks are installed, run:

$ pre-commit install

You should see this (or similar) output:

pre-commit installed at .git/hooks/pre-commit

Testing#

The core functionality of PyPLUTO is tested through a set of pytest benchmarks present in the Tests folder. To run the tests, you can use:

$ pytest --cov=pyPLUTO --cov-report=term-missing

This will run all tests and provide a coverage report in the terminal. Please ensure that all tests pass before submitting a pull request.

Pre-commit Hooks#

PyPLUTO uses pre-commit hooks to ensure code quality and consistency. These hooks will automatically format your code and check for common issues before committing. In order to use them, make sure you have pre-commit installed and run:

$ pre-commit run --all-files

The following pre-commit hooks are active and run automatically before every commit:

  1. official pre-commit hooks checks for common issues like trailing whitespace, end-of-file newlines, case conflict and more.

  2. docformatter automatically reformats Python docstrings in-place using Black-style formatting with enforced blank lines.

  3. blacken-docs formats code blocks inside docstrings using Black with a line length of 80 characters.

  4. ruff lints and fixes Python code, catching both stylistic and logical issues. Runs with –fix enabled to apply auto-fixes.

  5. black automatically formats all Python files according to Black’s style guide for consistent code formatting.

The code undergoes a strict series of checks during every pull request. In order to avoid rejections, is convenient to run the full set of checks through the command

$ pre-commit run --all-files --hook-stage manual

In addition to all the previous pre-commit checks, the code also runs the following tools:

  1. pytest runs automatically all the tests (see Testing section above) ensuring a minimum coverage of 45% (will be increased in the near future).

  2. interrogate ensures a docstring coverage above 70% (will also be increased in the near future).

We aim at also adding checking tools such as mypy and pylint, although they have not been included yet.

Code style#

During every pre-commit the code is automatically formatted to adhere with the black codestyle. In order to format automatically the code at every saving in VsCode, you can do the following:

  1. Search the VS Code Marketplace fot the formatter extension “Black formatter”

  2. Go to File -> Preferences -> Settings

  3. Search “format”

  4. In the “Editor: Default formatter” panel select “Black formatter”

  5. Check the “Format on save” box

Code Structure#

The code is mainly structured in the following way:

  • gui: Contains the GUI code, including panels, widgets, and main window logic

  • imagefuncs: Contains image processing functions and utilities

  • loadfuncs: Contains functions for loading and processing data files

  • toolsfuncs: Contains various utility functions and classes for data manipulation

  • utils: Contains utility functions and classes used across the project

Note that the Image relies on a series of Manager classes (located in the imagefuncs folder) that handle the image processing and plotting functionalities. In order to share the relevant methods and attributes across the Managers and the Image class, two classes (ImageState and ImageMixin) are used.

Questions or Suggestions?#

For any question, suggestion or comment please send an e-mail to G. Mattia (mail: mattia@mpia.de).

Feel also free to open an issue or discuss in the GitHub repo.

Happy coding!