yarl — Yet Another URL Library

Warnings

• breaking URL.build() and URL.with_host() raise TypeError when port is passed as a string. Previously a string port silently produced a malformed URL.
  Fix: Always pass port as int: URL.build(scheme='https', host='example.com', port=443)
• breaking propcache is now a required hard dependency (split out ~v1.17). Environments that vendor or vendor-pin transitive deps without propcache will fail to import yarl.
  Fix: Ensure propcache is present in all deployment targets. pip install yarl handles this automatically.
• deprecated cache_configure() parameters ip_address_size and host_validate_size are deprecated in favour of encode_host_size and will be removed in a future release.
  Fix: Replace cache_configure(ip_address_size=N, host_validate_size=N) with cache_configure(encode_host_size=N)
• gotcha URL properties (e.g. .path, .host, .query_string) return percent-DECODED values. Pass these to other URLs or HTTP wire formats and you risk double-encoding. Use the raw_ prefixed variants (.raw_path, .raw_host, .raw_query_string) for wire-safe strings.
  Fix: Use str(url) or url.raw_path / url.raw_query_string when constructing HTTP request lines.
• gotcha Passing boolean values to with_query() or URL.build(query=...) raises TypeError. yarl refuses to guess how to serialize True/False.
  Fix: Convert bools to strings before passing: {'flag': 'true'} not {'flag': True}
• gotcha encoded=True skips all auto-encoding but any subsequent mutation method (.with_query(), /, etc.) may re-quote parts, silently corrupting pre-encoded values. The docs explicitly warn against relying on this.
  Fix: Use encoded=True only as a last resort and avoid chaining mutation methods on encoded URLs. Prefer URL.build() or proper string inputs instead.
• gotcha The / operator (URL.__truediv__) and URL.joinpath() strip a trailing slash from the base path before appending the segment. URL('https://example.com/api/') / 'v1' gives /api/v1, not /api//v1. This matches pathlib semantics but surprises users expecting query-string-style appending.
  Fix: Use URL.joinpath(*parts) with explicit trailing slash control, or URL.with_path() for full path replacement.

Install

• pip install yarl Latest (with C extension)
• YARL_NO_EXTENSIONS=1 pip install yarl Pure-Python fallback (slower)

Imports

• URL

  from yarl import URL

  Always import URL directly from yarl; the top-level module is rarely used on its own.
• cache_configure

  from yarl import cache_configure
  cache_configure(encode_host_size=256)

  ip_address_size and host_validate_size are deprecated since ~1.17 in favour of encode_host_size and will be removed in a future release.

Quickstart

Parse, inspect, and mutate URLs; build from parts; path-join with /; apply query with %.

from yarl import URL

# Parse an existing URL
url = URL('https://user:pw@api.example.com:8080/v1/items?page=1&q=foo#section')
print(url.scheme)        # 'https'
print(url.host)          # 'api.example.com'  (decoded)
print(url.raw_host)      # IDNA-encoded form
print(url.port)          # 8080 (explicit); None falls back to scheme default
print(url.path)          # '/v1/items'  (percent-decoded)
print(url.raw_path)      # '/v1/items'  (percent-encoded, wire form)
print(url.query)         # MultiDictProxy with parsed key/value pairs
print(url.query_string)  # 'page=1&q=foo'
print(url.fragment)      # 'section'

# Build from components — port must be int, not str
base = URL.build(scheme='https', host='api.example.com', port=8080, path='/v1')
print(base)  # https://api.example.com:8080/v1

# Path-join (like pathlib)
endpoint = base / 'items' / '42'
print(endpoint)  # https://api.example.com:8080/v1/items/42

# Apply a query string with %
with_query = endpoint % {'expand': 'true', 'format': 'json'}
print(with_query)

# Mutation methods return new URL objects (immutable)
updated = endpoint.with_query({'page': '2'}).with_fragment('results')
print(str(updated))      # wire-safe string for HTTP clients
print(updated.human_repr())  # human-readable (non-ASCII decoded)

# Non-ASCII is encoded automatically
unicode_url = URL('https://example.com/пошук?q=кіт')
print(str(unicode_url))      # percent-encoded
print(unicode_url.human_repr())  # readable