yarl 1.22.0
Yet another URL library
License: Apache-2.0
Requires Python: >=3.9
Keywords: cython, cext, yarl

yarl
====

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

.. image:: https://github.com/aio-libs/yarl/workflows/CI/badge.svg
   :target: https://github.com/aio-libs/yarl/actions?query=workflow%3ACI
   :align: right

.. image:: https://codecov.io/gh/aio-libs/yarl/graph/badge.svg?flag=pytest
   :target: https://app.codecov.io/gh/aio-libs/yarl?flags[]=pytest
   :alt: Codecov coverage for the pytest-driven measurements

.. image:: https://img.shields.io/endpoint?url=https://codspeed.io/badge.json
   :target: https://codspeed.io/aio-libs/yarl

.. image:: https://badge.fury.io/py/yarl.svg
   :target: https://badge.fury.io/py/yarl

.. image:: https://readthedocs.org/projects/yarl/badge/?version=latest
   :target: https://yarl.aio-libs.org

.. image:: https://img.shields.io/pypi/pyversions/yarl.svg
   :target: https://pypi.python.org/pypi/yarl

.. image:: https://img.shields.io/matrix/aio-libs:matrix.org?label=Discuss%20on%20Matrix%20at%20%23aio-libs%3Amatrix.org&logo=matrix&server_fqdn=matrix.org&style=flat
   :target: https://matrix.to/#/%23aio-libs:matrix.org
   :alt: Matrix Room — #aio-libs:matrix.org

.. image:: https://img.shields.io/matrix/aio-libs-space:matrix.org?label=Discuss%20on%20Matrix%20at%20%23aio-libs-space%3Amatrix.org&logo=matrix&server_fqdn=matrix.org&style=flat
   :target: https://matrix.to/#/%23aio-libs-space:matrix.org
   :alt: Matrix Space — #aio-libs-space:matrix.org


Introduction
------------

Url is constructed from ``str``:

.. code-block:: pycon

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

.. code-block:: pycon

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

.. code-block:: pycon

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

.. code-block:: pycon

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

.. code-block:: pycon

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

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

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

.. code-block:: pycon

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

For full documentation please read https://yarl.aio-libs.org.


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 where wheels are not provided,
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 multidict_ and propcache_ libraries.


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

The documentation is located at https://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 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.


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

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

  The library has rich functionality but the ``furl`` object 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.

  ``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 do any decode/encode transformations leaving the
  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.

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/yarl

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

.. _propcache: https://github.com/aio-libs/propcache

=========
Changelog
=========

..
    You should *NOT* be adding new change log entries to this file, this
    file is managed by towncrier. You *may* edit previous change logs to
    fix problems like typo corrections or such.
    To add a new change log entry, please see
    https://pip.pypa.io/en/latest/development/#adding-a-news-entry
    we named the news folder "changes".

    WARNING: Don't drop the next directive!

.. towncrier release notes start

1.22.0
======

*(2025-10-05)*


Features
--------

- Added arm64 Windows wheel builds
  -- by `@finnagin <https://github.com/sponsors/finnagin>`__.

  *Related issues and pull requests on GitHub:*
  `#1516 <https://github.com/aio-libs/yarl/issues/1516>`__.


----


1.21.0
======

*(2025-10-05)*


Contributor-facing changes
--------------------------

- The ``reusable-cibuildwheel.yml`` workflow has been refactored to
  be more generic and ``ci-cd.yml`` now holds all the configuration
  toggles -- by `@webknjaz <https://github.com/sponsors/webknjaz>`__.

  *Related issues and pull requests on GitHub:*
  `#1535 <https://github.com/aio-libs/yarl/issues/1535>`__.

- When building wheels, the source distribution is now passed directly
  to the ``cibuildwheel`` invocation -- by `@webknjaz <https://github.com/sponsors/webknjaz>`__.

  *Related issues and pull requests on GitHub:*
  `#1536 <https://github.com/aio-libs/yarl/issues/1536>`__.

- Added CI for Python 3.14 -- by `@kumaraditya303 <https://github.com/sponsors/kumaraditya303>`__.

  *Related issues and pull requests on GitHub:*
  `#1560 <https://github.com/aio-libs/yarl/issues/1560>`__.


----


