Welcome! In this series of videos you’ll get an overview of the features of the Real Python platform, so you can make the most of your membership. Follow along and get tips on:

• How to find the most valuable learning resources for your current skill level
• How to meet and interact with other students and the RP Team
• How to learn effectively

Just click the Watch Now button below to start with the first lesson.

[ Improve Your Python With 🐍 Python Tricks 💌 – Get a short & sweet Python Trick delivered to your inbox every couple of days. >> Click here to learn more and see examples ]

Learn Python online in 5 steps, with hands-on missions that can take you from zero experience to data scientist quicker than you think!

The post 5 Steps to Learning Python the Right Way appeared first on Dataquest.

fromPyQt5.QtWidgetsimport*fromPyQt5.QtCoreimport*fromPyQt5.QtGuiimport*# Only needed for access to command line argumentsimportsys# Subclass QMainWindow to customise your application's main windowclassMainWindow(QMainWindow):def__init__(self,*args,**kwargs):super(MainWindow,self).__init__(*args,**kwargs)self.setWindowTitle("My Awesome App")layout=QVBoxLayout()widgets=[QCheckBox,QComboBox,QDateEdit,QDateTimeEdit,QDial,QDoubleSpinBox,QFontComboBox,QLCDNumber,QLabel,QLineEdit,QProgressBar,QPushButton,QRadioButton,QSlider,QSpinBox,QTimeEdit]forwinwidgets:layout.addWidget(w())widget=QWidget()widget.setLayout(layout)# Set the central widget of the Window. Widget will expand# to take up all the space in the window by default.self.setCentralWidget(widget)# You need one (and only one) QApplication instance per application.# Pass in sys.argv to allow command line arguments for your app.# If you know you won't use command line arguments QApplication([]) works too.app=QApplication(sys.argv)window=MainWindow()window.show()# IMPORTANT!!!!! Windows are hidden by default.# Start the event loop.app.exec_()# Your application won't reach here until you exit and the event # loop has stopped.

fromPySide2.QtWidgetsimport*fromPySide2.QtCoreimport*fromPySide2.QtGuiimport*# Only needed for access to command line argumentsimportsys# Subclass QMainWindow to customise your application's main windowclassMainWindow(QMainWindow):def__init__(self,*args,**kwargs):super(MainWindow,self).__init__(*args,**kwargs)self.setWindowTitle("My Awesome App")layout=QVBoxLayout()widgets=[QCheckBox,QComboBox,QDateEdit,QDateTimeEdit,QDial,QDoubleSpinBox,QFontComboBox,QLCDNumber,QLabel,QLineEdit,QProgressBar,QPushButton,QRadioButton,QSlider,QSpinBox,QTimeEdit]forwinwidgets:layout.addWidget(w())widget=QWidget()widget.setLayout(layout)# Set the central widget of the Window. Widget will expand# to take up all the space in the window by default.self.setCentralWidget(widget)# You need one (and only one) QApplication instance per application.# Pass in sys.argv to allow command line arguments for your app.# If you know you won't use command line arguments QApplication([]) works too.app=QApplication(sys.argv)window=MainWindow()window.show()# IMPORTANT!!!!! Windows are hidden by default.# Start the event loop.app.exec_()# Your application won't reach here until you exit and the event # loop has stopped.

Big ol' list of widgets.

widget=QLabel("Hello")

widget=QLabel("1")# The label is created with the text 1.widget.setText("2")# The label now shows 2.

classMainWindow(QMainWindow):def__init__(self,*args,**kwargs):super(MainWindow,self).__init__(*args,**kwargs)self.setWindowTitle("My Awesome App")widget=QLabel("Hello")font=widget.font()font.setPointSize(30)widget.setFont(font)widget.setAlignment(Qt.AlignHCenter|Qt.AlignVCenter)self.setCentralWidget(widget)

align_top_left=Qt.AlignLeft|Qt.AlignTop

widget.setPixMap(QPixmap('otje.jpg'))

Otgon "Otje" Ginge the cat.

