What do square brackets, "[]", mean in function/class documentation?

Understanding Square Brackets '[]' in Function and Class Documentation

Demystify the use of square brackets in Python function signatures and class constructors, learning how they indicate optional arguments and type hints.

When reading documentation for functions or class constructors in Python, you often encounter square brackets [] around certain parameters. These brackets are not part of the syntax you type when calling the function; instead, they serve as a conventional notation to indicate that the enclosed arguments are optional. This article will explain what these brackets mean, why they are used, and how to interpret them in various documentation contexts.

Square Brackets for Optional Arguments

The primary use of square brackets in function or method signatures within documentation is to denote optional parameters. If a parameter is enclosed in [], it means you do not have to provide a value for it when calling the function. If omitted, the parameter typically has a default value, or its absence triggers specific behavior within the function.

This convention is particularly common in API documentation, library references, and even built-in Python function help messages. Understanding this notation helps you quickly grasp which arguments are essential and which can be safely ignored or customized.

def func_with_optional(required_arg, optional_arg=None):
    """
    This is a sample function.

    Args:
        required_arg (str): A necessary argument.
        optional_arg (int, optional): An optional argument. Defaults to None.
    """
    if optional_arg is not None:
        print(f"Required: {required_arg}, Optional: {optional_arg}")
    else:
        print(f"Required: {required_arg}, Optional argument not provided.")

# How this might appear in documentation:
# func_with_optional(required_arg[, optional_arg])

func_with_optional("Hello")
func_with_optional("World", 123)

A Python function demonstrating an optional argument and how its signature might appear in documentation.

Advanced Usage: Type Hinting and Union Types

While less common for simply indicating optionality, square brackets also have a specific syntactical meaning in Python's type hinting system, particularly when dealing with typing.Union or typing.Optional. Before Python 3.10, Optional[X] was used to indicate that a variable could be either type X or None. Optional[X] is essentially syntactic sugar for Union[X, None].

With Python 3.10+, you can use the | operator for union types, making X | None equivalent to Optional[X]. This is distinct from the documentation convention for optional arguments, but the use of brackets can sometimes lead to confusion. It's crucial to distinguish between documentation notation and actual Python syntax.

In documentation, you might see something like List[str] which is actual Python type hinting syntax indicating a list containing strings, not an optional list.

Distinguishing between documentation notation and type hinting syntax for square brackets.

Interpreting Different Documentation Styles

Different documentation generators and styles might present optional arguments slightly differently, but the [] convention remains widely understood. For instance:

• Sphinx/reStructuredText: Often uses [argument_name] or argument_name (optional).
• Google Style Docstrings: Might explicitly state (optional) or define a default value in the Args section.
• NumPy Style Docstrings: Similar to Google style, often clarifies optionality and default values.

Regardless of the specific format, if you see square brackets around a parameter in a function signature, it's a strong indicator that you don't have to provide that argument.

def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

# Documentation might show: greet(name[, greeting])

# INCORRECT usage (will raise SyntaxError):
# greet("Alice"[, "Hi"])

# CORRECT usage:
greet("Bob") # Uses default greeting
greet("Charlie", "Hi") # Provides an optional greeting

Demonstrating the correct way to call functions with optional arguments, avoiding the documentation brackets.