yarl

https://yarl.aio-libs.org/en/latest
Admin
yarl is a Python library that provides a handy URL class for parsing, manipulating, and generating...
Tokens:76,180
Snippets:435
Trust Score:6.1
Update:10 months ago
Show doc for...
Tokens:
Raw
### Installing yarl with Pip

Source: https://yarl.aio-libs.org/en/latest/_sources/index.rst

Provides the command-line instruction to install the yarl library using pip. It also mentions the option to disable C extensions for environments where compilation is problematic.

```console
pip install yarl

pip install yarl --config-settings=pure-python=false
```

--------------------------------

### Installing yarl using pip

Source: https://yarl.aio-libs.org/en/latest/index

Provides the command-line instruction for installing the yarl library using pip. It also mentions that yarl is Python 3 only and that binary wheels are available for common operating systems.

```bash
$ pip install yarl
```

--------------------------------

### Installing yarl with Pure-Python Fallback

Source: https://yarl.aio-libs.org/en/latest/index

Shows how to install yarl while opting out of C extension compilation, forcing a pure-Python installation. This is useful for systems where compilation is not possible or desired, though it results in slower performance.

```bash
$ pip install yarl --config-settings=pure-python=false
```

--------------------------------

### Build Documentation Locally with Sphinx

Source: https://yarl.aio-libs.org/en/latest/_sources/contributing/guidelines.rst

This command triggers the local generation of the project's documentation website using Sphinx. Ensure you have the necessary build tools and dependencies installed.

```shell
make doc
```

--------------------------------

### Get URL Origin

Source: https://yarl.aio-libs.org/en/latest/api

Returns a new URL containing only the scheme, host, and port parts. User, password, path, query, and fragment are removed.

```python
URL('http://example.com/path/to?arg#frag').origin()
URL('http://example.com')
URL('http://user:pass@example.com/path').origin()
URL('http://example.com')
```

--------------------------------

### Create and Represent URLs with yarl

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Demonstrates the creation of URL objects from strings and their string representation. Shows how yarl handles encoding for non-ASCII characters automatically, and how to get a human-readable representation.

```python
from yarl import URL

# Creating a URL object
url_ascii = URL('http://example.com/path/to/?arg1=a&arg2=b#fragment')
print(url_ascii)

# URL with non-ASCII characters, yarl automatically encodes them
url_non_ascii = URL('http://εμπορικόσήμα.eu/шлях/這裡')
print(str(url_non_ascii))

# Already encoded URL is not changed
encoded_url = URL('http://xn--jxagkqfkduily1i.eu')
print(encoded_url)

# Getting a human-readable representation
print(url_non_ascii.human_repr())
```

--------------------------------

### Construct and Represent URL Objects

Source: https://yarl.aio-libs.org/en/latest/api

Examples of creating `URL` objects from strings and their string representations. It highlights how the library handles standard URL formats and automatic encoding for non-ASCII characters.

```python
>>> URL('http://example.com/path/to/?arg1=a&arg2=b#fragment')
URL('http://example.com/path/to/?arg1=a&arg2=b#fragment')
>>> str(URL('http://εμπορικόσήμα.eu/шлях/這裡'))
'http://xn--jxagkqfkduily1i.eu/%D1%88%D0%BB%D1%8F%D1%85/%E9%80%99%E8%A3%A1'
>>> URL('http://xn--jxagkqfkduily1i.eu')
URL('http://xn--jxagkqfkduily1i.eu')
```

--------------------------------

### URL Building with C Extensions

Source: https://yarl.aio-libs.org/en/latest/changes

Enforces the building of C Accelerated modules when installing from a source tarball. The `YARL_NO_EXTENSIONS` environment variable can be used to fall back to a slower Pure Python implementation.

```python
# Example demonstrating YARL_NO_EXTENSIONS for C extension fallback
# (Specific code not provided in text, but functionality described)

```

--------------------------------

### URL Parsing with Relative Path Segment

Source: https://yarl.aio-libs.org/en/latest/changes

Illustrates support for relative URLs, such as those starting with a query string like `'?key=value'`. This allows for parsing and handling URLs that might not have a full scheme and authority.

```python
# Example demonstrating support for relative URLs like '?key=value'
# (Specific code not provided in text, but functionality described)

```

--------------------------------

### Get List of Raw URL File Suffixes

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Returns a tuple of URL-encoded file extensions from the last path segment. Handles multiple extensions and supports inspecting the raw encoded suffixes.

```python
from yarl import URL

url = URL('http://example.com/шлях.тут.ось')
print(url.raw_suffixes)  # Output: ('.%D1%82%D1%83%D1%82', '.%D0%BE%D1%81%D1%8C')
```

--------------------------------

### Get URL Scheme

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the scheme of a URL. Returns an empty string for relative URLs or those starting with '//'.

```python
from yarl import URL

print(URL('http://example.com').scheme)
print(URL('//example.com').scheme)
print(URL('page.html').scheme)
```

--------------------------------

