Stylist is a tool for checking code style. It implements a framework which supports multiple styles across multiple languages.
But aren't there many such tools out there, why create a new one?
The simple reason is that few of them support Fortran, a language still in widespread use in the scientific computing domain. They can also tend towards the zealous when enforcing the "one true style" whereas long running science models tend to diverge quite radically in what they like, style-wise.
Large models also tend to be implemented using more than one language so a tool which is capable of understanding all of them would be welcomed by science developers.
This is the goal of Stylist development.
The project is still in its infancy so only a few rules have been implemented and only for Fortran. Stubs are provided to show how it might be extended to support C.
Find the project at <https://github.com/MetOffice/stylist>
Installation can be as simple as pip install stylist
or
conda install -c conda-forge stylist
.
As always it is also possible to install from the project source using
pip install --editable .
. The source may be obtained by downloading a
tarball or by cloning the repository.
If you are interested in developing this tool then a few useful prerequisite lists are provided.
Command | Tool Set |
---|---|
pip install .[dev] |
For development. |
pip install .[test] |
For testing. |
pip install .[performance] |
For monitoring performance. |
pip install .[docs] |
For generating documentation. |
pip install .[release] |
For creating releases. |
Note that the documenatation requires the PlantUML tool to be installed.
Until PEP725 or similar is adopted this cannot be expressed in the
pyproject.toml
file so it is noted here.
Stylist provides a command-line tool stylist
for normal use. It can also be
used as a package if you want to integrate it with another tool. Documentation
regarding this second option is maintained in the project wiki.
The command-line tool is not complicated to use:
stylist [-help] [-verbose] [-configuration FILENAME] [-style NAME] FILE ...
The only required arguments are a configuration file and one or more filenames. These are the files which will be checked. If a directory is specified then the tool will automatically descend into it checking all files which it recognises by extension.
If you want a running commentary of what the tool is doing then use the
-verbose
argument.
A configuration file may specified with -configuration
. This file should
be formatted as documented below. There must be a configuration file which
defines at least one style. While the fallback mechanism which allows for user
and site configurations has not been implemented it must be specified with this
argument.
The configuration may define several styles, in which case one can be chosen
using the -style
argument. If it is not then the first in the configuration
file will be used.
The configuration file is a simple python script where variable definitions are used to define the configuration.
Stylist uses the concept of "File Pipes" to specify the series of steps needed
to process a particular file type. They are defined by creating a FilePipe
object and associated with a file extension by assignment to a variable.
For example:
from stylist.source import (FilePipe, FortranSource, PFUnitProcessor, FortranPreprocessor) pf = FilePipe(FortranSource, PFUnitProcessor, FortranPreprocessor)
Here a pipeline consisting the pFUnit processor followed by the Fortran
preprocessor produces Fortran source. This pipeline should be used for all
files with the .pf
extension.
Styles are collections of rules and are defined in a similar way. The variable name is the style name and the object is constructed with the rules which make up the style.
An illustrative example:
from re import compile as recompile from stylist.style import Style from stylist.fortran import FortranCharacterset, KindPattern simple = Style(FortranCharacterset(), KindPattern(integer=recompile(r'i_.+'), real=recompile(r'r_.+')))