Reading Python Official Documentation
Square brackets in documentation indicate optional arguments; they are not part of the actual code.
Why Documentation Uses Brackets
When you look up a Python method, its documentation must show both the arguments that every call requires and the arguments that a call may omit. Python documentation uses square brackets for this purpose. The brackets are notation for the reader: they are not part of the actual Python code.
An argument outside square brackets is required. An argument inside square brackets is optional. Do not type the documentation brackets in your method call.
Separating Notation from Code
Read the signature from left to right. In the pattern find(sub[, start[, end]]), find is the method name and sub is outside every optional bracket, so sub is required. The brackets surrounding start and end are documentation markers. They tell you which arguments may be omitted; they do not tell Python to expect literal square brackets.
Required and Optional Arguments
Arguments written outside square brackets are required, so every call must include them. Arguments written inside square brackets are optional, so a call may leave them out.
Reading the find Signature
Interpret the documented pattern find(sub[, start[, end]]).
Read the unbracketed part: The argument sub appears outside square brackets. It is required in every call.
Read the outer optional group: The group containing start and the nested end argument is optional, so start may be omitted.
Translate the minimum call: Because sub is the only required argument, a call can provide sub and omit both optional arguments.
Add the next argument: A call may also provide sub and start. The optional end argument is still omitted in this form.
The signature describes calls with one required argument, with optional additional arguments that follow it in order.
| Documentation part | Meaning |
|---|---|
| sub | Required argument |
| [ start ] | Optional argument |
| [ end ] | Optional argument with a dependency on start |
The required and optional parts of find(sub[, start[, end]])
Reading Nested Optional Groups
Nested brackets communicate dependency. In find(sub[, start[, end]]), start is inside the outer optional group, while end is inside a further nested group. Therefore, end is available only after start has been supplied. You cannot skip start and provide end by itself.
- Provide sub alone when you need only the required argument.
- Provide sub and start when you want to include the first optional argument.
- Provide sub, start, and end when you want to include the nested optional argument.
- Do not try to provide sub and end while omitting start.
Translating Signatures into Calls
| Documentation form | Arguments supplied | Resulting call shape |
|---|---|---|
| find(sub) | sub | One argument |
| find(sub[, start]) | sub and start | Two arguments |
| find(sub[, start[, end]]) | sub, start, and end | Three arguments |
The documented pattern maps to a method call by removing the square brackets and choosing how many arguments to supply. The order remains left to right: sub comes first, start comes next, and end comes last. The optional arguments do not become interchangeable merely because both are optional.
Suppose you are reading documentation for a string method and see find(sub[, start[, end]]). A call using only the required argument follows the sub form. A call that supplies a starting position follows the sub, start form. A call that supplies both boundaries follows the sub, start, end form. In each case, the documentation brackets are left out of the actual call.
Mistakes Beginners Make
Typing the documentation brackets into the method call
Square brackets in this documentation pattern indicate optional arguments; they are not part of the actual code. Including them in the attempted call can cause a syntax error.
Fix:
Remove the documentation brackets and provide only the arguments you want to pass.Treating every argument as optional
sub appears outside the brackets, so every call must include it.
Fix:
Begin by identifying the arguments outside brackets. Those arguments are required.Using end without start
The nested brackets show that end is optional only if start has already been provided.
Fix:
Supply arguments from left to right and include start before end.
When you encounter a new method signature, first mark every argument outside square brackets as required. Then inspect nested brackets from left to right to determine which optional arguments depend on earlier ones.
Practice Reading a Signature
Read the signature find(sub[, start[, end]]) and write down the valid argument groups in order. Then identify which argument cannot be supplied unless another argument has already been supplied.
Hints
- Start with the argument outside all square brackets.
- The first optional argument is in the outer group.
- The second optional argument is nested inside that group.
What do you think happens?
For find(sub[, start[, end]]), can a call provide sub and end while omitting start?
Reveal answer
Answer: No, because end depends on start.
The inner brackets around end are nested inside the optional group containing start. The nesting requires start to be supplied before end can be used.
Key Takeaways
- Square brackets in Python documentation mark optional arguments and are not typed into the code.
- Arguments outside brackets are required in every call.
- Nested brackets show dependency: a nested optional argument requires the outer optional arguments before it.
- For find(sub[, start[, end]]), sub is required, start is optional, and end is optional only when start is provided.
- Read method signatures from left to right to determine the correct number and order of arguments.
Key Takeaways
- Square brackets in official documentation describe optional arguments; they are not code syntax to copy.
- Every argument outside brackets must be supplied.
- Nested optional arguments must be supplied in dependency order.
- The signature find(sub[, start[, end]]) describes one required argument followed by two optional arguments with a dependency between them.