0
# Core URL Manipulation
1

2
The furl class provides comprehensive URL parsing, construction, and manipulation capabilities. It serves as the primary interface for working with URLs, automatically handling encoding, component validation, and URL structure integrity.
3

4
## Capabilities
5

6
### URL Construction and Parsing
7

8
Create furl objects from URL strings or construct URLs from individual components with validation and automatic formatting.
9

10
```python { .api }
11
class furl:
12
    def __init__(self, url='', args=None, path=None, fragment=None,
13
                 scheme=None, netloc=None, origin=None,
14
                 fragment_path=None, fragment_args=None,
15
                 fragment_separator=None, host=None, port=None,
16
                 query=None, query_params=None, username=None,
17
                 password=None, strict=False):
18
        """
19
        Initialize a furl object.
20
        
21
        Args:
22
            url (str): Complete URL string to parse
23
            args (dict): Query parameters dictionary  
24
            path (str): URL path component
25
            fragment (str): URL fragment component
26
            scheme (str): URL scheme (http, https, etc.)
27
            netloc (str): Network location (host:port)
28
            origin (str): Origin (scheme://host:port)
29
            fragment_path (str): Fragment path component
30
            fragment_args (dict): Fragment query parameters
31
            fragment_separator (str): Fragment separator character
32
            host (str): Host/domain name
33
            port (int): Port number
34
            query (str): Query string
35
            query_params (dict): Query parameters dictionary
36
            username (str): Username for authentication
37
            password (str): Password for authentication
38
            strict (bool): Enable strict parsing mode
39
        """
40

41
    def load(self, url):
42
        """
43
        Load and parse a URL string into the furl object.
44
        
45
        Args:
46
            url (str): URL string to parse
47
            
48
        Returns:
49
            furl: Self for method chaining
50
        """
51
```
52

53
**Usage:**
54

55
```python
56
from furl import furl
57

58
# Parse a complete URL
59
f = furl('https://user:pass@example.com:8080/path?key=value#fragment')
60

61
# Construct from components
62
f = furl(scheme='https', host='example.com', path='/api/v1', 
63
         args={'token': 'abc123'})
64

65
# Load new URL into existing object
66
f.load('http://newdomain.com/different/path')
67
```
68

69
### Component Access and Modification
70

71
Direct access to all URL components with automatic validation and encoding.
72

73
```python { .api }
74
class furl:
75
    @property
76
    def scheme(self) -> str | None:
77
        """URL scheme (http, https, ftp, etc.) or None"""
78
        
79
    @scheme.setter
80
    def scheme(self, scheme: str | None):
81
        """Set URL scheme with validation"""
82
        
83
    username: str | None
84
        """Username for authentication or None (direct attribute)"""
85
        
86
    password: str | None
87
        """Password for authentication or None (direct attribute)"""
88
        
89
    @property
90
    def host(self) -> str | None:
91
        """Host/domain name or None"""
92
        
93
    @host.setter
94
    def host(self, host: str | None):
95
        """Set host with IDNA encoding support"""
96
        
97
    @property
98
    def port(self) -> int | None:
99
        """Port number or default port for scheme"""
100
        
101
    @port.setter
102
    def port(self, port: int | None):
103
        """Set port number with validation"""
104
        
105
    @property
106
    def netloc(self) -> str:
107
        """Network location (username:password@host:port)"""
108
        
109
    @netloc.setter
110
    def netloc(self, netloc: str):
111
        """Set network location string"""
112
        
113
    @property
114
    def origin(self) -> str:
115
        """Origin (scheme://host:port)"""
116
        
117
    @origin.setter
118
    def origin(self, origin: str):
119
        """Set origin string"""
120
        
121
    @property
122
    def url(self) -> str:
123
        """Complete URL string"""
124
        
125
    @url.setter
126
    def url(self, url: str):
127
        """Load new URL (alias for load())"""
128
        
129
    @property
130
    def path(self) -> Path:
131
        """Path object for path manipulation"""
132
        
133
    @property
134
    def query(self) -> Query:
135
        """Query object for query parameter manipulation"""
136
        
137
    @property
138
    def fragment(self) -> Fragment:
139
        """Fragment object for fragment manipulation"""
140
        
141
    @property
142
    def args(self) -> omdict1D:
143
        """Alias for query.params (deprecated, use query.params)"""
144
        
145
    @property
146
    def pathstr(self) -> str:
147
        """DEPRECATED: String representation of path (use str(furl.path))"""
148
        
149
    @property
150
    def querystr(self) -> str:
151
        """DEPRECATED: String representation of query (use str(furl.query))"""
152
        
153
    @property
154
    def fragmentstr(self) -> str:
155
        """DEPRECATED: String representation of fragment (use str(furl.fragment))"""
156
```
157

