Yarl

==================

Bug fixes
---------

- Started raising :py:exc:`TypeError` when a string value is passed into
:py:meth:`~yarl.URL.build` as the ``port`` argument -- by :user:`commonism`.

Previously the empty string as port would create malformed URLs when rendered as string representations. (:issue:`883`)


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

- The leading ``--`` has been dropped from the :pep:`517` in-tree build
backend config setting names. ``--pure-python`` is now just ``pure-python``
-- by :user:`webknjaz`.

The usage now looks as follows:

.. code-block:: console

$ python -m build \
--config-setting=pure-python=true \
--config-setting=with-cython-tracing=true

(:issue:`963`)


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

- A step-by-step :doc:`Release Guide <contributing/release_guide>` guide has
been added, describing how to release *yarl* -- by :user:`webknjaz`.

This is primarily targeting maintainers. (:issue:`960`)
- Coverage collection has been implemented for the Cython modules
-- by :user:`webknjaz`.

It will also be reported to Codecov from any non-release CI jobs.

To measure coverage in a development environment, *yarl* can be
installed in editable mode, which requires an environment variable
``YARL_CYTHON_TRACING=1`` to be set:

.. code-block:: console

$ YARL_CYTHON_TRACING=1 python -Im pip install -e .

Editable install produces C-files required for the Cython coverage
plugin to map the measurements back to the PYX-files. (:issue:`961`)
- It is now possible to request line tracing in Cython builds using the
``with-cython-tracing`` :pep:`517` config setting
-- :user:`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:

.. code-block:: console

$ python -Im pip install . --config-settings=with-cython-tracing=true

For editable installs, this setting is on by default. Otherwise, it's
off unless requested explicitly. (:issue:`962`)

==================

Bug fixes
---------

- Stopped dropping trailing slashes in :py:meth:`~yarl.URL.joinpath` -- by :user:`gmacon`. (:issue:`862`, :issue:`866`)
- Started accepting string subclasses in ``__truediv__()`` operations (``URL / segment``) -- by :user:`mjpieters`. (:issue:`871`, :issue:`884`)
- Fixed the human representation of URLs with square brackets in usernames and passwords -- by :user:`mjpieters`. (:issue:`876`, :issue:`882`)
- Updated type hints to include ``URL.missing_port()``, ``URL.__bytes__()``
and the ``encoding`` argument to :py:meth:`~yarl.URL.joinpath`
-- by :user:`mjpieters`. (:issue:`891`)


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

- Integrated Cython 3 to enable building *yarl* under Python 3.12 -- by :user:`mjpieters`. (:issue:`829`, :issue:`881`)
- Declared modern ``setuptools.build_meta`` as the :pep:`517` build
backend in :file:`pyproject.toml` explicitly -- by :user:`webknjaz`. (:issue:`886`)
- Converted most of the packaging setup into a declarative :file:`setup.cfg`
config -- by :user:`webknjaz`. (:issue:`890`)
- The packaging is replaced from an old-fashioned :file:`setup.py` to an
in-tree :pep:`517` build backend -- by :user:`webknjaz`.

Whenever the end-users or downstream packagers need to build ``yarl`` from
source (a Git checkout or an sdist), they may pass a ``config_settings``
flag ``--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 with ``pip``:

.. code-block:: console

$ python -m pip install . --config-settings=--pure-python=false

This will also work with ``-e | --editable``.

The same can be achieved via ``pypa/build``:

.. code-block:: console

$ python -m build --config-setting=--pure-python=false

Adding ``-w | --wheel`` can force ``pypa/build`` produce a wheel from source
directly, as opposed to building an ``sdist`` and then building from it. (:issue:`893`)

.. attention::

v1.9.3 was the only version using the ``--pure-python`` setting name.
Later versions dropped the ``--`` prefix, making it just ``pure-python``.

- Declared Python 3.12 supported officially in the distribution package metadata
-- by :user:`edgarrmondragon`. (:issue:`942`)


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

- A regression test for no-host URLs was added per :issue:`821`
and :rfc:`3986` -- by :user:`kenballus`. (:issue:`821`, :issue:`822`)
- Started testing *yarl* against Python 3.12 in CI -- by :user:`mjpieters`. (:issue:`881`)
- All Python 3.12 jobs are now marked as required to pass in CI
-- by :user:`edgarrmondragon`. (:issue:`942`)
- MyST is now integrated in Sphinx -- by :user:`webknjaz`.

This allows the contributors to author new documents in Markdown
when they have difficulties with going straight RST. (:issue:`953`)

==================

Bugfixes
--------

- Fix regression with ``__truediv__`` and absolute URLs with empty paths causing the raw path to lack the leading ``/``.
(`854 <https://github.com/aio-libs/yarl/issues/854>`_)

==================

Bugfixes
--------

- Marked 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 <https://github.com/aio-libs/yarl/issues/850>`_)

==================

This release was never published to PyPI, due to issues with the build process.

Features
--------

- Added ``URL.joinpath(*elements)``, to create a new URL appending multiple path elements. (`704 <https://github.com/aio-libs/yarl/issues/704>`_)
- Made ``URL.__truediv__()`` return ``NotImplemented`` if called with an
unsupported type — by :user:`michaeljpeters`.
(`832 <https://github.com/aio-libs/yarl/issues/832>`_)


Bugfixes
--------

- Path normalization for absolute URLs no longer raises a ValueError exception
when ``..`` segments would otherwise go beyond the URL path root.
(`536 <https://github.com/aio-libs/yarl/issues/536>`_)
- Fixed an issue with update_query() not getting rid of the query when argument is None. (`792 <https://github.com/aio-libs/yarl/issues/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 <https://github.com/aio-libs/yarl/issues/793>`_)
- Made :py:meth:`~yarl.URL.build` raise a :py:exc:`TypeError` if the ``host`` argument is :py:data:`None` — by :user:`paulpapacz`. (`808 <https://github.com/aio-libs/yarl/issues/808>`_)
- Fixed an issue with ``update_query()`` getting rid of the query when the argument
is empty but not ``None``. (`845 <https://github.com/aio-libs/yarl/issues/845>`_)


Misc
----

- `220 <https://github.com/aio-libs/yarl/issues/220>`_

==================

This is the first release that started shipping wheels for Python 3.11.