1.20.1
======

*(2025-06-09)*


Bug fixes
---------

- Started raising a ``ValueError`` exception raised for corrupted
  IPv6 URL values.

  These fixes the issue where exception ``IndexError`` was
  leaking from the internal code because of not being handled and
  transformed into a user-facing error. The problem was happening
  under the following conditions: empty IPv6 URL, brackets in
  reverse order.

  -- by `@MaelPic <https://github.com/sponsors/MaelPic>`__.

  *Related issues and pull requests on GitHub:*
  `#1512 <https://github.com/aio-libs/yarl/issues/1512>`__.


Packaging updates and notes for downstreams
-------------------------------------------

- Updated to use Cython 3.1 universally across the build path -- by `@lysnikolaou <https://github.com/sponsors/lysnikolaou>`__.

  *Related issues and pull requests on GitHub:*
  `#1514 <https://github.com/aio-libs/yarl/issues/1514>`__.

- Made Cython line tracing opt-in via the ``with-cython-tracing`` build config setting -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  Previously, line tracing was enabled by default in ``pyproject.toml``, which caused build issues for some users and made wheels nearly twice as slow.
  Now line tracing is only enabled when explicitly requested via ``pip install . --config-setting=with-cython-tracing=true`` or by setting the ``YARL_CYTHON_TRACING`` environment variable.

  *Related issues and pull requests on GitHub:*
  `#1521 <https://github.com/aio-libs/yarl/issues/1521>`__.


----


1.20.0
======

*(2025-04-16)*


Features
--------

- Implemented support for the free-threaded build of CPython 3.13 -- by `@lysnikolaou <https://github.com/sponsors/lysnikolaou>`__.

  *Related issues and pull requests on GitHub:*
  `#1456 <https://github.com/aio-libs/yarl/issues/1456>`__.


Packaging updates and notes for downstreams
-------------------------------------------

- Started building wheels for the free-threaded build of CPython 3.13 -- by `@lysnikolaou <https://github.com/sponsors/lysnikolaou>`__.

  *Related issues and pull requests on GitHub:*
  `#1456 <https://github.com/aio-libs/yarl/issues/1456>`__.


----


1.19.0
======

*(2025-04-05)*


Bug fixes
---------

- Fixed entire name being re-encoded when using ``yarl.URL.with_suffix()`` -- by `@NTFSvolume <https://github.com/sponsors/NTFSvolume>`__.

  *Related issues and pull requests on GitHub:*
  `#1468 <https://github.com/aio-libs/yarl/issues/1468>`__.


Features
--------

- Started building armv7l wheels for manylinux -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1495 <https://github.com/aio-libs/yarl/issues/1495>`__.


Contributor-facing changes
--------------------------

- GitHub Actions CI/CD is now configured to manage caching pip-ecosystem
  dependencies using `re-actors/cache-python-deps`_ -- an action by
  `@webknjaz <https://github.com/sponsors/webknjaz>`__ that takes into account ABI stability and the exact
  version of Python runtime.

  .. _`re-actors/cache-python-deps`:
     https://github.com/marketplace/actions/cache-python-deps

  *Related issues and pull requests on GitHub:*
  `#1471 <https://github.com/aio-libs/yarl/issues/1471>`__.

- Increased minimum `propcache`_ version to 0.2.1 to fix failing tests -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  .. _`propcache`:
     https://github.com/aio-libs/propcache

  *Related issues and pull requests on GitHub:*
  `#1479 <https://github.com/aio-libs/yarl/issues/1479>`__.

- Added all hidden folders to pytest's ``norecursedirs`` to prevent it
  from trying to collect tests there -- by `@lysnikolaou <https://github.com/sponsors/lysnikolaou>`__.

  *Related issues and pull requests on GitHub:*
  `#1480 <https://github.com/aio-libs/yarl/issues/1480>`__.


Miscellaneous internal changes
------------------------------

- Improved accuracy of type annotations -- by `@Dreamsorcerer <https://github.com/sponsors/Dreamsorcerer>`__.

  *Related issues and pull requests on GitHub:*
  `#1484 <https://github.com/aio-libs/yarl/issues/1484>`__.

- Improved performance of parsing query strings -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1493 <https://github.com/aio-libs/yarl/issues/1493>`__, `#1497 <https://github.com/aio-libs/yarl/issues/1497>`__.

