# yarl

The module provides handy `URL` class for URL parsing and changing.

## 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 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 are automatically encoded giving canonical representation as result:

    >>> 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:

    >>> url.path
    '/шлях'

    >>> url.raw_path
    '/%D1%88%D0%BB%D1%8F%D1%85'

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

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

For full documentation please read Public 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.:

    $ 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 the `multidict` and `propcache` libraries.

It installs it automatically.

## API documentation

Open Public 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.

## 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.

The `URL` could be used as a field type in pydantic models seamlessly:

    from pydantic import BaseModel
    from yarl import URL

    class Model(BaseModel):
        url: URL

## 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.

## 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:

- Public API
  - `URL`
  - URL properties
  - Absolute and relative URLs
  - New URL generation
  - Human readable representation
  - Default port substitution
  - Cache control
  - References

What's new

- Changelog
  - To be included in v1.23.0- (if present)
  - Released versions
  - 1.23.0
    - Features
    - Packaging updates and notes for downstreams
    - Contributor-facing changes
  - 1.22.0
    - Features
  - 1.21.0
    - Contributor-facing changes
  - 1.20.1
    - Bug fixes
    - Packaging updates and notes for downstreams
  - 1.20.0
    - Features
    - Packaging updates and notes for downstreams
  - 1.19.0
    - Bug fixes
    - Features
    - Contributor-facing changes
    - Miscellaneous internal changes
  - 1.18.3
    - Bug fixes
    - Miscellaneous internal changes
  - 1.18.2
  - 1.18.1
    - Miscellaneous internal changes
  - 1.18.0
    - Features
    - Contributor-facing changes
    - Miscellaneous internal changes
  - 1.17.2
    - Bug fixes
    - Features
    - Packaging updates and notes for downstreams
    - Miscellaneous internal changes
  - 1.17.1
    - Miscellaneous internal changes
  - 1.17.0
    - Features
  - 1.16.0
    - Bug fixes
    - Removals and backward incompatible breaking changes
    - Miscellaneous internal changes
  - 1.15.5
    - Miscellaneous internal changes
  - 1.15.4
    - Miscellaneous internal changes
  - 1.15.3
    - Bug fixes
    - Removals and backward incompatible breaking changes
    - Miscellaneous internal changes
  - 1.15.2
    - Miscellaneous internal changes
  - 1.15.1
    - Miscellaneous internal changes
  - 1.15.0
    - Bug fixes
    - Features
    - Miscellaneous internal changes
  - 1.14.0
    - Packaging updates and notes for downstreams
    - Contributor-facing changes
    - Miscellaneous internal changes
  - 1.13.1
    - Miscellaneous internal changes
  - 1.13.0
    - Bug fixes
    - Features
  - 1.12.1
  - 1.12.0
    - Features
    - Removals and backward incompatible breaking changes
    - Miscellaneous internal changes
  - 1.11.1
    - Bug fixes
    - Features
    - Miscellaneous internal changes
  - 1.11.0
    - Features
    - Miscellaneous internal changes
  - 1.10.0
    - Bug fixes
    - Features
    - Contributor-facing changes
    - Miscellaneous internal changes
  - 1.9.11
    - Bug fixes
    - Miscellaneous internal changes
  - 1.9.10
    - Bug fixes
    - Features
  - 1.9.9
    - Bug fixes
  - 1.9.8
    - Features
    - Contributor-facing changes
    - Miscellaneous internal changes
  - 1.9.7
    - Removals and backward incompatible breaking changes
    - Miscellaneous internal changes
  - 1.9.6
    - Bug fixes
  - 1.9.5
    - Bug fixes
    - Removals and backward incompatible breaking changes
    - Improved documentation
    - Packaging updates and notes for downstreams
    - Contributor-facing changes
    - Miscellaneous internal changes
  - 1.9.4 (2023-12-06)
    - Bug fixes
    - Packaging updates and notes for downstreams
    - Contributor-facing changes
  - 1.9.3 (2023-11-20)
    - Bug fixes
    - Packaging updates and notes for downstreams
    - Contributor-facing changes
  - 1.9.2 (2023-04-25)
    - Bugfixes
  - 1.9.1 (2023-04-21)
    - Bugfixes
  - 1.9.0 (2023-04-19)
    - Features
    - Bugfixes
    - Misc
  - 1.8.2 (2022-12-03)
  - 1.8.1 (2022-08-01)
    - Misc
  - 1.8.0 (2022-08-01)
    - Features
    - Improved Documentation
    - Deprecations and Removals
    - Misc
  - 1.7.2 (2021-11-01)
    - Bugfixes
  - 1.7.1 (2021-10-07)
    - Bugfixes
  - 1.7.0 (2021-10-06)
    - Features
  - 1.6.3 (2020-11-14)
    - Bugfixes
  - 1.6.2 (2020-10-12)
    - Bugfixes
  - 1.6.1 (2020-10-12)
    - Features
    - Bugfixes
    - Removal
  - 1.6.0 (2020-09-23)
    - Features
    - Bugfixes
  - 1.5.1 (2020-08-01)
    - Bugfixes
    - Misc
  - 1.5.0 (2020-07-26)
    - Features
    - Bugfixes
  - 1.4.2 (2019-12-05)
    - Features
  - 1.4.1 (2019-11-29)
  - 1.4.0 (2019-11-29)
  - 1.3.0 (2018-12-11)
  - 1.2.6 (2018-06-14)
  - 1.2.5 (2018-05-23)
  - 1.2.4 (2018-05-08)
  - 1.2.3 (2018-05-03)
  - 1.2.2 (2018-05-01)
  - 1.2.1 (2018-04-30)
  - 1.2.0 (2018-04-30)
  - 1.1.1 (2018-02-17)
  - 1.1.0 (2018-01-21)
  - 1.0.0 (2018-01-15)
  - 0.18.0 (2018-01-10)
  - 0.17.0 (2017-12-30)
  - 0.16.0 (2017-12-07)
  - 0.15.0 (2017-11-23)
  - 0.14.2 (2017-11-14)
  - 0.14.1 (2017-11-13)
  - 0.14.0 (2017-11-11)
  - 0.13.0 (2017-10-01)
  - 0.12.0 (2017-06-26)
  - 0.11.0 (2017-06-26)
  - 0.10.3 (2017-06-13)
  - 0.10.2 (2017-05-05)
  - 0.10.1 (2017-05-03)
  - 0.10.0 (2017-03-14)
  - 0.9.8 (2017-02-16)
  - 0.9.7 (2017-02-16)
  - 0.9.6 (2017-02-15)
  - 0.9.5 (2017-02-14)
  - 0.9.4 (2017-02-14)
  - 0.9.3 (2017-02-14)
  - 0.9.2 (2017-02-08)
  - 0.9.1 (2017-02-07)
  - 0.9.0 (2017-02-07)
  - 0.8.1 (2016-12-03)
  - 0.8.0 (2016-12-03)
  - 0.7.1 (2016-11-18)
  - 0.7.0 (2016-11-07)
  - 0.6.0 (2016-11-07)
  - 0.5.3 (2016-11-02)
  - 0.5.2 (2016-11-02)
  - 0.5.1 (2016-11-02)
  - 0.5.0 (2016-11-02)
  - 0.4.3 (2016-09-29)
  - 0.4.2 (2016-09-29)
  - 0.4.1 (2016-09-28)
  - 0.4.0 (2016-09-27)
  - 0.3.2 (2016-09-27)
  - 0.3.1 (2016-09-26)
  - 0.3.0 (2016-09-26)
  - 0.2.1 (2016-09-26)
  - 0.2.0 (2016-09-18)
  - 0.1.4 (2016-09-09)
  - 0.1.3 (2016-09-07)
  - 0.1.2 (2016-09-07)
  - 0.1.1 (2016-09-06)
  - 0.1.0 (2016-09-06)
  - 0.0.1 (2016-08-30)

Contributing

- Contributing docs
  - Adding change notes with your PRs
  - Alright! So how to add a news fragment?
  - Examples for adding changelog entries to your Pull Requests

Maintenance

- Release Guide
  - Pre-release activities
  - The release stage

# Indices and tables

- Index

- Module Index

- Search Page