or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cache-management.mdcore-url.mdindex.mdpath-operations.mdquery-handling.mdurl-modification.md
tile.json

tessl/pypi-yarl

Yet another URL library - comprehensive URL parsing and manipulation for Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/yarl@1.20.x

To install, run

npx @tessl/cli install tessl/pypi-yarl@1.20.0

index.mddocs/

YARL - Yet Another URL Library

A comprehensive Python library for URL parsing, manipulation, and construction that provides a clean, immutable API for working with URLs. YARL offers performance-optimized URL handling with comprehensive support for all URL components, query parameters, path operations, and encoding/decoding according to web standards.

Package Information

  • Package Name: yarl
  • Language: Python
  • Installation: pip install yarl
  • Python Requirements: >=3.9
  • Dependencies: idna >= 2.0, multidict >= 4.0, propcache >= 0.2.1

Core Imports

from yarl import URL

For query handling:

from yarl import URL, Query, SimpleQuery, QueryVariable

For accessing query results:

from multidict import MultiDictProxy  # URL.query returns MultiDictProxy[str]

For cache management:

from yarl import URL, cache_clear, cache_configure, cache_info

Basic Usage

from yarl import URL

# Create URLs from strings
url = URL('https://user:password@example.com:8080/path/to/resource?query=value&multi=1&multi=2#fragment')

# Access URL components
print(url.scheme)     # 'https'
print(url.host)       # 'example.com'
print(url.port)       # 8080
print(url.path)       # '/path/to/resource'
print(url.query)      # MultiDictProxy with query parameters
print(url.fragment)   # 'fragment'

# URLs are immutable - modifications return new instances
new_url = url.with_host('api.example.com').with_port(443)
path_url = url / 'subpath' / 'file.txt'
query_url = url % {'new_param': 'value'}

# Build URLs from components
built_url = URL.build(
    scheme='https',
    host='api.example.com',
    port=8080,
    path='/v1/users',
    query={'limit': 10, 'offset': 0}
)

# Path operations
parent = url.parent
filename = url.name
extension = url.suffix

# Human-readable representation
print(url.human_repr())  # URL with decoded non-ASCII characters

Architecture

YARL provides an immutable URL class with comprehensive component access and manipulation capabilities:

  • Immutable Design: All URL operations return new instances, ensuring thread safety
  • Component Access: Properties for all URL parts (scheme, host, port, path, query, fragment)
  • Encoding Handling: Automatic encoding/decoding with proper URL quoting rules
  • Performance Optimization: LRU caching for encoding/decoding operations with optional Cython extensions
  • Standards Compliance: Full adherence to URL parsing and encoding standards
  • MultiDict Integration: Query parameters handled via multidict for multiple values per key

Capabilities

Core URL Manipulation

Core URL construction, parsing, and component access functionality. Provides the main URL class with properties for accessing all URL components and methods for URL validation and comparison.

class URL:
    def __new__(cls, val: str) -> "URL": ...
    
    @classmethod
    def build(cls, *, scheme: str = "", authority: str = "", user: str = None, 
              password: str = None, host: str = "", port: int = None,
              path: str = "", query: Query = None, query_string: str = "",
              fragment: str = "", encoded: bool = False) -> "URL": ...
    
    # Properties
    scheme: str
    host: str | None
    port: int | None
    path: str
    query: MultiDictProxy[str]
    fragment: str
    
    # State checking
    def is_absolute(self) -> bool: ...
    def is_default_port(self) -> bool: ...

Core URL Manipulation

URL Modification Operations

Methods for creating modified versions of URLs by changing individual components. All methods return new URL instances as URLs are immutable.

def with_scheme(self, scheme: str) -> "URL": ...
def with_host(self, host: str) -> "URL": ...
def with_port(self, port: int | None) -> "URL": ...
def with_path(self, path: str, *, encoded: bool = False, 
              keep_query: bool = False, keep_fragment: bool = False) -> "URL": ...
def with_fragment(self, fragment: str | None) -> "URL": ...

URL Modification

Query Parameter Handling

Comprehensive query string manipulation with support for multiple values per parameter, various input formats, and MultiDict integration for robust parameter handling.

def with_query(self, query: Query = None, **kwargs: QueryVariable) -> "URL": ...
def extend_query(self, query: Query = None, **kwargs: QueryVariable) -> "URL": ...
def update_query(self, query: Query = None, **kwargs: QueryVariable) -> "URL": ...
def without_query_params(self, *query_params: str) -> "URL": ...

# Type definitions
SimpleQuery = Union[str, SupportsInt, float]
QueryVariable = Union[SimpleQuery, Sequence[SimpleQuery]]
Query = Union[None, str, Mapping[str, QueryVariable], Sequence[tuple[str, QueryVariable]]]

Query Parameter Handling

Path Operations

Path manipulation, normalization, and joining operations for URL path components, including filename and extension handling.

def joinpath(self, *other: str, encoded: bool = False) -> "URL": ...
def join(self, url: "URL") -> "URL": ...
def with_name(self, name: str, *, keep_query: bool = False, 
              keep_fragment: bool = False) -> "URL": ...
def with_suffix(self, suffix: str, *, keep_query: bool = False, 
                keep_fragment: bool = False) -> "URL": ...

# Path properties
parent: "URL"
name: str
suffix: str
suffixes: tuple[str, ...]
parts: tuple[str, ...]

Path Operations

Cache Management

Performance optimization through configurable LRU caching for encoding/decoding operations, particularly beneficial for applications processing many URLs.

def cache_clear() -> None: ...
def cache_info() -> CacheInfo: ...
def cache_configure(*, idna_encode_size: int = 256, idna_decode_size: int = 256,
                   ip_address_size: int = 256, host_validate_size: int = 256,
                   encode_host_size: int = 256) -> None: ...

class CacheInfo(TypedDict):
    idna_encode: _CacheInfo
    idna_decode: _CacheInfo
    ip_address: _CacheInfo
    host_validate: _CacheInfo
    encode_host: _CacheInfo

Cache Management

Error Handling

YARL raises standard Python exceptions for various error conditions:

  • TypeError: When arguments have incorrect types (e.g., non-string URL values)
  • ValueError: For invalid values such as float('inf') or float('nan') in query parameters
  • UnicodeError: During encoding/decoding of international domain names (IDN)

Error handling is straightforward with standard Python exception handling patterns.