0
# Core URL Manipulation
1

2
Core URL construction, parsing, and component access functionality. The URL class provides comprehensive access to all URL components with proper encoding/decoding and validation.
3

4
## Capabilities
5

6
### URL Construction
7

8
Create URL objects from string representations or build them from individual components.
9

10
```python { .api }
11
class URL:
12
    def __new__(cls, val: str | SplitResult | "URL" = UNDEFINED, *, 
13
                encoded: bool = False, strict: bool | None = None) -> "URL":
14
        """
15
        Create URL from string representation or other URL-like objects.
16
        
17
        Args:
18
            val (str | SplitResult | URL, optional): URL string, SplitResult, or URL object to parse (default: UNDEFINED)
19
            encoded (bool): Whether the input is already encoded (default: False)
20
            strict (bool, optional): Deprecated parameter, ignored
21
            
22
        Returns:
23
            URL: New URL object
24
            
25
        Raises:
26
            ValueError: If URL string is invalid or SplitResult used without encoded=True
27
            TypeError: If val has unsupported type
28
        """
29

30
    @classmethod  
31
    def build(cls, *, 
32
              scheme: str = "",
33
              authority: str = "", 
34
              user: str | None = None,
35
              password: str | None = None,
36
              host: str = "",
37
              port: int | None = None,
38
              path: str = "",
39
              query: Query = None,
40
              query_string: str = "",
41
              fragment: str = "",
42
              encoded: bool = False) -> "URL":
43
        """
44
        Build URL from individual components.
45
        
46
        Args:
47
            scheme (str): URL scheme (http, https, etc.)
48
            authority (str): Complete authority component
49
            user (str, optional): Username for authentication
50
            password (str, optional): Password for authentication  
51
            host (str): Hostname or IP address
52
            port (int, optional): Port number
53
            path (str): Path component
54
            query (Query, optional): Query parameters as dict, sequence, or string
55
            query_string (str): Raw query string
56
            fragment (str): Fragment identifier
57
            encoded (bool): Whether components are already encoded
58
            
59
        Returns:
60
            URL: New URL object built from components
61
        """
62
```
63

64
### Component Access Properties
65

66
Access individual URL components with automatic encoding/decoding.
67

68
```python { .api }
69
# Scheme component
70
@property
71
def scheme(self) -> str:
72
    """URL scheme (http, https, ftp, etc.)"""
73

74
# Authority components  
75
@property
76
def raw_authority(self) -> str:
77
    """Raw authority component (user:pass@host:port)"""
78

79
@property  
80
def authority(self) -> str:
81
    """Decoded authority component"""
82

83
@property
84
def raw_user(self) -> str | None:
85
    """Raw username component"""
86

87
@property
88
def user(self) -> str | None:
89
    """Decoded username component"""
90

91
@property
92
def raw_password(self) -> str | None:
93
    """Raw password component"""
94

95
@property
96
def password(self) -> str | None:
97
    """Decoded password component"""
98

99
# Host components
100
@property
101
def raw_host(self) -> str | None:
102
    """Raw hostname component"""
103

104
@property
105
def host(self) -> str | None:
106
    """Decoded hostname component"""
107

108
@property  
109
def host_subcomponent(self) -> str | None:
110
    """Host subcomponent for IPv6/regular hosts"""
111

112
@property
113
def host_port_subcomponent(self) -> str | None:
114
    """Host:port subcomponent"""
115

116
# Port components
117
@property
118
def port(self) -> int | None:
119
    """Port number with scheme defaults (80 for http, 443 for https, etc.)"""
120

121
@property
122
def explicit_port(self) -> int | None:
123
    """Explicitly specified port number (no defaults)"""
124

125
# Path components
126
@property
127
def raw_path(self) -> str:
128
    """Raw path component"""
129

130
@property
131
def path(self) -> str:
132
    """Decoded path component"""
133

134
@property
135
def path_safe(self) -> str:
136
    """Path with safe decoding (preserves /)""" 
137

138
# Query components
139
@property
140
def query(self) -> MultiDictProxy[str]:
141
    """Query parameters as MultiDictProxy"""
142

143
@property
144
def raw_query_string(self) -> str:
145
    """Raw query string"""
146

147
@property
148
def query_string(self) -> str:
149
    """Decoded query string"""
150

151
@property
152
def path_qs(self) -> str:
153
    """Decoded path + query string"""
154

155
@property
156
def raw_path_qs(self) -> str:
157
    """Raw path + query string"""
158

159
# Fragment component
160
@property
161
def raw_fragment(self) -> str:
162
    """Raw fragment component"""
163

164
@property
165
def fragment(self) -> str:
166
    """Decoded fragment component"""
167
```
168

169
### Path Component Access
170

171
Access path components as individual parts and filename components.
172