158
**Usage:**
159

160
```python
161
f = furl('http://example.com/path?key=value')
162

163
# Access components
164
print(f.scheme)    # 'http'
165
print(f.host)      # 'example.com'
166
print(f.port)      # 80 (default for http)
167
print(f.netloc)    # 'example.com'
168
print(f.origin)    # 'http://example.com'
169

170
# Modify components
171
f.scheme = 'https'
172
f.host = 'secure.example.com'
173
f.port = 443
174
print(f.url)  # 'https://secure.example.com/path?key=value'
175
```
176

177
### URL Manipulation Methods
178

179
Add, set, and remove URL components with method chaining support.
180

181
```python { .api }
182
class furl:
183
    def add(self, args=None, path=None, fragment_path=None, 
184
            fragment_args=None, query_params=None):
185
        """
186
        Add components to the URL.
187
        
188
        Args:
189
            args (dict): Query parameters to add
190
            path (str): Path segments to add
191
            fragment_path (str): Fragment path segments to add
192
            fragment_args (dict): Fragment query parameters to add
193
            query_params (dict): Alias for args
194
            
195
        Returns:
196
            furl: Self for method chaining
197
        """
198
        
199
    def set(self, args=None, path=None, fragment=None, query=None,
200
            scheme=None, username=None, password=None, host=None,
201
            port=None, netloc=None, origin=None, query_params=None,
202
            fragment_path=None, fragment_args=None, fragment_separator=None):
203
        """
204
        Set URL components, replacing existing values.
205
        
206
        Args:
207
            args (dict): Query parameters to set
208
            path (str): Path to set
209
            fragment (str): Fragment to set
210
            query (str): Query string to set
211
            scheme (str): Scheme to set
212
            username (str): Username to set
213
            password (str): Password to set
214
            host (str): Host to set
215
            port (int): Port to set
216
            netloc (str): Network location to set
217
            origin (str): Origin to set
218
            query_params (dict): Alias for args
219
            fragment_path (str): Fragment path to set
220
            fragment_args (dict): Fragment query parameters to set
221
            fragment_separator (str): Fragment separator to set
222
            
223
        Returns:
224
            furl: Self for method chaining
225
        """
226
        
227
    def remove(self, args=None, path=None, fragment=None, query=None,
228
               scheme=False, username=False, password=False, 
229
               host=False, port=False, netloc=False, origin=False,
230
               query_params=None, fragment_path=None, fragment_args=None):
231
        """
232
        Remove URL components.
233
        
234
        Args:
235
            args (list): Query parameter keys to remove
236
            path (str|bool): Path segments to remove or True for all
237
            fragment (bool): Remove entire fragment if True
238
            query (bool): Remove entire query if True
239
            scheme (bool): Remove scheme if True
240
            username (bool): Remove username if True
241
            password (bool): Remove password if True
242
            host (bool): Remove host if True
243
            port (bool): Remove port if True
244
            netloc (bool): Remove netloc if True
245
            origin (bool): Remove origin if True
246
            query_params (list): Alias for args
247
            fragment_path (str): Fragment path segments to remove
248
            fragment_args (list): Fragment query parameter keys to remove
249
            
250
        Returns:
251
            furl: Self for method chaining
252
        """
253
```
254

255
**Usage:**
256