### Get URL Scheme

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Retrieves the scheme component of an absolute URL. For relative URLs or URLs starting with '//', an empty string is returned. The scheme is accessed via the `_scheme` attribute.

```python
@cached_property
def scheme(self) -> str:
    """Scheme for absolute URLs.

    Empty string for relative URLs or URLs starting with //

    """
    return self._scheme
```

--------------------------------

### Get Human-Readable URL Representation

Source: https://yarl.aio-libs.org/en/latest/api

Demonstrates the use of the `human_repr()` method on a `URL` object to get a human-readable representation, which decodes percent-encoded characters for display purposes, contrasting with the default string representation.

```python
>>> url = URL('http://εμπορικόσήμα.eu/шлях/這裡')
>>> str(url)
'http://xn--jxagkqfkduily1i.eu/%D1%88%D0%BB%D1%8F%D1%85/%E9%80%99%E8%A3%A1'
>>> url.human_repr()
'http://εμπορικόσήμα.eu/шлях/這裡'
```

--------------------------------

### PEP 517 Build Backend Configuration Example

Source: https://yarl.aio-libs.org/en/latest/changes

Demonstrates how to configure PEP 517 build backend settings for yarl, specifically for enabling or disabling pure-python builds and Cython tracing. This is useful for developers and packagers to control the build process and optimize for specific environments or debugging needs.

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

```bash
python -Im pip install -e .

```

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

```

```bash
python -Im pip install -e .

```

```bash
python -m pip install . --config-settings=--pure-python=false

```

```bash
python -m build --config-setting=--pure-python=false

```

--------------------------------

### Create and Sign Git Tag for Release

Source: https://yarl.aio-libs.org/en/latest/_sources/contributing/release_guide.rst

This command creates a GPG-signed Git tag for a new release. The tag name should be the version number prefixed with 'v'. It also includes a commit message describing the release contents. This is a key step in the release process, marking the specific commit for the new version.

```shell-session
[dir:yarl] $ git tag \
               -s 'VERSION_WITH_LEADING_V' \
               -m 'VERSION_WITH_LEADING_V' \
               -m 'This release does X and Y.'
```

--------------------------------

### URL Path Manipulation

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Provides a method to get a new URL with the last part of the path removed.

```APIDOC
## URL Path Manipulation

### Description
Provides a method to derive a parent URL.

### Methods
#### `parent` (getter)
- **Returns**: `URL` - A new URL with the last part of the path removed, and cleaned up query and fragment.
```

--------------------------------

### Build and Commit Changelog and Version

Source: https://yarl.aio-libs.org/en/latest/_sources/contributing/release_guide.rst

This snippet demonstrates how to use the 'towncrier' tool to build the changelog from fragments and update the version string in `yarl/__init__.py`. It then commits these changes along with the removal of changelog fragments. This process is crucial for preparing a new release according to PEP 440 versioning.

```shell-session
[dir:yarl] $ yarl/__init__.py
[dir:yarl] $ python -m towncrier build \
               -- --version 'VERSION_WITHOUT_LEADING_V'
[dir:yarl] $ git commit -v CHANGES{.rst,/} yarl/__init__.py
```

--------------------------------

### Push Git Tag to Upstream Repository

Source: https://yarl.aio-libs.org/en/latest/_sources/contributing/release_guide.rst

This command pushes the newly created Git tag to the upstream repository, typically named 'origin'. Pushing the tag makes the release available on the remote repository and is necessary for the CI/CD pipeline to pick up the release.

```shell-session
[dir:yarl] $ git push origin 'VERSION_WITH_LEADING_V'
```

--------------------------------

### Get Encoded URL Password

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the encoded password part of a URL. Returns None if the password is missing.

```python
from yarl import URL

print(URL('http://user:пароль@example.com').raw_password)
```

--------------------------------

### URL Construction and Basic Properties

Source: https://yarl.aio-libs.org/en/latest/_sources/index.rst

Demonstrates how to create a URL object from a string and access its fundamental components like scheme, host, path, query string, and fragment. It highlights that URL manipulations produce new objects.

```python
from yarl import URL

url = URL('https://www.python.org/~guido?arg=1#frag')

print(url.scheme)
print(url.host)
print(url.path)
print(url.query_string)
print(url.query)
print(url.fragment)
```

--------------------------------

### Get Decoded URL Password

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the decoded password part of a URL. Returns None if the password is missing.

```python
from yarl import URL

print(URL('http://john:pass@example.com').password)
print(URL('http://степан:пароль@example.com').password)
print(URL('http://example.com').password is None)
```

--------------------------------

### Build Project In-Tree with Python Build Backend

Source: https://yarl.aio-libs.org/en/latest/changes

Demonstrates how to use the Python 'build' module to configure the build backend to create artifacts in-tree. This is useful for controlling build behavior and can affect wheel generation. It requires the 'build' package to be installed.

```bash
python -m build \
    --config-setting=build-inplace=true

```

--------------------------------

### Get Encoded URL User

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the encoded user part of a URL. Returns None if the user is missing.

```python
from yarl import URL