173
```python { .api }
174
@property
175
def raw_parts(self) -> tuple[str, ...]:
176
    """Raw path parts as tuple"""
177

178
@property  
179
def parts(self) -> tuple[str, ...]:
180
    """Decoded path parts as tuple"""
181

182
@property
183
def parent(self) -> "URL":
184
    """Parent URL (removes last path segment)"""
185

186
@property
187
def raw_name(self) -> str:
188
    """Raw filename component (last path segment)"""
189

190
@property
191
def name(self) -> str:
192
    """Decoded filename component (last path segment)"""
193

194
@property
195
def raw_suffix(self) -> str:
196
    """Raw file extension including dot"""
197

198
@property
199
def suffix(self) -> str:
200
    """Decoded file extension including dot"""
201

202
@property
203
def raw_suffixes(self) -> tuple[str, ...]:
204
    """All raw file extensions as tuple"""
205

206
@property
207
def suffixes(self) -> tuple[str, ...]:
208
    """All decoded file extensions as tuple"""
209
```
210

211
### URL State Testing
212

213
Check URL properties and validity.
214

215
```python { .api }
216
def is_absolute(self) -> bool:
217
    """
218
    Check if URL is absolute (has scheme).
219
    
220
    Returns:
221
        bool: True if URL has a scheme, False otherwise
222
    """
223

224
@property
225
def absolute(self) -> bool:
226
    """Same as is_absolute() for compatibility"""
227

228
def is_default_port(self) -> bool:
229
    """
230
    Check if URL uses default port for its scheme.
231
    
232
    Returns:
233
        bool: True if using default port or no port specified
234
    """
235

236
def origin(self) -> "URL":
237
    """
238
    Get origin URL (scheme + authority only).
239
    
240
    Returns:
241
        URL: New URL with only scheme and authority components
242
    """
243

244
def relative(self) -> "URL":
245
    """
246
    Get relative URL (path + query + fragment only).
247
    
248
    Returns:
249
        URL: New URL with only path, query, and fragment
250
    """
251
```
252

253
### String Representations
254

255
Convert URLs to various string formats.
256

257
```python { .api }
258
def __str__(self) -> str:
259
    """Standard string representation of URL"""
260

261
def __repr__(self) -> str:
262
    """Debug string representation"""
263

264
def __bytes__(self) -> bytes:
265
    """Bytes representation of URL"""
266

267
def human_repr(self) -> str:
268
    """
269
    Human-readable URL representation with decoded Unicode characters.
270
    
271
    Returns:
272
        str: URL with decoded non-ASCII characters for display
273
    """
274
```
275

276
### Comparison and Hashing
277

278
URL comparison and hash operations for use in sets and dictionaries.
279

280
```python { .api }
281
def __eq__(self, other: object) -> bool:
282
    """Equality comparison with another URL"""
283

284
def __hash__(self) -> int:
285
    """Hash value for use in sets and dicts"""
286

287
def __le__(self, other: object) -> bool:
288
    """Less than or equal comparison"""
289

290
def __lt__(self, other: object) -> bool:
291
    """Less than comparison"""
292

293
def __ge__(self, other: object) -> bool:
294
    """Greater than or equal comparison"""
295

296
def __gt__(self, other: object) -> bool:
297
    """Greater than comparison"""
298

299
def __bool__(self) -> bool:
300
    """Boolean evaluation (always True for URL objects)"""
301
```
302

303

304
## Usage Examples
305

306
### Basic URL Parsing
307

308
```python
309
from yarl import URL
310

311
# Parse a complex URL
312
url = URL('https://user:pass@example.com:8080/path/to/file.html?param=value#section')
313

314
# Access components
315
print(url.scheme)    # 'https'
316
print(url.user)      # 'user' 
317
print(url.password)  # 'pass'
318
print(url.host)      # 'example.com'
319
print(url.port)      # 8080
320
print(url.path)      # '/path/to/file.html'
321
print(url.name)      # 'file.html'
322
print(url.suffix)    # '.html'
323
print(url.fragment)  # 'section'
324
```
325

326
### URL Construction
327

328
```python
329
from yarl import URL
330

331
# Build from components
332
api_url = URL.build(
333
    scheme='https',
334
    host='api.example.com',
335
    port=443,
336
    path='/v1/users',
337
    query={'active': True, 'limit': 50}
338
)
339

340
print(api_url)  # https://api.example.com/v1/users?active=True&limit=50
341
```
342

343
### URL Validation and Testing
344

345
```python
346
from yarl import URL
347

348
url = URL('https://example.com/path')
349
relative_url = URL('/path/only')
350

351
print(url.is_absolute())          # True
352
print(relative_url.is_absolute()) # False
353
print(url.is_default_port())      # True (443 is default for https)
354

355
# Get URL parts
356
print(url.origin())    # URL('https://example.com')
357
print(url.relative())  # URL('/path')
358
```