257
```python
258
f = furl('http://example.com/')
259

260
# Add components
261
f.add(args={'token': 'abc123'}, path='api/v1')
262
print(f.url)  # 'http://example.com/api/v1?token=abc123'
263

264
# Set components (replace existing)
265
f.set(args={'key': 'value'}, path='/new/path')
266
print(f.url)  # 'http://example.com/new/path?key=value'
267

268
# Remove components
269
f.remove(args=['key'], path=True)
270
print(f.url)  # 'http://example.com/'
271

272
# Method chaining
273
result = (furl('http://example.com/')
274
          .add({'step': '1'})
275
          .set(path='/process')
276
          .add({'step': '2'}))
277
print(result.url)  # 'http://example.com/process?step=1&step=2'
278
```
279

280
### URL String Generation
281

282
Convert furl objects to URL strings with customizable formatting options.
283

284
```python { .api }
285
class furl:
286
    def tostr(self, query_delimiter='&', query_quote_plus=True,
287
              query_dont_quote=''):
288
        """
289
        Convert furl object to URL string.
290
        
291
        Args:
292
            query_delimiter (str): Delimiter for query parameters
293
            query_quote_plus (bool): Use '+' for spaces in query values
294
            query_dont_quote (str): Characters not to percent-encode
295
            
296
        Returns:
297
            str: Complete URL string
298
        """
299
        
300
    def __str__(self):
301
        """String representation of the URL"""
302
        
303
    def __unicode__(self):
304
        """Unicode representation of the URL"""
305
```
306

307
**Usage:**
308

309
```python
310
f = furl('http://example.com/path?key=value&other=data')
311

312
# Default string conversion
313
url_string = str(f)  # or f.tostr()
314

315
# Custom formatting
316
custom_url = f.tostr(query_delimiter=';', query_quote_plus=False)
317
print(custom_url)  # Different query parameter formatting
318
```
319

320
### URL Joining and Copying
321

322
Join URLs and create copies of furl objects.
323

324
```python { .api }
325
class furl:
326
    def join(self, *urls):
327
        """
328
        Join the current URL with one or more additional URLs.
329
        
330
        Args:
331
            *urls: URL strings to join
332
            
333
        Returns:
334
            furl: Self for method chaining
335
        """
336
        
337
    def copy(self):
338
        """
339
        Create a deep copy of the furl object.
340
        
341
        Returns:
342
            furl: New furl object with identical components
343
        """
344
        
345
    def __truediv__(self, path):
346
        """
347
        Path division operator (/) for adding path segments.
348
        
349
        Args:
350
            path (str): Path segment to add
351
            
352
        Returns:
353
            furl: New furl object with added path
354
        """
355
        
356
    def asdict(self):
357
        """
358
        Convert furl object to dictionary representation.
359
        
360
        Returns:
361
            dict: Dictionary with all URL components
362
        """
363
```
364

365
**Usage:**
366

367
```python
368
base = furl('http://example.com/api')
369

370
# Join URLs
371
api_endpoint = base.copy().join('v1', 'users', '123')
372
print(api_endpoint.url)  # 'http://example.com/api/v1/users/123'
373

374
# Path division operator
375
user_profile = base / 'v1' / 'users' / 'profile'
376
print(user_profile.url)  # 'http://example.com/api/v1/users/profile'
377

378
# Create copy
379
backup = base.copy()
380
base.add(args={'token': 'secret'})
381
# backup remains unchanged
382

383
# Convert to dictionary
384
components = base.asdict()
385
print(components['scheme'])  # 'http'
386
print(components['host'])    # 'example.com'
387
```
388

389
## Error Handling
390

391
The furl class handles various error conditions:
392

393
- **Invalid URLs**: Malformed URL strings raise appropriate exceptions
394
- **Invalid ports**: Non-numeric or out-of-range ports raise ValueError
395
- **Invalid schemes**: Malformed schemes are validated
396
- **Encoding errors**: Unicode and encoding issues are handled gracefully
397
- **Strict mode**: When `strict=True`, warnings are raised for improperly encoded strings