- Improved performance of the C unquoter -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1496 <https://github.com/aio-libs/yarl/issues/1496>`__, `#1498 <https://github.com/aio-libs/yarl/issues/1498>`__.


----


1.18.3
======

*(2024-12-01)*


Bug fixes
---------

- Fixed uppercase ASCII hosts being rejected by ``URL.build()()`` and ``yarl.URL.with_host()`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#954 <https://github.com/aio-libs/yarl/issues/954>`__, `#1442 <https://github.com/aio-libs/yarl/issues/1442>`__.


Miscellaneous internal changes
------------------------------

- Improved performances of multiple path properties on cache miss -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1443 <https://github.com/aio-libs/yarl/issues/1443>`__.


----


1.18.2
======

*(2024-11-29)*


No significant changes.


----


1.18.1
======

*(2024-11-29)*


Miscellaneous internal changes
------------------------------

- Improved cache performance when ``~yarl.URL`` objects are constructed from ``yarl.URL.build()`` with ``encoded=True`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1432 <https://github.com/aio-libs/yarl/issues/1432>`__.

- Improved cache performance for operations that produce a new ``~yarl.URL`` object -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1434 <https://github.com/aio-libs/yarl/issues/1434>`__, `#1436 <https://github.com/aio-libs/yarl/issues/1436>`__.


----


1.18.0
======

*(2024-11-21)*


Features
--------

- Added ``keep_query`` and ``keep_fragment`` flags in the ``yarl.URL.with_path()``, ``yarl.URL.with_name()`` and ``yarl.URL.with_suffix()`` methods, allowing users to optionally retain the query string and fragment in the resulting URL when replacing the path -- by `@paul-nameless <https://github.com/sponsors/paul-nameless>`__.

  *Related issues and pull requests on GitHub:*
  `#111 <https://github.com/aio-libs/yarl/issues/111>`__, `#1421 <https://github.com/aio-libs/yarl/issues/1421>`__.


Contributor-facing changes
--------------------------

- Started running downstream ``aiohttp`` tests in CI -- by `@Cycloctane <https://github.com/sponsors/Cycloctane>`__.

  *Related issues and pull requests on GitHub:*
  `#1415 <https://github.com/aio-libs/yarl/issues/1415>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of converting ``~yarl.URL`` to a string -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1422 <https://github.com/aio-libs/yarl/issues/1422>`__.


----


1.17.2
======

*(2024-11-17)*


Bug fixes
---------

- Stopped implicitly allowing the use of Cython pre-release versions when
  building the distribution package -- by `@ajsanchezsanz <https://github.com/sponsors/ajsanchezsanz>`__ and
  `@markgreene74 <https://github.com/sponsors/markgreene74>`__.

  *Related issues and pull requests on GitHub:*
  `#1411 <https://github.com/aio-libs/yarl/issues/1411>`__, `#1412 <https://github.com/aio-libs/yarl/issues/1412>`__.

- Fixed a bug causing ``~yarl.URL.port`` to return the default port when the given port was zero
  -- by `@gmacon <https://github.com/sponsors/gmacon>`__.

  *Related issues and pull requests on GitHub:*
  `#1413 <https://github.com/aio-libs/yarl/issues/1413>`__.


Features
--------

- Make error messages include details of incorrect type when ``port`` is not int in ``yarl.URL.build()``.
  -- by `@Cycloctane <https://github.com/sponsors/Cycloctane>`__.

  *Related issues and pull requests on GitHub:*
  `#1414 <https://github.com/aio-libs/yarl/issues/1414>`__.


Packaging updates and notes for downstreams
-------------------------------------------

- Stopped implicitly allowing the use of Cython pre-release versions when
  building the distribution package -- by `@ajsanchezsanz <https://github.com/sponsors/ajsanchezsanz>`__ and
  `@markgreene74 <https://github.com/sponsors/markgreene74>`__.

  *Related issues and pull requests on GitHub:*
  `#1411 <https://github.com/aio-libs/yarl/issues/1411>`__, `#1412 <https://github.com/aio-libs/yarl/issues/1412>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of the ``yarl.URL.joinpath()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1418 <https://github.com/aio-libs/yarl/issues/1418>`__.


