0
# Furl
1

2
Furl is a small Python library that makes parsing and manipulating URLs easy. It provides an intuitive, object-oriented API for working with all URL components including scheme, authentication, host, port, path, query parameters, and fragments with automatic percent-encoding and decoding.
3

4
## Package Information
5

6
- **Package Name**: furl
7
- **Language**: Python
8
- **Installation**: `pip install furl`
9
- **Version**: 2.1.4
10
- **License**: Unlicense (public domain)
11
- **Dependencies**: six (>=1.8.0), orderedmultidict (>=1.0.1)
12

13
## Core Imports
14

15
```python
16
from furl import furl
17
```
18

19
Import specific components:
20

21
```python
22
from furl import furl, Path, Query, Fragment
23
```
24

25
## Basic Usage
26

27
```python
28
from furl import furl
29

30
# Create a furl object from a URL string
31
f = furl('http://www.google.com/?one=1&two=2')
32

33
# Add a path segment using the /= operator
34
f /= 'path'
35

36
# Manipulate query parameters
37
del f.args['one']
38
f.args['three'] = '3'
39

40
# Get the complete URL
41
print(f.url)  # 'http://www.google.com/path?two=2&three=3'
42

43
# Chain operations using inline methods
44
result = furl('http://www.google.com/?one=1').add({'two':'2'}).url
45
print(result)  # 'http://www.google.com/?one=1&two=2'
46

47
# Unicode and encoding support
48
f = furl('http://www.google.com/')
49
f.path = 'some encoding here'
50
f.args['and some encoding'] = 'here, too'
51
print(f.url)  # 'http://www.google.com/some%20encoding%20here?and+some+encoding=here,+too'
52
```
53

54
## Architecture
55

56
Furl uses a hierarchical component-based design:
57

58
- **furl**: Main URL manipulation class containing all URL components
59
- **Path**: Manages URL path segments with automatic encoding/decoding
60
- **Query**: Handles query parameters using ordered multivalue dictionaries
61
- **Fragment**: Manages URL fragments with their own path and query components
62
- **omdict1D**: One-dimensional ordered multivalue dictionary for parameters
63

64
This design enables precise manipulation of any URL component while maintaining proper encoding and URL structure integrity.
65

66
## Capabilities
67

68
### Core URL Manipulation
69

70
Primary functionality for parsing, constructing, and manipulating complete URLs. Provides the main furl class with comprehensive URL component access and modification methods.
71

72
```python { .api }
73
class furl:
74
    def __init__(self, url='', args=None, path=None, fragment=None,
75
                 scheme=None, netloc=None, origin=None,
76
                 fragment_path=None, fragment_args=None,
77
                 fragment_separator=None, host=None, port=None,
78
                 query=None, query_params=None, username=None,
79
                 password=None, strict=False): ...
80
    
81
    def load(self, url): ...
82
    def add(self, args=None, path=None, fragment_path=None, 
83
            fragment_args=None, query_params=None): ...
84
    def set(self, args=None, path=None, fragment=None, query=None,
85
            scheme=None, username=None, password=None, host=None,
86
            port=None, netloc=None, origin=None): ...
87
    def remove(self, args=None, path=None, fragment=None, query=None,
88
               scheme=False, username=False, password=False, 
89
               host=False, port=False): ...
90
    def tostr(self, query_delimiter='&', query_quote_plus=True,
91
              query_dont_quote=''): ...
92
    def join(self, *urls): ...
93
    def copy(self): ...
94
    def asdict(self): ...
95
```
96

97
[Core URL Manipulation](./core-url.md)
98

99
### Path Manipulation
100

101
URL path handling with segment-based manipulation, automatic encoding/decoding, and support for both absolute and relative paths.
102

