yarl¶

The module provides handyURL class for URL parsing andchanging.

Introduction¶

URL is constructed fromstr:

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

All URL parts:scheme,user,password,host,port,path,query andfragment 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 produces a new URL object:

>>>url.parent/'downloads/source'URL('https://www.python.org/downloads/source')

A URL object can be modified with/ and% operators:

>>>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 areautomatically encoded giving canonical representation as result:

>>>url=URL('https://www.python.org/шлях')>>>urlURL('https://www.python.org/%D1%88%D0%BB%D1%8F%D1%85')

Regular properties arepercent-decoded, useraw_ versions forgettingencoded strings:

>>>url.path'/шлях'>>>url.raw_path'/%D1%88%D0%BB%D1%8F%D1%85'

Human readable representation of URL is available ashuman_repr():

>>>url.human_repr()'https://www.python.org/шлях'

For full documentation please readPublic API section.

Installation¶

$ pip install yarl

The library is Python 3 only!

PyPI contains binary wheels for Linux, Windows and MacOS. If you want to installyarl on another operating system (likeAlpine Linux, which is notmanylinux-compliant because of the missing glibc and therefore, cannot beused with our wheels) the the tarball will be used to compile the library fromthe 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 517configuration settingpure-python, or setting theYARL_NO_EXTENSIONSenvironment variable to a non-empty value, e.g.:

$pipinstallyarl--config-settings=pure-python=false

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

Dependencies¶

yarl requires themultidict andpropcache libraries.

It installs it automatically.

API documentation¶

OpenPublic API for reading full list of available methods.

Comparison with other URL libraries¶

furl (https://pypi.python.org/pypi/furl)
The library has a rich functionality butfurl object is mutable.
I afraid to pass this object into foreign code: who knows if thecode will modify my URL in a terrible way while I just want to send URLwith handy helpers for accessing URL properties.
furl has other non obvious tricky things but the main objectionis 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 any decode/encode transformations leaving enduser to cope with these gory details.

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

There is no standard for boolean representation of boolean values.

Some systems prefertrue/false, others likeyes/no,on/off,Y/N,1/0, etc.

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