PySPEDAS docstring format: Difference between revisions

From SPEDAS Wiki
Jump to navigation Jump to search
No edit summary
 
(2 intermediate revisions by one other user not shown)
Line 2: Line 2:


PySPEDAS uses NumPy style docstrings as header comments to document the purpose, parameters, return values, and example usage of PySPEDAS routines.
PySPEDAS uses NumPy style docstrings as header comments to document the purpose, parameters, return values, and example usage of PySPEDAS routines.
https://numpydoc.readthedocs.io/en/latest/format.html
Here is an example including all the elements we want to have, for any routine users might be expected to call (or understand):
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">
<syntaxhighlight lang="python">
def state(trange=['2007-03-23', '2007-03-24'],
def state(trange=['2007-03-23', '2007-03-24'],
           probe='c',
           probe='c',
Line 19: Line 23:
           keep_spin=False):
           keep_spin=False):
     """
     """
     Load THEMIS state data
     Load THEMIS state data.


     Parameters:
     Parameters
        trange: list of str
    ----------
            time range of interest [starttime, endtime] with the format
    trange : list of str
            ['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
            time range of interest [starttime, endtime] with the format
            ['YYYY-MM-DD/hh:mm:ss','YYYY-MM-DD/hh:mm:ss']
            ['YYYY-MM-DD','YYYY-MM-DD'] or to specify more or less than a day
            Default: ['2007-03-23', '2007-03-24']
            ['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
    probe : str or list of str
             Spacecraft probe letter(s) ('a', 'b', 'c', 'd' and/or 'e')
             Spacecraft probe letter(s) ('a', 'b', 'c', 'd' and/or 'e')
             Default: 'c'
             Default: 'c'


        level: str
    level : str
             Data type; Valid options: 'l1'
             Data type; Valid options: 'l1'
             Default: 'l1'
             Default: 'l1'


        suffix: str
    suffix : str
             The tplot variable names will be given this suffix. By default,
             The tplot variable names will be given this suffix.
             no suffix is added.
             Default: None


        get_support_data: bool
    get_support_data : bool
             Data with an attribute "VAR_TYPE" with a value of "support_data"
             Data with an attribute "VAR_TYPE" with a value of "support_data"
             will be loaded into tplot.
             will be loaded into tplot.
             Default: False
             Default: False


        varformat: str
    varformat : str
             The file variable formats to load into tplot.  Wildcard character
             The file variable formats to load into tplot.  Wildcard character
             "*" is accepted.  By default, all variables are loaded in.
             "*" is accepted.  By default, all variables are loaded in.
            Default: None (all variables are loaded)


        exclude_format: str
    exclude_format : str
             If specified, CDF variables matching this pattern will not be processed.
             If specified, CDF variables matching this pattern will not be processed.
             Wildcard character "*" is accepted. By default, no variables are excluded.
             Wildcard character "*" is accepted.
            Default: None


        varnames: list of str
    varnames : list of str
             List of variable names to load
             List of variable names to load. If list is empty or unsoecified, all data variables are loaded
             (if not specified, all data variables are loaded)
             Default: [] (all variables are loaded)


        downloadonly: bool
    downloadonly : bool
             Set this flag to download the CDF files, but not load them into
             Set this flag to download the CDF files, but not load them into
             tplot variables
             tplot variables
             Default: false
             Default: false


        notplot: bool
    notplot : bool
             Return the data in hash tables instead of creating tplot variables
             Return the data in hash tables instead of creating tplot variables
             Default: false
             Default: false


        no_update: bool
    no_update : bool
             If set, only load data from your local cache
             If set, only load data from your local cache
             Default: false
             Default: false


        time_clip: bool
    time_clip : bool
             Time clip the variables to exactly the range specified
             Time clip the variables to exactly the range specified
             in the trange keyword
             in the trange keyword
             Default: false
             Default: false


        keep_spin: bool
    keep_spin : bool
             If True, do not delete the spin model tplot variables after the spin models are built.
             If True, do not delete the spin model tplot variables after the spin models are built.
              
             Default: False
 


     Returns:
     Returns
        List of tplot variables created.
    -------
    list of str
            List of tplot variables created.


     Example:
     Example
    -------
         >>> import pyspedas
         >>> 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'])
         >>> pyspedas.themis.state(trange=['2007-03-23', '2007-03-24'], probe='a', varnames=['tha_pos_gse','tha_vel_gse'])
         ['tha_pos_gse', 'tha_vel_gse']
         >>> tplot['tha_pos_gse', 'tha_vel_gse'])


     """
     """


</syntaxhighlight>
</syntaxhighlight >


== One line description ==
== 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").
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. For mission-specific load routines and other utilities, the mission name should appear in the one-line help (because other missions may have routines with similar names and usage). 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 ==
== Parameters ==

Latest revision as of 02:55, 17 January 2024

Example header comments

PySPEDAS uses NumPy style docstrings as header comments to document the purpose, parameters, return values, and example usage of PySPEDAS routines.

https://numpydoc.readthedocs.io/en/latest/format.html

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 str
           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. For mission-specific load routines and other utilities, the mission name should appear in the one-line help (because other missions may have routines with similar names and usage). 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.)