Package: yarl
yarlThe module provides handy URL class for URL parsing and changing.IntroductionUrl 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,queryandfragmentare 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 produce a new url object:>>>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/шлях')>>>urlURL('https://www.python.org/%D1%88%D0%BB%D1%8F%D1%85')Regular properties arepercent-decoded, useraw_versions for
gettingencodedstrings:>>>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 readhttps://yarl.aio-libs.org.Installation$ pip install yarlThe library is Python 3 only!PyPI contains binary wheels for Linux, Windows and MacOS.  If you want to installyarlon another operating system (likeAlpine 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 settingpure-python, or setting theYARL_NO_EXTENSIONSenvironment variable to a non-empty value, e.g.:$pipinstallyarl--config-settings=pure-python=falsePlease 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.DependenciesYARL requiresmultidictlibrary.API documentationThe documentation is located athttps://yarl.aio-libs.org.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.yarlcannot make an unambiguous decision on how to serializeboolvalues 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.Comparison with other URL librariesfurl (https://pypi.python.org/pypi/furl)The library has rich functionality but thefurlobject is mutable.I’m 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.furlhas 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 do any decode/encode transformations leaving the
end user to cope with these gory details.Source codeThe project is hosted onGitHubPlease file an issue on thebug trackerif you have found a bug
or have some suggestion in order to improve the library.The library usesAzure Pipelinesfor
Continuous Integration.Discussion listaio-libsgoogle group:https://groups.google.com/forum/#!forum/aio-libsFeel free to post your questions and ideas here.Authors and LicenseTheyarlpackage is written by Andrew Svetlov.It’sApache 2licensed and freely available.1.9.4 (2023-12-06)Bug fixesStarted raisingTypeErrorwhen a string value is passed intoyarl.URL.build()as theportargument  – by@commonism.Previously the empty string as port would create malformed URLs when rendered as string representations. (#883)Packaging updates and notes for downstreamsThe leading--has been dropped from thePEP 517in-tree build
backend config setting names.--pure-pythonis now justpure-python– by@webknjaz.The usage now looks as follows:$python-mbuild\--config-setting=pure-python=true\--config-setting=with-cython-tracing=true(#963)Contributor-facing changesA step-by-stepRelease Guideguide has
been added, describing how to releaseyarl– by@webknjaz.This is primarily targeting maintainers. (#960)Coverage collection has been implemented for the Cython modules
– by@webknjaz.It will also be reported to Codecov from any non-release CI jobs.To measure coverage in a development environment,yarlcan be
installed in editable mode, which requires an environment variableYARL_CYTHON_TRACING=1to be set:$YARL_CYTHON_TRACING=1python-Impipinstall-e.Editable install produces C-files required for the Cython coverage
plugin to map the measurements back to the PYX-files. (#961)It is now possible to request line tracing in Cython builds using thewith-cython-tracingPEP 517config setting
–@webknjaz.This can be used in CI and development environment to measure coverage
on Cython modules, but is not normally useful to the end-users or
downstream packagers.Here’s a usage example:$python-Impipinstall.--config-settings=with-cython-tracing=trueFor editable installs, this setting is on by default. Otherwise, it’s
off unless requested explicitly. (#962)1.9.3 (2023-11-20)Bug fixesStopped dropping trailing slashes inyarl.URL.joinpath()– by@gmacon. (#862,#866)Started accepting string subclasses in__truediv__()operations (URL / segment) – by@mjpieters. (#871,#884)Fixed the human representation of URLs with square brackets in usernames and passwords – by@mjpieters. (#876,#882)Updated type hints to includeURL.missing_port(),URL.__bytes__()and theencodingargument toyarl.URL.joinpath()– by@mjpieters. (#891)Packaging updates and notes for downstreamsIntegrated Cython 3 to enable buildingyarlunder Python 3.12 – by@mjpieters. (#829,#881)Declared modernsetuptools.build_metaas thePEP 517build
backend inpyproject.tomlexplicitly – by@webknjaz. (#886)Converted most of the packaging setup into a declarativesetup.cfgconfig – by@webknjaz. (#890)The packaging is replaced from an old-fashionedsetup.pyto an
in-treePEP 517build backend – by@webknjaz.Whenever the end-users or downstream packagers need to buildyarlfrom
source (a Git checkout or an sdist), they may pass aconfig_settingsflag--pure-python. If this flag is not set, a C-extension will be built
and included into the distribution.Here is how this can be done withpip:$python-mpipinstall.--config-settings=--pure-python=falseThis will also work with-e|--editable.The same can be achieved viapypa/build:$python-mbuild--config-setting=--pure-python=falseAdding-w|--wheelcan forcepypa/buildproduce a wheel from source
directly, as opposed to building ansdistand then building from it. (#893)Attention!v1.9.3 was the only version using the--pure-pythonsetting name.
Later versions dropped the--prefix, making it justpure-python.Declared Python 3.12 supported officially in the distribution package metadata
– by@edgarrmondragon. (#942)Contributor-facing changesA regression test for no-host URLs was added per#821and3986– by@kenballus. (#821,#822)Started testingyarlagainst Python 3.12 in CI – by@mjpieters. (#881)All Python 3.12 jobs are now marked as required to pass in CI
– by@edgarrmondragon. (#942)MyST is now integrated in Sphinx – by@webknjaz.This allows the contributors to author new documents in Markdown
when they have difficulties with going straight RST. (#953)1.9.2 (2023-04-25)BugfixesFix regression with__truediv__and absolute URLs with empty paths causing the raw path to lack the leading/.
(#854)1.9.1 (2023-04-21)BugfixesMarked tests that fail on older Python patch releases (< 3.7.10, < 3.8.8 and < 3.9.2) as expected to fail due to missing a security fix for CVE-2021-23336. (#850)1.9.0 (2023-04-19)This release was never published to PyPI, due to issues with the build process.FeaturesAddedURL.joinpath(*elements), to create a new URL appending multiple path elements. (#704)MadeURL.__truediv__()returnNotImplementedif called with an
unsupported type — by@michaeljpeters.
(#832)BugfixesPath normalization for absolute URLs no longer raises a ValueError exception
when..segments would otherwise go beyond the URL path root.
(#536)Fixed an issue with update_query() not getting rid of the query when argument is None. (#792)Added some input restrictions on with_port() function to prevent invalid boolean inputs or out of valid port inputs; handled incorrect 0 port representation. (#793)Madeyarl.URL.build()raise aTypeErrorif thehostargument isNone— by@paulpapacz. (#808)Fixed an issue withupdate_query()getting rid of the query when the argument
is empty but notNone. (#845)Misc#2201.8.2 (2022-12-03)This is the first release that started shipping wheels for Python 3.11.1.8.1 (2022-08-01)Misc#694,#699,#700,#701,#702,#703,#7391.8.0 (2022-08-01)FeaturesAddedURL.raw_suffix,URL.suffix,URL.raw_suffixes,URL.suffixes,URL.with_suffix. (#613)Improved DocumentationFixed broken internal references toyarl.URL.human_repr().
(#665)Fixed broken external references tomultidict:indexdocs. (#665)Deprecations and RemovalsDropped Python 3.6 support. (#672)Misc#646,#699,#7011.7.2 (2021-11-01)BugfixesChanged call inwith_port()to stop reencoding parts of the URL that were already encoded. (#623)1.7.1 (2021-10-07)BugfixesFix 1.7.0 build error1.7.0 (2021-10-06)FeaturesAdd__bytes__()magic method so thatbytes(url)will work and use optimal ASCII encoding.
(#582)Started shipping platform-specific arm64 wheels for Apple Silicon. (#622)Started shipping platform-specific wheels with themusltag targeting typical Alpine Linux runtimes. (#622)Added support for Python 3.10. (#622)1.6.3 (2020-11-14)BugfixesNo longer loose characters when decoding incorrect percent-sequences (like%e2%82%f8). All non-decodable percent-sequences are now preserved.#517Provide x86 Windows wheels.#5351.6.2 (2020-10-12)BugfixesProvide generated.cfiles in TarBall distribution.#5301.6.1 (2020-10-12)FeaturesProvide wheels foraarch64,i686,ppc64le,s390xarchitectures on
Linux as well asx86_64.#507Provide wheels for Python 3.9.#526Bugfixeshuman_repr()now always produces valid representation equivalent to the original URL (if the original URL is valid).#511Fixed  requoting a single percent followed by a percent-encoded character in the Cython implementation.#514Fix ValueError when decoding%which is not followed by two hexadecimal digits.#516Fix decoding%followed by a space and hexadecimal digit.#520Fix annotation ofwith_query()/update_query()methods forkey=[val1,val2]case.#528RemovalDrop Python 3.5 support; Python 3.6 is the minimal supported Python version.1.6.0 (2020-09-23)FeaturesAllow for int and float subclasses in query, while still denying bool.#492BugfixesDo not requote arguments inURL.build(),with_xxx()and in/operator.#502Keep IPv6 brackets inorigin().#5041.5.1 (2020-08-01)BugfixesFix including relocated internalyarl._quoting_cC-extension into published PyPI dists.#485Misc#4841.5.0 (2020-07-26)FeaturesConvert host to lowercase on URL building.#386Allow usingmodoperator (%) for updating query string (an alias forupdate_query()method).#435Allow use of sequences such aslistandtuplein the values
of a mapping such asdictto represent that a key has many values:url = URL("http://example.com")
assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2")#443SupportURL.build()with scheme and path (creates a relative URL).#464Cache slow IDNA encode/decode calls.#476Add@final/Finaltype hints#477Support URL authority/raw_authority properties and authority argument ofURL.build()method.#478Hide the library implementation details, make the exposed public list very clean.#483BugfixesFix tests with newer Python (3.7.6, 3.8.1 and 3.9.0+).#409Fix a bug where query component, passed in a form of mapping or sequence, is unquoted in unexpected way.#426HideQueryandQueryVariabletype aliases in__init__.pyi, now they are prefixed with underscore.#431Keep IPv6 brackets after updating port/user/password.#4511.4.2 (2019-12-05)FeaturesWorkaround for missingstr.isascii()in Python 3.6#3891.4.1 (2019-11-29)Fix regression, make the library work on Python 3.5 and 3.6 again.1.4.0 (2019-11-29)Distinguish an empty password in URL from a password not provided at all (#262)Fixed annotations for optional parameters ofURL.build(#309)Use None as default value ofuserparameter ofURL.build(#309)Enforce building C Accelerated modules when installing from source tarball, useYARL_NO_EXTENSIONSenvironment variable for falling back to (slower) Pure Python
implementation (#329)Drop Python 3.5 supportFix quoting of plus in path by pure python version (#339)Don’t create a new URL if fragment is unchanged (#292)Included in error message the path that produces starting slash forbidden error (#376)Skip slow IDNA encoding for ASCII-only strings (#387)1.3.0 (2018-12-11)Fix annotations forqueryparameter (#207)An incoming query sequence can have int variables (the same as for
Mapping type) (#208)AddURL.explicit_portproperty (#218)Give a friendlier error when port can’t be converted to int (#168)bool(URL())now returnsFalse(#272)1.2.6 (2018-06-14)Drop Python 3.4 trove classifier (#205)1.2.5 (2018-05-23)Fix annotations forbuild(#199)1.2.4 (2018-05-08)Fix annotations forcached_property(#195)1.2.3 (2018-05-03)Acceptstrsubclasses inURLconstructor (#190)1.2.2 (2018-05-01)Fix build1.2.1 (2018-04-30)Pin minimal required Python to 3.5.3 (#189)1.2.0 (2018-04-30)Forbid inheritance, replace__init__with__new__(#171)Support PEP-561 (provide type hinting marker) (#182)1.1.1 (2018-02-17)Fix performance regression: don’t encode emptynetloc(#170)1.1.0 (2018-01-21)Make pure Python quoter consistent with Cython version (#162)1.0.0 (2018-01-15)Use fast path if quoted string does not need requoting (#154)Speed up quoting/unquoting by_Quoterand_Unquoterclasses (#155)Dropyarl.quoteandyarl.unquotepublic functions (#155)Add custom string writer, reuse static buffer if available (#157)
Code is 50-80 times faster than Pure Python version (was 4-5 times faster)Don’t recode IP zone (#144)Supportencoded=Trueinyarl.URL.build()(#158)Fix updating query with multiple keys (#160)0.18.0 (2018-01-10)Fallback to IDNA 2003 if domain name is not IDNA 2008 compatible (#152)0.17.0 (2017-12-30)Use IDNA 2008 for domain name processing (#149)0.16.0 (2017-12-07)Fix raisingTypeErrorbyurl.query_string()afterurl.with_query({})(empty mapping) (#141)0.15.0 (2017-11-23)Addraw_path_qsattribute (#137)0.14.2 (2017-11-14)Restorestrictparameter as no-op inquote/unquote0.14.1 (2017-11-13)Restorestrictparameter as no-op for sake of compatibility with
aiohttp 2.20.14.0 (2017-11-11)Drop strict mode (#123)Fix"ValueError: Unallowed PCT %"when there’s a"%"in the URL (#124)0.13.0 (2017-10-01)Documentencodedparameter (#102)Support relative URLs like'?key=value'(#100)Unsafe encoding for QS fixed. Encode;character in value parameter (#104)Process passwords without user names (#95)0.12.0 (2017-06-26)Properly support paths without leading slash inURL.with_path()(#90)Enable type annotation checks0.11.0 (2017-06-26)Normalize path (#86)Clear query and fragment parts in.with_path()(#85)0.10.3 (2017-06-13)Prevent double URL arguments unquoting (#83)0.10.2 (2017-05-05)Unexpected hash behavior (#75)0.10.1 (2017-05-03)Unexpected compare behavior (#73)Do not quote or unquote + if not a query string. (#74)0.10.0 (2017-03-14)AddedURL.buildclass method (#58)Addedpath_qsattribute (#42)0.9.8 (2017-02-16)Do not quote:in path0.9.7 (2017-02-16)Load from pickle without _cache (#56)Percent-encoded pluses in path variables become spaces (#59)0.9.6 (2017-02-15)Revert backward incompatible change (BaseURL)0.9.5 (2017-02-14)Fix BaseURL rich comparison support0.9.4 (2017-02-14)Use BaseURL0.9.3 (2017-02-14)Added BaseURL0.9.2 (2017-02-08)Remove debug print0.9.1 (2017-02-07)Do not lose tail chars (#45)0.9.0 (2017-02-07)Allow to quote%in non strict mode (#21)Incorrect parsing of query parameters with %3B (;) inside (#34)Fix core dumps (#41)tmpbuf- compiling error (#43)AddedURL.update_path()methodAddedURL.update_query()method (#47)0.8.1 (2016-12-03)Fix broken aiohttp: revert backquote/unquote.0.8.0 (2016-12-03)Support more verbose error messages in.with_query()(#24)Don’t percent-encode@and:in path (#32)Don’t exposeyarl.quoteandyarl.unquote, these functions are
part of private API0.7.1 (2016-11-18)Accept not onlystrbut all classes inherited fromstralso (#25)0.7.0 (2016-11-07)Acceptintas value for.with_query()0.6.0 (2016-11-07)Explicitly use UTF8 encoding insetup.py(#20)Properly unquote non-UTF8 strings (#19)0.5.3 (2016-11-02)Don’t usetyping.NamedTuplefields but indexes on URL construction0.5.2 (2016-11-02)Inline_encodeclass method0.5.1 (2016-11-02)Make URL construction faster by removing extra classmethod calls0.5.0 (2016-11-02)Add Cython optimization for quoting/unquotingProvide binary wheels0.4.3 (2016-09-29)Fix typing stubs0.4.2 (2016-09-29)Exposequote()andunquote()as public API0.4.1 (2016-09-28)Support empty values in query ('/path?arg')0.4.0 (2016-09-27)Introducerelative()(#16)0.3.2 (2016-09-27)Typo fixes #150.3.1 (2016-09-26)Support sequence of pairs aswith_query()parameter0.3.0 (2016-09-26)Introduceis_default_port()0.2.1 (2016-09-26)Raise ValueError for URLs like ‘http://:8080/’0.2.0 (2016-09-18)Avoid doubling slashes when joining paths (#13)Appending path starting from slash is forbidden (#12)0.1.4 (2016-09-09)Addkwargssupport forwith_query()(#10)0.1.3 (2016-09-07)Documentwith_query(),with_fragment()andorigin()AllowNoneforwith_query()andwith_fragment()0.1.2 (2016-09-07)Fix links, tune docs theme.0.1.1 (2016-09-06)Update README, old version used obsolete API0.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.