bytes.partition()

Always three parts, whatever the input. That guarantee is the whole point — unpacking can never fail the way it does with split.

Bytes methodPython 3.0+Live demo
Common call
head, sep, tail = data.partition(b'=')
Returns
a 3-tuple, always — no length surprises
Replaces
split(sep, 1) plus a length check
Watch out
a missing separator puts everything in the HEAD, not the tail
bytes.partition(sepsep — Separator to split on, at its first occurrence. An empty separator raises ValueError.type: bytes · required)
→ tuple

Demo

Live evaluation
Try:
Inputs
sstrdata (encoded as utf-8)
sepstrseparator
Output
bytes('a=b', 'utf-8').partition(bytes('=', 'utf-8'))
(b'a', b'=', b'b')

Three parts come back every time. With a separator present you get what is before it, the separator itself, and what is after — and only the FIRST occurrence splits, so "a=b=c" leaves the second equals sign in the tail. When the separator is absent the head holds the entire input and the other two are empty, which is the detail to remember: check the separator, not the tail, to find out whether a split happened.

Parameters

NameTypeRequiredDescription
sepbytesyesSeparator to split on, at its first occurrence. An empty separator raises ValueError.

Return value

tuple — Always a three-item tuple: (head, separator, tail). When the separator is absent, the head holds everything and the other two are empty.

Common patterns

Parse a key-value line safely
No unpacking error is possible, whatever the input looks like.
key, sep, value = line.partition(b'=')
if not sep:
    raise ValueError('missing =')
Split a header from a body
The tail keeps everything after the first separator.
head, _, body = payload.partition(b'\r\n\r\n')
Take the part before a marker
Works whether or not the marker is present.
prefix = data.partition(b'#')[0]

Examples

1. Separator present
b'a=b'.partition(b'=')
Returns
(b'a', b'=', b'b')
2. Splits at first
b'a=b=c'.partition(b'=')
Returns
(b'a', b'=', b'b=c')
3. Absent
b'abc'.partition(b'=')
Returns
(b'abc', b'', b'')
4. At the start
b'=abc'.partition(b'=')
Returns
(b'', b'=', b'abc')
5. At the end
b'abc='.partition(b'=')
Returns
(b'abc', b'=', b'')
6. Unpack is safe
h, s, t = b'abc'.partition(b'=')
Returns
always works

Pitfalls

1. A missing separator fills the HEAD
People reliably expect the tail. Code that reads the third element as "the value" silently gets empty bytes when the separator was absent, instead of failing.
Empty value
b'novalue'.partition(b'=')[2]
b''
Test the separator
h, s, t = data.partition(b'=')
if not s:
    raise ValueError('no separator')
explicit
2. Only the first occurrence splits
Later separators stay in the tail. That is usually what you want for key=value data, and wrong when you expected every field split out.
Rest stays joined
b'a=b=c'.partition(b'=')
(b'a', b'=', b'b=c')
Use split
b'a=b=c'.split(b'=')
[b'a', b'b', b'c']
3. An empty separator raises
There is no meaningful place to split, so Python refuses. A separator built from a variable that turned out empty fails here rather than where it was set.
No split point
b'abc'.partition(b'')
ValueError: empty separator
Guard it
parts = data.partition(sep) if sep else (data, b'', b'')
explicit
4. The separator must be bytes
A str is a TypeError, as with every bytes method. Common when parsing code written for text is pointed at a file opened in binary mode.
str rejected
b'a=b'.partition('=')
TypeError: a bytes-like object is required, not 'str'
Bytes literal
b'a=b'.partition(b'=')
(b'a', b'=', b'b')

When to use

Use it
  • Key-value parsing where malformed input must not crash
  • Splitting a header from a body at the first delimiter
  • Anywhere split(sep, 1) would need a length check afterwards
Reach for something else
  • You want every field → split
  • You want the LAST separator → rpartition
  • The data is text → decode first and use str.partition

Notes

Complexity
O(n) worst case; stops at the first match
Return
A new three-item tuple of new bytes objects
CPython impl
Objects/bytesobject.c :: bytes_partition
Memory
Allocates the tuple and up to three parts
Thread-safe
Yes — bytes are immutable

FAQ

So that the head always means "everything up to the separator". With no separator, that is the whole input. It also makes data.partition(sep)[0] a safe way to take the prefix whether or not the separator exists.

b'abc'.partition(b'=')
# (b'abc', b'', b'')

History

3.0
bytes.partition arrived with the bytes type in the text/binary split.