widget.setScaledContents(True)

classMainWindow(QMainWindow):def__init__(self,*args,**kwargs):super(MainWindow,self).__init__(*args,**kwargs)self.setWindowTitle("My Awesome App")widget=QCheckBox()widget.setCheckState(Qt.Checked)# For tristate: widget.setCheckState(Qt.PartiallyChecked)# Or: widget.setTriState(True)widget.stateChanged.connect(self.show_state)self.setCentralWidget(widget)defshow_state(self,s):print(s==Qt.Checked)print(s)

classMainWindow(QMainWindow):def__init__(self,*args,**kwargs):super(MainWindow,self).__init__(*args,**kwargs)self.setWindowTitle("My Awesome App")widget=QComboBox()widget.addItems(["One","Two","Three"])# The default signal from currentIndexChanged sends the indexwidget.currentIndexChanged.connect(self.index_changed)# The same signal can send a text stringwidget.currentIndexChanged[str].connect(self.text_changed)self.setCentralWidget(widget)defindex_changed(self,i):# i is an intprint(i)deftext_changed(self,s):# s is a strprint(s)

widget.setEditable(True)

widget.setInsertPolicy(QComboBox.InsertAlphabetically)

widget.setMaxCount(10)

classMainWindow(QMainWindow):def__init__(self,*args,**kwargs):super(MainWindow,self).__init__(*args,**kwargs)self.setWindowTitle("My Awesome App")widget=QListWidget()widget.addItems(["One","Two","Three"])# In QListWidget there are two separate signals for the item, and the strwidget.currentItemChanged.connect(self.index_changed)widget.currentTextChanged.connect(self.text_changed)self.setCentralWidget(widget)defindex_changed(self,i):# Not an index, i is a QListItemprint(i.text())deftext_changed(self,s):# s is a strprint(s)

classMainWindow(QMainWindow):def__init__(self,*args,**kwargs):super(MainWindow,self).__init__(*args,**kwargs)self.setWindowTitle("My Awesome App")widget=QLineEdit()widget.setMaxLength(10)widget.setPlaceholderText("Enter your text")#widget.setReadOnly(True) # uncomment this to make readonlywidget.returnPressed.connect(self.return_pressed)widget.selectionChanged.connect(self.selection_changed)widget.textChanged.connect(self.text_changed)widget.textEdited.connect(self.text_edited)self.setCentralWidget(widget)defreturn_pressed(self):print("Return pressed!")self.centralWidget().setText("BOOM!")defselection_changed(self):print("Selection changed")print(self.centralWidget().selectedText())deftext_changed(self,s):print("Text changed...")print(s)deftext_edited(self,s):print("Text edited...")print(s)

Continue reading: “Dialogs and Alerts”

To keep your codebase clean, it helps to have a separation of concerns. Splitting your codebase into a backend and frontend directory a great way to do this.

Unfortunately Heroku buildpacks do not detect nested applications in a repo. There are two ways to overcome this:

Option 1 - Use a third party subdir module (heroku-buildpack-subdir)

Use a Third party buildpack that supports applications in project subdirectories. There’s a few out there, but I recommend heroku-buildpack-subdir as it has the most stars. Most only support 1 folder depth, but that should be all you need.

Add heroku-buildpack-subdir to your heroku app’s settings dashboard.

Dashboard -> Settings -> Buildpacks

Once done, Create a new file called .buildpacks and add it to your project root.

frontend=https://github.com/heroku/heroku-buildpack-nodejs.git
backend=https://github.com/heroku/heroku-buildpack-python.git

Heroku will now install the correct buildpacks for the backend and frontend directory next time you deploy!

Note: You can do the same thing for Review Apps by adding heroku-buildpack-subdir to your app.json.

Option 2 - Ensure your backend and frontend entry points are available in the project root

Most application’s entry points can be moved around, so why not do that for a django/node application?

Say you have the following project structure:

backend/
    example_app/
    Manage.py
    Pipfile
frontend/
    src/
        index.jsx
    webpack.config.js
    package.json