print(URL('http://довбуш@example.com').raw_user)
print(URL('http://example.com').raw_user is None)
```

--------------------------------

### URL Building with Sequence Values

Source: https://yarl.aio-libs.org/en/latest/changes

Demonstrates how to use sequences (lists or tuples) as values for query string parameters when building URLs. This allows a single key to have multiple associated values in the query string. The example uses the `URL` class and its `with_query` method.

```python
from yarl import URL

url = URL("http://example.com")
assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2")

```

--------------------------------

### Get Decoded URL User

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the decoded user part of a URL. Returns None if the user is missing.

```python
from yarl import URL

print(URL('http://john@example.com').user)
print(URL('http://бажан@example.com').user)
print(URL('http://example.com').user is None)
```

--------------------------------

### URL Building with Scheme and Path

Source: https://yarl.aio-libs.org/en/latest/changes

Illustrates the use of the `URL.build()` method to construct a relative URL by providing only the scheme and path components. This is useful for creating URLs that do not require a full authority or query string.

```python
# Example demonstrating URL.build() with scheme and path
# (Specific code not provided in text, but functionality described)

```

--------------------------------

### URL.scheme

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the scheme of an absolute URL. For relative URLs or URLs starting with '//', it returns an empty string.

```APIDOC
## URL.scheme

### Description
Scheme for absolute URLs, empty string for relative URLs or URLs starting with `'//'`.

### Method
GET

### Endpoint
N/A (Property Access)

### Parameters
None

### Request Example
```python
from yarl import URL

url1 = URL('http://example.com')
print(url1.scheme)  # Output: 'http'

url2 = URL('//example.com')
print(url2.scheme)  # Output: ''

url3 = URL('page.html')
print(url3.scheme)  # Output: ''
```

### Response
#### Success Response (200)
- **scheme** (string) - The scheme of the URL, or an empty string.
```

--------------------------------

### Get IDNA Decoded URL Host

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the IDNA decoded host part of a URL. Returns None for relative URLs.

```python
from yarl import URL

print(URL('http://хост.домен').raw_host)
print(URL('http://[::1]').raw_host)
```

--------------------------------

### URL Constructor and Initialization Logic

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Handles the logic for initializing a URL object from various input types, including SplitResult, strings, and UNDEFINED. It includes checks for encoding and raises TypeErrors for invalid input types.

```python
if type(val) is SplitResult:
            if not encoded:
                raise ValueError("Cannot apply decoding to SplitResult")
            return from_parts(*val)
        if isinstance(val, str):
            return pre_encoded_url(str(val)) if encoded else encode_url(str(val))
        if val is UNDEFINED:
            # Special case for UNDEFINED since it might be unpickling and we do
            # not want to cache as the `__set_state__` call would mutate the URL
            # object in the `pre_encoded_url` or `encoded_url` caches.
            self = object.__new__(URL)
            self._scheme = self._netloc = self._path = self._query = self._fragment = ""
            self._cache = {}
            return self
        raise TypeError("Constructor parameter should be str")
```

--------------------------------

### Get Encoded URL Fragment

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Returns the raw, encoded fragment identifier of the URL. If the URL does not contain a fragment, an empty string is returned.

```Python
@cached_property
def raw_fragment(self) -> str:
        """Encoded fragment part of URL.

        Empty string if fragment is missing.

        """
        return self._fragment
```

--------------------------------

### URL Joining Logic (Python)

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

This method constructs a full URL by combining a base URL (self) with another URL. It prioritizes the provided URL's scheme, network location, path, query, and fragment, falling back to the base URL's components when necessary. It handles relative paths and normalizes the resulting path.

```python
def join(self, url: "URL") -> "URL":
        """Join URLs

        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.

        """
        if type(url) is not URL:
            raise TypeError("url should be URL")

        scheme = url._scheme or self._scheme
        if scheme != self._scheme or scheme not in USES_RELATIVE:
            return url

        # scheme is in uses_authority as uses_authority is a superset of uses_relative
        if (join_netloc := url._netloc) and scheme in USES_AUTHORITY:
            return from_parts(scheme, join_netloc, url._path, url._query, url._fragment)

        orig_path = self._path
        if join_path := url._path:
            if join_path[0] == "/":
                path = join_path
            elif not orig_path:
                path = f"/{join_path}"
            elif orig_path[-1] == "/":
                path = f"{orig_path}{join_path}"
            else:
                # …
                # and relativizing ".."
                # parts[0] is / for absolute urls,
                # this join will add a double slash there
                path = "/".join([*self.parts[:-1], ""]) + join_path
                # which has to be removed
                if orig_path[0] == "/":
                    path = path[1:]
            path = normalize_path(path) if "." in path else path
        else:
            path = orig_path

        return from_parts(
            scheme,
            self._netloc,
            path,
            url._query if join_path or url._query else self._query,
            url._fragment if join_path or url._fragment else self._fragment,
        )
