Introduction

Url is constructed from str:

>>> from yarl import URL
>>> url = URL('https://www.python.org/~guido?arg=1#frag')
>>> url
URL('https://www.python.org/~guido?arg=1#frag')

All url parts: scheme, user, password, host, port, path, query and fragment are accessible by properties:

>>> url.scheme
'https'
>>> url.host
'www.python.org'
>>> url.path
'/~guido'
>>> url.query_string
'arg=1'
>>> url.query
<MultiDictProxy('arg': '1')>
>>> url.fragment
'frag'

All url manipulations produce a new url object:

>>> url = URL('https://www.python.org')
>>> url / 'foo' / 'bar'
URL('https://www.python.org/foo/bar')
>>> url / 'foo' % {'bar': 'baz'}
URL('https://www.python.org/foo?bar=baz')

Strings passed to constructor and modification methods are automatically encoded giving canonical representation as result:

>>> url = URL('https://www.python.org/путь')
>>> url
URL('https://www.python.org/%D0%BF%D1%83%D1%82%D1%8C')

Regular properties are percent-decoded, use raw_ versions for getting encoded strings:

>>> url.path
'/путь'

>>> url.raw_path
'/%D0%BF%D1%83%D1%82%D1%8C'

Human readable representation of URL is available as .human_repr():

>>> url.human_repr()
'https://www.python.org/путь'

For full documentation please read https://yarl.aio-libs.org.

Installation

$ pip install yarl

The library is Python 3 only!

PyPI contains binary wheels for Linux, Windows and MacOS. If you want to install yarl on another operating system (like Alpine Linux, which is not manylinux-compliant because of the missing glibc and therefore, cannot be used with our wheels) the the tarball will be used to compile the library from the source code. It requires a C compiler and and Python headers installed.

To skip the compilation you must explicitly opt-in by using a PEP 517 configuration setting --pure-python, or setting the YARL_NO_EXTENSIONS environment variable to a non-empty value, e.g.:

$ pip install yarl --config-settings=--pure-python=

Please note that the pure-Python (uncompiled) version is much slower. However, PyPy always uses a pure-Python implementation, and, as such, it is unaffected by this variable.

Dependencies

YARL requires multidict library.

API documentation

The documentation is located at https://yarl.aio-libs.org.

Why isn’t boolean supported by the URL query API?

There is no standard for boolean representation of boolean values.

Some systems prefer true/false, others like yes/no, on/off, Y/N, 1/0, etc.

yarl cannot make an unambiguous decision on how to serialize bool values because it is specific to how the end-user’s application is built and would be different for different apps. The library doesn’t accept booleans in the API; a user should convert bools into strings using own preferred translation protocol.

Comparison with other URL libraries

