1.2 Functions and Methods
In this section, “function” means a method, function, or generator.
A docstring should give enough information to write a call to the function without reading the function’s code.
Certain aspects of a function should be documented in special sections. These sections can be omitted in cases where the function’s name and signature are informative enough that it can be aptly described using a one-line docstring. The sections used in a function docstring include a summary line, a description, an Args section, and a Returns section. These sections may include special formatting markups such as lists, code blocks and literals (see section 1.4 Other Formatting Markups).
A one line string literal followed by a blank line using the following guidelines:
- If this is a one-line docstring the closing quotes are on the same line as the opening quotes.
- In multi-line docstrings the summary line may be on the same line as the opening quotes (""") or on the next line.
- When specifying default values in this section use
Default is xinstead ofDefault: x. Colons are used in other formatting elements inside Sphinx and may affect the generated format of the line.
Separated from the summary line with a blank line, this section includes a more elaborate description that may extend multiple lines.
If your function includes attributes, they should be documented here in the Args section using the following guidelines:
- List each attribute by name.
- A description should follow the name, and be separated by a colon and a space. If the description is too long to fit on a single 80-character line, use a hanging indent of four spaces (be consistent with the rest of the file).
- The description should include required type(s).
Describe the type and semantics of the return value. If the return value is a tuple, list or dictionary, describe each of its items. The format of this section depends on the return type.
If description is a multi-liner, lines use same indenting as first line.
Use variable_name -- Description format. If description is a multi-liner, lines have same indenting as first line.
Each of the return items should be listed with their names and follow the formatting guidelines below:
- In the first line specify the type of data structure and number of elements that it contains. Is impotant to omit the colon (':') at the end of the line to avoid conflicts with Sphinx autodoc generator.
- Each return item should have a name.
- Each item starts with dash symbol ('-') followed by three spaces and item name.
- In single-line descriptions use return_name -- Description format.
- Multi-line descriptions should be placed in a separate line with a hanging indent of four spaces.
Example 1: Single line summary with default value
@property
def radius(self):
"""Sphere radius as a number. Default is 10."""
return self._radius
Html
Example 2: Description / Args / Single return with description and no variable name
def sub_faces_by_ratio_rectangle(self, ratio, tolerance):
"""Get a list of faces with a combined area equal to the ratio times this face area.
This function is virtually equivalent to the sub_faces_by_ratio method
but a check will be performed to see if any rectangles can be pulled out
of this face's geometry. This tends to make the result a bit cleaner,
especially for concave faces that have rectangles (like L-shaped faces).
Args:
ratio: A number between 0 and 1 for the ratio between the area of
the sub faces and the area of this face.
tolerance: The maximum difference between point values for them to be
considered a part of a rectangle.
Returns:
A list of Face3D objects for sub faces. If there is a rectangle in this
shape, the scaled rectangle will be the first item in this list.
"""
Html
Example 3: Single return with description and with variable name
def calc_sky_temperature(horiz_ir, source_emissivity=1):
"""Calculate sky temperature in Celcius.
See EnergyPlus Enrineering Reference for more information:
https://bigladdersoftware.com/epx/docs/8-9/engineering-reference/
climate-calculations.html#energyplus-sky-temperature-calculation
Args:
horiz_ir: A float value that represents horizontal infrared radiation
intensity in W/m2.
source_emissivity: A float value between 0 and 1 indicating the emissivity
of the heat source that is radiating to the sky. Default is 1 for
most outdoor surfaces.
Returns:
sky_temp -- A sky temperature value in C.
"""
Html
Example 4: Multiple returns
def extract_rectangle(self, tolerance):
"""Extract top and bottom line segments of a rectangle within this Face.
This method will only return geometry if:
1) There are no holes in the face.
2) The face is not parallel to the World XY plane.
3) There are two parallel edges to this face, which are either
oriented horizontally or vertically.
4) There must be enough overlap between these edges for a rectangle
to be drawn between them.
If this Face does not satisfy this criteria, None will be returned.
Args:
tolerance: The maximum difference between point values for them to be
considered a part of a rectangle.
Returns:
A tuple with three elements
- bottom_edge: A LineSegment3D representing the bottom of the rectangle.
- top_edge: A LineSegment3D representing the top of the rectangle.
- other_faces:
A list of Face3D objects for the parts of this face not
included in the rectangle. The length of this list will be between
0 (if this face is already rectangular) and 2 (if there are non-
rectangular geometries on either side of the rectangle.)
"""
Html
