urllib.parse.ParseResultBytes

Give urlparse, urlsplit or urldefrag bytes and every field comes back as bytes, in a *Bytes result class. Internally the bytes are decoded as ASCII, parsed as str and encoded again — so the input must be pure ASCII, and str and bytes arguments cannot be mixed.

urllib.parse classPython 3.2+Live demo
Common call
urlsplit(b'https://example.com/a')
Returns
SplitResultBytes(scheme=b'https', netloc=b'example.com', ...)
Replaces
decoding the URL bytes yourself before parsing
Watch out
Non-ASCII bytes raise UnicodeDecodeError — percent-encode them first
urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)
→ ParseResultBytes | SplitResultBytes | DefragResultBytes

Demo

Live evaluation
The URL text encoded as UTF-8 bytes, then split. Non-ASCII characters make it fail.
Try:
Inputs
urlstra URL
Code
from urllib.parse import urlsplit
urlsplit('https://Example.com:8080/a?q=1#f'.encode())
Result
SplitResultBytes(scheme=b'https', netloc=b'Example.com:8080', path=b'/a', query=b'q=1', fragment=b'f')

Bytes input is decoded with the ascii codec before parsing, so 'café' encoded as UTF-8 fails at the first byte of é: "'ascii' codec can't decode byte 0xc3 in position ...". Everything else works as for str: .hostname is lowercased bytes, .port is an int, geturl() returns bytes and .decode() converts the whole result to ParseResult.

Parameters

NameTypeRequiredDescription
scheme, netloc, path, params, query, fragmentbytesyesParseResultBytes fields (SplitResultBytes has no params; DefragResultBytes has url and fragment). Usually created by the parse functions, not by hand.

Return value

ParseResultBytes | SplitResultBytes | DefragResultBytes — Named tuples of bytes fields. .decode(encoding="ascii", errors="strict") returns the str class; geturl() returns bytes.

Common patterns

Parse URLs read as bytes
Raw HTTP or log data; decode the result once at the end.
from urllib.parse import urlsplit
parts = urlsplit(raw_url_bytes)
host = parts.hostname.decode('ascii')
Convert between the two families
encode() on a str result, decode() on a bytes result (ASCII by default).
from urllib.parse import urlparse
b = urlparse(url).encode('utf-8')
s = b.decode('utf-8')

Examples

1. urlparse(bytes)
from urllib.parse import urlparse urlparse(b'https://example.com/a?q=1')
Returns
ParseResultBytes(scheme=b'https', netloc=b'example.com', path=b'/a', params=b'', query=b'q=1', fragment=b'')
2. hostname is bytes, port is int
from urllib.parse import urlsplit r = urlsplit(b'https://Example.com:8080/') (r.hostname, r.port)
Returns
(b'example.com', 8080)
3. decode() → ParseResult
from urllib.parse import urlparse urlparse(b'https://example.com/a').decode()
Returns
ParseResult(scheme='https', netloc='example.com', path='/a', params='', query='', fragment='')
4. encode() → ParseResultBytes
from urllib.parse import urlparse urlparse('https://example.com/a').encode()
Returns
ParseResultBytes(scheme=b'https', netloc=b'example.com', path=b'/a', params=b'', query=b'', fragment=b'')
5. SplitResultBytes.geturl
from urllib.parse import urlsplit urlsplit(b'https://example.com/a#f').geturl()
Returns
b'https://example.com/a#f'
6. ParseResultBytes.geturl
from urllib.parse import urlparse urlparse(b'https://example.com/a;p').geturl()
Returns
b'https://example.com/a;p'
7. DefragResultBytes.geturl
from urllib.parse import urldefrag urldefrag(b'https://example.com/a#f').geturl()
Returns
b'https://example.com/a#f'

Pitfalls

1. Raw UTF-8 bytes in the URL
The bytes are decoded as ASCII before parsing. Percent-encode non-ASCII bytes first (quote_from_bytes), or parse the str.
raw é
from urllib.parse import urlsplit
urlsplit('https://example.com/café'.encode())
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 23: ordinal not in range(128)
percent-encoded
from urllib.parse import urlsplit, quote
urlsplit(quote('https://example.com/café', safe=':/').encode()).path
b'/caf%C3%A9'
2. Mixing str and bytes arguments
All arguments must be str, or all bytes. The default scheme must be bytes too.
scheme='http'
from urllib.parse import urlsplit
urlsplit(b'example.com/a', 'http')
TypeError: Cannot mix str and non-str arguments
scheme=b'http'
from urllib.parse import urlsplit
urlsplit(b'example.com/a', b'http').scheme
b'http'
3. encode() with non-ASCII fields
A str result's encode() defaults to ASCII; give it the encoding you want.
encode()
from urllib.parse import urlparse
urlparse('https://example.com/café').encode()
UnicodeEncodeError: 'ascii' codec can't encode character '\xe9' in position 4: ordinal not in range(128)
encode('utf-8')
from urllib.parse import urlparse
urlparse('https://example.com/café').encode('utf-8').path
b'/caf\xc3\xa9'

When to use

Use it
  • URLs that arrive as bytes (sockets, binary logs) and are pure ASCII
  • Keeping a bytes pipeline bytes end to end
Reach for something else
  • Text URLs → the str functions and ParseResult / SplitResult
  • Non-ASCII bytes → percent-encode them, or decode to str first

Notes

CPython impl
_coerce_args decodes every bytes argument with 'ascii' strict, the str parser runs, and the result's encode() (ascii strict) produces the *Bytes class
Classes
ParseResultBytes, SplitResultBytes and DefragResultBytes subclass the same namedtuples as their str twins; the netloc helpers (hostname, port, username, password) work on bytes
Since
Python 3.2 — bytes input to the URL parsing functions and these classes were added together

FAQ

Yes, since Python 3.2: urlparse(b'https://example.com/') returns a ParseResultBytes with bytes fields. The bytes must be ASCII — non-ASCII bytes raise UnicodeDecodeError.