----


1.17.1
======

*(2024-10-30)*


Miscellaneous internal changes
------------------------------

- Improved performance of many ``~yarl.URL`` methods -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1396 <https://github.com/aio-libs/yarl/issues/1396>`__, `#1397 <https://github.com/aio-libs/yarl/issues/1397>`__, `#1398 <https://github.com/aio-libs/yarl/issues/1398>`__.

- Improved performance of passing a `dict` or `str` to ``yarl.URL.extend_query()`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1401 <https://github.com/aio-libs/yarl/issues/1401>`__.


----


1.17.0
======

*(2024-10-28)*


Features
--------

- Added ``~yarl.URL.host_port_subcomponent`` which returns the ``3986#section-3.2.2`` host and ``3986#section-3.2.3`` port subcomponent -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1375 <https://github.com/aio-libs/yarl/issues/1375>`__.


----


1.16.0
======

*(2024-10-21)*


Bug fixes
---------

- Fixed blocking I/O to load Python code when creating a new ``~yarl.URL`` with non-ascii characters in the network location part -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1342 <https://github.com/aio-libs/yarl/issues/1342>`__.


Removals and backward incompatible breaking changes
---------------------------------------------------

- Migrated to using a single cache for encoding hosts -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  Passing ``ip_address_size`` and ``host_validate_size`` to ``yarl.cache_configure()`` is deprecated in favor of the new ``encode_host_size`` parameter and will be removed in a future release. For backwards compatibility, the old parameters affect the ``encode_host`` cache size.

  *Related issues and pull requests on GitHub:*
  `#1348 <https://github.com/aio-libs/yarl/issues/1348>`__, `#1357 <https://github.com/aio-libs/yarl/issues/1357>`__, `#1363 <https://github.com/aio-libs/yarl/issues/1363>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of constructing ``~yarl.URL`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1336 <https://github.com/aio-libs/yarl/issues/1336>`__.

- Improved performance of calling ``yarl.URL.build()`` and constructing unencoded ``~yarl.URL`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1345 <https://github.com/aio-libs/yarl/issues/1345>`__.

- Reworked the internal encoding cache to improve performance on cache hit -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1369 <https://github.com/aio-libs/yarl/issues/1369>`__.


----


1.15.5
======

*(2024-10-18)*


Miscellaneous internal changes
------------------------------

- Improved performance of the ``yarl.URL.joinpath()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1304 <https://github.com/aio-libs/yarl/issues/1304>`__.

- Improved performance of the ``yarl.URL.extend_query()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1305 <https://github.com/aio-libs/yarl/issues/1305>`__.

- Improved performance of the ``yarl.URL.origin()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1306 <https://github.com/aio-libs/yarl/issues/1306>`__.

- Improved performance of the ``yarl.URL.with_path()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1307 <https://github.com/aio-libs/yarl/issues/1307>`__.

- Improved performance of the ``yarl.URL.with_query()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1308 <https://github.com/aio-libs/yarl/issues/1308>`__, `#1328 <https://github.com/aio-libs/yarl/issues/1328>`__.

- Improved performance of the ``yarl.URL.update_query()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1309 <https://github.com/aio-libs/yarl/issues/1309>`__, `#1327 <https://github.com/aio-libs/yarl/issues/1327>`__.

- Improved performance of the ``yarl.URL.join()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1313 <https://github.com/aio-libs/yarl/issues/1313>`__.

- Improved performance of ``~yarl.URL`` equality checks -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1315 <https://github.com/aio-libs/yarl/issues/1315>`__.

- Improved performance of ``~yarl.URL`` methods that modify the network location -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1316 <https://github.com/aio-libs/yarl/issues/1316>`__.

- Improved performance of the ``yarl.URL.with_fragment()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1317 <https://github.com/aio-libs/yarl/issues/1317>`__.

- Improved performance of calculating the hash of ``~yarl.URL`` objects -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1318 <https://github.com/aio-libs/yarl/issues/1318>`__.

- Improved performance of the ``yarl.URL.relative()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1319 <https://github.com/aio-libs/yarl/issues/1319>`__.

- Improved performance of the ``yarl.URL.with_name()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1320 <https://github.com/aio-libs/yarl/issues/1320>`__.

