String Methods Overview
Square brackets in documentation indicate optional arguments; they are not part of the actual code.
Reading the Signature
When Python documentation shows a method signature, its punctuation communicates how the method can be called. In the pattern find(sub[, start[, end]]), the argument sub is required, while start and end are optional. The square brackets are documentation notation: they explain the method's argument rules, but they are not characters that you type in the call.
The Required Argument
Arguments written outside square brackets are required. Every call must include them. In find(sub[, start[, end]]), sub appears outside the brackets, so a call must provide a value for sub. The brackets around start and end do not change that requirement; they only show that those two arguments may be left out.
Separating Required and Optional Parts
Interpret the signature find(sub[, start[, end]]).
Find the unbracketed argument: The argument sub is outside square brackets, so it is required.
Find the bracketed arguments: The arguments start and end are inside square brackets, so they are optional.
Build the shortest call: Because sub is required and the other arguments can be omitted, the shortest form supplies only sub.
The signature permits a call with sub, a call with sub and start, or a call with sub, start, and end.
Nested Optional Arguments
Nested brackets show dependency, not just a list of unrelated choices. In find(sub[, start[, end]]), the bracket containing start is the outer optional level. The bracket containing end is nested inside it. Therefore, end is available only after start has been provided. You cannot use the inner optional argument while skipping the outer one.
What do you think happens?
Which argument must be supplied before end can be used in find(sub[, start[, end]])?
Reveal answer
Answer: start
sub is required in every call, and the nested placement of end shows that start must be provided before end can be used.
From Signature to Call
| Documented form | Arguments supplied | Meaning of the form |
|---|---|---|
| find(sub[, start[, end]]) | sub | Required argument only |
| find(sub[, start[, end]]) | sub, start | Required argument plus the outer optional argument |
| find(sub[, start[, end]]) | sub, start, end | Required argument plus both optional arguments |
When translating documentation into code, remove the square brackets, keep the argument order, and begin with every argument outside the brackets. Then add optional arguments from the outside inward. For find(sub[, start[, end]]), end cannot be moved ahead of start or supplied while start is absent.
Documentation Only Symbols
Typing the square brackets from the documentation in the method call
The brackets indicate optional arguments in documentation; they are not part of Python code. Typing them in the call causes a syntax error.
Fix:
Write the call without documentation brackets, such as text.find('a'), text.find('a', 0), or text.find('a', 0, 5).Trying to provide end without start
The nested brackets show that end depends on start.
Fix:
Supply sub first, then start, and only then add end.Treating every argument as required
Arguments inside square brackets are optional.
Fix:
Include the required argument sub, then decide whether the optional arguments are needed.
Practice Translation
Translate the signature find(sub[, start[, end]]) into three valid call forms. Then explain why a form that supplies end while omitting start does not follow the documented dependency.
Hints
- Begin with the argument outside all brackets.
- Add the outer optional argument before the nested optional argument.
- Do not type the square brackets themselves.
A Reliable Reading Process
Use the documentation pattern find(sub[, start[, end]]) to decide the argument order.
Read the required part: sub is outside brackets, so it must appear in every call.
Read the first optional level: start is inside the outer brackets, so it may be added after sub.
Read the nested level: end is inside the brackets nested within start, so it may be added only after start.
Remove notation brackets: The square brackets explain optionality and must not be typed in the call.
The permitted argument sequences are sub; sub followed by start; or sub followed by start and end.
Key Takeaways
- Arguments outside square brackets in documentation are required.
- Arguments inside square brackets are optional, and the brackets are not typed in the actual code.
- Nested brackets show dependency: an inner optional argument requires the surrounding outer optional argument first.
- In find(sub[, start[, end]]), sub is required, start is optional, and end is optional only when start is supplied.
- Translate signatures from left to right, preserving argument order and removing documentation-only brackets.
Key Takeaways
- Square brackets in Python method documentation indicate optional arguments; they are not part of the code.
- Every argument outside brackets must be supplied.
- Nested optional arguments must be supplied from the outside inward.
- The signature find(sub[, start[, end]]) permits sub, sub with start, or sub with start and end.
- Reading documentation from left to right helps produce calls with the correct number and order of arguments.