1.3 Classes

Classes should have a docstring below their definition describing the class.

Certain aspects of a class should be documented in special sections (listed below) following these guidelines:

• If your class has public attributes, they should be documented here in the Args section and excluded from the __init__ method.
• If your class has public properties, they should be documented here in the Properties section.
• The sections may include special formatting markups such as lists, code blocks and literals (see section 1.4 Other Formatting Markups).

1.3.1 Summary line

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.

1.3.2 Description

Separated from the summary line with a blank line, this section includes a more elaborate description that may extend multiple lines.

1.3.3 Args

The class Args section follows the same formatting guidelines as the function's Args section (see Functions and Methods: Args section).

1.3.4 Properties

List the class public properties under the Properties section header as follows:

• Use a hanging indent of four spaces and place an asterisk at the start of each property item.
• Only the property name should be listed, no description or property type should be included.
• If the class is inherited from another class, include also the parent class public properties.

1.3.5 Examples of class docstrings

Example 1: Summary line

class AlignmentTypes(object):
    """Enumeration of text alignment types."""

Html

---

Example 2: Summary / Arga / Properties

class Date(date):
    """Ladybug Date.

    Args:
        month: A value for month between 1-12. Defualt: 1.
        day: A value for day between 1-31. Defualt: 1.
        leap_year: A boolean to indicate if date is for a leap year. Default: False.

    Properties:
        * day
        * doy
        * leap_year
        * month
        * year
    """

Html

---

Example 3: Description with code-block markup

class Brighttext(Pattern):
    """Radiance Brighttext Pattern.

    Brighttext is like colortext, but the writing is monochromatic.

    .. code-block:: shell

        mod brighttext id
        2 fontfile textfile
        0
        11+
                Ox Oy Oz
                Rx Ry Rz
                Dx Dy Dz
                foreground background
                [spacing]

    or:

    .. code-block:: shell

        mod brighttext id
        2+N fontfile . This is a line with N words ...
        0
        11+
                Ox Oy Oz
                Rx Ry Rz
                Dx Dy Dz
                foreground background
                [spacing]

    By default, a uniform spacing algorithm is used that guarantees every character will
    appear in a precisely determined position. Unfortunately, such a scheme results in
    rather unattractive and difficult to read text with most fonts. The optional spacing
    value defines the distance between characters for proportional spacing. A positive
    value selects a spacing algorithm that preserves right margins and indentation, but
    does not provide the ultimate in proportionally spaced text. A negative value insures
    that characters are properly spaced, but the placement of words then varies
    unpredictably. The choice depends on the relative importance of spacing versus
    formatting. When presenting a section of formatted text, a positive spacing value is
    usually preferred. A single line of text will often be accompanied by a negative
    spacing value. A section of text meant to depict a picture, perhaps using a special
    purpose font such as hexbit4x1.fnt, calls for uniform spacing. Reasonable magnitudes
    for proportional spacing are between 0.1 (for tightly spaced characters) and 0.3 (for
    wide spacing).
    """

Html

---

Example 4: Args with list markup

class SimulationOutput(object):
    """Object to hold EnergyPlus simulation outputs.


    Args:
        outputs: A list of EnergyPlus output names as strings, which are requested
            from the simulation. If None, no outputs will be requested.
            Note that this object does not check whether the outputs exist
            within the EnergyPlus IDD or are request-able from a given Model.
            (eg. ['Zone Ideal Loads Supply Air Total Cooling Energy']).
            Default: None.
        reporting_frequency: Text for the frequency at which the outputs
            are reported. Default: 'Hourly'.
            Choose from the following:

            * Annual
            * Monthly
            * Daily
            * Hourly
            * Timestep

        include_sqlite: Boolean to note whether a SQLite report should be
            generated from the simulation, which contains all of the outputs and
            summary_reports. Default: True.
        include_html: Boolean to note whether an HTML report should be generated
            from the simulation, which contains all of the summary_reports.
            Default: False.
        summary_reports: An array of EnergyPlus summary report names as strings.
            An empty list or None will result in no summary reports.
            Default: ('AllSummary',). See the Input Output Reference SummaryReports
            section for a full list of all reports that can be requested.
            (https://bigladdersoftware.com/epx/docs/9-1/input-output-reference/\
output-table-summaryreports.html#outputtablesummaryreports).

    Properties:
        * outputs
        * reporting_frequency
        * include_sqlite
        * include_html
        * summary_reports
    """

Html