- Improved performance of ``~yarl.URL.parent`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1321 <https://github.com/aio-libs/yarl/issues/1321>`__.

- Improved performance of the ``yarl.URL.with_scheme()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1322 <https://github.com/aio-libs/yarl/issues/1322>`__.


----


1.15.4
======

*(2024-10-16)*


Miscellaneous internal changes
------------------------------

- Improved performance of the quoter when all characters are safe -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1288 <https://github.com/aio-libs/yarl/issues/1288>`__.

- Improved performance of unquoting strings -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1292 <https://github.com/aio-libs/yarl/issues/1292>`__, `#1293 <https://github.com/aio-libs/yarl/issues/1293>`__.

- Improved performance of calling ``yarl.URL.build()`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1297 <https://github.com/aio-libs/yarl/issues/1297>`__.


----


1.15.3
======

*(2024-10-15)*


Bug fixes
---------

- Fixed ``yarl.URL.build()`` failing to validate paths must start with a ``/`` when passing ``authority`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  The validation only worked correctly when passing ``host``.

  *Related issues and pull requests on GitHub:*
  `#1265 <https://github.com/aio-libs/yarl/issues/1265>`__.


Removals and backward incompatible breaking changes
---------------------------------------------------

- Removed support for Python 3.8 as it has reached end of life -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1203 <https://github.com/aio-libs/yarl/issues/1203>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of constructing ``~yarl.URL`` when the net location is only the host -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1271 <https://github.com/aio-libs/yarl/issues/1271>`__.


----


1.15.2
======

*(2024-10-13)*


Miscellaneous internal changes
------------------------------

- Improved performance of converting ``~yarl.URL`` to a string -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1234 <https://github.com/aio-libs/yarl/issues/1234>`__.

- Improved performance of ``yarl.URL.joinpath()`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1248 <https://github.com/aio-libs/yarl/issues/1248>`__, `#1250 <https://github.com/aio-libs/yarl/issues/1250>`__.

- Improved performance of constructing query strings from ``~multidict.MultiDict`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1256 <https://github.com/aio-libs/yarl/issues/1256>`__.

- Improved performance of constructing query strings with ``int`` values -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1259 <https://github.com/aio-libs/yarl/issues/1259>`__.


----


1.15.1
======

*(2024-10-12)*


Miscellaneous internal changes
------------------------------

- Improved performance of calling ``yarl.URL.build()`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1222 <https://github.com/aio-libs/yarl/issues/1222>`__.

- Improved performance of all ``~yarl.URL`` methods that create new ``~yarl.URL`` objects -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1226 <https://github.com/aio-libs/yarl/issues/1226>`__.

- Improved performance of ``~yarl.URL`` methods that modify the network location -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1229 <https://github.com/aio-libs/yarl/issues/1229>`__.


----


1.15.0
======

*(2024-10-11)*


Bug fixes
---------

- Fixed validation with ``yarl.URL.with_scheme()`` when passed scheme is not lowercase -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1189 <https://github.com/aio-libs/yarl/issues/1189>`__.


Features
--------

- Started building ``armv7l`` wheels -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1204 <https://github.com/aio-libs/yarl/issues/1204>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of constructing unencoded ``~yarl.URL`` objects -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1188 <https://github.com/aio-libs/yarl/issues/1188>`__.

- Added a cache for parsing hosts to reduce overhead of encoding ``~yarl.URL`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1190 <https://github.com/aio-libs/yarl/issues/1190>`__.

- Improved performance of constructing query strings from ``~collections.abc.Mapping`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1193 <https://github.com/aio-libs/yarl/issues/1193>`__.

- Improved performance of converting ``~yarl.URL`` objects to strings -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1198 <https://github.com/aio-libs/yarl/issues/1198>`__.


----


1.14.0
======

*(2024-10-08)*


Packaging updates and notes for downstreams
-------------------------------------------

- Switched to using the ``propcache`` package for property caching
  -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  The ``propcache`` package is derived from the property caching
  code in ``yarl`` and has been broken out to avoid maintaining it for multiple
  projects.

  *Related issues and pull requests on GitHub:*
  `#1169 <https://github.com/aio-libs/yarl/issues/1169>`__.


Contributor-facing changes
--------------------------