If you deploy this right now, Heroku will fail because it doesn’t know what kind of project it’s looking at. 

To fix this, move the Django project’s Pipfile and the Node project’s package.json to the root directory and configure to use nested project assets. Like so:

backend/
    example_app/
    Manage.py
frontend/
    src/
        Index.jsx
    webpack.config.js
package.json
Pipfile

The benefit of this approach is having no extra buildpack configuration in Heroku. For this reason I’d recommend Option 2 over Option 1.

Using one of these methods will enable you to use multiple buildpacks with your Heroku app!

One of the items of feedback I got from the article about interface immutability is that it did not give any concrete feedback for how to design interfaces. Given that they are forever, it would be good to have some sort of guidance.

The first item is that you want something that uses the implementation, as well as several distinct implementations. However, this item is too obvious: in almost all cases I have seen in the wild of a bad interface, this guideline was followed.

It was also followed in all cases of a good interface.

I think this guideline is covered well enough that by the time anyone designs a real interface, they understand that. Why am I mentioning this guideline at all, then?

Because I think it is important for the context of the guideline that I do think actually distinguishes good interfaces from bad interfaces. It is almost identical to the non-criterion above!

The real guideline is: something that uses the implementation, as well as several distinct implementations that do not share a superclass (other than object or whatever is in the top of the hierarchy).

This simple addition, preventing the implementations from sharing a superclass, is surprisingly powerful. It means each implementation has to implement the "boring" parts by hand. This will immediately cause pressure to avoid "boring" parts, and instead put them in a wrapper, or in the interface user.

Otherwise, the most common failure mode is that the implementations are all basic variants on what is mostly the "big superclass".

In my experience, just the constraint on not having a "helper superclass" puts appropriate pressure on interfaces to be good.

(Thanks to Tom Most for his encouragement to write this, and the feedback on an earlier draft. Any mistakes that remain are my responsibility.)

Using a computer in order to do rather complex Math is one of the reasons this machine was originally developed. As long as integer numbers and additions, subtractions, and multiplications are exclusively involved in the calculations, everything is fine. As soon as floating point numbers or fractions, as well as divisions, come into play it enormously complicates the whole matter.

As a regular user, we are not fully aware of these issues that happen behind the scenes and may end up with rather suprising, and possibly inaccurate results for our calculations. As developers, we have to ensure that appropriate measures are taken into account in order to instruct the computer to work in the right way.

In our daily life we use the decimal system that is based on the number 10. The computer uses the binary system, which is base 2, and internally it stores and processes the values as a sequence of 1s and 0s. The values we work with have to be constantly transformed between the two representations. As explained in Python's documentation:

...most decimal fractions cannot be represented exactly as binary fractions. A consequence is that, in general, the decimal floating-point numbers you enter are only approximated by the binary floating-point numbers actually stored in the machine.

This behaviour leads to surprising results in simple additions, as shown here:

Listing 1: Inaccuracies with floating point numbers

>>> s = 0.3 + 0.3 + 0.3
>>> s
0.8999999999999999

As you can see here, the output is innaccurate, as it should result to 0.9.

Listing 2 shows a similar case for formatting a floating point number for 17 decimal places.

Listing 2: Formatting a floating point number

>>> format(0.1, '.17f')
'0.10000000000000001'

As you may have learned from the examples above, dealing with floating point numbers is a bit tricky, and requires additional measures in order to achieve the correct result, and to minimize computing errors. Rounding the value can solve at least some of the problems. One possibility is the built-in round() function (for more details regarding its usage see below):

Listing 3: Calculating with rounded values

>>> s = 0.3 + 0.3 + 0.3
>>> s
0.8999999999999999
>>> s == 0.9
False
>>> round(0.9, 1) == 0.9
True

As an alternative, you can work with the math module, or explicitly work with fractions stored as two values (numerator and denominator) instead of the rounded, rather inexact floating point values.

In order to store the values like that the two Python modules decimal and fraction come into play (see examples below). But first, let us have a closer look at the term "rounding".