```

--------------------------------

### Build New URL - Python

Source: https://yarl.aio-libs.org/en/latest/api

Creates a new URL instance using the `build` class method. It allows specifying various URL components like scheme, host, and query parameters. Invalid combinations of query and query_string will raise a ValueError. Calling `build` without arguments is equivalent to `__init__`.

```python
>>> from yarl import URL
>>> URL.build(scheme="http", host="example.com")
URL('http://example.com')

>>> URL.build(scheme="http", host="example.com", query={"a": "b"})
URL('http://example.com/?a=b')

>>> URL.build(scheme="http", host="example.com", query_string="a=b")
URL('http://example.com/?a=b')

>>> URL.build()
URL('')
```

--------------------------------

### Get Encoded URL Password

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Retrieves the raw, encoded password part of the URL. Returns None if the password is missing. The result is cached.

```python
@cached_property
def raw_password(self) -> Union[str, None]:
    """Encoded password part of URL.

    None if password is missing.

    """
    self._cache_netloc()
    return self._cache["raw_password"]
```

--------------------------------

### URL Builder API

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

This section details the `build` class method used to construct a new URL object.

```APIDOC
## POST /websites/yarl_aio-libs_en/build

### Description
Constructs and returns a new URL object based on provided components.

### Method
POST

### Endpoint
/websites/yarl_aio-libs_en/build

### Parameters
#### Query Parameters
- **scheme** (str) - Optional - The scheme of the URL (e.g., 'http', 'https').
- **authority** (str) - Optional - The authority part of the URL (e.g., 'user:pass@host:port'). Cannot be used with user, password, host, or port.
- **user** (str) - Optional - The username for authentication.
- **password** (str) - Optional - The password for authentication.
- **host** (str) - Optional - The hostname of the URL.
- **port** (int) - Optional - The port number.
- **path** (str) - Optional - The path component of the URL.
- **query** (Query) - Optional - A Query object representing the query parameters.
- **query_string** (str) - Optional - A string representation of the query parameters. Cannot be used with 'query'.
- **fragment** (str) - Optional - The fragment identifier of the URL.
- **encoded** (bool) - Optional - If true, the URL components will be pre-encoded.

### Request Example
```json
{
  "scheme": "https",
  "host": "www.example.com",
  "path": "/path/to/resource",
  "query_string": "key=value",
  "fragment": "section"
}
```

### Response
#### Success Response (200)
- **URL** (object) - The constructed URL object.

#### Response Example
```json
{
  "url": "https://www.example.com/path/to/resource?key=value#section"
}
```

### Errors
- **ValueError**: If 'authority' is used with 'user', 'password', 'host', or 'port'.
- **ValueError**: If 'port' is provided without 'host'.
- **ValueError**: If both 'query' and 'query_string' are provided.
- **TypeError**: If 'port' is not an integer.
- **TypeError**: If 'scheme', 'authority', 'host', 'path', 'query_string', or 'fragment' is None.
```

--------------------------------

### Get URL Parent Path

Source: https://yarl.aio-libs.org/en/latest/api

Returns a new URL with the last part of the path removed. It also cleans up the query and fragment parts.

```python
URL('http://example.com/path/to?arg#frag').parent
URL('http://example.com/path')
```

--------------------------------

### Get Decoded URL Path

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the decoded path part of a URL. Returns '/' for absolute URLs without a path part.

```python
from yarl import URL

print(URL('http://example.com/path/to').path)
print(URL('http://example.com/шлях/сюди').path)
print(URL('http://example.com').path)
```

--------------------------------

### URL Building with `URL.build` Annotations

Source: https://yarl.aio-libs.org/en/latest/changes

Fixes annotations for optional parameters of the `URL.build` method and uses `None` as the default value for the `user` parameter. This improves type hinting and parameter handling.

```python
# Example demonstrating fixed annotations and default user for URL.build
# (Specific code not provided in text, but functionality described)

```

--------------------------------

### Get Fragment Part of a URL

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Retrieves the fragment part of a URL. Returns an empty string if the fragment is missing. Supports Unicode characters in the fragment.

```python
from yarl import URL

url1 = URL('http://example.com/path#fragment')
print(url1.fragment)  # Output: 'fragment'

url2 = URL('http://example.com/path#якір')
print(url2.fragment)  # Output: 'якір'

url3 = URL('http://example.com/path')
print(url3.fragment)  # Output: ''
```

--------------------------------

### URL.origin

Source: https://yarl.aio-libs.org/en/latest/api

Returns a new URL containing only the scheme, host, and port parts. User, password, path, query, and fragment are removed.

```APIDOC
## URL.origin

### Description
Returns a new URL with only the scheme, host, and port parts. User, password, path, query, and fragment are removed.

### Method
`origin()`

### Endpoint
N/A (Method on URL object)

### Request Example
```python
from yarl import URL

url1 = URL('http://example.com/path/to?arg#frag')
origin1 = url1.origin()
# origin1 is URL('http://example.com')

url2 = URL('http://user:pass@example.com/path')
origin2 = url2.origin()
# origin2 is URL('http://example.com')
```

