yarl 0.1.1

Yet another URL library

yarl
====

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*, *passsword*, *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 produces a new url object:

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

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/%D0%BF%D1%83%D1%82%D1%8C')

Regular properties are *percent-encoded*, use ``raw_`` versions for
getting *decoded* 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.readthedocs.org.


Installation
------------

::

$ pip install yarl

The library is Python 3 only!


Dependencies
------------

YARL requires multidict library.


API documentation
------------------

The documentation is located at https://yarl.readthedocs.org

Comparison with other URL libraries
------------------------------------

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

The libray has a rich functionality but ``furl`` object is mutable.

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

``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 transormations leaving end
user to cope with these gory details.


Source code
-----------

The project is hosted on GitHub_

Please file an issue on the `bug tracker
<https://github.com/aio-libs/yarl/issues>`_ if you have found a bug
or have some suggestion in order to improve the library.

The library uses `Travis <https://travis-ci.org/aio-libs/yarl>`_ 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.


.. _GitHub: https://github.com/aio-libs/multidict


CHANGES
=======

0.1.0 (2016-09-06)
------------------

* The library was deeply refactored, bytes are gone away but all
accepted strings are encoded if needed.

0.0.1 (2016-08-30)
------------------

* The first release.