### Requesting Cython Tracing during Install Source: https://github.com/aio-libs/yarl/blob/master/docs/changes.md Illustrates how to request line tracing in Cython builds using PEP 517 config settings during installation. ```console python -Im pip install . --config-settings=with-cython-tracing=true ``` -------------------------------- ### Install Development Dependencies and Run Tests Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md Install development dependencies and build the Cython extension in place, then run the pytest suite for the project. ```bash make .develop pytest ./tests ./yarl ``` -------------------------------- ### Install yarl Source: https://github.com/aio-libs/yarl/blob/master/docs/index.md Install the yarl library using pip. This command installs the default version, which may include compiled extensions. ```bash pip install yarl ``` -------------------------------- ### Install yarl with pure Python build Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Install yarl using pip with the --config-settings=--pure-python=false flag to build the C-extension. This flag is used when building from source. ```console $ python -m pip install . --config-settings=--pure-python=false ``` -------------------------------- ### Install yarl with Pure Python Option Source: https://github.com/aio-libs/yarl/blob/master/README.rst Install yarl using pip with a configuration setting to force the pure-Python implementation, which avoids compilation but is slower. ```console $ pip install yarl --config-settings=pure-python=false ``` -------------------------------- ### Install yarl with Cython tracing enabled Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Install yarl with the --config-settings=with-cython-tracing=true flag to enable line tracing in Cython builds. This is useful for measuring coverage on Cython modules. ```console $ python -Im pip install . --config-settings=with-cython-tracing=true ``` -------------------------------- ### Example Changelog Entry: GenericAliases Support Source: https://github.com/aio-libs/yarl/blob/master/CHANGES/README.rst This is an example of a changelog entry for a feature category, announcing the added support for GenericAliases (MultiDict[str]) in Python 3.9 and higher. It includes an author attribution. ```rst Added support for ``GenericAliases`` (``MultiDict[str]``) under Python 3.9 and higher -- by :user:`mjpieters`. ``` -------------------------------- ### Install yarl with pure Python build using pip Source: https://github.com/aio-libs/yarl/blob/master/docs/changes.md Use this command to install yarl from source, forcing a pure Python build. This is useful for packagers or end-users who need to build from source. ```console $ python -m pip install . --config-settings=--pure-python=false ``` -------------------------------- ### Example Bugfix News Fragment Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md This is an example of a news fragment file for a bugfix. It uses reStructuredText and includes a signature. The filename indicates the PR number and category. ```rst Rejected URLs containing text before the opening bracket in the host component (e.g. ``http://127.0.0.1[aa::ff]``), which were previously parsed by silently dropping the prefix -- by :user:`github-handle`. ``` -------------------------------- ### Example Changelog Entry: Dropped Python 3.5 Support Source: https://github.com/aio-libs/yarl/blob/master/CHANGES/README.rst This is an example of a changelog entry for a removal category, indicating the dropping of Python 3.5 support. It uses reStructuredText syntax and includes an author attribution. ```rst Dropped Python 3.5 support; Python 3.6 is the minimal supported Python version -- by :user:`webknjaz`. ``` -------------------------------- ### Example Changelog Entry: Shipping Windows Wheels Source: https://github.com/aio-libs/yarl/blob/master/CHANGES/README.rst This is an example of a changelog entry for a bugfix category, noting the addition of Windows wheels for the x86 architecture. It includes an author attribution. ```rst Started shipping Windows wheels for the x86 architecture -- by :user:`Dreamsorcerer`. ``` -------------------------------- ### aio-libs Pull Request Template Example Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md This markdown snippet shows the required structure for pull request bodies in the yarl repository. Ensure all sections are filled out verbatim. ```markdown ## What do these changes do? ## Are there changes in behavior for the user? ## Is it a substantial burden for the maintainers to support this? ## Related issue number Fixes #NNNN ## Checklist - [x] I think the code is well written - [x] Unit tests for the changes exist - [x] Documentation reflects the changes - [ ] If you provide code modification, please add yourself to `CONTRIBUTORS.txt` - [x] Add a new news fragment into the `CHANGES/` folder ``` -------------------------------- ### Install yarl with editable mode for Cython coverage Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Install yarl in editable mode to enable Cython coverage collection. This produces C-files needed for the Cython coverage plugin. ```console $ python -Im pip install -e . ``` -------------------------------- ### Human Readable URL Representation Source: https://github.com/aio-libs/yarl/blob/master/docs/index.md Demonstrates how to get a human-readable string representation of a URL object using the `human_repr()` method. ```python from yarl import URL url = URL('http://example.com/path?query=value#fragment') print(url.human_repr()) # http://example.com/path?query=value#fragment ``` -------------------------------- ### Build Documentation Locally Source: https://github.com/aio-libs/yarl/blob/master/docs/contributing/guidelines.md Execute this command to build the documentation website locally using Sphinx. ```shell $ make doc ``` -------------------------------- ### PEP 517 Build Configuration Source: https://github.com/aio-libs/yarl/blob/master/docs/changes.md Demonstrates how to configure PEP 517 in-tree build backend settings, specifically for pure Python and Cython tracing. ```console python -m build \ --config-setting=pure-python=true \ --config-setting=with-cython-tracing=true ``` -------------------------------- ### In-tree Build Backend Configuration Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Illustrates the updated syntax for PEP 517 in-tree build backend configuration, removing leading dashes. ```console $ python -m build \ ``` -------------------------------- ### Enabling Cython Tracing via Environment Variable Source: https://github.com/aio-libs/yarl/blob/master/docs/changes.md Demonstrates how to enable Cython tracing using an environment variable, equivalent to the PEP 517 config setting. ```console YARL_CYTHON_TRACING=1 ``` -------------------------------- ### Build yarl wheel with pypa/build Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Use pypa/build to create a wheel directly from source by passing the --config-setting=--pure-python=false flag. The -w or --wheel flag can be added to force wheel production. ```console $ python -m build --config-setting=--pure-python=false ``` -------------------------------- ### URL.build Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Creates and returns a new URL instance with specified components. ```APIDOC #### *classmethod* URL.build(, scheme=..., authority=..., user=..., password=..., host=..., port=..., path=..., query=..., query_string=..., fragment=..., encoded=False) Creates and returns a new URL: Calling `build` method without arguments is equal to calling `__init__` without arguments. #### NOTE Only one of `query` or `query_string` should be passed then ValueError will be raised. ``` -------------------------------- ### URL.absolute Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md A check for absolute URLs. Returns True for absolute ones (having scheme or starting with '//'), False otherwise. ```APIDOC #### URL.absolute > A check for absolute URLs. > Return `True` for absolute ones (having *scheme* or starting > with `'//'`), `False` otherwise. #### Versionchanged Changed in version 1.9.10: The [`absolute`](#yarl.URL.absolute) property is preferred over the `is_absolute()` method. ``` -------------------------------- ### URL Properties: Scheme Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Access the scheme of an absolute URL. For relative URLs or URLs starting with '//', this property returns an empty string. ```python from yarl import URL url = URL('http://example.com/path') print(url.scheme) # Output: http url_relative = URL('/path') print(url_relative.scheme) # Output: ``` -------------------------------- ### Build yarl with pure Python build using pypa/build Source: https://github.com/aio-libs/yarl/blob/master/docs/changes.md Use this command with the pypa/build tool to create a distribution package for yarl, ensuring a pure Python build. The --pure-python=false flag forces the C-extension to be built. ```console $ python -m build --config-setting=--pure-python=false ``` -------------------------------- ### Run Lint and Pytest Suite Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md Execute the Makefile target to run both linting and the pytest suite. ```bash make test ``` -------------------------------- ### URL with multiple query values Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Demonstrates how to represent a key with multiple values in a URL's query string using a list or tuple. ```python url = URL("http://example.com") assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2") ``` -------------------------------- ### URL.origin() Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Returns a new URL containing only the scheme, host, and port parts. The user, password, path, query, and fragment are removed. ```APIDOC ## URL.origin() ### Description A new URL with *scheme*, *host* and *port* parts only. *user*, *password*, *path*, *query* and *fragment* are removed. ``` -------------------------------- ### Build wheel in-tree with PEP 517 Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Use this setting to control whether to build the project in-tree or in a temporary directory. It only affects wheels and is set up to build in a temporary directory by default. Editable wheel builds will keep being built in-tree regardless. ```console python -m build \ --config-setting=build-inplace=true ``` -------------------------------- ### URL.__truediv__(url) Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Shortcut for URL.joinpath() with a single element and encoded=False. ```APIDOC ## URL.__truediv__(url) ### Description Shortcut for [`URL.joinpath()`](#yarl.URL.joinpath) with a single element and `encoded=False`. ``` -------------------------------- ### Create URL Object from String Source: https://github.com/aio-libs/yarl/blob/master/README.rst Instantiate a URL object by passing a string representation of the URL to the URL constructor. ```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') ``` -------------------------------- ### URL Joining with Relative Path Source: https://github.com/aio-libs/yarl/blob/master/docs/changes.md Shows how URL.join() now matches RFC 3986 by making URLs with schemes relative, prefixing with './'. ```python >>> 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') ``` -------------------------------- ### Run Pre-commit Across Tree Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md Execute the Makefile target to run pre-commit hooks across the entire project tree for formatting and style checks. ```bash make fmt ``` -------------------------------- ### URL.path_qs Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Provides the decoded path part of the URL along with the query string. ```APIDOC #### URL.path_qs Decoded *path* part of URL and query string, `'/'` for absolute URLs without *path* part. ``` -------------------------------- ### Run Documentation Spell Check Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md Execute the documentation spell check command before pushing changes to ensure all technical terms are recognized or added to the wordlist. ```bash make doc-spelling ``` -------------------------------- ### URL.relative() Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Creates a new relative URL with only path, query, and fragment parts. Scheme, user, password, host, and port are removed. The division operator '/' appends path parts and cleans query/fragment. ```APIDOC ## URL.relative() ### Description A new *relative* URL with *path*, *query* and *fragment* parts only. *scheme*, *user*, *password*, *host* and *port* are removed. Division (`/`) operator creates a new URL with appended *path* parts and cleaned up *query* and *fragment* parts. The path is encoded if needed. ``` -------------------------------- ### URL.raw_path_qs Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Provides the encoded path part of the URL along with the query string. ```APIDOC #### URL.raw_path_qs Encoded *path* part of URL and query string, `'/'` for absolute URLs without *path* part. #### Versionadded Added in version 0.15. ``` -------------------------------- ### URL.raw_suffixes Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md A list of file extensions for the URL's raw name. ```APIDOC #### URL.raw_suffixes A list of [`raw_name`](#yarl.URL.raw_name)’s file extensions. ``` -------------------------------- ### URL.suffixes Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md A list of file extensions for the URL's name. ```APIDOC #### URL.suffixes A list of [`name`](#yarl.URL.name)’s file extensions. ``` -------------------------------- ### Create GPG-Signed Git Tag Source: https://github.com/aio-libs/yarl/blob/master/docs/contributing/release_guide.md Tag the release commit with a version number that includes a leading 'v'. The tag should be GPG-signed and include a descriptive message. ```shell git tag \ -s 'VERSION_WITH_LEADING_V' \ -m 'VERSION_WITH_LEADING_V' \ -m 'This release does X and Y.' ``` -------------------------------- ### Commit Version and Changelog Changes Source: https://github.com/aio-libs/yarl/blob/master/docs/contributing/release_guide.md Commit the updated yarl/__init__.py file, the generated CHANGES.rst, and any removed changelog fragments. ```shell [dir:yarl] $ git commit -v CHANGES{.rst,/} yarl/__init__.py ``` -------------------------------- ### Build Changelog with Towncrier Source: https://github.com/aio-libs/yarl/blob/master/docs/contributing/release_guide.md Use Towncrier to build the changelog from fragments and commit changes. Ensure the version number does not have a leading 'v' and follows PEP 440. ```shell [dir:yarl] $ python -m towncrier build \ -- --version 'VERSION_WITHOUT_LEADING_V' ``` -------------------------------- ### URL.join(url) Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Constructs a full absolute URL by combining a base URL (self) with another URL (url). It uses components of the base URL to provide missing components in the relative URL. ```APIDOC ## URL.join(url) ### Description Construct a full (“absolute”) URL by combining a “base URL” (`self`) with another URL (`url`). Informally, this uses components of the base URL, in particular the addressing scheme, the network location and (part of) the path, to provide missing components in the relative URL, e.g.: #### NOTE If `url` is an absolute URL (that is, starting with `//` or `scheme://`), the URL‘s host name and/or scheme will be present in the result, e.g.: ``` -------------------------------- ### URL Path Joining with Empty Segments Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Illustrates how the '/' operator and URL.joinpath() handle joining URLs with empty segments, preserving them in the base path. ```python URL("https://web.archive.org/web/") / "https://github.com/" ``` -------------------------------- ### URL Joining with Empty Segments Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Demonstrates how URL.join() handles joining URLs with empty segments, aligning with RFC 3986. ```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') ``` ```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') ``` -------------------------------- ### URL Joining with Empty Segments in Base and Joined Part Source: https://github.com/aio-libs/yarl/blob/master/docs/changes.md Demonstrates that empty segments are honored in both the base URL and the part being joined. ```python >>> 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') ``` -------------------------------- ### Optional Agent Run Details in PR Footer Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md Agent output, such as test or lint results, should be placed in a collapsed
block at the very bottom of the PR body, below the human-readable summary. ```markdown
Agent run details (optional, for reviewers) Tests: Lint:
``` -------------------------------- ### URL.with_path Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Returns a new URL with the path replaced, encoding the path if needed. Optionally keeps the existing query or fragment. ```APIDOC #### URL.with_path(path, , keep_query=False, keep_fragment=False) Return a new URL with *path* replaced, encode *path* if needed. If `keep_query=True` or `keep_fragment=True` it retains the existing query or fragment in the URL. #### Versionchanged Changed in version 1.18: Added *keep_query* and *keep_fragment* parameters. ``` -------------------------------- ### Building URL with String Port Source: https://github.com/aio-libs/yarl/blob/master/CHANGES.rst Shows that passing a string value to the 'port' argument of URL.build now raises a TypeError. ```python URL("https://example.org/") / "" ``` -------------------------------- ### yarl.cache_configure() Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Sets the cache sizes for IDNA encode, IDNA decode, and host encode operations. Caches can be made unbounded by passing None. ```APIDOC ### yarl.cache_configure(, idna_encode_size=256, idna_decode_size=256, encode_host_size=512) Set the IDNA encode, IDNA decode, and host encode cache sizes. Pass `None` to make the corresponding cache unbounded (may speed up host encoding operation a little but the memory footprint can be very high, please use with caution). ``` -------------------------------- ### Push Git Tag to Upstream Source: https://github.com/aio-libs/yarl/blob/master/docs/contributing/release_guide.md Push the newly created GPG-signed Git tag to the upstream repository, typically named 'origin'. ```shell git push origin 'VERSION_WITH_LEADING_V' ``` -------------------------------- ### URL.with_scheme Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Returns a new URL with the scheme replaced. The port may change due to default port substitution. ```APIDOC #### URL.with_scheme(scheme) Return a new URL with *scheme* replaced: Returned URL may have a *different* `port` ([default port substitution](#yarl-api-default-ports)). ``` -------------------------------- ### URL.with_port Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Returns a new URL with the port replaced. Clears port to default if None is passed. ```APIDOC #### URL.with_port(port) Return a new URL with *port* replaced. Clear port to default if `None` is passed. ``` -------------------------------- ### URL Structure Representation Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Illustrates the structure of absolute and relative URLs as understood by yarl, including scheme, host, port, path, query, and fragment. ```default [scheme:]//[user[:password]@]host[:port][/path][?query][#fragment] ``` ```default [/path][?query][#fragment] ``` ```default http://user:pass@example.com:8042/over/there?name=ferret#nose \__/ \__/ \__/ \_________/ \__/ ``` -------------------------------- ### Run Pytest with Coverage Source: https://github.com/aio-libs/yarl/blob/master/AGENTS.md Execute the Makefile target to run pytest with coverage enabled. ```bash make cov ``` -------------------------------- ### yarl.cache_info() Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Returns a dictionary with cache information for IDNA encoding/decoding and host encoding. ```APIDOC ### yarl.cache_info() Return a dictionary with `"idna_encode"`, `"idna_decode"`, and `"encode_host"` keys, each value points to corresponding `CacheInfo` structure (see `functools.lru_cache()` for details): ``` -------------------------------- ### URL.human_repr() Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Provides a human-readable representation of the URL. ```APIDOC ## URL.human_repr() ### Description Returns a human-readable representation of the URL. This method is useful for displaying URLs in a format that is easy for users to understand. ### Method `human_repr()` ### Parameters None ### Request Example ```python from yarl import URL url = URL('http://example.com/path?query=value#fragment') human_readable = url.human_repr() print(human_readable) # http://example.com/path?query=value#fragment ``` ### Response #### Success Response (str) - **str**: A human-readable string representation of the URL. ``` -------------------------------- ### URL.with_user Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Returns a new URL with the user replaced, auto-encoding the user if needed. Clears user/password if user is None. ```APIDOC #### URL.with_user(user) Return a new URL with *user* replaced, auto-encode *user* if needed. Clear user/password if *user* is `None`. ``` -------------------------------- ### URL.joinpath(*other, encoded=False) Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md Constructs a new URL by appending all `other` elements to the path, and cleaning up query and fragment parts. The `encoded` parameter controls auto-encoding of path elements. ```APIDOC ## URL.joinpath(*other, encoded=False) ### Description Construct a new URL by with all `other` elements appended to *path*, and cleaned up *query* and *fragment* parts. Passing `encoded=True` parameter prevents path element auto-encoding, the caller is responsible for taking care of URL correctness. ``` -------------------------------- ### URL.suffix Source: https://github.com/aio-libs/yarl/blob/master/docs/api.md The file extension of the URL's name. ```APIDOC #### URL.suffix The file extension of [`name`](#yarl.URL.name). ```