103
```python { .api }
104
class Path:
105
    def __init__(self, path='', force_absolute=lambda _: False, strict=False): ...
106
    def load(self, path): ...
107
    def add(self, path): ...
108
    def set(self, path): ...
109
    def remove(self, path): ...
110
    def normalize(self): ...
111
    
112
    @property
113
    def segments(self): ...  # List of path segments
114
    @property 
115
    def isabsolute(self): ...  # Boolean for absolute paths
116
    @property
117
    def isdir(self): ...  # Boolean for directory paths
118
    @property
119
    def isfile(self): ...  # Boolean for file paths
120
```
121

122
[Path Manipulation](./path.md)
123

124
### Query Parameters
125

126
Query string manipulation with support for multiple values per key, custom delimiters, and various encoding options.
127

128
```python { .api }
129
class Query:
130
    def __init__(self, query='', strict=False): ...
131
    def load(self, query): ...
132
    def add(self, args): ...
133
    def set(self, mapping): ...
134
    def remove(self, query): ...
135
    def encode(self, delimiter='&', quote_plus=True, dont_quote=''): ...
136
    
137
    @property
138
    def params(self): ...  # omdict1D of parameters
139
```
140

141
[Query Parameters](./query.md)
142

143
### Fragment Handling
144

145
URL fragment manipulation supporting both path and query components within fragments, with flexible separator handling.
146

147
```python { .api }
148
class Fragment:
149
    def __init__(self, fragment='', strict=False): ...
150
    def load(self, fragment): ...
151
    def add(self, path=None, args=None): ...
152
    def set(self, path=None, args=None, separator=None): ...
153
    def remove(self, fragment=None, path=None, args=None): ...
154
    
155
    @property
156
    def path(self): ...  # Fragment path object
157
    @property
158
    def query(self): ...  # Fragment query object
159
    @property
160
    def separator(self): ...  # Separator between path and query
161
```
162

163
[Fragment Handling](./fragment.md)
164

165
### Utility Functions
166

167
Collection of utility functions for URL validation, encoding, parsing, and manipulation operations.
168

169
```python { .api }
170
def urlsplit(url): ...
171
def urljoin(base, url): ...
172
def get_scheme(url): ...
173
def strip_scheme(url): ...
174
def set_scheme(url, scheme): ...
175
def is_valid_scheme(scheme): ...
176
def is_valid_host(hostname): ...
177
def is_valid_port(port): ...
178
def join_path_segments(*args): ...
179
def remove_path_segments(segments, remove): ...
180
```
181

182
[Utility Functions](./utilities.md)
183

184
## Types
185

186
```python { .api }
187
# Main URL manipulation class
188
class furl:
189
    scheme: str | None
190
    username: str | None  
191
    password: str | None
192
    host: str | None
193
    port: int | None
194
    netloc: str
195
    origin: str
196
    path: Path
197
    query: Query
198
    fragment: Fragment
199
    url: str
200
    args: omdict1D  # Alias for query.params
201

202
# Path manipulation class
203
class Path:
204
    segments: list[str]
205
    isabsolute: bool
206
    isdir: bool
207
    isfile: bool
208

209
# Query parameters class  
210
class Query:
211
    params: omdict1D
212

213
# Fragment class
214
class Fragment:
215
    path: Path
216
    query: Query
217
    separator: str | None
218

219
# Ordered multivalue dictionary
220
class omdict1D:
221
    def __init__(self): ...
222
    def add(self, key, value): ...
223
    def set(self, key, value): ...
224
    def getlist(self, key): ...
225
    def items(self): ...
226
    def allitems(self): ...
227

228
# Package version constants
229
__title__: str = 'furl'
230
__version__: str = '2.1.4'
231
__license__: str = 'Unlicense'
232
__author__: str = 'Ansgar Grunseid'
233
__contact__: str = 'grunseid@gmail.com'
234
__url__: str = 'https://github.com/gruns/furl'
235
__copyright__: str = 'Copyright Ansgar Grunseid'
236
__description__: str = 'URL manipulation made simple.'
237
```