-
Notifications
You must be signed in to change notification settings - Fork 453
Expand file tree
/
Copy pathtemplate.py
More file actions
168 lines (126 loc) · 5.41 KB
/
template.py
File metadata and controls
168 lines (126 loc) · 5.41 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
# template.py - template file for python-control module
# RMM, 3 Jan 2024
"""Template file for python-control module.
This file provides a template that can be used when creating a new
file/module in python-control. The key elements of a module are included
in this template, following the suggestions in the Developer Guidelines.
The first line of a module file should be the name of the file and a short
description. The next few lines can contain information about who created
the file (your name/initials and date). For this file I used the short
version (initials, date), but a longer version would be to do something of
the form::
# filename.py - short one line description
#
# Initial author: Full name
# Creation date: date the file was created
After the header comments, the next item is the module docstring, which
should be a multi-line comment, like this one. The first line of the
comment is a one line summary phrase, starting with a capital letter and
ending in a period (often the same as the line at the very top). The rest
of the docstring is an extended summary (this one is a bit longer than
would be typical).
After the docstring, you should have the following elements (in Python):
* Package imports, using the `isort -m2` format (library, standard, custom)
* __all__ command, listing public objects in the file
* Class definitions (if any)
* Public function definitions
* Internal function definitions (starting with '_')
* Function aliases (short = long_name)
The rest of this file contains examples of these elements.
"""
import warnings # Python packages
import numpy as np # Standard external packages
from . import config # Other modules/packages in python-control
from .lti import LTI # Public function or class from a module
__all__ = ['SampleClass', 'sample_function']
class SampleClass():
"""Sample class in the python-control package.
This is an example of a class definition. The docstring follows
numpydoc format. The first line should be a summary (which will show
up in `autosummary` entries in the Sphinx documentation) and then an
extended summary describing what the class does. Then the usual
sections, per numpydoc.
Additional guidelines on what should be listed in the various sections
can be found in the 'Class docstrings' section of the Developer
Guidelines.
Parameters
----------
sys : InputOutputSystem
Short description of the parameter.
Attributes
----------
data : array
Short description of an attribute.
"""
def __init__(self, sys):
# No docstring required here
self.sys = sys # Parameter passed as argument
self.data = sys.name # Attribute created within class
def sample_method(self, data):
"""Sample method within a class.
This is an example of a method within a class. Document using
numpydoc format.
"""
return None
def sample_function(data, option=False, **kwargs):
"""Sample function in the template module.
This is an example of a public function within the template module.
This function will usually be placed in the `control` namespace by
updating `__init__.py` to import the function (often by importing the
entire module).
Docstring should be in standard numpydoc format. The extended summary
(this text) should describe the basic operation of the function, with
technical details in the "Notes" section.
Parameters
----------
data : array
Sample parameter for sample function, with short docstring.
option : bool, optional
Optional parameter, with default value `False`.
Returns
-------
out : float
Short description of the function output.
Additional Parameters
---------------------
inputs : int, str, or list of str
Parameters that are less commonly used, in this case a keyword
parameter.
See Also
--------
function1, function2
Notes
-----
This section can contain a more detailed description of how the system
works. OK to include some limited mathematics, either via inline math
directions for a short formula (like this: ..math:`x = \alpha y`) or via a
displayed equation:
..math::
a = \int_0^t f(t) dt
The trick in the docstring is to write something that looks good in
pure text format but is also processed by sphinx correctly.
If you refer to parameters, such as the `data` argument to this
function, but them in single backticks (which will render them in code
style in Sphinx). Strings that should be interpreted as Python code
use double backticks: ``mag, phase, omega = response``. Python
built-in objects, like True, False, and None are written on their own.
"""
inputs = kwargs['inputs']
if option is True:
return data
else:
return None
#
# Internal functions
#
# Functions that are not intended for public use can go anyplace, but I
# usually put them at the bottom of the file (out of the way). Their name
# should start with an underscore. Docstrings are optional, but if you
# don't include a docstring, make sure to include comments describing how
# the function works.
#
# Sample internal function to process data
def _internal_function(data):
return None
# Aliases (short versions of long function names)
sf = sample_function