### Response
#### Success Response (URL object)
- **URL object** - A new URL instance representing the origin of the original URL.
```

--------------------------------

### Check if a URL is Absolute

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Determines if a URL is absolute. Returns True if the URL has a scheme or starts with '//', False otherwise. This is the preferred method over `is_absolute()`.

```python
from yarl import URL

print(URL('http://example.com').absolute)  # Output: True
print(URL('//example.com').absolute)  # Output: True
print(URL('/path/to').absolute)  # Output: False
print(URL('path').absolute)  # Output: False
```

--------------------------------

### Get Human-Readable URL Representation

Source: https://yarl.aio-libs.org/en/latest/api

Returns a decoded, human-readable string representation of the URL. This is useful because URL data is stored internally in an encoded form.

```python
url = URL('http://xn--jxagkqfkduily1i.eu/%E9%80%99%E8%A3%A1')
str(url)
'http://xn--jxagkqfkduily1i.eu/%E9%80%99%E8%A3%A1'
url.human_repr()
'http://εμπορικόσήμα.eu/這裡'
```

--------------------------------

### URL Path with `with_path`

Source: https://yarl.aio-libs.org/en/latest/changes

Demonstrates how the `with_path()` method handles paths without a leading slash, ensuring correct URL construction. It also shows clearing query and fragment parts when using `with_path()`.

```python
# Example demonstrating URL.with_path() with paths without leading slash
# (Specific code not provided in text, but functionality described)

```

--------------------------------

### Python URL Default Ports and Relative URL Schemes

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Defines dictionaries and sets for handling default ports for various URL schemes and identifies schemes that support relative URL references. This is crucial for correctly constructing and interpreting URLs.

```Python
DEFAULT_PORTS = {"http": 80, "https": 443, "ws": 80, "wss": 443, "ftp": 21}
USES_RELATIVE = frozenset(uses_relative)
```

--------------------------------

### Get File Suffix of a URL

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Extracts the file extension from the last path segment of a URL. Returns an empty string if there is no extension. Handles Unicode characters.

```python
from yarl import URL

url1 = URL('http://example.com/path/to.txt')
print(url1.suffix)  # Output: '.txt'

url2 = URL('http://example.com/шлях.сюди')
print(url2.suffix)  # Output: '.сюди'

url3 = URL('http://example.com/path')
print(url3.suffix)  # Output: ''
```

--------------------------------

### URL Building

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Constructs new URL objects using various components.

```APIDOC
## URL Building

### Description
The `URL.build` class method provides a flexible way to construct new `URL` objects by specifying individual components like scheme, host, path, query, etc. The `URL` object is immutable, so all modification operations return new instances.

### Class Method

*   **`URL.build(*, scheme=None, authority=None, user=None, password=None, host=None, port=None, path='', query=None, query_string=None, fragment=None, encoded=False)`**
    Creates and returns a new `URL` instance.

    - `scheme` (str): The URL scheme (e.g., 'http').
    - `authority` (str): The URL authority part (includes user, password, host, port).
    - `user` (str): Username for authentication.
    - `password` (str): Password for authentication.
    - `host` (str): The hostname.
    - `port` (int): The port number.
    - `path` (str): The URL path.
    - `query` (dict or MultiDict): Query parameters as a dictionary or MultiDict.
    - `query_string` (str): Query parameters as a raw string.
    - `fragment` (str): The URL fragment identifier.
    - `encoded` (bool): If True, path and query will be encoded.

    **Note**: Only one of `query` or `query_string` should be provided.

### Request Example
```python
from yarl import URL

# Basic URL construction
url1 = URL.build(scheme="http", host="example.com")
print(url1)  # Output: URL('http://example.com')

# With query parameters
url2 = URL.build(scheme="http", host="example.com", query={"a": "b", "c": "d"})
print(url2)  # Output: URL('http://example.com/?a=b&c=d')

# With query string
url3 = URL.build(scheme="http", host="example.com", query_string="a=b")
print(url3)  # Output: URL('http://example.com/?a=b')

# Empty URL
url4 = URL.build()
print(url4)  # Output: URL('')
```
```

--------------------------------

### Get Encoded URL Query String

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Returns the raw, encoded query string of the URL. If the URL does not contain a query string, an empty string is returned.

```Python
@cached_property
def raw_query_string(self) -> str:
        """Encoded query part of URL.

        Empty string if query is missing.

        """
        return self._query
```

--------------------------------

### Get Decoded URL Host

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Returns the decoded host part of the URL. Returns None for relative URLs. It handles IDNA decoding for non-IP addresses.

```python
@cached_property
def host(self) -> Union[str, None]:
    """Decoded host part of URL.

    None for relative URLs.

    """
    if (raw := self.raw_host) is None:
        return None
    if raw and raw[-1].isdigit() or ":" in raw:
        # IP addresses are never IDNA encoded
        return raw
    return _idna_decode(raw)