What is Rounding?

In a few words, the process of rounding means:

...replacing [a value] with a different number that is approximately equal to the original, but has a shorter, simpler, or more explicit representation.

Source: https://en.wikipedia.org/wiki/Rounding

Basically, it adds inaccuracy to a precisely calculated value by shortening it. In most cases this is done by removing digits after the decimal point, for example from 3.73 to 3.7, 16.67 to 16.7, or 999.95 to 1000.

Such a reduction is done for several reasons - for example, saving space when storing the value, or simply for removing unused digits. Furthermore, output devices such as analogue displays or clocks can show the computed value with only a limited precision, and require adjusted input data.

In general, two rather simple rules are applied for rounding, you may remember them from school. The digits 0 to 4 lead to rounding down, and the numbers 5 to 9 lead to rounding up. The table below shows a selection of use cases.

| original value | rounded to   | result |
|----------------|--------------|--------|
| 226            | the ten      | 230    |
| 226            | the hundred  | 200    |
| 274            | the hundred  | 300    |
| 946            | the thousand | 1,000  |
| 1,024          | the thousand | 1,000  |
| 10h45m50s      | the minute   | 10h45m |

Rounding Methods

Mathematicians have developed a variety of different rounding methods in order to address the problem of rounding. This includes simple truncation, rounding up, rounding down, rounding half-up, rounding half-down, as well as rounding half away from zero and rounding half to even.

As an example, rounding half away from zero is applied by the European Commission on Economical and Financial Affairs when converting currencies to the Euro. Several countries, such as Sweden, The Netherlands, New Zealand, and South Africa follow the rule named "cash rounding", "penny rounding", or "Swedish rounding".

[Cash rounding] occurs when the minimum unit of account is smaller than the lowest physical denomination of currency. The amount payable for a cash transaction is rounded to the nearest multiple of the minimum currency unit available, whereas transactions paid in other ways are not rounded.

Source: https://en.wikipedia.org/wiki/Cash_rounding

In South Africa, since 2002 cash rounding is done to the nearest 5 cents. In general, this kind of rounding does not apply to electronic non-cash payments.

In contrast, rounding half to even is the default strategy for Python, Numpy, and Pandas, and is in use by the built-in round() function that was already mentioned before. It belongs to the category of the round-to-nearest methods, and is also known as convergent rounding, statistician's rounding, Dutch rounding, Gaussian rounding, odd–even rounding, and bankers' rounding. This method is defined in IEEE 754 and works in such a way, that "if the fractional part of x is 0.5, then y is the even integer nearest to x." It is assumed "that the probabilities of a tie in a dataset being rounded down or rounded up are equal" which is usually the case, in practice. Although not fully perfect this strategy leads to appreciable results.

The table below gives practical rounding examples for this method:

| original value | rounded to |
|----------------|------------|
| 23.3           | 23         |
| 23.5           | 24         |
| 24.0           | 24         |
| 24.5           | 24         |
| 24.8           | 25         |
| 25.5           | 26         |

Python Functions

Python comes with the built-in function round() that is quite useful in our case. It accepts two parameters - the original value, and the number of digits after the decimal point. The listing below illustrates the usage of the method for one, two, and four digits after the decimal point.

Listing 4: Rounding with a specified number of digits

>>> round(15.45625, 1)
15.5
>>> round(15.45625, 2)
15.46
>>> round(15.45625, 4)
15.4563

If you call this function without the second parameter the value is rounded to a full integer value.

Listing 5: Rounding without a specified number of digits

>>> round(0.85)
1
>>> round(0.25)
0
>>> round(1.5)
2

Rounded values work fine in case you do not require absolutely precise results. Be aware of the fact that comparing rounded values can also be a nightmare. It will become more obvious in the following example - the comparison of rounded values based on pre-rounding, and post-rounding.

The first calculation of Listing 6 contains pre-rounded values, and describes rounding before adding the values up. The second calculation contains a post-rounded summary which means rounding after the summation. You will notice that the outcome of the comparison is different.