- Started testing with Hypothesis -- by `@webknjaz <https://github.com/sponsors/webknjaz>`__ and `@bdraco <https://github.com/sponsors/bdraco>`__.

  Special thanks to `@Zac-HD <https://github.com/sponsors/Zac-HD>`__ for helping us get started with this framework.

  *Related issues and pull requests on GitHub:*
  `#860 <https://github.com/aio-libs/yarl/issues/860>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of ``yarl.URL.is_default_port()`` when no explicit port is set -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1168 <https://github.com/aio-libs/yarl/issues/1168>`__.

- Improved performance of converting ``~yarl.URL`` to a string when no explicit port is set -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1170 <https://github.com/aio-libs/yarl/issues/1170>`__.

- Improved performance of the ``yarl.URL.origin()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1175 <https://github.com/aio-libs/yarl/issues/1175>`__.

- Improved performance of encoding hosts -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1176 <https://github.com/aio-libs/yarl/issues/1176>`__.


----


1.13.1
======

*(2024-09-27)*


Miscellaneous internal changes
------------------------------

- Improved performance of calling ``yarl.URL.build()`` with ``authority`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1163 <https://github.com/aio-libs/yarl/issues/1163>`__.


----


1.13.0
======

*(2024-09-26)*


Bug fixes
---------

- Started rejecting ASCII hostnames with invalid characters. For host strings that
  look like authority strings, the exception message includes advice on what to do
  instead -- by `@mjpieters <https://github.com/sponsors/mjpieters>`__.

  *Related issues and pull requests on GitHub:*
  `#880 <https://github.com/aio-libs/yarl/issues/880>`__, `#954 <https://github.com/aio-libs/yarl/issues/954>`__.

- Fixed IPv6 addresses missing brackets when the ``~yarl.URL`` was converted to a string -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1157 <https://github.com/aio-libs/yarl/issues/1157>`__, `#1158 <https://github.com/aio-libs/yarl/issues/1158>`__.


Features
--------

- Added ``~yarl.URL.host_subcomponent`` which returns the ``3986#section-3.2.2`` host subcomponent -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  The only current practical difference between ``~yarl.URL.raw_host`` and ``~yarl.URL.host_subcomponent`` is that IPv6 addresses are returned bracketed.

  *Related issues and pull requests on GitHub:*
  `#1159 <https://github.com/aio-libs/yarl/issues/1159>`__.


----


1.12.1
======

*(2024-09-23)*


No significant changes.


----


1.12.0
======

*(2024-09-23)*


Features
--------

- Added ``~yarl.URL.path_safe`` to be able to fetch the path without ``%2F`` and ``%25`` decoded -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1150 <https://github.com/aio-libs/yarl/issues/1150>`__.


Removals and backward incompatible breaking changes
---------------------------------------------------

- Restore decoding ``%2F`` (``/``) in ``URL.path`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  This change restored the behavior before `#1057 <https://github.com/aio-libs/yarl/issues/1057>`__.

  *Related issues and pull requests on GitHub:*
  `#1151 <https://github.com/aio-libs/yarl/issues/1151>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of processing paths -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1143 <https://github.com/aio-libs/yarl/issues/1143>`__.


----


1.11.1
======

*(2024-09-09)*


Bug fixes
---------

- Allowed scheme replacement for relative URLs if the scheme does not require a host -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#280 <https://github.com/aio-libs/yarl/issues/280>`__, `#1138 <https://github.com/aio-libs/yarl/issues/1138>`__.

- Allowed empty host for URL schemes other than the special schemes listed in the WHATWG URL spec -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1136 <https://github.com/aio-libs/yarl/issues/1136>`__.


Features
--------

- Loosened restriction on integers as query string values to allow classes that implement ``__int__`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1139 <https://github.com/aio-libs/yarl/issues/1139>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of normalizing paths -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1137 <https://github.com/aio-libs/yarl/issues/1137>`__.


----


1.11.0
======

*(2024-09-08)*


Features
--------

- Added ``URL.extend_query()()`` method, which can be used to extend parameters without replacing same named keys -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  This method was primarily added to replace the inefficient hand rolled method currently used in ``aiohttp``.

  *Related issues and pull requests on GitHub:*
  `#1128 <https://github.com/aio-libs/yarl/issues/1128>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of the Cython ``cached_property`` implementation -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1122 <https://github.com/aio-libs/yarl/issues/1122>`__.

