Python replace(): Replace Literal Text and Limit the Count

Start with a small, explicit task

A synthetic note contains the marker [WAIT] twice. Replace only the first occurrence for a first-item preview, then replace every occurrence for the complete display. Also use a dot-containing label to check whether a dot is interpreted literally.

Run the complete example

This original example was checked with Python 3.12.14. Save it as python_replace.py and run it with Python 3.12. It uses only the standard library. The assertions check the stated results.

note = "[WAIT] shelf A; [WAIT] shelf B"
preview = note.replace("[WAIT]", "[READY]", 1)
complete = note.replace("[WAIT]", "[READY]")
assert preview == "[READY] shelf A; [WAIT] shelf B"
assert complete == "[READY] shelf A; [READY] shelf B"
assert note == "[WAIT] shelf A; [WAIT] shelf B"
assert "a.b.c".replace(".", "-") == "a-b-c"
assert note.replace("absent", "x") == note
print(preview)
print(complete)
print("a.b.c".replace(".", "-"))

Explain the result

The preview changes the first marker and leaves the second intact because count is one. The complete display changes both. The source note still contains two waiting markers, demonstrating that a returned string must be retained if the change is meant to be used later.

The dot is an ordinary character in replace, so it changes only the two actual dots. A regex pattern containing a dot would have different matching semantics unless escaped. The absent-marker assertion also shows that no-match replacement returns equivalent text rather than signaling a failed validation. If finding a marker is mandatory, check that requirement separately.

Avoid these mistakes

Avoid using an empty old string by accident: it targets insertion positions rather than a meaningful marker. Replacements also affect matching text inside larger words, so define a token boundary or use an appropriate parser when whole words or a structured format matter.