Listing 6: Pre-rounding vs. post-rounding

>>> round(0.3, 10) + round(0.3, 10) + round(0.3, 10) == round(0.9, 10)
False
>>> round(0.3 + 0.3 + 0.3, 10) == round(0.9, 10)
True

Python Modules for Floating Point Calculations

There are four popular modules that can help you properly deal with floating point numbers. This includes the math module, the Numpy module, the decimal module, and the fractions module.

The math module is centered around mathematical constants, floating point operations, and trigonometric methods. The Numpy module describes itself as "the fundamental package for scientific computing", and is famous for its variety of array methods. The decimal module covers decimal fixed point and floating point arithmetic, and the fractions module deals with rational numbers, specifically.

First, we have to try to improve the calculation from Listing 1. As Listing 7 shows, after having imported the math module we can access the method fsum() that accepts a list of floating point numbers. For the first calculation there is no difference between the built-in sum() method, and the fsum() method from the math module, but for the second one it is, and returns the correct result we would expect. The precision depends on the underlying IEEE 754 algorithm.

Listing 7: Floating-point calculations with the help of the math module

>>> import math
>>> sum([0.1, 0.1, 0.1])
0.30000000000000004
>>> math.fsum([0.1, 0.1, 0.1])
0.30000000000000004
>>> sum([0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1])
0.9999999999999999
>>> math.fsum([0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1])
1.0

Second, let us have a look at the Numpy module. It comes with the around() method that rounds the values provided as an array. It processes the single values in the same way as the default round() method.

In order to compare values Numpy offers the equal() method. Similar to around() it accepts single values as well as lists of values (so-called vectors) to be processed. Listing 8 shows a comparison for single values as well as rounded values. The observed behaviour is quite similar to the previously shown methods.

Listing 8: Comparing values using the equal method from the Numpy module

>>> import numpy
>>> print (numpy.equal(0.3, 0.3))
True
>>> print (numpy.equal(0.3 + 0.3 + 0.3 , 0.9))
False
>>> print (numpy.equal(round(0.3 + 0.3 + 0.3) , round(0.9)))
True

Option three is the decimal module. It offers exact decimal representation, and preserves the signifcant digits. The default precision is 28 digits, and you can change this value to a number that is as large as needed for your problem. Listing 9 shows how to use a precision of 8 digits.

Listing 9: Creating decimal numbers using the decimal module

>>> import decimal
>>> decimal.getcontext().prec = 8
>>> a = decimal.Decimal(1)
>>> b = decimal.Decimal(7)
>>> a / b
Decimal('0.14285714')

Now, comparing of float values becomes a lot easier, and leads to the result we were looking for.

Listing 10: Comparisons using the decimal module

>>> import decimal
>>> decimal.getcontext().prec = 1
>>> a = decimal.Decimal(0.3)
>>> b = decimal.Decimal(0.3)
>>> c = decimal.Decimal(0.3)
>>> a + b + c
Decimal('0.9')
>>> a + b + c == decimal.Decimal('0.9')
True

The decimal module also comes with a method to round values - quantize(). The default rounding strategy is set to rounding half to even, and can also be changed to a different method if needed. Listing 11 illustrates the usage of the quantize() method. Please note that the number of digits is specified using a decimal value as a parameter.

Listing 11: Rounding a value using quantize()

>>> d = decimal.Decimal(4.6187)
>>> d.quantize(decimal.Decimal("1.00"))
Decimal('4.62')

Last but not least, we will have a look at the fractions module. This module allows you to handle floating point values as fractions, for example 0.3 as 3/10. This simplifies the comparison of floating point values, and completely eliminates rounding of values. Listing 12 shows how to use the fractions module.

Listing 12: Storing and comparing floating point values as fractions

>>> import fractions
>>> fractions.Fraction(4, 10)
Fraction(2, 5)
>>> fractions.Fraction(6, 18)
Fraction(1, 3)
>>> fractions.Fraction(125)
Fraction(125, 1)
>>> a = fractions.Fraction(6, 18)
>>> b = fractions.Fraction(1, 3)
>>> a == b
True

