Random features and tips

Table of Contents

1. The any and all keywords in Python
2. Python Docstring
3. EEPROM in Arduino
4. Named groups in Python regex

The any and all keywords in Python

any behaves like the mathematical OR operator. It takes an iterable and returns True if at least one of the elements in the iterable is truthy. See any documentation

>>> any([0, 1, 2, 3])
True

>>> any([0, False, None])
False

>>> any([0, False, None, 1])
True

all behaves like the mathematical AND operator. It takes an iterable and returns True only if all of the elements in the iterable are truthy. See all documentation

>>> all([0, 1, 2, 3])
False

>>> all([1, 2, 3])
True

>>> all([1, 2, 3, None])
False

See the Python documentation for more built-in functions.

Python Docstring

These are strings used for documenting a Python module, class, function or method in a consistent format. They are used to generate online or offline documentation, and editors like VS Code will automatically pick up on them (and Markdown formatting!) to give tooltips. See docstring convention.

Here’s an example from a project I’m working on:

def get_all_papers() -> list[dict]:
    """
    Required structure is a list of this dictionary:
    ```py
    {
        "id": int,
        "title": str,
        "days": [
            {
                "id": int,
                "delivery": bool,
                "cost": float
            }
        ]
    }
    ```
    """

    papers = models.Paper.objects.all()

    papers_list = []

    for paper in papers:
        paper_dict = {
            "id": paper.id,
            "title": paper.title,
            "days": []
        }

        costs = models.Cost.objects.filter(paper=paper)

        for cost in costs:
            paper_dict["days"].append({
                "id": cost.id,
                "delivery": cost.delivery,
                "cost": cost.cost
            })

        papers_list.append(paper_dict)

    return papers_list

Here is the documentation generated by VS Code:

It may also interest you to look into these:

1. Doxygen: A tool for generating documentation from source code; this is internally used by the example above to some extent. See Doxygen documentation.
2. Guide to documenting Python code: A look at the technical aspects of writing documentation for Python code, by Real Python. Link to article
3. Write The Docs: A community/wiki with information on writing good documentation. Link to website.

EEPROM in Arduino

While I have been using micro-controllers for a few years at thing point, I only recently discovered that the Arduino framework has built-in EEPROM support. This is a small amount of memory that can be used to store data that will persist even when the device is powered off. See EEPROM documentation

This allows for some really cool behaviour, such as storing settings right on the board.

Named groups in Python regex

For the uninitiated, using regex (regular expressions) is a way of matching patterns in strings. Here are some examples:

## Import the regex module
import re

## An (oversimplified) email regex
email_regex = r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"

# test
print(re.match(email_regex, "someone@example.com"))
print(re.match(email_regex, "someone@example,com"))

Since regex is fairly standardized, learning it once means the skill carries well over to other languages. Check out the CS50P episode on regex to learn more: CS50P - Lecture 7 - Regular Expressions.

However, Python has a feature called named groups. This allows you to name a group of characters in a regex, and then access them by name. This is useful for extracting data from strings. See named groups documentation.

## Import the regex module
import re

## An email regex with named groups
email_regex = r"^(?P<username>[a-zA-Z0-9_.+-]+)@(?P<domain>[a-zA-Z0-9-]+)\.(?P<tld>[a-zA-Z0-9-.]+)$"

# test
match = re.match(email_regex, "someone@example.com")
print(match.group("username"))
print(match.group("domain"))
print(match.group("tld"))