PySPEDAS docstring format
Example header comments
PySPEDAS uses NumPy style docstrings as header comments to document the purpose, parameters, return values, and example usage of PySPEDAS routines. Here is an example including all the elements we want to have, for any routine users might be expected to call (or understand):
<syntaxhighlight lang="python"> def state(trange=['2007-03-23', '2007-03-24'],
probe='c',
level='l1',
suffix=,
get_support_data=False,
varformat=None,
exclude_format=None,
varnames=[],
downloadonly=False,
notplot=False,
no_update=False,
time_clip=False,
keep_spin=False):
"""
Load THEMIS state data
Parameters:
trange: list of str
time range of interest [starttime, endtime] with the format
['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
Default: ['2007-03-23', '2007-03-24']
probe: str or list of str
Spacecraft probe letter(s) ('a', 'b', 'c', 'd' and/or 'e')
Default: 'c'
level: str
Data type; Valid options: 'l1'
Default: 'l1'
suffix: str
The tplot variable names will be given this suffix.
Default: None
get_support_data: bool
Data with an attribute "VAR_TYPE" with a value of "support_data"
will be loaded into tplot.
Default: False
varformat: str
The file variable formats to load into tplot. Wildcard character
"*" is accepted. By default, all variables are loaded in.
Default: None (all variables are loaded)
exclude_format: str
If specified, CDF variables matching this pattern will not be processed.
Wildcard character "*" is accepted.
Default: None
varnames: list of str
List of variable names to load. If list is empty or unsoecified, all data variables are loaded
Default: [] (all variables are loaded)
downloadonly: bool
Set this flag to download the CDF files, but not load them into
tplot variables
Default: false
notplot: bool
Return the data in hash tables instead of creating tplot variables
Default: false
no_update: bool
If set, only load data from your local cache
Default: false
time_clip: bool
Time clip the variables to exactly the range specified
in the trange keyword
Default: false
keep_spin: bool
If True, do not delete the spin model tplot variables after the spin models are built.
Default: False
Returns:
List of tplot variables created.
Example:
>>> import pyspedas
>>> from pytplot import tplot
>>> pyspedas.themis.state(trange=['2007-03-23', '2007-03-24'], probe='a', varnames=['tha_pos_gse','tha_vel_gse'])
>>> tplot['tha_pos_gse', 'tha_vel_gse'])
"""
</syntaxhighlight>
One line description
The first line after the opening triple-quote should give a one-line description of what the routine does. This is what will be displayed in the 'help' command. It seems there is a preference in the Python community to phrase this as an imperative ("Load THEMIS state data") rather than a description ("This routine loads THEMIS state data").
Parameters
Each parameter should be described, including the expected type (string, bool, list or array of <whatever>), the valid values (if it's a smallish set of strings), and default value (if defined).
Return values
Amy return values should be described.
Usage example
A simple example showing a typical usage of the routine. Examples should be self-contained, including any imports or setup needed to call the routine being documented. We prefer to "import pyspedas", then call the routine using its fully qualified name, to make it clear where it fits into the pyspedas namespace. It is OK to use defaults for some parameters, if that's how the user would normally call the routine. In this case, we want to make the time range and probe explicit, while letting some of the lesser-used parameters go to the defaults.
The chevron prefix ">>>" should be used to denote what the user is expected to write. Any output expected from the call should follow, without the chevrons. (There are tools that can pull examples out of docstrings and use them as tests, so following this format gives us more options for automated testing.)