yarl DocumentationRelease 1.6.3-

Andrew Svetlov

Nov 16, 2020

CONTENTS

1 Introduction 3

2 Installation 5

3 Dependencies 7

4 API documentation 9

5 Comparison with other URL libraries 11

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

7 Source code 15

8 Discussion list 17

9 Authors and License 199.1 Public API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

10 Indices and tables 31

Python Module Index 33

Index 35

i

ii

yarl Documentation, Release 1.6.3-

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

CONTENTS 1

yarl Documentation, Release 1.6.3-

2 CONTENTS

CHAPTER

ONE

INTRODUCTION

URL is constructed from str:

>>> from yarl import URL>>> 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 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 asresult:

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

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

3

yarl Documentation, Release 1.6.3-

>>> 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 Public API section.

4 Chapter 1. Introduction

CHAPTER

TWO

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 withour wheels) the the tarball will be used to compile the library from the source code. It requires a C compiler and andPython headers installed.

To skip the compilation you must explicitly opt-in by setting the YARL_NO_EXTENSIONS environment variable to anon-empty value, e.g.:

$ YARL_NO_EXTENSIONS=1 pip install yarl

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

5

yarl Documentation, Release 1.6.3-

6 Chapter 2. Installation

CHAPTER

THREE

DEPENDENCIES

YARL requires multidict library.

It installs it automatically.

7

yarl Documentation, Release 1.6.3-

8 Chapter 3. Dependencies

CHAPTER

FOUR

API DOCUMENTATION

Open Public API for reading full list of available methods.

9

yarl Documentation, Release 1.6.3-

10 Chapter 4. API documentation

CHAPTER

FIVE

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

11

yarl Documentation, Release 1.6.3-

12 Chapter 5. Comparison with other URL libraries

CHAPTER

SIX

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; auser should convert bools into strings using own preferred translation protocol.

13

yarl Documentation, Release 1.6.3-

14 Chapter 6. Why isn’t boolean supported by the URL query API?

CHAPTER

SEVEN

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.

15

yarl Documentation, Release 1.6.3-

16 Chapter 7. Source code

CHAPTER

EIGHT

DISCUSSION LIST

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

Feel free to post your questions and ideas here.

17

yarl Documentation, Release 1.6.3-

18 Chapter 8. Discussion list

CHAPTER

NINE

AUTHORS AND LICENSE

The yarl package is written by Andrew Svetlov.

It’s Apache 2 licensed and freely available.

Contents:

9.1 Public API

The only public yarl class is URL:

>>> from yarl import URL

class yarl.URL(arg, *, encoded=False)

Represents URL as

[scheme:]//[user[:password]@]host[:port][/path][?query][#fragment]

for absolute URLs and

