For Developers

spyral-utils is always looking for input and improvements! Pull requests are always welcome, however, they may not always be accepted.

Below we've outlined some of the rules for additions to spyral-utils:

pdm

spyral-utils uses pdm as its ecosystem. Please use pdm when developing new features for spyral-utils, and follow the pdm guidelines where possible.

Statement of Intent

Please state in the pull request what the goal of is of this modification to spyral-utils and what was changed to accomplish this. If there is no statement of intent, the pull request will not be accepted.

Statement of Dependencies

Please state in the pull request what new dependencies (if any) were added and please make sure that these new dependencies were added to the spyral-utils pyproject.toml with a version specified and updated the pdm.lock. If the dependencies were not stated, the pull request will not be accepted. Please check to make sure that any new dependencies are compliant with the GPL3 license which is used by spyral-utils.

Code Requirements

Below are some of the requirements for any code added to spyral-utils:

Docstrings

Please provide docstrings for each function and class using the numpydocs guidelines. Dataclasses do not necessarily need docstrings. This helps other developers understand what the purpose and usage code. Check out some of the docstrings in spyral-utils to get a feel for the expected format.

Type Hints

Please use type hints to annotate your code where applicable. This includes function arguments, return values, and any variables where the type might be ambiguous. In general, a good rule to follow is: can your IDE determine the type of the variable? If it can it doesn't need a type hint. If it can't, the variable needs a type hint. The Any type hint is allowed in some specific cases. Functions which return None do not need a return type hint.

Formatting

spyral-utils follows the default black style. Please use black to format your code.

Files

Please try to keep files from being monster 1000 lines of code documents. This is not a hard and fast rule, but in general files should contain a unqiue individual unit of code which interfaces with the rest of the framework. There can be execptions.

Tests

spyral-utils uses the pytest framework. Existing tests are located in the tests/ directory. When new features are developed for spyral-utils, tests should be added to demonstrate the functionality. Tests are automatically run through CI on pushes to spyral-utils. Pull requests will be reviewed to make sure that appropriate tests were written for new features.

Documentation

If you decide to contribute a new major feature to spyral-utils, please prepeare some documentation to be added to this site. It should at least outline what new configuration parameters are exposed and what effect this may have upon the data. Documentation should be contributed in the form of Markdown files in the docs directory. Our documenation is built using the amazing MkDocs and the MkDocs-Material theme, with API documentation autogenerated using mkdocstrings and the mkdocstrings-python handler.

Final Thoughts

Below is an example pull request descripton:

Intent:
Fix a bug in configuration parsing in spyral-utils Cut2D and switch to YAML

Dependencies Added:
pyyaml

Feel free to use this as a simple template if you wish!