Furthermore, the two modules decimal and fractions can be combined, as shown in the next example.

Listing 13: Working with decimals and fractions

>>> import fractions
>>> import decimal
>>> a = fractions.Fraction(1,10)
>>> b = fractions.Fraction(decimal.Decimal(0.1))
>>> a,b
(Fraction(1, 10), Fraction(3602879701896397, 36028797018963968))
>>> a == b
False

Conclusion

Storing and processing floating point values correctly is a bit of a mission, and requires a lot of attention for programmers. Rounding the values may help, but be sure to check the correct order of rounding, and the method that you use. This is most important when developing things like financial software, so you'll want to check the rules of local law for rounding.

Python gives you all the tools that are needed, and comes with "batteries included". Happy hacking!

Acknowledgements

The author would like to thank Zoleka Hofmann for her critical comments while preparing this article.

As already pointed out in a previous article titled Commenting Python Code you have learned that documentation is an essential, and a continuous step in the process of software development. The article mentioned above briefly introduced the concept of docstrings which is a way to create documentation for your Python code from within the code. This in-code documentation works for modules, classes, methods, and functions, and it is the preferred way to document all Python code.

There is a lot more to it, and that's why we will have a closer look at this subject in this article. We'll cover conventions on how to write docstrings correctly, as well as various docstring formats that are used in practice, followed by accessing a docstring from your Python script. And lastly, we'll present you a number of tools in order to use and evaluate docstrings.

Diving into Docstrings

The term docstring is an abbreviation for documentation string, and describes your source code - i.e. what your function, module, or class does. It is added as a regular comment right below the head of a function, module, class, or method.

A typical example looks as follows, and is taken from a Python class for working with a measurement device like a mobile sensor to measure temperature, humidity, and wind velocity.

Listing 1: Python code with a single-line docstring

class Device:
    def __init__(self, temp=0.0):
        "Initialize the Device object with the given temperature value."
        
        self.set_temperature(temp)
        return

In order to write a docstring correctly follow a number of conventions. These conventions are explained in more detail in the PEP 257, which stands for Python Enhancement Proposal.

Single-Line Docstrings

Due to simplicity the docstring used in Listing 1 comes as a single-line comment. Keep in mind to begin the text of a docstring with a capital letter, and end it with a period. Based on the fact that code is typically read more often than it is written, it is recommended to describe what the documented structure does as a kind of command instead of how it is done. Mentioning which kind of value is returned to the caller helps to understand the result of the function or method.

You may have noted that the method's docstring from Listing 1 is framed in single double-quotes. Well, as long as both the beginning and the end quotes are similar, Python is quite tolerant, and you are also allowed to use three single-quotes as well as three double-quotes, instead:

    def get_temperature(self):
        '''Return the stored temperature value as a float value.'''

        return self.temperature
    
    def set_temperature(self, temp):
        """Set the temperature value."""

        self.temperature = float(temp)
        return

Please make sure that the closing quotes are in the same line as with the opening quotes. Also, do not add any empty lines before, or after the text of the docstring.

Multi-line Docstrings

Furthermore, a docstring can also be written as a multi-line comment. When using multi-line comments, two things change - the encapsulation of the docstring must be written in triple single- or double-quotes, and the structure of the docstring itself has a deeper meaning that is assigned to the entire text.

The first line of the docstring is interpreted as an abstract, or a short description, and is recommended to be written in the same way as a single-line docstring. An empty line that follows is interpreted as a separator between the abstract and the full description below. Listing 2 extends Listing 1, and does not use a specific format for the description, as mentioned below.