• furl (https://pypi.python.org/pypi/furl)

  The library has rich functionality but the furl object is mutable.

  I’m afraid to pass this object into foreign code: who knows if the code will modify my url in a terrible way while I just want to send URL with handy helpers for accessing URL properties.

  furl has other non-obvious tricky things but the main objection is mutability.

• URLObject (https://pypi.python.org/pypi/URLObject)

  URLObject is immutable, that’s pretty good.

  Every URL change generates a new URL object.

  But the library doesn’t do any decode/encode transformations leaving the end user to cope with these gory details.

Source code

The project is hosted on GitHub

Please file an issue on the bug tracker if you have found a bug or have some suggestion in order to improve the library.

The library uses Azure Pipelines for Continuous Integration.

Discussion list

aio-libs google group: https://groups.google.com/forum/#!forum/aio-libs

Feel free to post your questions and ideas here.

Authors and License

The yarl package is written by Andrew Svetlov.

It’s Apache 2 licensed and freely available.

Bug fixes

• Stopped dropping trailing slashes in yarl.URL.joinpath() – by @mjpieters. (#862, #866)

• Started accepting string subclasses in __truediv__() operations (URL / segment) – by @mjpieters. (#871, #884)

• Fixed the human representation of URLs with square brackets in usernames and passwords – by @mjpieters. (#876, #882)

• Updated type hints to include URL.missing_port(), URL.__bytes__() and the encoding argument to yarl.URL.joinpath() – by @mjpieters. (#891)

Packaging updates and notes for downstreams

• Integrated Cython 3 to enable building yarl under Python 3.12 – by @mjpieters. (#829, #881)

• Declared modern setuptools.build_meta as the 517 build backend in pyproject.toml explicitly – by @webknjaz. (#886)

• Converted most of the packaging setup into a declarative setup.cfg config – by @webknjaz. (#890)

• Replaced the packaging is replaced from an old-fashioned setup.py to an in-tree 517 build backend – by @webknjaz.

  Whenever the end-users or downstream packagers need to build yarl from source (a Git checkout or an sdist), they may pass a config_settings flag --pure-python. If this flag is not set, a C-extension will be built and included into the distribution.

  Here is how this can be done with pip:

  $ python -m pip install . --config-settings=--pure-python=

  This will also work with -e | --editable.

  The same can be achieved via pypa/build:

  $ python -m build --config-setting=--pure-python=

  Adding -w | --wheel can force pypa/build produce a wheel from source directly, as opposed to building an sdist and then building from it. (#893)

• Declared Python 3.12 supported officially in the distribution package metadata – by @edgarrmondragon. (#942)

Contributor-facing changes

• A regression test for no-host URLs was added per #821 and 3986 – by @kenballus. (#821, #822)

• Started testing yarl against Python 3.12 in CI – by @mjpieters. (#881)

• All Python 3.12 jobs are now marked as required to pass in CI – by @edgarrmondragon. (#942)

• MyST is now integrated in Sphinx – by @webknjaz.

  This allows the contributors to author new documents in Markdown when they have difficulties with going straight RST. (#953)

Bugfixes

• Fix regression with __truediv__ and absolute URLs with empty paths causing the raw path to lack the leading /. (#854)

Bugfixes

• Marked tests that fail on older Python patch releases (< 3.7.10, < 3.8.8 and < 3.9.2) as expected to fail due to missing a security fix for CVE-2021-23336. (#850)

Features

• Added URL.joinpath(*elements), to create a new URL appending multiple path elements. (#704)

• Made URL.__truediv__() return NotImplemented if called with an unsupported type — by @michaeljpeters. (#832)

Bugfixes

• Path normalization for absolute URLs no longer raises a ValueError exception when .. segments would otherwise go beyond the URL path root. (#536)

• Fixed an issue with update_query() not getting rid of the query when argument is None. (#792)

• Added some input restrictions on with_port() function to prevent invalid boolean inputs or out of valid port inputs; handled incorrect 0 port representation. (#793)

• Made yarl.URL.build() raise a TypeError if the host argument is None — by @paulpapacz. (#808)

• Fixed an issue with update_query() getting rid of the query when the argument is empty but not None. (#845)

Misc

• #220

Misc

• #694, #699, #700, #701, #702, #703, #739

Features

• Added URL.raw_suffix, URL.suffix, URL.raw_suffixes, URL.suffixes, URL.with_suffix. (#613)

Improved Documentation

• Fixed broken internal references to yarl.URL.human_repr(). (#665)

• Fixed broken external references to multidict:index docs. (#665)

Deprecations and Removals

• Dropped Python 3.6 support. (#672)

Misc

• #646, #699, #701

Bugfixes

• Changed call in with_port() to stop reencoding parts of the URL that were already encoded. (#623)

Bugfixes

• Fix 1.7.0 build error

Features

• Add __bytes__() magic method so that bytes(url) will work and use optimal ASCII encoding. (#582)

• Started shipping platform-specific arm64 wheels for Apple Silicon. (#622)

• Started shipping platform-specific wheels with the musl tag targeting typical Alpine Linux runtimes. (#622)

• Added support for Python 3.10. (#622)

Bugfixes

• No longer loose characters when decoding incorrect percent-sequences (like %e2%82%f8). All non-decodable percent-sequences are now preserved. #517

• Provide x86 Windows wheels. #535

Bugfixes

• Provide generated .c files in TarBall distribution. #530

Features

• Provide wheels for aarch64, i686, ppc64le, s390x architectures on Linux as well as x86_64. #507

• Provide wheels for Python 3.9. #526

Bugfixes

• human_repr() now always produces valid representation equivalent to the original URL (if the original URL is valid). #511

• Fixed requoting a single percent followed by a percent-encoded character in the Cython implementation. #514

• Fix ValueError when decoding % which is not followed by two hexadecimal digits. #516

• Fix decoding % followed by a space and hexadecimal digit. #520

• Fix annotation of with_query()/update_query() methods for key=[val1, val2] case. #528

Removal

• Drop Python 3.5 support; Python 3.6 is the minimal supported Python version.

Features

• Allow for int and float subclasses in query, while still denying bool. #492

Bugfixes

• Do not requote arguments in URL.build(), with_xxx() and in / operator. #502

• Keep IPv6 brackets in origin(). #504

Bugfixes

• Fix including relocated internal yarl._quoting_c C-extension into published PyPI dists. #485

Misc

• #484

Features

• Convert host to lowercase on URL building. #386

• Allow using mod operator (%) for updating query string (an alias for update_query() method). #435

• Allow use of sequences such as list and tuple in the values of a mapping such as dict to represent that a key has many values:

  url = URL("http://example.com")
  assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2")

  #443

• Support URL.build() with scheme and path (creates a relative URL). #464

• Cache slow IDNA encode/decode calls. #476

• Add @final / Final type hints #477

• Support URL authority/raw_authority properties and authority argument of URL.build() method. #478

• Hide the library implementation details, make the exposed public list very clean. #483

Bugfixes

• Fix tests with newer Python (3.7.6, 3.8.1 and 3.9.0+). #409

• Fix a bug where query component, passed in a form of mapping or sequence, is unquoted in unexpected way. #426

• Hide Query and QueryVariable type aliases in __init__.pyi, now they are prefixed with underscore. #431

• Keep IPv6 brackets after updating port/user/password. #451

Features

• Workaround for missing str.isascii() in Python 3.6 #389