././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1743903941.5992763
yarl-1.19.0/ 0000755 0001751 0000166 00000000000 14774356306 012173 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/.coveragerc 0000644 0001751 0000166 00000001251 14774356277 014322 0 ustar 00runner docker [html]
show_contexts = true
skip_covered = false
[paths]
_site-packages-to-src-mapping =
.
*/lib/pypy*/site-packages
*/lib/python*/site-packages
*\Lib\site-packages
[report]
fail_under = 98.95
skip_covered = true
skip_empty = true
show_missing = true
exclude_also =
^\s*@pytest\.mark\.xfail
if TYPE_CHECKING
assert False
: \.\.\.(\s*#.*)?$
^ +\.\.\.$
[run]
branch = true
cover_pylib = false
# https://coverage.rtfd.io/en/latest/contexts.html#dynamic-contexts
# dynamic_context = test_function # conflicts with `pytest-cov` if set here
parallel = true
plugins =
covdefaults
Cython.Coverage
relative_files = true
source =
.
source_pkgs =
yarl
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1743903941.5842762
yarl-1.19.0/CHANGES/ 0000755 0001751 0000166 00000000000 14774356306 013243 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/CHANGES/.TEMPLATE.rst 0000644 0001751 0000166 00000004675 14774356277 015311 0 ustar 00runner docker {# TOWNCRIER TEMPLATE #}
*({{ versiondata.date }})*
{% for section, _ in sections.items() %}
{% set underline = underlines[0] %}{% if section %}{{section}}
{{ underline * section|length }}{% set underline = underlines[1] %}
{% endif %}
{% if sections[section] %}
{% for category, val in definitions.items() if category in sections[section]%}
{{ definitions[category]['name'] }}
{{ underline * definitions[category]['name']|length }}
{% if definitions[category]['showcontent'] %}
{% for text, change_note_refs in sections[section][category].items() %}
- {{ text }}
{{- '\n' * 2 -}}
{#-
NOTE: Replacing 'e' with 'f' is a hack that prevents Jinja's `int`
NOTE: filter internal implementation from treating the input as an
NOTE: infinite float when it looks like a scientific notation (with a
NOTE: single 'e' char in between digits), raising an `OverflowError`,
NOTE: subsequently. 'f' is still a hex letter so it won't affect the
NOTE: check for whether it's a (short or long) commit hash or not.
Ref: https://github.com/pallets/jinja/issues/1921
-#}
{%-
set pr_issue_numbers = change_note_refs
| map('lower')
| map('replace', 'e', 'f')
| map('int', default=None)
| select('integer')
| map('string')
| list
-%}
{%- set arbitrary_refs = [] -%}
{%- set commit_refs = [] -%}
{%- with -%}
{%- set commit_ref_candidates = change_note_refs | reject('in', pr_issue_numbers) -%}
{%- for cf in commit_ref_candidates -%}
{%- if cf | length in (7, 8, 40) and cf | int(default=None, base=16) is not none -%}
{%- set _ = commit_refs.append(cf) -%}
{%- else -%}
{%- set _ = arbitrary_refs.append(cf) -%}
{%- endif -%}
{%- endfor -%}
{%- endwith -%}
{% if pr_issue_numbers %}
*Related issues and pull requests on GitHub:*
:issue:`{{ pr_issue_numbers | join('`, :issue:`') }}`.
{{- '\n' * 2 -}}
{%- endif -%}
{% if commit_refs %}
*Related commits on GitHub:*
:commit:`{{ commit_refs | join('`, :commit:`') }}`.
{{- '\n' * 2 -}}
{%- endif -%}
{% if arbitrary_refs %}
*Unlinked references:*
{{ arbitrary_refs | join(', ') }}.
{{- '\n' * 2 -}}
{%- endif -%}
{% endfor %}
{% else %}
- {{ sections[section][category]['']|join(', ') }}
{% endif %}
{% if sections[section][category]|length == 0 %}
No significant changes.
{% else %}
{% endif %}
{% endfor %}
{% else %}
No significant changes.
{% endif %}
{% endfor %}
----
{{ '\n' * 2 }}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/CHANGES/.gitignore 0000644 0001751 0000166 00000000576 14774356277 015252 0 ustar 00runner docker *
!.TEMPLATE.rst
!.gitignore
!README.rst
!*.bugfix
!*.bugfix.rst
!*.bugfix.*.rst
!*.breaking
!*.breaking.rst
!*.breaking.*.rst
!*.contrib
!*.contrib.rst
!*.contrib.*.rst
!*.deprecation
!*.deprecation.rst
!*.deprecation.*.rst
!*.doc
!*.doc.rst
!*.doc.*.rst
!*.feature
!*.feature.rst
!*.feature.*.rst
!*.misc
!*.misc.rst
!*.misc.*.rst
!*.packaging
!*.packaging.rst
!*.packaging.*.rst
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/CHANGES/README.rst 0000644 0001751 0000166 00000010772 14774356277 014750 0 ustar 00runner docker .. _Adding change notes with your PRs:
Adding change notes with your PRs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is very important to maintain a log for news of how
updating to the new version of the software will affect
end-users. This is why we enforce collection of the change
fragment files in pull requests as per `Towncrier philosophy`_.
The idea is that when somebody makes a change, they must record
the bits that would affect end-users only including information
that would be useful to them. Then, when the maintainers publish
a new release, they'll automatically use these records to compose
a change log for the respective version. It is important to
understand that including unnecessary low-level implementation
related details generates noise that is not particularly useful
to the end-users most of the time. And so such details should be
recorded in the Git history rather than a changelog.
Alright! So how to add a news fragment?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``yarl`` uses `towncrier `_
for changelog management.
To submit a change note about your PR, add a text file into the
``CHANGES/`` folder. It should contain an
explanation of what applying this PR will change in the way
end-users interact with the project. One sentence is usually
enough but feel free to add as many details as you feel necessary
for the users to understand what it means.
**Use the past tense** for the text in your fragment because,
combined with others, it will be a part of the "news digest"
telling the readers **what changed** in a specific version of
the library *since the previous version*. You should also use
*reStructuredText* syntax for highlighting code (inline or block),
linking parts of the docs or external sites.
However, you do not need to reference the issue or PR numbers here
as *towncrier* will automatically add a reference to all of the
affected issues when rendering the news file.
If you wish to sign your change, feel free to add ``-- by
:user:`github-username``` at the end (replace ``github-username``
with your own!).
Finally, name your file following the convention that Towncrier
understands: it should start with the number of an issue or a
PR followed by a dot, then add a patch type, like ``feature``,
``doc``, ``contrib`` etc., and add ``.rst`` as a suffix. If you
need to add more than one fragment, you may add an optional
sequence number (delimited with another period) between the type
and the suffix.
In general the name will follow ``..rst`` pattern,
where the categories are:
- ``bugfix``: A bug fix for something we deemed an improper undesired
behavior that got corrected in the release to match pre-agreed
expectations.
- ``feature``: A new behavior, public APIs. That sort of stuff.
- ``deprecation``: A declaration of future API removals and breaking
changes in behavior.
- ``breaking``: When something public gets removed in a breaking way.
Could be deprecated in an earlier release.
- ``doc``: Notable updates to the documentation structure or build
process.
- ``packaging``: Notes for downstreams about unobvious side effects
and tooling. Changes in the test invocation considerations and
runtime assumptions.
- ``contrib``: Stuff that affects the contributor experience. e.g.
Running tests, building the docs, setting up the development
environment.
- ``misc``: Changes that are hard to assign to any of the above
categories.
A pull request may have more than one of these components, for example
a code change may introduce a new feature that deprecates an old
feature, in which case two fragments should be added. It is not
necessary to make a separate documentation fragment for documentation
changes accompanying the relevant code changes.
Examples for adding changelog entries to your Pull Requests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File :file:`CHANGES/603.removal.1.rst`:
.. code-block:: rst
Dropped Python 3.5 support; Python 3.6 is the minimal supported Python
version -- by :user:`webknjaz`.
File :file:`CHANGES/550.bugfix.rst`:
.. code-block:: rst
Started shipping Windows wheels for the x86 architecture
-- by :user:`Dreamsorcerer`.
File :file:`CHANGES/553.feature.rst`:
.. code-block:: rst
Added support for ``GenericAliases`` (``MultiDict[str]``) under Python 3.9
and higher -- by :user:`mjpieters`.
.. tip::
See :file:`towncrier.toml` for all available categories
(``tool.towncrier.type``).
.. _Towncrier philosophy:
https://towncrier.readthedocs.io/en/stable/#philosophy
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/CHANGES.rst 0000644 0001751 0000166 00000146504 14774356277 014016 0 ustar 00runner docker =========
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.19.0
======
*(2025-04-05)*
Bug fixes
---------
- Fixed entire name being re-encoded when using :py:meth:`yarl.URL.with_suffix` -- by :user:`NTFSvolume`.
*Related issues and pull requests on GitHub:*
:issue:`1468`.
Features
--------
- Started building armv7l wheels for manylinux -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`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
:user:`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:*
:issue:`1471`.
- Increased minimum `propcache`_ version to 0.2.1 to fix failing tests -- by :user:`bdraco`.
.. _`propcache`:
https://github.com/aio-libs/propcache
*Related issues and pull requests on GitHub:*
:issue:`1479`.
- Added all hidden folders to pytest's ``norecursedirs`` to prevent it
from trying to collect tests there -- by :user:`lysnikolaou`.
*Related issues and pull requests on GitHub:*
:issue:`1480`.
Miscellaneous internal changes
------------------------------
- Improved accuracy of type annotations -- by :user:`Dreamsorcerer`.
*Related issues and pull requests on GitHub:*
:issue:`1484`.
- Improved performance of parsing query strings -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1493`, :issue:`1497`.
- Improved performance of the C unquoter -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1496`, :issue:`1498`.
----
1.18.3
======
*(2024-12-01)*
Bug fixes
---------
- Fixed uppercase ASCII hosts being rejected by :meth:`URL.build() ` and :py:meth:`~yarl.URL.with_host` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`954`, :issue:`1442`.
Miscellaneous internal changes
------------------------------
- Improved performances of multiple path properties on cache miss -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1443`.
----
1.18.2
======
*(2024-11-29)*
No significant changes.
----
1.18.1
======
*(2024-11-29)*
Miscellaneous internal changes
------------------------------
- Improved cache performance when :class:`~yarl.URL` objects are constructed from :py:meth:`~yarl.URL.build` with ``encoded=True`` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1432`.
- Improved cache performance for operations that produce a new :class:`~yarl.URL` object -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1434`, :issue:`1436`.
----
1.18.0
======
*(2024-11-21)*
Features
--------
- Added ``keep_query`` and ``keep_fragment`` flags in the :py:meth:`yarl.URL.with_path`, :py:meth:`yarl.URL.with_name` and :py:meth:`yarl.URL.with_suffix` methods, allowing users to optionally retain the query string and fragment in the resulting URL when replacing the path -- by :user:`paul-nameless`.
*Related issues and pull requests on GitHub:*
:issue:`111`, :issue:`1421`.
Contributor-facing changes
--------------------------
- Started running downstream ``aiohttp`` tests in CI -- by :user:`Cycloctane`.
*Related issues and pull requests on GitHub:*
:issue:`1415`.
Miscellaneous internal changes
------------------------------
- Improved performance of converting :class:`~yarl.URL` to a string -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`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 :user:`ajsanchezsanz` and
:user:`markgreene74`.
*Related issues and pull requests on GitHub:*
:issue:`1411`, :issue:`1412`.
- Fixed a bug causing :attr:`~yarl.URL.port` to return the default port when the given port was zero
-- by :user:`gmacon`.
*Related issues and pull requests on GitHub:*
:issue:`1413`.
Features
--------
- Make error messages include details of incorrect type when ``port`` is not int in :py:meth:`~yarl.URL.build`.
-- by :user:`Cycloctane`.
*Related issues and pull requests on GitHub:*
:issue:`1414`.
Packaging updates and notes for downstreams
-------------------------------------------
- Stopped implicitly allowing the use of Cython pre-release versions when
building the distribution package -- by :user:`ajsanchezsanz` and
:user:`markgreene74`.
*Related issues and pull requests on GitHub:*
:issue:`1411`, :issue:`1412`.
Miscellaneous internal changes
------------------------------
- Improved performance of the :py:meth:`~yarl.URL.joinpath` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1418`.
----
1.17.1
======
*(2024-10-30)*
Miscellaneous internal changes
------------------------------
- Improved performance of many :class:`~yarl.URL` methods -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1396`, :issue:`1397`, :issue:`1398`.
- Improved performance of passing a `dict` or `str` to :py:meth:`~yarl.URL.extend_query` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1401`.
----
1.17.0
======
*(2024-10-28)*
Features
--------
- Added :attr:`~yarl.URL.host_port_subcomponent` which returns the :rfc:`3986#section-3.2.2` host and :rfc:`3986#section-3.2.3` port subcomponent -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1375`.
----
1.16.0
======
*(2024-10-21)*
Bug fixes
---------
- Fixed blocking I/O to load Python code when creating a new :class:`~yarl.URL` with non-ascii characters in the network location part -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1342`.
Removals and backward incompatible breaking changes
---------------------------------------------------
- Migrated to using a single cache for encoding hosts -- by :user:`bdraco`.
Passing ``ip_address_size`` and ``host_validate_size`` to :py:meth:`~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:*
:issue:`1348`, :issue:`1357`, :issue:`1363`.
Miscellaneous internal changes
------------------------------
- Improved performance of constructing :class:`~yarl.URL` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1336`.
- Improved performance of calling :py:meth:`~yarl.URL.build` and constructing unencoded :class:`~yarl.URL` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1345`.
- Reworked the internal encoding cache to improve performance on cache hit -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1369`.
----
1.15.5
======
*(2024-10-18)*
Miscellaneous internal changes
------------------------------
- Improved performance of the :py:meth:`~yarl.URL.joinpath` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1304`.
- Improved performance of the :py:meth:`~yarl.URL.extend_query` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1305`.
- Improved performance of the :py:meth:`~yarl.URL.origin` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1306`.
- Improved performance of the :py:meth:`~yarl.URL.with_path` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1307`.
- Improved performance of the :py:meth:`~yarl.URL.with_query` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1308`, :issue:`1328`.
- Improved performance of the :py:meth:`~yarl.URL.update_query` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1309`, :issue:`1327`.
- Improved performance of the :py:meth:`~yarl.URL.join` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1313`.
- Improved performance of :class:`~yarl.URL` equality checks -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1315`.
- Improved performance of :class:`~yarl.URL` methods that modify the network location -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1316`.
- Improved performance of the :py:meth:`~yarl.URL.with_fragment` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1317`.
- Improved performance of calculating the hash of :class:`~yarl.URL` objects -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1318`.
- Improved performance of the :py:meth:`~yarl.URL.relative` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1319`.
- Improved performance of the :py:meth:`~yarl.URL.with_name` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1320`.
- Improved performance of :attr:`~yarl.URL.parent` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1321`.
- Improved performance of the :py:meth:`~yarl.URL.with_scheme` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1322`.
----
1.15.4
======
*(2024-10-16)*
Miscellaneous internal changes
------------------------------
- Improved performance of the quoter when all characters are safe -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1288`.
- Improved performance of unquoting strings -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1292`, :issue:`1293`.
- Improved performance of calling :py:meth:`~yarl.URL.build` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1297`.
----
1.15.3
======
*(2024-10-15)*
Bug fixes
---------
- Fixed :py:meth:`~yarl.URL.build` failing to validate paths must start with a ``/`` when passing ``authority`` -- by :user:`bdraco`.
The validation only worked correctly when passing ``host``.
*Related issues and pull requests on GitHub:*
:issue:`1265`.
Removals and backward incompatible breaking changes
---------------------------------------------------
- Removed support for Python 3.8 as it has reached end of life -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1203`.
Miscellaneous internal changes
------------------------------
- Improved performance of constructing :class:`~yarl.URL` when the net location is only the host -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1271`.
----
1.15.2
======
*(2024-10-13)*
Miscellaneous internal changes
------------------------------
- Improved performance of converting :class:`~yarl.URL` to a string -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1234`.
- Improved performance of :py:meth:`~yarl.URL.joinpath` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1248`, :issue:`1250`.
- Improved performance of constructing query strings from :class:`~multidict.MultiDict` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1256`.
- Improved performance of constructing query strings with ``int`` values -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1259`.
----
1.15.1
======
*(2024-10-12)*
Miscellaneous internal changes
------------------------------
- Improved performance of calling :py:meth:`~yarl.URL.build` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1222`.
- Improved performance of all :class:`~yarl.URL` methods that create new :class:`~yarl.URL` objects -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1226`.
- Improved performance of :class:`~yarl.URL` methods that modify the network location -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1229`.
----
1.15.0
======
*(2024-10-11)*
Bug fixes
---------
- Fixed validation with :py:meth:`~yarl.URL.with_scheme` when passed scheme is not lowercase -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1189`.
Features
--------
- Started building ``armv7l`` wheels -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1204`.
Miscellaneous internal changes
------------------------------
- Improved performance of constructing unencoded :class:`~yarl.URL` objects -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1188`.
- Added a cache for parsing hosts to reduce overhead of encoding :class:`~yarl.URL` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1190`.
- Improved performance of constructing query strings from :class:`~collections.abc.Mapping` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1193`.
- Improved performance of converting :class:`~yarl.URL` objects to strings -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1198`.
----
1.14.0
======
*(2024-10-08)*
Packaging updates and notes for downstreams
-------------------------------------------
- Switched to using the :mod:`propcache ` package for property caching
-- by :user:`bdraco`.
The :mod:`propcache ` package is derived from the property caching
code in :mod:`yarl` and has been broken out to avoid maintaining it for multiple
projects.
*Related issues and pull requests on GitHub:*
:issue:`1169`.
Contributor-facing changes
--------------------------
- Started testing with Hypothesis -- by :user:`webknjaz` and :user:`bdraco`.
Special thanks to :user:`Zac-HD` for helping us get started with this framework.
*Related issues and pull requests on GitHub:*
:issue:`860`.
Miscellaneous internal changes
------------------------------
- Improved performance of :py:meth:`~yarl.URL.is_default_port` when no explicit port is set -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1168`.
- Improved performance of converting :class:`~yarl.URL` to a string when no explicit port is set -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1170`.
- Improved performance of the :py:meth:`~yarl.URL.origin` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1175`.
- Improved performance of encoding hosts -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1176`.
----
1.13.1
======
*(2024-09-27)*
Miscellaneous internal changes
------------------------------
- Improved performance of calling :py:meth:`~yarl.URL.build` with ``authority`` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`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 :user:`mjpieters`.
*Related issues and pull requests on GitHub:*
:issue:`880`, :issue:`954`.
- Fixed IPv6 addresses missing brackets when the :class:`~yarl.URL` was converted to a string -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1157`, :issue:`1158`.
Features
--------
- Added :attr:`~yarl.URL.host_subcomponent` which returns the :rfc:`3986#section-3.2.2` host subcomponent -- by :user:`bdraco`.
The only current practical difference between :attr:`~yarl.URL.raw_host` and :attr:`~yarl.URL.host_subcomponent` is that IPv6 addresses are returned bracketed.
*Related issues and pull requests on GitHub:*
:issue:`1159`.
----
1.12.1
======
*(2024-09-23)*
No significant changes.
----
1.12.0
======
*(2024-09-23)*
Features
--------
- Added :attr:`~yarl.URL.path_safe` to be able to fetch the path without ``%2F`` and ``%25`` decoded -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1150`.
Removals and backward incompatible breaking changes
---------------------------------------------------
- Restore decoding ``%2F`` (``/``) in ``URL.path`` -- by :user:`bdraco`.
This change restored the behavior before :issue:`1057`.
*Related issues and pull requests on GitHub:*
:issue:`1151`.
Miscellaneous internal changes
------------------------------
- Improved performance of processing paths -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1143`.
----
1.11.1
======
*(2024-09-09)*
Bug fixes
---------
- Allowed scheme replacement for relative URLs if the scheme does not require a host -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`280`, :issue:`1138`.
- Allowed empty host for URL schemes other than the special schemes listed in the WHATWG URL spec -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1136`.
Features
--------
- Loosened restriction on integers as query string values to allow classes that implement ``__int__`` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1139`.
Miscellaneous internal changes
------------------------------
- Improved performance of normalizing paths -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1137`.
----
1.11.0
======
*(2024-09-08)*
Features
--------
- Added :meth:`URL.extend_query() ` method, which can be used to extend parameters without replacing same named keys -- by :user:`bdraco`.
This method was primarily added to replace the inefficient hand rolled method currently used in ``aiohttp``.
*Related issues and pull requests on GitHub:*
:issue:`1128`.
Miscellaneous internal changes
------------------------------
- Improved performance of the Cython ``cached_property`` implementation -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1122`.
- Simplified computing ports by removing unnecessary code -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1123`.
- Improved performance of encoding non IPv6 hosts -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1125`.
- Improved performance of :meth:`URL.build() ` when the path, query string, or fragment is an empty string -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1126`.
- Improved performance of the :meth:`URL.update_query() ` method -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1130`.
- Improved performance of processing query string changes when arguments are :class:`str` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1131`.
----
1.10.0
======
*(2024-09-06)*
Bug fixes
---------
- Fixed joining a path when the existing path was empty -- by :user:`bdraco`.
A regression in :meth:`URL.join() ` was introduced in :issue:`1082`.
*Related issues and pull requests on GitHub:*
:issue:`1118`.
Features
--------
- Added :meth:`URL.without_query_params() ` method, to drop some parameters from query string -- by :user:`hongquan`.
*Related issues and pull requests on GitHub:*
:issue:`774`, :issue:`898`, :issue:`1010`.
- The previously protected types ``_SimpleQuery``, ``_QueryVariable``, and ``_Query`` are now available for use externally as ``SimpleQuery``, ``QueryVariable``, and ``Query`` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1050`, :issue:`1113`.
Contributor-facing changes
--------------------------
- Replaced all :class:`~typing.Optional` with :class:`~typing.Union` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1095`.
Miscellaneous internal changes
------------------------------
- Significantly improved performance of parsing the network location -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1112`.
- Added internal types to the cache to prevent future refactoring errors -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1117`.
----
1.9.11
======
*(2024-09-04)*
Bug fixes
---------
- Fixed a :exc:`TypeError` with ``MultiDictProxy`` and Python 3.8 -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1084`, :issue:`1105`, :issue:`1107`.
Miscellaneous internal changes
------------------------------
- Improved performance of encoding hosts -- by :user:`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 :rfc:`3986#section-3.2.2`.
*Related issues and pull requests on GitHub:*
:issue:`1104`.
----
1.9.10
======
*(2024-09-04)*
Bug fixes
---------
- :meth:`URL.join() ` has been changed to match
:rfc:`3986` and align with
:meth:`/ operation ` and :meth:`URL.joinpath() `
when joining URLs with empty segments.
Previously :py:func:`urllib.parse.urljoin` was used,
which has known issues with empty segments
(`python/cpython#84774 `_).
Due to the semantics of :meth:`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 honored in the base as well as the joined part.
.. code-block:: pycon
>>> URL("https://web.archive.org/web/https://").join(URL("github.com/aio-libs/yarl"))
URL('https://web.archive.org/web/https://github.com/aio-libs/yarl')
-- by :user:`commonism`
This change initially appeared in 1.9.5 but was reverted in 1.9.6 to resolve a problem with query string handling.
*Related issues and pull requests on GitHub:*
:issue:`1039`, :issue:`1082`.
Features
--------
- Added :attr:`~yarl.URL.absolute` which is now preferred over ``URL.is_absolute()`` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1100`.
----
1.9.9
=====
*(2024-09-04)*
Bug fixes
---------
- Added missing type on :attr:`~yarl.URL.port` -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1097`.
----
1.9.8
=====
*(2024-09-03)*
Features
--------
- Covered the :class:`~yarl.URL` object with types -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1084`.
- Cache parsing of IP Addresses when encoding hosts -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1086`.
Contributor-facing changes
--------------------------
- Covered the :class:`~yarl.URL` object with types -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1084`.
Miscellaneous internal changes
------------------------------
- Improved performance of handling ports -- by :user:`bdraco`.
*Related issues and pull requests on GitHub:*
:issue:`1081`.
----
1.9.7
=====
*(2024-09-01)*
Removals and backward incompatible breaking changes
---------------------------------------------------
- Removed support :rfc:`3986#section-3.2.3` port normalization when the scheme is not one of ``http``, ``https``, ``wss``, or ``ws`` -- by :user:`bdraco`.
Support for port normalization was recently added in :issue:`1033` and contained code that would do blocking I/O if the scheme was not one of the four listed above. The code has been removed because this library is intended to be safe for usage with :mod:`asyncio`.
*Related issues and pull requests on GitHub:*
:issue:`1076`.
Miscellaneous internal changes
------------------------------
- Improved performance of property caching -- by :user:`bdraco`.
The ``reify`` implementation from ``aiohttp`` was adapted to replace the internal ``cached_property`` implementation.
*Related issues and pull requests on GitHub:*
:issue:`1070`.
----
1.9.6
=====
*(2024-08-30)*
Bug fixes
---------
- Reverted :rfc:`3986` compatible :meth:`URL.join() ` honoring empty segments which was introduced in :issue:`1039`.
This change introduced a regression handling query string parameters with joined URLs. The change was reverted to maintain compatibility with the previous behavior.
*Related issues and pull requests on GitHub:*
:issue:`1067`.
----
1.9.5
=====
*(2024-08-30)*
Bug fixes
---------
- Joining URLs with empty segments has been changed
to match :rfc:`3986`.
Previously empty segments would be removed from path,
breaking use-cases such as
.. code-block:: python
URL("https://web.archive.org/web/") / "https://github.com/"
Now :meth:`/ operation ` and :meth:`URL.joinpath() `
keep empty segments, but do not introduce new empty segments.
e.g.
.. code-block:: python
URL("https://example.org/") / ""
does not introduce an empty segment.
-- by :user:`commonism` and :user:`youtux`
*Related issues and pull requests on GitHub:*
:issue:`1026`.
- The default protocol ports of well-known URI schemes are now taken into account
during the normalization of the URL string representation in accordance with
:rfc:`3986#section-3.2.3`.
Specified ports are removed from the :class:`str` representation of a :class:`~yarl.URL`
if the port matches the scheme's default port -- by :user:`commonism`.
*Related issues and pull requests on GitHub:*
:issue:`1033`.
- :meth:`URL.join() ` has been changed to match
:rfc:`3986` and align with
:meth:`/ operation ` and :meth:`URL.joinpath() `
when joining URLs with empty segments.
Previously :py:func:`urllib.parse.urljoin` was used,
which has known issues with empty segments
(`python/cpython#84774 `_).
Due to the semantics of :meth:`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 honored in the base as well as the joined part.
.. code-block:: pycon
>>> URL("https://web.archive.org/web/https://").join(URL("github.com/aio-libs/yarl"))
URL('https://web.archive.org/web/https://github.com/aio-libs/yarl')
-- by :user:`commonism`
*Related issues and pull requests on GitHub:*
:issue:`1039`.
Removals and backward incompatible breaking changes
---------------------------------------------------
- Stopped decoding ``%2F`` (``/``) in ``URL.path``, as this could lead to code incorrectly treating it as a path separator
-- by :user:`Dreamsorcerer`.
*Related issues and pull requests on GitHub:*
:issue:`1057`.
- Dropped support for Python 3.7 -- by :user:`Dreamsorcerer`.
*Related issues and pull requests on GitHub:*
:issue:`1016`.
Improved documentation
----------------------
- On the :doc:`Contributing docs ` page,
a link to the ``Towncrier philosophy`` has been fixed.
*Related issues and pull requests on GitHub:*
:issue:`981`.
- The pre-existing :meth:`/ magic method `
has been documented in the API reference -- by :user:`commonism`.
*Related issues and pull requests on GitHub:*
:issue:`1026`.
Packaging updates and notes for downstreams
-------------------------------------------
- A flaw in the logic for copying the project directory into a
temporary folder that led to infinite recursion when :envvar:`TMPDIR`
was set to a project subdirectory path. This was happening in Fedora
and its downstream due to the use of `pyproject-rpm-macros
`__. It was
only reproducible with ``pip wheel`` and was not affecting the
``pyproject-build`` users.
-- by :user:`hroncok` and :user:`webknjaz`
*Related issues and pull requests on GitHub:*
:issue:`992`, :issue:`1014`.
- Support Python 3.13 and publish non-free-threaded wheels
*Related issues and pull requests on GitHub:*
:issue:`1054`.
Contributor-facing changes
--------------------------
- The CI/CD setup has been updated to test ``arm64`` wheels
under macOS 14, except for Python 3.7 that is unsupported
in that environment -- by :user:`webknjaz`.
*Related issues and pull requests on GitHub:*
:issue:`1015`.
- Removed unused type ignores and casts -- by :user:`hauntsaninja`.
*Related issues and pull requests on GitHub:*
:issue:`1031`.
Miscellaneous internal changes
------------------------------
- ``port``, ``scheme``, and ``raw_host`` are now ``cached_property`` -- by :user:`bdraco`.
``aiohttp`` accesses these properties quite often, which cause :mod:`urllib` to build the ``_hostinfo`` property every time. ``port``, ``scheme``, and ``raw_host`` are now cached properties, which will improve performance.
*Related issues and pull requests on GitHub:*
:issue:`1044`, :issue:`1058`.
----
1.9.4 (2023-12-06)
==================
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 ` 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:
.. code-block:: console
$ 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.
The following produces C-files required for the Cython coverage
plugin to map the measurements back to the PYX-files:
.. code-block:: console
$ python -Im pip install -e .
Alternatively, the ``YARL_CYTHON_TRACING=1`` environment variable
can be set to do the same as the :pep:`517` config setting.
:issue:`962`
1.9.3 (2023-11-20)
==================
Bug fixes
---------
- Stopped dropping trailing slashes in :py:meth:`~yarl.URL.joinpath` -- by :user:`gmacon`. (:issue:`862`, :issue:`866`)
- Started accepting string subclasses in :meth:`~yarl.URL.__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`)
1.9.2 (2023-04-25)
==================
Bugfixes
--------
- Fix regression with :meth:`~yarl.URL.__truediv__` and absolute URLs with empty paths causing the raw path to lack the leading ``/``.
(`#854 `_)
1.9.1 (2023-04-21)
==================
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 `_)
1.9.0 (2023-04-19)
==================
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 `_)
- Made :meth:`URL.__truediv__() ` return ``NotImplemented`` if called with an
unsupported type — by :user:`michaeljpeters`.
(`#832 `_)
Bugfixes
--------
- Path 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 `_)
- Made :py:meth:`~yarl.URL.build` raise a :py:exc:`TypeError` if the ``host`` argument is :py:data:`None` — by :user:`paulpapacz`. (`#808 `_)
- Fixed an issue with ``update_query()`` getting rid of the query when the argument
is empty but not ``None``. (`#845 `_)
Misc
----
- `#220 `_
1.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 `_, `#739 `_
1.8.0 (2022-08-01)
==================
Features
--------
- Added ``URL.raw_suffix``, ``URL.suffix``, ``URL.raw_suffixes``, ``URL.suffixes``, ``URL.with_suffix``. (`#613 `_)
Improved Documentation
----------------------
- Fixed broken internal references to :meth:`~yarl.URL.human_repr`.
(`#665 `_)
- Fixed broken external references to :doc:`multidict:index` docs. (`#665 `_)
Deprecations and Removals
-------------------------
- Dropped Python 3.6 support. (`#672 `_)
Misc
----
- `#646 `_, `#699 `_, `#701 `_
1.7.2 (2021-11-01)
==================
Bugfixes
--------
- Changed call in ``with_port()`` to stop reencoding parts of the URL that were already encoded. (`#623 `_)
1.7.1 (2021-10-07)
==================
Bugfixes
--------
- Fix 1.7.0 build error
1.7.0 (2021-10-06)
==================
Features
--------
- Add ``__bytes__()`` magic method so that ``bytes(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 the ``musl`` tag targeting typical Alpine Linux runtimes. (`#622 `_)
- Added support for Python 3.10. (`#622 `_)
1.6.3 (2020-11-14)
==================
Bugfixes
--------
- No longer loose characters when decoding incorrect percent-sequences (like ``%e2%82%f8``). All non-decodable percent-sequences are now preserved.
`#517 `_
- Provide x86 Windows wheels.
`#535 `_
----
1.6.2 (2020-10-12)
==================
Bugfixes
--------
- Provide generated ``.c`` files in TarBall distribution.
`#530 `_
1.6.1 (2020-10-12)
==================
Features
--------
- Provide wheels for ``aarch64``, ``i686``, ``ppc64le``, ``s390x`` architectures on
Linux as well as ``x86_64``.
`#507 `_
- Provide wheels for Python 3.9.
`#526 `_
Bugfixes
--------
- ``human_repr()`` now always produces valid representation equivalent to the original URL (if the original URL is valid).
`#511 `_
- Fixed requoting a single percent followed by a percent-encoded character in the Cython implementation.
`#514 `_
- Fix ValueError when decoding ``%`` which is not followed by two hexadecimal digits.
`#516 `_
- Fix decoding ``%`` followed by a space and hexadecimal digit.
`#520 `_
- Fix annotation of ``with_query()``/``update_query()`` methods for ``key=[val1, val2]`` case.
`#528 `_
Removal
-------
- Drop Python 3.5 support; Python 3.6 is the minimal supported Python version.
----
1.6.0 (2020-09-23)
==================
Features
--------
- Allow for int and float subclasses in query, while still denying bool.
`#492 `_
Bugfixes
--------
- Do not requote arguments in ``URL.build()``, ``with_xxx()`` and in ``/`` operator.
`#502 `_
- Keep IPv6 brackets in ``origin()``.
`#504 `_
----
1.5.1 (2020-08-01)
==================
Bugfixes
--------
- Fix including relocated internal ``yarl._quoting_c`` C-extension into published PyPI dists.
`#485 `_
Misc
----
- `#484 `_
----
1.5.0 (2020-07-26)
==================
Features
--------
- Convert host to lowercase on URL building.
`#386 `_
- Allow using ``mod`` operator (``%``) for updating query string (an alias for ``update_query()`` method).
`#435 `_
- Allow use of sequences such as ``list`` and ``tuple`` in the values
of a mapping such as ``dict`` to 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")
`#443 `_
- Support ``URL.build()`` with scheme and path (creates a relative URL).
`#464 `_
- Cache slow IDNA encode/decode calls.
`#476 `_
- Add ``@final`` / ``Final`` type hints
`#477 `_
- Support URL authority/raw_authority properties and authority argument of ``URL.build()`` method.
`#478 `_
- Hide the library implementation details, make the exposed public list very clean.
`#483 `_
Bugfixes
--------
- Fix tests with newer Python (3.7.6, 3.8.1 and 3.9.0+).
`#409 `_
- Fix a bug where query component, passed in a form of mapping or sequence, is unquoted in unexpected way.
`#426 `_
- Hide ``Query`` and ``QueryVariable`` type aliases in ``__init__.pyi``, now they are prefixed with underscore.
`#431 `_
- Keep IPv6 brackets after updating port/user/password.
`#451 `_
----
1.4.2 (2019-12-05)
==================
Features
--------
- Workaround for missing ``str.isascii()`` in Python 3.6
`#389 `_
----
1.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 of ``URL.build`` (#309)
* Use None as default value of ``user`` parameter of ``URL.build`` (#309)
* Enforce building C Accelerated modules when installing from source tarball, use
``YARL_NO_EXTENSIONS`` environment variable for falling back to (slower) Pure Python
implementation (#329)
* Drop Python 3.5 support
* Fix 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 for ``query`` parameter (#207)
* An incoming query sequence can have int variables (the same as for
Mapping type) (#208)
* Add ``URL.explicit_port`` property (#218)
* Give a friendlier error when port can't be converted to int (#168)
* ``bool(URL())`` now returns ``False`` (#272)
1.2.6 (2018-06-14)
==================
* Drop Python 3.4 trove classifier (#205)
1.2.5 (2018-05-23)
==================
* Fix annotations for ``build`` (#199)
1.2.4 (2018-05-08)
==================
* Fix annotations for ``cached_property`` (#195)
1.2.3 (2018-05-03)
==================
* Accept ``str`` subclasses in ``URL`` constructor (#190)
1.2.2 (2018-05-01)
==================
* Fix build
1.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 empty ``netloc`` (#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 ``_Quoter`` and ``_Unquoter`` classes (#155)
* Drop ``yarl.quote`` and ``yarl.unquote`` public 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)
* Support ``encoded=True`` in ``yarl.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 raising ``TypeError`` by ``url.query_string()`` after
``url.with_query({})`` (empty mapping) (#141)
0.15.0 (2017-11-23)
===================
* Add ``raw_path_qs`` attribute (#137)
0.14.2 (2017-11-14)
===================
* Restore ``strict`` parameter as no-op in ``quote`` / ``unquote``
0.14.1 (2017-11-13)
===================
* Restore ``strict`` parameter as no-op for sake of compatibility with
aiohttp 2.2
0.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)
===================
* Document ``encoded`` parameter (#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 in ``URL.with_path()`` (#90)
* Enable type annotation checks
0.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)
===================
* Added ``URL.build`` class method (#58)
* Added ``path_qs`` attribute (#42)
0.9.8 (2017-02-16)
==================
* Do not quote ``:`` in path
0.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 support
0.9.4 (2017-02-14)
==================
* Use BaseURL
0.9.3 (2017-02-14)
==================
* Added BaseURL
0.9.2 (2017-02-08)
==================
* Remove debug print
0.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)
* Added ``URL.update_path()`` method
* Added ``URL.update_query()`` method (#47)
0.8.1 (2016-12-03)
==================
* Fix broken aiohttp: revert back ``quote`` / ``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 expose ``yarl.quote`` and ``yarl.unquote``, these functions are
part of private API
0.7.1 (2016-11-18)
==================
* Accept not only ``str`` but all classes inherited from ``str`` also (#25)
0.7.0 (2016-11-07)
==================
* Accept ``int`` as value for ``.with_query()``
0.6.0 (2016-11-07)
==================
* Explicitly use UTF8 encoding in :file:`setup.py` (#20)
* Properly unquote non-UTF8 strings (#19)
0.5.3 (2016-11-02)
==================
* Don't use :py:class:`typing.NamedTuple` fields but indexes on URL construction
0.5.2 (2016-11-02)
==================
* Inline ``_encode`` class method
0.5.1 (2016-11-02)
==================
* Make URL construction faster by removing extra classmethod calls
0.5.0 (2016-11-02)
==================
* Add Cython optimization for quoting/unquoting
* Provide binary wheels
0.4.3 (2016-09-29)
==================
* Fix typing stubs
0.4.2 (2016-09-29)
==================
* Expose ``quote()`` and ``unquote()`` as public API
0.4.1 (2016-09-28)
==================
* Support empty values in query (``'/path?arg'``)
0.4.0 (2016-09-27)
==================
* Introduce ``relative()`` (#16)
0.3.2 (2016-09-27)
==================
* Typo fixes #15
0.3.1 (2016-09-26)
==================
* Support sequence of pairs as ``with_query()`` parameter
0.3.0 (2016-09-26)
==================
* Introduce ``is_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)
==================
* Add ``kwargs`` support for ``with_query()`` (#10)
0.1.3 (2016-09-07)
==================
* Document ``with_query()``, ``with_fragment()`` and ``origin()``
* Allow ``None`` for ``with_query()`` and ``with_fragment()``
0.1.2 (2016-09-07)
==================
* Fix links, tune docs theme.
0.1.1 (2016-09-06)
==================
* Update README, old version used obsolete API
0.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.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/LICENSE 0000644 0001751 0000166 00000026136 14774356277 013217 0 ustar 00runner docker
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/MANIFEST.in 0000644 0001751 0000166 00000000566 14774356277 013747 0 ustar 00runner docker include .coveragerc
include pyproject.toml
include pytest.ini
include towncrier.toml
include LICENSE
include NOTICE
include CHANGES.rst
include README.rst
graft yarl
graft packaging
graft docs
graft CHANGES
graft requirements
graft tests
global-exclude *.pyc
global-exclude *.cache
exclude yarl/*.c
exclude yarl/*.html
exclude yarl/*.so
exclude yarl/*.pyd
prune docs/_build
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1743903935.0
yarl-1.19.0/NOTICE 0000644 0001751 0000166 00000001141 14774356277 013103 0 ustar 00runner docker Copyright 2016-2021, Andrew Svetlov and aio-libs team
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1743903941.5992763
yarl-1.19.0/PKG-INFO 0000644 0001751 0000166 00000214113 14774356306 013272 0 ustar 00runner docker Metadata-Version: 2.4
Name: yarl
Version: 1.19.0
Summary: Yet another URL library
Home-page: https://github.com/aio-libs/yarl
Author: Andrew Svetlov
Author-email: andrew.svetlov@gmail.com
Maintainer: aiohttp team
Maintainer-email: team@aiohttp.org
License: Apache-2.0
Project-URL: Chat: Matrix, https://matrix.to/#/#aio-libs:matrix.org
Project-URL: Chat: Matrix Space, https://matrix.to/#/#aio-libs-space:matrix.org
Project-URL: CI: GitHub Workflows, https://github.com/aio-libs/yarl/actions?query=branch:master
Project-URL: Code of Conduct, https://github.com/aio-libs/.github/blob/master/CODE_OF_CONDUCT.md
Project-URL: Coverage: codecov, https://codecov.io/github/aio-libs/yarl
Project-URL: Docs: Changelog, https://yarl.aio-libs.org/en/latest/changes/
Project-URL: Docs: RTD, https://yarl.aio-libs.org
Project-URL: GitHub: issues, https://github.com/aio-libs/yarl/issues
Project-URL: GitHub: repo, https://github.com/aio-libs/yarl
Keywords: cython,cext,yarl
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: NOTICE
Requires-Dist: idna>=2.0
Requires-Dist: multidict>=4.0
Requires-Dist: propcache>=0.2.1
Dynamic: license-file
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
>>> 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
`_ 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.19.0
======
*(2025-04-05)*
Bug fixes
---------
- Fixed entire name being re-encoded when using ``yarl.URL.with_suffix()`` -- by `@NTFSvolume `__.
*Related issues and pull requests on GitHub:*
`#1468 `__.
Features
--------
- Started building armv7l wheels for manylinux -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#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 `__ 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 `__.
- Increased minimum `propcache`_ version to 0.2.1 to fix failing tests -- by `@bdraco `__.
.. _`propcache`:
https://github.com/aio-libs/propcache
*Related issues and pull requests on GitHub:*
`#1479 `__.
- Added all hidden folders to pytest's ``norecursedirs`` to prevent it
from trying to collect tests there -- by `@lysnikolaou `__.
*Related issues and pull requests on GitHub:*
`#1480 `__.
Miscellaneous internal changes
------------------------------
- Improved accuracy of type annotations -- by `@Dreamsorcerer `__.
*Related issues and pull requests on GitHub:*
`#1484 `__.
- Improved performance of parsing query strings -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1493 `__, `#1497 `__.
- Improved performance of the C unquoter -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1496 `__, `#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 `__.
*Related issues and pull requests on GitHub:*
`#954 `__, `#1442 `__.
Miscellaneous internal changes
------------------------------
- Improved performances of multiple path properties on cache miss -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#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 `__.
*Related issues and pull requests on GitHub:*
`#1432 `__.
- Improved cache performance for operations that produce a new ``~yarl.URL`` object -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1434 `__, `#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 `__.
*Related issues and pull requests on GitHub:*
`#111 `__, `#1421 `__.
Contributor-facing changes
--------------------------
- Started running downstream ``aiohttp`` tests in CI -- by `@Cycloctane `__.
*Related issues and pull requests on GitHub:*
`#1415 `__.
Miscellaneous internal changes
------------------------------
- Improved performance of converting ``~yarl.URL`` to a string -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#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 `__ and
`@markgreene74 `__.
*Related issues and pull requests on GitHub:*
`#1411 `__, `#1412 `__.
- Fixed a bug causing ``~yarl.URL.port`` to return the default port when the given port was zero
-- by `@gmacon `__.
*Related issues and pull requests on GitHub:*
`#1413 `__.
Features
--------
- Make error messages include details of incorrect type when ``port`` is not int in ``yarl.URL.build()``.
-- by `@Cycloctane `__.
*Related issues and pull requests on GitHub:*
`#1414 `__.
Packaging updates and notes for downstreams
-------------------------------------------
- Stopped implicitly allowing the use of Cython pre-release versions when
building the distribution package -- by `@ajsanchezsanz `__ and
`@markgreene74 `__.
*Related issues and pull requests on GitHub:*
`#1411 `__, `#1412 `__.
Miscellaneous internal changes
------------------------------
- Improved performance of the ``yarl.URL.joinpath()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1418 `__.
----
1.17.1
======
*(2024-10-30)*
Miscellaneous internal changes
------------------------------
- Improved performance of many ``~yarl.URL`` methods -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1396 `__, `#1397 `__, `#1398 `__.
- Improved performance of passing a `dict` or `str` to ``yarl.URL.extend_query()`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#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 `__.
*Related issues and pull requests on GitHub:*
`#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 `__.
*Related issues and pull requests on GitHub:*
`#1342 `__.
Removals and backward incompatible breaking changes
---------------------------------------------------
- Migrated to using a single cache for encoding hosts -- by `@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 `__, `#1357 `__, `#1363 `__.
Miscellaneous internal changes
------------------------------
- Improved performance of constructing ``~yarl.URL`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1336 `__.
- Improved performance of calling ``yarl.URL.build()`` and constructing unencoded ``~yarl.URL`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1345 `__.
- Reworked the internal encoding cache to improve performance on cache hit -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1369 `__.
----
1.15.5
======
*(2024-10-18)*
Miscellaneous internal changes
------------------------------
- Improved performance of the ``yarl.URL.joinpath()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1304 `__.
- Improved performance of the ``yarl.URL.extend_query()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1305 `__.
- Improved performance of the ``yarl.URL.origin()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1306 `__.
- Improved performance of the ``yarl.URL.with_path()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1307 `__.
- Improved performance of the ``yarl.URL.with_query()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1308 `__, `#1328 `__.
- Improved performance of the ``yarl.URL.update_query()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1309 `__, `#1327 `__.
- Improved performance of the ``yarl.URL.join()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1313 `__.
- Improved performance of ``~yarl.URL`` equality checks -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1315 `__.
- Improved performance of ``~yarl.URL`` methods that modify the network location -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1316 `__.
- Improved performance of the ``yarl.URL.with_fragment()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1317 `__.
- Improved performance of calculating the hash of ``~yarl.URL`` objects -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1318 `__.
- Improved performance of the ``yarl.URL.relative()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1319 `__.
- Improved performance of the ``yarl.URL.with_name()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1320 `__.
- Improved performance of ``~yarl.URL.parent`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1321 `__.
- Improved performance of the ``yarl.URL.with_scheme()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1322 `__.
----
1.15.4
======
*(2024-10-16)*
Miscellaneous internal changes
------------------------------
- Improved performance of the quoter when all characters are safe -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1288 `__.
- Improved performance of unquoting strings -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1292 `__, `#1293 `__.
- Improved performance of calling ``yarl.URL.build()`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#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 `__.
The validation only worked correctly when passing ``host``.
*Related issues and pull requests on GitHub:*
`#1265 `__.
Removals and backward incompatible breaking changes
---------------------------------------------------
- Removed support for Python 3.8 as it has reached end of life -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1203 `__.
Miscellaneous internal changes
------------------------------
- Improved performance of constructing ``~yarl.URL`` when the net location is only the host -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1271 `__.
----
1.15.2
======
*(2024-10-13)*
Miscellaneous internal changes
------------------------------
- Improved performance of converting ``~yarl.URL`` to a string -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1234 `__.
- Improved performance of ``yarl.URL.joinpath()`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1248 `__, `#1250 `__.
- Improved performance of constructing query strings from ``~multidict.MultiDict`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1256 `__.
- Improved performance of constructing query strings with ``int`` values -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1259 `__.
----
1.15.1
======
*(2024-10-12)*
Miscellaneous internal changes
------------------------------
- Improved performance of calling ``yarl.URL.build()`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1222 `__.
- Improved performance of all ``~yarl.URL`` methods that create new ``~yarl.URL`` objects -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1226 `__.
- Improved performance of ``~yarl.URL`` methods that modify the network location -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1229 `__.
----
1.15.0
======
*(2024-10-11)*
Bug fixes
---------
- Fixed validation with ``yarl.URL.with_scheme()`` when passed scheme is not lowercase -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1189 `__.
Features
--------
- Started building ``armv7l`` wheels -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1204 `__.
Miscellaneous internal changes
------------------------------
- Improved performance of constructing unencoded ``~yarl.URL`` objects -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1188 `__.
- Added a cache for parsing hosts to reduce overhead of encoding ``~yarl.URL`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1190 `__.
- Improved performance of constructing query strings from ``~collections.abc.Mapping`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1193 `__.
- Improved performance of converting ``~yarl.URL`` objects to strings -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1198 `__.
----
1.14.0
======
*(2024-10-08)*
Packaging updates and notes for downstreams
-------------------------------------------
- Switched to using the ``propcache`` package for property caching
-- by `@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 `__.
Contributor-facing changes
--------------------------
- Started testing with Hypothesis -- by `@webknjaz `__ and `@bdraco `__.
Special thanks to `@Zac-HD `__ for helping us get started with this framework.
*Related issues and pull requests on GitHub:*
`#860 `__.
Miscellaneous internal changes
------------------------------
- Improved performance of ``yarl.URL.is_default_port()`` when no explicit port is set -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1168 `__.
- Improved performance of converting ``~yarl.URL`` to a string when no explicit port is set -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1170 `__.
- Improved performance of the ``yarl.URL.origin()`` method -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1175 `__.
- Improved performance of encoding hosts -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1176 `__.
----
1.13.1
======
*(2024-09-27)*
Miscellaneous internal changes
------------------------------
- Improved performance of calling ``yarl.URL.build()`` with ``authority`` -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#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 `__.
*Related issues and pull requests on GitHub:*
`#880 `__, `#954 `__.
- Fixed IPv6 addresses missing brackets when the ``~yarl.URL`` was converted to a string -- by `@bdraco `__.
*Related issues and pull requests on GitHub:*
`#1157 `__, `#1158 `__.
Features
--------
- Added ``~yarl.URL.host_subcomponent`` which returns the ``3986#section-3.2.2`` host subcomponent -- by `@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 `__.
----
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 `__.
*Related issues and pull requests on GitHub:*
`#1150