- Simplified computing ports by removing unnecessary code -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1123 <https://github.com/aio-libs/yarl/issues/1123>`__.

- Improved performance of encoding non IPv6 hosts -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1125 <https://github.com/aio-libs/yarl/issues/1125>`__.

- Improved performance of ``URL.build()()`` when the path, query string, or fragment is an empty string -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1126 <https://github.com/aio-libs/yarl/issues/1126>`__.

- Improved performance of the ``URL.update_query()()`` method -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1130 <https://github.com/aio-libs/yarl/issues/1130>`__.

- Improved performance of processing query string changes when arguments are ``str`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1131 <https://github.com/aio-libs/yarl/issues/1131>`__.


----


1.10.0
======

*(2024-09-06)*


Bug fixes
---------

- Fixed joining a path when the existing path was empty -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  A regression in ``URL.join()()`` was introduced in `#1082 <https://github.com/aio-libs/yarl/issues/1082>`__.

  *Related issues and pull requests on GitHub:*
  `#1118 <https://github.com/aio-libs/yarl/issues/1118>`__.


Features
--------

- Added ``URL.without_query_params()()`` method, to drop some parameters from query string -- by `@hongquan <https://github.com/sponsors/hongquan>`__.

  *Related issues and pull requests on GitHub:*
  `#774 <https://github.com/aio-libs/yarl/issues/774>`__, `#898 <https://github.com/aio-libs/yarl/issues/898>`__, `#1010 <https://github.com/aio-libs/yarl/issues/1010>`__.

- The previously protected types ``_SimpleQuery``, ``_QueryVariable``, and ``_Query`` are now available for use externally as ``SimpleQuery``, ``QueryVariable``, and ``Query`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1050 <https://github.com/aio-libs/yarl/issues/1050>`__, `#1113 <https://github.com/aio-libs/yarl/issues/1113>`__.


Contributor-facing changes
--------------------------

- Replaced all ``~typing.Optional`` with ``~typing.Union`` -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1095 <https://github.com/aio-libs/yarl/issues/1095>`__.


Miscellaneous internal changes
------------------------------

- Significantly improved performance of parsing the network location -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1112 <https://github.com/aio-libs/yarl/issues/1112>`__.

- Added internal types to the cache to prevent future refactoring errors -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1117 <https://github.com/aio-libs/yarl/issues/1117>`__.


----


1.9.11
======

*(2024-09-04)*


Bug fixes
---------

- Fixed a ``TypeError`` with ``MultiDictProxy`` and Python 3.8 -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  *Related issues and pull requests on GitHub:*
  `#1084 <https://github.com/aio-libs/yarl/issues/1084>`__, `#1105 <https://github.com/aio-libs/yarl/issues/1105>`__, `#1107 <https://github.com/aio-libs/yarl/issues/1107>`__.


Miscellaneous internal changes
------------------------------

- Improved performance of encoding hosts -- by `@bdraco <https://github.com/sponsors/bdraco>`__.

  Previously, the library would unconditionally try to parse a host as an IP Address. The library now avoids trying to parse a host as an IP Address if the string is not in one of the formats described in ``3986#section-3.2.2``.

  *Related issues and pull requests on GitHub:*
  `#1104 <https://github.com/aio-libs/yarl/issues/1104>`__.


----


1.9.10
======

*(2024-09-04)*


Bug fixes
---------

- ``URL.join()()`` has been changed to match
  ``3986`` and align with
  ``/ operation()`` and ``URL.joinpath()()``
  when joining URLs with empty segments.
  Previously ``urllib.parse.urljoin`` was used,
  which has known issues with empty segments
  (`python/cpython#84774 <https://github.com/python/cpython/issues/84774>`_).

  Due to the semantics of ``URL.join()()``, joining an
  URL with scheme requires making it relative, prefixing with ``./``.

  .. code-block:: pycon

     >>> URL("https://web.archive.org/web/").join(URL("./https://github.com/aio-libs/yarl"))
     URL('https://web.archive.org/web/https://github.com/aio-libs/yarl')


  Empty segments are hon