```

--------------------------------

### URL Construction with `URL` Constructor

Source: https://yarl.aio-libs.org/en/latest/changes

Allows the `URL` constructor to accept subclasses of `str`, providing more flexibility in how URL strings are passed to the constructor.

```python
# Example demonstrating URL constructor accepting str subclasses
# (Specific code not provided in text, but functionality described)

```

--------------------------------

### Get Encoded URL User

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Retrieves the raw, encoded user part of the URL. Returns None if the user information is missing. The result is cached for efficiency.

```python
@cached_property
def raw_user(self) -> Union[str, None]:
    """Encoded user part of URL.

    None if user is missing.

    """
    # not .username
    self._cache_netloc()
    return self._cache["raw_user"]
```

--------------------------------

### URL Joining API

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

This endpoint allows you to join a base URL with another URL. It intelligently combines components like scheme, network location, and path to form a complete URL.

```APIDOC
## POST /url/join

### Description
Joins a base URL (self) with another URL (url) to construct a full, absolute URL. It uses components of the base URL to provide missing parts in the relative URL.

### Method
POST

### Endpoint
`/url/join`

### Parameters
#### Request Body
- **base_url** (string) - Required - The base URL.
- **relative_url** (string) - Required - The relative URL to join with the base URL.

### Request Example
```json
{
  "base_url": "http://example.com/path/",
  "relative_url": "another/path"
}
```

### Response
#### Success Response (200)
- **joined_url** (string) - The resulting joined URL.

#### Response Example
```json
{
  "joined_url": "http://example.com/path/another/path"
}
```
```

--------------------------------

### Get Relative URL

Source: https://yarl.aio-libs.org/en/latest/api

Returns a new relative URL containing only the path, query, and fragment parts. Scheme, user, password, host, and port are removed.

```python
URL('http://example.com/path/to?arg#frag').relative()
URL('/path/to?arg#frag')
```

--------------------------------

### Get URL Fragment

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the decoded fragment identifier of a URL. Returns an empty string if the URL has no fragment. This attribute provides the human-readable fragment part.

```python
>>> URL('http://example.com/path#fragment').fragment
'fragment'
```

```python
>>> URL('http://example.com/path').fragment
''
```

--------------------------------

### PEP-561 Type Hinting Marker

Source: https://yarl.aio-libs.org/en/latest/changes

Adds support for PEP-561, providing a type hinting marker (`py.typed` file). This allows static analysis tools to better understand and check the library's types.

```python
# Example demonstrating PEP-561 support (py.typed file)
# (Specific code not provided in text, but functionality described)

```

--------------------------------

### Combined Path and Query

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Provides access to the combined path and query string in both encoded and decoded formats.

```APIDOC
## Combined Path and Query

### Description
Provides access to the combined path and query string.

### Methods
#### `path_qs` (getter)
- **Returns**: `str` - The decoded path of the URL with the decoded query string appended.

#### `raw_path_qs` (getter)
- **Returns**: `str` - The encoded path of the URL with the encoded query string appended.
```

--------------------------------

### Absolute URL Check

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

The is_absolute method checks if a URL is absolute (i.e., has a scheme or starts with '//'). It is recommended to use the cached '.absolute' property for performance.

```python
def is_absolute(self) -> bool:
    """A check for absolute URLs.

    Return True for absolute ones (having scheme or starting
    with //), False otherwise.

    Is is preferred to call the .absolute property instead
    as it is cached.
    """
    return self.absolute
```

--------------------------------

### Get Decoded URL Fragment

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Returns the decoded fragment identifier of the URL. If the URL does not contain a fragment, an empty string is returned. This provides a human-readable version of the fragment.

```Python
@cached_property
def fragment(self) -> str:
        """Decoded fragment part of URL.

        Empty string if fragment is missing.

        """
        return UNQUOTER(self._fragment) if self._fragment else ""
```

--------------------------------

### URL Encoding and Decoding

Source: https://yarl.aio-libs.org/en/latest/_sources/index.rst

Illustrates yarl's automatic handling of URL encoding, particularly for non-ASCII characters in the path. It also shows how to access the raw, percent-encoded path using the 'raw_' prefix.

```python
from yarl import URL

url = URL('https://www.python.org/шлях')

print(url)
print(url.path)
print(url.raw_path)
```

--------------------------------

### Get URL Host Subcomponent

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the RFC 3986 Section 3.2.2 host subcomponent of a URL. Returns None for relative URLs. Added in version 1.13.

```python
from yarl import URL

