.. yarl documentation master file, created by sphinx-quickstart on Mon Aug 29 19:55:36 2016. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. yarl ==== The module provides handy :class:`~yarl.URL` class for URL parsing and changing. Introduction ------------ URL is constructed from :class:`str`: .. doctest:: >>> 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: .. doctest:: >>> url.scheme 'https' >>> url.host 'www.python.org' >>> url.path '/~guido' >>> url.query_string 'arg=1' >>> url.query >>> url.fragment 'frag' All URL manipulations produces a new URL object: .. doctest:: >>> url.parent / 'downloads/source' URL('https://www.python.org/downloads/source') A URL object can be modified with ``/`` and ``%`` operators: .. doctest:: >>> 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: .. doctest:: >>> url = URL('https://www.python.org/шлях') >>> url URL('https://www.python.org/%D1%88%D0%BB%D1%8F%D1%85') Regular properties are *percent-decoded*, use ``raw_`` versions for getting *encoded* strings: .. doctest:: >>> url.path '/шлях' >>> url.raw_path '/%D1%88%D0%BB%D1%8F%D1%85' Human readable representation of URL is available as :meth:`~yarl.URL.human_repr`: .. doctest:: >>> url.human_repr() 'https://www.python.org/шлях' For full documentation please read :ref:`yarl-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 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.: .. code-block:: console $ pip install yarl --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 unaffected by this variable. Dependencies ------------ ``yarl`` requires :mod:`multidict` library. It installs it automatically. API documentation ------------------ Open :ref:`yarl-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 but ``furl`` object is mutable. I 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 any decode/encode transformations leaving end user to cope with these gory details. .. _yarl-bools-support: 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 :class:`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. 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. Contents: .. toctree:: :maxdepth: 2 api .. toctree:: :caption: What's new changes .. toctree:: :caption: Contributing contributing/guidelines .. toctree:: :caption: Maintenance contributing/release_guide Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` .. _GitHub: https://github.com/aio-libs/yarl