str.partition()

Split the string at the FIRST occurrence of sep, returning a fixed-shape three-tuple: what came before, the separator itself, and what came after.

String methodPython 2.5+Live demo
Common call
key, _, value = "a=1".partition("=")
Returns
3-tuple, always — sep preserved in the middle
Replaces
the split-then-check-length dance for key/value strings
Watch out
no match → (original, "", ""); empty sep raises ValueError
str.partition(sepsep — Substring to split on. Empty string raises ValueError. First occurrence only.type: str · required)
→ tuple[str, str, str]

Demo

Live evaluation
Try:
Inputs
stringstrthe source
sepstrthe separator
Output
'user=alice'.partition('=')
['user', '=', 'alice']

partition always returns exactly three strings — no guessing at tuple length. When the separator is not found, before is the entire string and the other two slots are empty; when it IS found, the separator itself is preserved in the middle slot. Splitting a value that contains additional separators only splits at the first — the rest stays in the tail.

Parameters

NameTypeRequiredDescription
sepstryesSubstring to split on. Empty string raises ValueError. First occurrence only.

Return value

tuple[str, str, str] — Always a 3-tuple (before, sep, after). If sep is not found: (original_string, "", "").

Common patterns

Parse key=value once
Perfect for lines from a config or query string where the value may itself contain the separator.
key, _, value = line.partition("=")
Optional prefix stripping
Strip only if present, leave the string alone otherwise — no branch.
before, sep, after = url.partition("://")
rest = after if sep else before
First-token split
Head + tail without materializing a full split.
first, _, rest = sentence.partition(" ")

Examples

1. Basic key/value
"user=alice".partition("=")
Returns
("user", "=", "alice")
2. Multiple separators
"a=b=c".partition("=")
Returns
("a", "=", "b=c")
3. Not found
"hello".partition("=")
Returns
("hello", "", "")
4. Separator at start
"=alone".partition("=")
Returns
("", "=", "alone")
5. Multi-char separator
"a->b".partition("->")
Returns
("a", "->", "b")
6. Empty sep raises
"hello".partition("")
Returns
ValueError: empty separator

Pitfalls

1. Not-found returns the original — in the FIRST slot
Newcomers expect ("", "", original) or an error. It is the other way: before = original, middle and after are empty. Fine once you know it — surprising until then.
Wrong unpacking
_, _, value = "no-eq-here".partition("=")
# value is "" — the data went into slot 0
value = ""
Check sep
before, sep, after = s.partition("=")
if sep:
    key, value = before, after
explicit fallback
2. Empty separator raises ValueError
Unlike split (which errors similarly), partition rejects an empty sep too — there is no sensible three-way split.
Runtime error
"hello".partition("")
ValueError: empty separator
Guard
if sep:
    a, s, b = text.partition(sep)
no-op when sep is empty
3. Splits only at the FIRST occurrence
The tail keeps any additional separators intact — useful for key=value where the value itself contains `=`, but wrong when you meant a full split.
Not a full split
"a=b=c".partition("=")
("a", "=", "b=c")
Use split for all
"a=b=c".split("=")
["a", "b", "c"]

When to use

Use it
  • Key-value strings where the value may contain the separator
  • "Split if present, keep original otherwise" in one call
  • Head + tail extraction without materializing an N-way split
  • Getting a fixed-shape return you can always unpack into three names
Reach for something else
  • Full N-way split → split
  • Last-occurrence split → rpartition
  • Regex-based splits → re.split

Notes

Complexity
O(n) — one linear scan for the first match
Return
A 3-tuple of strings; identity-shared with the original when the separator is absent
CPython impl
Objects/unicodeobject.c :: unicode_partition
Memory
Two new substrings when the separator is found; no allocation otherwise
Thread-safe
Yes — strings are immutable

FAQ

partition splits at the FIRST occurrence only and always returns three items (before, sep, after). split can split every occurrence and does not preserve the separators. partition is safer for "take one, leave the rest" parsing.

History

2.5
partition() and rpartition() introduced.