print(URL('http://хост.домен').host_subcomponent)
print(URL('http://[::1]').host_subcomponent)
```

--------------------------------

### URL Class Method: build()

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

A class method to construct and return a new URL object. It accepts various components like scheme, authority, user, password, host, port, path, query, and fragment. It includes validation for conflicting parameters and type checking.

```python
@classmethod
    def build(
        cls,
        *,
        scheme: str = "",
        authority: str = "",
        user: Union[str, None] = None,
        password: Union[str, None] = None,
        host: str = "",
        port: Union[int, None] = None,
        path: str = "",
        query: Union[Query, None] = None,
        query_string: str = "",
        fragment: str = "",
        encoded: bool = False,
    ) -> "URL":
        """Creates and returns a new URL"""

        if authority and (user or password or host or port):
            raise ValueError(
                'Can\'t mix "authority" with "user", "password", "host" or "port".'
            )
        if port is not None and not isinstance(port, int):
            raise TypeError(f"The port is required to be int, got {type(port)!r}.")
        if port and not host:
            raise ValueError('Can\'t build URL with "port" but without "host".')
        if query and query_string:
            raise ValueError('Only one of "query" or "query_string" should be passed')
        if (
            scheme is None  # type: ignore[redundant-expr]
            or authority is None  # type: ignore[redundant-expr]
            or host is None  # type: ignore[redundant-expr]
            or path is None  # type: ignore[redundant-expr]
            or query_string is None  # type: ignore[redundant-expr]
            or fragment is None
        ):
            raise TypeError(
                'NoneType is illegal for "scheme", "authority", "host", "path", '
                '"query_string", and "fragment" args, use empty string instead.'
            )

        if query:
            query_string = get_str_query(query) or ""

        if encoded:
            return build_pre_encoded_url(
                scheme,
                authority,
                user,
                password,
                host,
                port,
                path,
                query_string,
                fragment,
            )

        self = object.__new__(URL)
        self._scheme = scheme
        _host: Union[str, None] = None
        if authority:
            user, password, _host, port = split_netloc(authority)
            _host = _encode_host(_host, validate_host=False) if _host else ""
        elif host:
            _host = _encode_host(host, validate_host=True)
        else:
            self._netloc = ""

        if _host is not None:
            if port is not None:
                port = None if port == DEFAULT_PORTS.get(scheme) else port
            if user is None and password is None:
                self._netloc = _host if port is None else f"{_host}:{port}"
            else:
                self._netloc = make_netloc(user, password, _host, port, True)

        path = PATH_QUOTER(path) if path else path
        if path and self._netloc:
            if "." in path:
                path = normalize_path(path)
            if path[0] != "/":
                msg = (
                    "Path in a URL with authority should "
                    "start with a slash ('/') if set"
                )
                raise ValueError(msg)

        self._path = path
        if not query and query_string:
            query_string = QUERY_QUOTER(query_string)
        self._query = query_string
        self._fragment = FRAGMENT_QUOTER(fragment) if fragment else fragment
        self._cache = {}
        return self
```

--------------------------------

### Get Last Path Part of a URL

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Retrieves the last segment of the URL's path. Returns an empty string if the path ends with a slash. Handles Unicode characters.

```python
from yarl import URL

url1 = URL('http://example.com/path/to')
print(url1.name)  # Output: 'to'

url2 = URL('http://example.com/шлях/сюди')
print(url2.name)  # Output: 'сюди'

url3 = URL('http://example.com/path/')
print(url3.name)  # Output: ''
```

--------------------------------

### URL Representation and Equality

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Provides methods for string and byte representation of URLs, along with a robust equality check that considers scheme, network location, path, query, and fragment. It also includes a hash method for URL objects.

```python
def __repr__(self) -> str:
    return f"{self.__class__.__name__}('{str(self)}')"

def __bytes__(self) -> bytes:
    return str(self).encode("ascii")

def __eq__(self, other: object) -> bool:
    if type(other) is not URL:
        return NotImplemented

    path1 = "/" if not self._path and self._netloc else self._path
    path2 = "/" if not other._path and other._netloc else other._path
    return (
        self._scheme == other._scheme
        and self._netloc == other._netloc
        and path1 == path2
        and self._query == other._query
        and self._fragment == other._fragment
    )

def __hash__(self) -> int:
    if (ret := self._cache.get("hash")) is None:
        path = "/" if not self._path and self._netloc else self._path
        ret = self._cache["hash"] = hash(
            (self._scheme, self._netloc, path, self._query, self._fragment)
        )
    return ret
```

--------------------------------

### URL State Management for Pickling

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Defines methods (__getstate__ and __setstate__) for controlling how URL objects are serialized and deserialized using Python's pickle module. This ensures proper restoration of the URL's internal state.

```python
def __getstate__(self) -> tuple[SplitResult]:
    return (tuple.__new__(SplitResult, self._val),)

def __setstate__(
    self, state: Union[tuple[SplitURLType], tuple[None, _InternalURLCache]]
) -> None:
    if state[0] is None and isinstance(state[1], dict):
        # default style pickle
        val = state[1]["_val"]
    else:
        unused: list[object]
        val, *unused = state
    self._scheme, self._netloc, self._path, self._query, self._fragment = val
    self._cache = {}
```

--------------------------------

### Check if URL is Absolute

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Determines if a URL is absolute. An absolute URL is defined as one having a scheme or starting with '//'. This check is performed efficiently by examining the `_netloc` attribute.

```python
@cached_property
def absolute(self) -> bool:
    """A check for absolute URLs.

    Return True for absolute ones (having scheme or starting
    with //), False otherwise.

    """
    # `netloc`` is an empty string for relative URLs
    # Checking `netloc` is faster than checking `hostname`
    # because `hostname` is a property that does some extra work
    # to parse the host from the `netloc`
    return self._netloc != ""