Listing 2: Multi-line docstring

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.
    """

    self.temperature = float(temp)
    return

Following the docstring structure for multi-line strings is strongly recommended as automated indexing tools evaluate these texts, and therefor rely on the compliance with the block order.

Docstring Formats

You might expect that there is just one binding docstring format. Unfortunately, there is more than one, and all of these format variants work with multi-line docstrings.

• reStructured text (reST) / Sphinx: This is the Official Python documentation standard. It uses the syntax of the lightweight markup language reStructured text (reST) which is similar in usage to Markdown.
• Google Docstrings: Google's style of docstring
• NumPy/SciPy Docstrings: A combination of reStructured text (reST) and Google Docstrings. Usable by Sphinx as well, and quite verbose.

Listing 3 shows how to write the docstring using reST. The keywords that you can use are the following:

• param and type: Parameter and its variable type
• return and rtype: Specify both the return value and type of the function or method
• .. seealso::: Further reading
• .. notes::: Add a note
• .. warning::: Add a warning

The order of the entries is not fixed, but stick to the same order throughout your entire project. The entries for seealso, notes, and warning are optional.

Listing 3: Multi-line docstring with reST data

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    :param temp: the temperature value
    :type temp: float
    :return: no value
    :rtype: none
    """

    self.temperature = float(temp)
    return

In order to understand Google's docstrings you may have a look at Listing 4. The format is less dense, and uses more horizontal space.

Listing 4: Multi-line docstring (Google Format)

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Args:
        temp (float): the temperature value

    Returns:
        no value
    """

    self.temperature = float(temp)
    return

Finally, Listing 5 shows the same method in NumPy docstring format. It uses more vertical space, and looks easier to read than the original format.

Listing 5: Multi-line docstring (NumPy Format)

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Parameters
    ----------
    temp : float
        the temperature value

    Returns
    -------
    no value
    """

    self.temperature = float(temp)
    return

Accessing Docstrings

In the Python interactive help system, the docstring is available via the __doc__ attribute. Listing 6 shows how to use code to access the documentation string, which in our example is based on Listing 1.

Listing 6: Accessing the docstring value

>>> def set_temperature (self, temp):
...     """Set the temperature value."""
...     temperature = float(temp)
...     return
... 
>>> print(set_temperature.__doc__)
Set the temperature value.

Tools to Use the Docstrings

There is a number of tools that auto-generate documentation from docstrings, such as Sphinx, Epydoc, Doxygen, PyDoc, pdoc, and the autodoc extension for Sphinx. Most of them generate HTML documents for local use.

Pydoc is part of the Python distribution, and derives information about a module for the console, a web browser, or as an HTML document. Inside the Python shell use the help() function in order to learn more about a module, function, class, or method. Figure 1 shows the docstring from Listing 1 via the Python help system.

Figure 1: The extracted docstring

In order to see the built-in documentation for all of the Python modules that are installed locally, you may run pydoc as a local webserver. Using the parameter -p followed by the port number starts a small webserver that is accessible using the given port. Listing 7 starts the pydoc server at port 1234, and Figure 2 shows the information extracted and made available by pydoc.

Listing 7: Running pydoc as a webserver

$ pydoc3 -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>
...

Figure 2: The extracted docstring on a local webserver

Conclusion

Following the guidelines for documentation helps you and others to understand source code today and at a later time. Docstrings are used for more than that, for example for the generation of manuals. This idea in mind allows projects at a greater scale.

These are the ten most rated questions at Stack Overflow last week.
Between brackets: [question score / answers count]
Build date: 2019-08-10 21:33:55 GMT

1. Is there a difference between `board[x, y]` and `board[x][y]` in Python? - [31/5]
2. Pandas: fill one column with count of # of obs between occurrences in a 2nd column - [9/4]
3. Unique combinations of a list of tuples - [7/5]
4. exact model converges on keras-tf but not on keras - [7/0]
5. Property annotation that checks assignment to a guard value initially set to None - [6/3]
6. What's the Pythonic way to write conditional statements based on installed modules? - [6/2]
7. What does 'del self.self ' in an __init__ function mean? - [6/2]
8. Is it possible to override __getitem__ at instance level in Python? - [6/2]
9. Apply python lazy map for in-place functions? - [6/1]
10. Why does numpy not short-circuit on non-contiguous arrays? - [6/1]