[/path][?query][#fragment]

for relative ones (Absolute and relative URLs).

The URL structure is:

http://user:pass@example.com:8042/over/there?name=ferret#nose\__/ \__/ \__/ \_________/ \__/\_________/ \_________/ \__/| | | | | | | |

scheme user password host port path query fragment

Internally all data are stored as percent-encoded strings for user, path, query and fragment URL parts and IDNA-encoded (RFC 5891) for host.

Constructor and modification operators perform encoding for all parts automatically. The library assumes all data usesUTF-8 for percent-encoded tokens.

>>> URL('http://example.com/path/to/?arg1=a&arg2=b#fragment')URL('http://example.com/path/to/?arg1=a&arg2=b#fragment')

Unless URL contain the only ascii characters there is no differences.

But for non-ascii case encoding is applied.

19

yarl Documentation, Release 1.6.3-

>>> str(URL('http://.eu//'))'http://xn--jxagkqfkduily1i.eu/%D0%BF%D1%83%D1%82%D1%8C/%E9%80%99%E8%A3%A1'

The same is true for user, password, query and fragment parts of URL.

Already encoded URL is not changed:

>>> URL('http://xn--jxagkqfkduily1i.eu')URL('http://xn--jxagkqfkduily1i.eu')

Use URL.human_repr() for getting human readable representation:

>>> url = URL('http://.eu//')>>> str(url)'http://xn--jxagkqfkduily1i.eu/%D0%BF%D1%83%D1%82%D1%8C/%E9%80%99%E8%A3%A1'>>> url.human_repr()'http://.eu//'

Note: Sometimes encoding performed by yarl is not acceptable for certain WEB server.

Passing encoded=True parameter prevents URL auto-encoding, user is responsible about URL correctness.

Don’t use this option unless there is no other way for keeping URL attributes not touched.

Any URL manipulations don’t guarantee correct encoding, URL parts could be re-quoted even if encoded parameterwas explicitly set.

9.1.1 URL properties

There are two kinds of properties: decoded and encoded (with raw_ prefix):

URL.schemeScheme for absolute URLs, empty string for relative URLs or URLs starting with ‘//’ (Absolute and relativeURLs).

>>> URL('http://example.com').scheme'http'>>> URL('//example.com').scheme''>>> URL('page.html').scheme''

URL.userDecoded user part of URL, None if user is missing.

>>> URL('http://john@example.com').user'john'>>> URL('http://@example.com').user''>>> URL('http://example.com').user is NoneTrue

URL.raw_userEncoded user part of URL, None if user is missing.

20 Chapter 9. Authors and License

yarl Documentation, Release 1.6.3-

>>> URL('http://@example.com').raw_user'%D0%B0%D0%BD%D0%B4%D1%80%D0%B5%D0%B9'>>> URL('http://example.com').raw_user is NoneTrue

URL.passwordDecoded password part of URL, None if user is missing.

>>> URL('http://john:pass@example.com').password'pass'>>> URL('http://:@example.com').password''>>> URL('http://example.com').password is NoneTrue

URL.raw_passwordEncoded password part of URL, None if user is missing.

>>> URL('http://user:@example.com').raw_password'%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C'

URL.hostEncoded host part of URL, None for relative URLs (Absolute and relative URLs).

Brackets are stripped for IPv6. Host is converted to lowercase, address is validated and converted to compressedform.

>>> URL('http://example.com').host'example.com'>>> URL('http://.').host'.'>>> URL('page.html').host is NoneTrue>>> URL('http://[::1]').host'::1'

URL.raw_hostIDNA decoded host part of URL, None for relative URLs (Absolute and relative URLs).

>>> URL('http://.').raw_host'xn--n1agdj.xn--d1acufc'

URL.portport part of URL, with scheme-based fallback.

None for relative URLs (Absolute and relative URLs) or for URLs without explicit port and URL.schemewithout default port substitution.

>>> URL('http://example.com:8080').port8080>>> URL('http://example.com').port80>>> URL('page.html').port is NoneTrue

URL.explicit_portexplicit_port part of URL, without scheme-based fallback.

9.1. Public API 21

yarl Documentation, Release 1.6.3-

None for relative URLs (Absolute and relative URLs) or for URLs without explicit port.

>>> URL('http://example.com:8080').explicit_port8080>>> URL('http://example.com').explicit_port is NoneTrue>>> URL('page.html').explicit_port is NoneTrue

New in version 1.3.

URL.authorityDecoded authority part of URL, a combination of user, password, host, and port.

authority = [ user [ ":" password ] "@" ] host [ ":" port ].

authority is empty string if all parts are missing.

>>> URL('http://john:pass@example.com:8000').authority'john:pass@example.com:8000'

New in version 1.5.

URL.raw_authorityEncoded authority part of URL, a combination of user, password, host, and port. empty string if all parts aremissing.

>>> URL('http://john:pass@.:8000').raw_authority'john:pass@xn--n1agdj.xn--d1acufc:8000'

New in version 1.5.

URL.pathDecoded path part of URL, '/' for absolute URLs without path part.

>>> URL('http://example.com/path/to').path'/path/to'>>> URL('http://example.com//').path'//'>>> URL('http://example.com').path'/'

URL.path_qsDecoded path part of URL and query string, '/' for absolute URLs without path part.

>>> URL('http://example.com/path/to?a1=a&a2=b').path_qs'/path/to?a1=a&a2=b'

URL.raw_path_qsEncoded path part of URL and query string, '/' for absolute URLs without path part.

>>> URL('http://example.com//?=').raw_path_qs'/%D0%BF%D1%83%D1%82%D1%8C/%D1%81%D1%8E%D0%B4%D0%B0?%D0%BA%D0%BB%D1%8E%D1%87=%D0→˓%B7%D0%BD%D0%B0%D1%87'

New in version 0.15.

URL.raw_pathEncoded path part of URL, '/' for absolute URLs without path part.

22 Chapter 9. Authors and License

yarl Documentation, Release 1.6.3-

>>> URL('http://example.com//').raw_path'/%D0%BF%D1%83%D1%82%D1%8C/%D1%81%D1%8E%D0%B4%D0%B0'

URL.query_stringDecoded query part of URL, empty string if query is missing.

>>> URL('http://example.com/path?a1=a&a2=b').query_string'a1=a&a2=b'>>> URL('http://example.com/path?=').query_string'='>>> URL('http://example.com/path').query_string''

URL.raw_query_stringEncoded query part of URL, empty string if query is missing.

>>> URL('http://example.com/path?=').raw_query_string'%D0%BA%D0%BB%D1%8E%D1%87=%D0%B7%D0%BD%D0%B0%D1%87'

URL.fragmentEncoded fragment part of URL, empty string if fragment is missing.

>>> URL('http://example.com/path#fragment').fragment'fragment'>>> URL('http://example.com/path#').fragment''>>> URL('http://example.com/path').fragment''

URL.raw_fragmentDecoded fragment part of URL, empty string if fragment is missing.

>>> URL('http://example.com/path#').raw_fragment'%D1%8F%D0%BA%D0%BE%D1%80%D1%8C'

For path and query yarl supports additional helpers:

URL.partsA tuple containing decoded path parts, ('/',) for absolute URLs if path is missing.

>>> URL('http://example.com/path/to').parts('/', 'path', 'to')>>> URL('http://example.com//').parts('/', '', '')>>> URL('http://example.com').parts('/',)

URL.raw_partsA tuple containing encoded path parts, ('/',) for absolute URLs if path is missing.

>>> URL('http://example.com//').raw_parts('/', '%D0%BF%D1%83%D1%82%D1%8C', '%D1%81%D1%8E%D0%B4%D0%B0')

URL.nameThe last part of parts.

9.1. Public API 23

yarl Documentation, Release 1.6.3-

>>> URL('http://example.com/path/to').name'to'>>> URL('http://example.com//').name''>>> URL('http://example.com/path/').name''

URL.raw_nameThe last part of raw_parts.

>>> URL('http://example.com//').raw_name'%D1%81%D1%8E%D0%B4%D0%B0'

URL.queryA multidict.MultiDictProxy representing parsed query parameters in decoded representation. Emptyvalue if URL has no query part.

>>> URL('http://example.com/path?a1=a&a2=b').query<MultiDictProxy('a1': 'a', 'a2': 'b')>>>> URL('http://example.com/path?=').query<MultiDictProxy('': '')>>>> URL('http://example.com/path').query<MultiDictProxy()>

9.1.2 Absolute and relative URLs

The module supports both absolute and relative URLs.

Absolute URL should start from either scheme or '//'.

URL.is_absolute()

A check for absolute URLs.

Return True for absolute ones (having scheme or starting with //), False otherwise.

>>> URL('http://example.com').is_absolute()True>>> URL('//example.com').is_absolute()True>>> URL('/path/to').is_absolute()False>>> URL('path').is_absolute()False

9.1.3 New URL generation

URL is an immutable object, every operation described in the section generates a new URL instance.

URL.build(*, scheme=..., authority=..., user=..., password=..., host=..., port=..., path=..., query=..,query_string=..., fragment=..., encoded=False)

Creates and returns a new URL:

>>> URL.build(scheme="http", host="example.com")URL('http://example.com')

(continues on next page)

24 Chapter 9. Authors and License

yarl Documentation, Release 1.6.3-

(continued from previous page)

>>> URL.build(scheme="http", host="example.com", query={"a": "b"})URL('http://example.com/?a=b')

>>> URL.build(scheme="http", host="example.com", query_string="a=b")URL('http://example.com/?a=b')

>>> URL.build()URL('')

Calling build method without arguments is equal to calling __init__ without arguments.

Note: Only one of query or query_string should be passed then ValueError will be raised.

URL.with_scheme(scheme)Return a new URL with scheme replaced:

>>> URL('http://example.com').with_scheme('https')URL('https://example.com')

URL.with_user(user)Return a new URL with user replaced, auto-encode user if needed.

Clear user/password if user is None.

>>> URL('http://user:pass@example.com').with_user('new_user')URL('http://new_user:pass@example.com')>>> URL('http://user:pass@example.com').with_user('')URL('http://%D0%B2%D0%B0%D1%81%D1%8F:pass@example.com')>>> URL('http://user:pass@example.com').with_user(None)URL('http://example.com')

URL.with_password(password)Return a new URL with password replaced, auto-encode password if needed.

Clear password if None is passed.

>>> URL('http://user:pass@example.com').with_password('')URL('http://user:%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C@example.com')>>> URL('http://user:pass@example.com').with_password(None)URL('http://user@example.com')

URL.with_host(host)Return a new URL with host replaced, auto-encode host if needed.

Changing host for relative URLs is not allowed, use URL.join() instead.

>>> URL('http://example.com/path/to').with_host('python.org')URL('http://python.org/path/to')>>> URL('http://example.com/path').with_host('.')URL('http://xn--n1agdj.xn--d1acufc/path')

URL.with_port(port)Return a new URL with port replaced.

Clear port to default if None is passed.

9.1. Public API 25

yarl Documentation, Release 1.6.3-

>>> URL('http://example.com:8888').with_port(9999)URL('http://example.com:9999')>>> URL('http://example.com:8888').with_port(None)URL('http://example.com')

URL.with_path(path)Return a new URL with path replaced, encode path if needed.

>>> URL('http://example.com/').with_path('/path/to')URL('http://example.com/path/to')

URL.with_query(query)URL.with_query(**kwargs)

Return a new URL with query part replaced.

Unlike update_query() the method replaces all query parameters.

Accepts any Mapping (e.g. dict, MultiDict instances) or str, auto-encode the argument if needed.

A sequence of (key, value) pairs is supported as well.

Also it can take an arbitrary number of keyword arguments.

Clear query if None is passed.

Note: The library accepts str, float, int and their subclasses except bool as query argument values.

If a mapping such as dict is used, the values may also be list or tuple to represent a key has many values.

Please see Why isn’t boolean supported by the URL query API? for the reason why bool is not supportedout-of-the-box.

>>> URL('http://example.com/path?a=b').with_query('c=d')URL('http://example.com/path?c=d')>>> URL('http://example.com/path?a=b').with_query({'c': 'd'})URL('http://example.com/path?c=d')>>> URL('http://example.com/path?a=b').with_query({'c': [1, 2]})URL('http://example.com/path?c=1&c=2')>>> URL('http://example.com/path?a=b').with_query({'': ''})URL('http://example.com/path?%D0%BA%D0%BB=%D0%B7%D0%BD')>>> URL('http://example.com/path?a=b').with_query(None)URL('http://example.com/path')>>> URL('http://example.com/path?a=b&b=1').with_query(b='2')URL('http://example.com/path?b=2')>>> URL('http://example.com/path?a=b&b=1').with_query([('b', '2')])URL('http://example.com/path?b=2')

Changed in version 1.5: Support list and tuple as a query parameter value.

Changed in version 1.6: Support subclasses of int (except bool) and float as a query parameter value.

URL.update_query(query)URL.update_query(**kwargs)

Returns a new URL with query part updated.

Unlike with_query() the method does not replace query completely.

Returned URL object will contain query string which updated parts from passed query parts (or parts of parsedquery string).

26 Chapter 9. Authors and License

yarl Documentation, Release 1.6.3-

Accepts any Mapping (e.g. dict, MultiDict instances) or str, auto-encode the argument if needed.

A sequence of (key, value) pairs is supported as well.

Also it can take an arbitrary number of keyword arguments.

Clear query if None is passed.

Mod operator (%) can be used as alternative to the direct call of URL.update_query().

Note: The library accepts str, float, int and their subclasses except bool as query argument values.

If a mapping such as dict is used, the values may also be list or tuple to represent a key has many values.

Please see Why isn’t boolean supported by the URL query API? for the reason why bool is not supportedout-of-the-box.

>>> URL('http://example.com/path?a=b').update_query('c=d')URL('http://example.com/path?a=b&c=d')>>> URL('http://example.com/path?a=b').update_query({'c': 'd'})URL('http://example.com/path?a=b&c=d')>>> URL('http://example.com/path?a=b').update_query({'c': [1, 2]})URL('http://example.com/path?a=b&c=1&c=2')>>> URL('http://example.com/path?a=b').update_query({'': ''})URL('http://example.com/path?a=b&%D0%BA%D0%BB=%D0%B7%D0%BD')>>> URL('http://example.com/path?a=b&b=1').update_query(b='2')URL('http://example.com/path?a=b&b=2')>>> URL('http://example.com/path?a=b&b=1').update_query([('b', '2')])URL('http://example.com/path?a=b&b=2')>>> URL('http://example.com/path?a=b&c=e&c=f').update_query(c='d')URL('http://example.com/path?a=b&c=d')>>> URL('http://example.com/path?a=b').update_query('c=d&c=f')URL('http://example.com/path?a=b&c=d&c=f')>>> URL('http://example.com/path?a=b') % {'c': 'd'}URL('http://example.com/path?a=b&c=d')

Changed in version 1.0: All multiple key/value pairs are applied to the multi-dictionary.

New in version 1.5: Support for mod operator (%) to update the URL’s query part.

Changed in version 1.5: Support list and tuple as a query parameter value.

Changed in version 1.6: Support subclasses of int (except bool) and float as a query parameter value.

URL.with_fragment(fragment)Return a new URL with fragment replaced, auto-encode fragment if needed.

Clear fragment to default if None is passed.

>>> URL('http://example.com/path#frag').with_fragment('anchor')URL('http://example.com/path#anchor')>>> URL('http://example.com/path#frag').with_fragment('')URL('http://example.com/path#%D1%8F%D0%BA%D0%BE%D1%80%D1%8C')>>> URL('http://example.com/path#frag').with_fragment(None)URL('http://example.com/path')

URL.with_name(name)Return a new URL with name (last part of path) replaced and cleaned up query and fragment parts.

Name is encoded if needed.

9.1. Public API 27

yarl Documentation, Release 1.6.3-

>>> URL('http://example.com/path/to?arg#frag').with_name('new')URL('http://example.com/path/new')>>> URL('http://example.com/path/to').with_name('')URL('http://example.com/path/%D0%B8%D0%BC%D1%8F')

URL.parentA new URL with last part of path removed and cleaned up query and fragment parts.

>>> URL('http://example.com/path/to?arg#frag').parentURL('http://example.com/path')

URL.origin()A new URL with scheme, host and port parts only. user, password, path, query and fragment are removed.

>>> URL('http://example.com/path/to?arg#frag').origin()URL('http://example.com')>>> URL('http://user:pass@example.com/path').origin()URL('http://example.com')

URL.relative()A new relative URL with path, query and fragment parts only. scheme, user, password, host and port areremoved.

>>> URL('http://example.com/path/to?arg#frag').relative()URL('/path/to?arg#frag')

Division (/) operator creates a new URL with appended path parts and cleaned up query and fragment parts.

The path is encoded if needed.

>>> url = URL('http://example.com/path?arg#frag') / 'to/subpath'>>> urlURL('http://example.com/path/to/subpath')>>> url.parts('/', 'path', 'to', 'subpath')>>> url = URL('http://example.com/path?arg#frag') / ''>>> urlURL('http://example.com/path/%D1%81%D1%8E%D0%B4%D0%B0')

URL.join(url)Construct a full (“absolute”) URL by combining a “base URL” (self) with another URL (url). Informally,this uses components of the base URL, in particular the addressing scheme, the network location and (part of)the path, to provide missing components in the relative URL, e.g.:

>>> base = URL('http://example.com/path/index.html')>>> base.join(URL('page.html'))URL('http://example.com/path/page.html')

Note: If url is an absolute URL (that is, starting with // or scheme://), the URL‘s host name and/orscheme will be present in the result, e.g.:

>>> base = URL('http://example.com/path/index.html')>>> base.join(URL('//python.org/page.html'))URL('http://python.org/page.html')

28 Chapter 9. Authors and License

yarl Documentation, Release 1.6.3-

9.1.4 Human readable representation

All URL data is stored in encoded form internally. It’s pretty good for passing str(url) everywhere URL string isaccepted but quite bad for memorizing by humans.

yarl.human_repr()Return decoded human readable string for URL representation.

>>> url = URL('http://.eu/')>>> str(url)'http://xn--jxagkqfkduily1i.eu/%E9%80%99%E8%A3%A1'>>> url.human_repr()'http://.eu/'

9.1.5 Default port substitution

yarl is aware about the following scheme -> port translations:

scheme port'http' 80'https' 443'ws' 80'wss' 443

URL.is_default_port()

A check for default port.

Return True if URL’s port is default for used scheme, False otherwise.

Relative URLs have no default port.

>>> URL('http://example.com').is_default_port()True>>> URL('http://example.com:80').is_default_port()True>>> URL('http://example.com:8080').is_default_port()False>>> URL('/path/to').is_default_port()False

9.1.6 Cache control

IDNA conversion used for host encoding is quite expensive operation, that’s why the yarl library caches IDNAencoding/decoding calls by storing last 256 encodes and last 256 decodes in the global LRU cache.

yarl.cache_clear()Clear IDNA caches.

yarl.cache_info()Return a dictionary with "idna_encode" and "idna_decode" keys, each value points to correspondingCacheInfo structure (see functools.lru_cache() for details):

9.1. Public API 29

yarl Documentation, Release 1.6.3-

>>> yarl.cache_info(){'idna_encode': CacheInfo(hits=5, misses=5, maxsize=256, currsize=5),'idna_decode': CacheInfo(hits=24, misses=15, maxsize=256, currsize=15)}

yarl.cache_configure(*, idna_encode_size=256, idna_decode_size=256)Set IDNA encode and decode cache sizes (256 for each by default).

Pass None to make the corresponding cache unbounded (may speed up the IDNA encoding/decoding operationa little but the memory footprint can be very high, please use with caution).

9.1.7 References

yarl stays on shoulders of giants: several RFC documents and low-level urllib.parse which performs almostall gory work.

The module borrowed design from pathlib in any place where it was possible.

See also:

RFC 5891 - Internationalized Domain Names in Applications (IDNA): Protocol Document describing non-ASCII domain name encoding.

RFC 3987 - Internationalized Resource Identifiers This specifies conversion rules for non-ASCII characters inURL.

RFC 3986 - Uniform Resource Identifiers This is the current standard (STD66). Any changes to yarl moduleshould conform to this. Certain deviations could be observed, which are mostly for backward compatibilitypurposes and for certain de-facto parsing requirements as commonly observed in major browsers.

RFC 2732 - Format for Literal IPv6 Addresses in URL’s. This specifies the parsing requirements of IPv6 URLs.

RFC 2396 - Uniform Resource Identifiers (URI): Generic Syntax Document describing the generic syntactic re-quirements for both Uniform Resource Names (URNs) and Uniform Resource Locators (URLs).

RFC 2368 - The mailto URL scheme. Parsing requirements for mailto URL schemes.

RFC 1808 - Relative Uniform Resource Locators This Request For Comments includes the rules for joining anabsolute and a relative URL, including a fair number of “Abnormal Examples” which govern the treatment ofborder cases.

RFC 1738 - Uniform Resource Locators (URL) This specifies the formal syntax and semantics of absolute URLs.

30 Chapter 9. Authors and License

CHAPTER

TEN

INDICES AND TABLES

• genindex

• modindex

• search

31

yarl Documentation, Release 1.6.3-

32 Chapter 10. Indices and tables

PYTHON MODULE INDEX

yyarl, 19

33

yarl Documentation, Release 1.6.3-

34 Python Module Index

INDEX

Aauthority (yarl.URL attribute), 22

Bbuild() (yarl.URL method), 24

Ccache_clear() (in module yarl), 29cache_configure() (in module yarl), 30cache_info() (in module yarl), 29

Eexplicit_port (yarl.URL attribute), 21

Ffragment (yarl.URL attribute), 23

Hhost (yarl.URL attribute), 21human_repr() (in module yarl), 29

Iis_absolute() (yarl.URL method), 24is_default_port() (yarl.URL method), 29

Jjoin() (yarl.URL method), 28

Mmodule

yarl, 19

Nname (yarl.URL attribute), 23

Oorigin() (yarl.URL method), 28

Pparent (yarl.URL attribute), 28

parts (yarl.URL attribute), 23password (yarl.URL attribute), 21path (yarl.URL attribute), 22path_qs (yarl.URL attribute), 22port (yarl.URL attribute), 21

Qquery (yarl.URL attribute), 24query_string (yarl.URL attribute), 23

Rraw_authority (yarl.URL attribute), 22raw_fragment (yarl.URL attribute), 23raw_host (yarl.URL attribute), 21raw_name (yarl.URL attribute), 24raw_parts (yarl.URL attribute), 23raw_password (yarl.URL attribute), 21raw_path (yarl.URL attribute), 22raw_path_qs (yarl.URL attribute), 22raw_query_string (yarl.URL attribute), 23raw_user (yarl.URL attribute), 20relative() (yarl.URL method), 28RFC

RFC 1738, 30RFC 1808, 30RFC 2368, 30RFC 2396, 30RFC 2732, 30RFC 3986, 30RFC 3987, 30RFC 5891, 30

RFCRFC 5891, 19

Sscheme (yarl.URL attribute), 20

Uupdate_query() (yarl.URL method), 26URL (class in yarl), 19user (yarl.URL attribute), 20

35

yarl Documentation, Release 1.6.3-

Wwith_fragment() (yarl.URL method), 27with_host() (yarl.URL method), 25with_name() (yarl.URL method), 27with_password() (yarl.URL method), 25with_path() (yarl.URL method), 26with_port() (yarl.URL method), 25with_query() (yarl.URL method), 26with_scheme() (yarl.URL method), 25with_user() (yarl.URL method), 25

Yyarl

module, 19

36 Index