tessl/pypi-yarl
Yet another URL library - comprehensive URL parsing and manipulation for Python
core-url.mddocs/
Core URL Manipulation
Core URL construction, parsing, and component access functionality. The URL class provides comprehensive access to all URL components with proper encoding/decoding and validation.
Capabilities
URL Construction
Create URL objects from string representations or build them from individual components.
class URL:
def __new__(cls, val: str | SplitResult | "URL" = UNDEFINED, *,
encoded: bool = False, strict: bool | None = None) -> "URL":
"""
Create URL from string representation or other URL-like objects.
Args:
val (str | SplitResult | URL, optional): URL string, SplitResult, or URL object to parse (default: UNDEFINED)
encoded (bool): Whether the input is already encoded (default: False)
strict (bool, optional): Deprecated parameter, ignored
Returns:
URL: New URL object
Raises:
ValueError: If URL string is invalid or SplitResult used without encoded=True
TypeError: If val has unsupported type
"""
@classmethod
def build(cls, *,
scheme: str = "",
authority: str = "",
user: str | None = None,
password: str | None = None,
host: str = "",
port: int | None = None,
path: str = "",
query: Query = None,
query_string: str = "",
fragment: str = "",
encoded: bool = False) -> "URL":
"""
Build URL from individual components.
Args:
scheme (str): URL scheme (http, https, etc.)
authority (str): Complete authority component
user (str, optional): Username for authentication
password (str, optional): Password for authentication
host (str): Hostname or IP address
port (int, optional): Port number
path (str): Path component
query (Query, optional): Query parameters as dict, sequence, or string
query_string (str): Raw query string
fragment (str): Fragment identifier
encoded (bool): Whether components are already encoded
Returns:
URL: New URL object built from components
"""Component Access Properties
Access individual URL components with automatic encoding/decoding.
# Scheme component
@property
def scheme(self) -> str:
"""URL scheme (http, https, ftp, etc.)"""
# Authority components
@property
def raw_authority(self) -> str:
"""Raw authority component (user:pass@host:port)"""
@property
def authority(self) -> str:
"""Decoded authority component"""
@property
def raw_user(self) -> str | None:
"""Raw username component"""
@property
def user(self) -> str | None:
"""Decoded username component"""
@property
def raw_password(self) -> str | None:
"""Raw password component"""
@property
def password(self) -> str | None:
"""Decoded password component"""
# Host components
@property
def raw_host(self) -> str | None:
"""Raw hostname component"""
@property
def host(self) -> str | None:
"""Decoded hostname component"""
@property
def host_subcomponent(self) -> str | None:
"""Host subcomponent for IPv6/regular hosts"""
@property
def host_port_subcomponent(self) -> str | None:
"""Host:port subcomponent"""
# Port components
@property
def port(self) -> int | None:
"""Port number with scheme defaults (80 for http, 443 for https, etc.)"""
@property
def explicit_port(self) -> int | None:
"""Explicitly specified port number (no defaults)"""
# Path components
@property
def raw_path(self) -> str:
"""Raw path component"""
@property
def path(self) -> str:
"""Decoded path component"""
@property
def path_safe(self) -> str:
"""Path with safe decoding (preserves /)"""
# Query components
@property
def query(self) -> MultiDictProxy[str]:
"""Query parameters as MultiDictProxy"""
@property
def raw_query_string(self) -> str:
"""Raw query string"""
@property
def query_string(self) -> str:
"""Decoded query string"""
@property
def path_qs(self) -> str:
"""Decoded path + query string"""
@property
def raw_path_qs(self) -> str:
"""Raw path + query string"""
# Fragment component
@property
def raw_fragment(self) -> str:
"""Raw fragment component"""
@property
def fragment(self) -> str:
"""Decoded fragment component"""Path Component Access
Access path components as individual parts and filename components.
@property
def raw_parts(self) -> tuple[str, ...]:
"""Raw path parts as tuple"""
@property
def parts(self) -> tuple[str, ...]:
"""Decoded path parts as tuple"""
@property
def parent(self) -> "URL":
"""Parent URL (removes last path segment)"""
@property
def raw_name(self) -> str:
"""Raw filename component (last path segment)"""
@property
def name(self) -> str:
"""Decoded filename component (last path segment)"""
@property
def raw_suffix(self) -> str:
"""Raw file extension including dot"""
@property
def suffix(self) -> str:
"""Decoded file extension including dot"""
@property
def raw_suffixes(self) -> tuple[str, ...]:
"""All raw file extensions as tuple"""
@property
def suffixes(self) -> tuple[str, ...]:
"""All decoded file extensions as tuple"""URL State Testing
Check URL properties and validity.
def is_absolute(self) -> bool:
"""
Check if URL is absolute (has scheme).
Returns:
bool: True if URL has a scheme, False otherwise
"""
@property
def absolute(self) -> bool:
"""Same as is_absolute() for compatibility"""
def is_default_port(self) -> bool:
"""
Check if URL uses default port for its scheme.
Returns:
bool: True if using default port or no port specified
"""
def origin(self) -> "URL":
"""
Get origin URL (scheme + authority only).
Returns:
URL: New URL with only scheme and authority components
"""
def relative(self) -> "URL":
"""
Get relative URL (path + query + fragment only).
Returns:
URL: New URL with only path, query, and fragment
"""String Representations
Convert URLs to various string formats.
def __str__(self) -> str:
"""Standard string representation of URL"""
def __repr__(self) -> str:
"""Debug string representation"""
def __bytes__(self) -> bytes:
"""Bytes representation of URL"""
def human_repr(self) -> str:
"""
Human-readable URL representation with decoded Unicode characters.
Returns:
str: URL with decoded non-ASCII characters for display
"""Comparison and Hashing
URL comparison and hash operations for use in sets and dictionaries.
def __eq__(self, other: object) -> bool:
"""Equality comparison with another URL"""
def __hash__(self) -> int:
"""Hash value for use in sets and dicts"""
def __le__(self, other: object) -> bool:
"""Less than or equal comparison"""
def __lt__(self, other: object) -> bool:
"""Less than comparison"""
def __ge__(self, other: object) -> bool:
"""Greater than or equal comparison"""
def __gt__(self, other: object) -> bool:
"""Greater than comparison"""
def __bool__(self) -> bool:
"""Boolean evaluation (always True for URL objects)"""Usage Examples
Basic URL Parsing
from yarl import URL
# Parse a complex URL
url = URL('https://user:pass@example.com:8080/path/to/file.html?param=value#section')
# Access components
print(url.scheme) # 'https'
print(url.user) # 'user'
print(url.password) # 'pass'
print(url.host) # 'example.com'
print(url.port) # 8080
print(url.path) # '/path/to/file.html'
print(url.name) # 'file.html'
print(url.suffix) # '.html'
print(url.fragment) # 'section'URL Construction
from yarl import URL
# Build from components
api_url = URL.build(
scheme='https',
host='api.example.com',
port=443,
path='/v1/users',
query={'active': True, 'limit': 50}
)
print(api_url) # https://api.example.com/v1/users?active=True&limit=50URL Validation and Testing
from yarl import URL
url = URL('https://example.com/path')
relative_url = URL('/path/only')
print(url.is_absolute()) # True
print(relative_url.is_absolute()) # False
print(url.is_default_port()) # True (443 is default for https)
# Get URL parts
print(url.origin()) # URL('https://example.com')
print(url.relative()) # URL('/path')Install with Tessl CLI
npx tessl i tessl/pypi-yarl