```

--------------------------------

### Check for Absolute URL

Source: https://yarl.aio-libs.org/en/latest/api

Determines if a URL is absolute. Returns True if the URL has a scheme or starts with '//', and False otherwise. This property is preferred over the deprecated is_absolute() method.

```python
>>> URL('http://example.com').absolute
True
```

```python
>>> URL('/path/to').absolute
False
```

--------------------------------

### URL Constructor and Representation

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

Describes the URL class constructor and its behavior for both absolute and relative URLs, including automatic percent-encoding.

```APIDOC
## URL Constructor and Representation

### Description
Represents a URL as a structured object. It handles both absolute and relative URLs, automatically percent-encoding parts of the URL as needed. The constructor accepts a string representation of the URL and an optional `encoded` flag.

### Constructor Signature
`URL(arg, *, encoded=False)`

### Parameters
- **arg** (str) - The string representation of the URL.
- **encoded** (bool) - If `True`, prevents automatic URL encoding. Defaults to `False`.

### Usage Examples
```python
# Creating an absolute URL
url1 = URL('http://example.com/path/to/?arg1=a&arg2=b#fragment')

# Creating a relative URL
url2 = URL('/path/to/page.html')

# Creating a URL with non-ASCII characters (auto-encoded)
url3 = URL('http://εμπορικόσήμα.eu/шлях/這裡')

# Creating an already encoded URL
url4 = URL('http://xn--jxagkqfkduily1i.eu')

# Using encoded=True (use with caution)
url5 = URL('http://example.com/unencoded_path', encoded=True)
```

### String Representation
- **Default**: Returns the URL with percent-encoded parts.
- **`human_repr()`**: Returns a human-readable representation with decoded characters.

### Examples
```python
>>> from yarl import URL
>>> url = URL('http://εμπορικόσήμα.eu/шлях/這裡')
>>> str(url)
'http://xn--jxagkqfkduily1i.eu/%D1%88%D0%BB%D1%8F%D1%85/%E9%80%99%E8%A3%A1'
>>> url.human_repr()
'http://εμπορικόσήμα.eu/шлях/這裡'
```
```

--------------------------------

### Get Encoded URL Host

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Retrieves the raw, encoded host part of the URL. Returns None for relative URLs. For IPv6 addresses, the `host_subcomponent` property should be used instead.

```python
@cached_property
def raw_host(self) -> Union[str, None]:
    """Encoded host part of URL.

    None for relative URLs.

    When working with IPv6 addresses, use the `host_subcomponent` property instead
    as it will return the host subcomponent with brackets.
    """
    # Use host instead of hostname for sake of shortness
    # May add .hostname prop later
    self._cache_netloc()
    return self._cache["raw_host"]
```

--------------------------------

### URL Properties and Checks

Source: https://yarl.aio-libs.org/en/latest/_modules/yarl/_url

Properties and methods for inspecting URL components and characteristics.

```APIDOC
## URL Properties and Checks

### `__bool__() -> bool`

**Description**: Returns `True` if the URL has a network location, path, query, or fragment; `False` otherwise.

### `is_absolute() -> bool`

**Description**: Returns `True` for absolute URLs (those with a scheme or starting with '//'), `False` otherwise. Prefer using the `.absolute` property for cached results.

### `is_default_port() -> bool`

**Description**: Returns `True` if the URL uses the default port for its scheme (e.g., 80 for HTTP, 443 for HTTPS). Returns `False` for relative URLs or URLs with non-default ports.

### `origin() -> "URL"`

**Description**: Returns a new URL containing only the scheme, host, and port. Userinfo, path, query, and fragment are removed. Raises `ValueError` if the URL is not absolute or lacks a scheme.
```

--------------------------------

### Get Encoded Path

Source: https://yarl.aio-libs.org/en/latest/api

Retrieves the encoded path component of a URL. Returns '/' for absolute URLs without a path. This attribute is useful when the raw, percent-encoded path is required.

```python
>>> URL('http://example.com/шлях/сюди').raw_path
'/%D1%88%D0%BB%D1%8F%D1%85/%D1%81%D1%8E%D0%B4%D0%B8'
```

--------------------------------

### Build a New URL

Source: https://yarl.aio-libs.org/en/latest/_sources/api.rst

A class method to construct a new URL instance. It accepts various components like scheme, host, path, query, etc. Only one of 'query' or 'query_string' should be provided.

```python
from yarl import URL

url1 = URL.build(scheme="http", host="example.com")
print(url1)  # Output: URL('http://example.com')

url2 = URL.build(scheme="http", host="example.com", query={"a": "b"})
print(url2)  # Output: URL('http://example.com/?a=b')

url3 = URL.build(scheme="http", host="example.com", query_string="a=b")
print(url3)  # Output: URL('http://example.com/?a=b')

url4 = URL.build()
print(url4)  # Output: URL('')
```
Tokens:
Raw