or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-url.mdfragment.mdindex.mdpath.mdquery.mdutilities.md
tile.json

tessl/pypi-furl

URL manipulation made simple.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/furl@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-furl@2.1.0

index.mddocs/

Furl

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.

Package Information

  • Package Name: furl
  • Language: Python
  • Installation: pip install furl
  • Version: 2.1.4
  • License: Unlicense (public domain)
  • Dependencies: six (>=1.8.0), orderedmultidict (>=1.0.1)

Core Imports

from furl import furl

Import specific components:

from furl import furl, Path, Query, Fragment

Basic Usage

from furl import furl

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

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

# Manipulate query parameters
del f.args['one']
f.args['three'] = '3'

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

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

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

Architecture

Furl uses a hierarchical component-based design:

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

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

Capabilities

Core URL Manipulation

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

class furl:
    def __init__(self, url='', args=None, path=None, fragment=None,
                 scheme=None, netloc=None, origin=None,
                 fragment_path=None, fragment_args=None,
                 fragment_separator=None, host=None, port=None,
                 query=None, query_params=None, username=None,
                 password=None, strict=False): ...
    
    def load(self, url): ...
    def add(self, args=None, path=None, fragment_path=None, 
            fragment_args=None, query_params=None): ...
    def set(self, args=None, path=None, fragment=None, query=None,
            scheme=None, username=None, password=None, host=None,
            port=None, netloc=None, origin=None): ...
    def remove(self, args=None, path=None, fragment=None, query=None,
               scheme=False, username=False, password=False, 
               host=False, port=False): ...
    def tostr(self, query_delimiter='&', query_quote_plus=True,
              query_dont_quote=''): ...
    def join(self, *urls): ...
    def copy(self): ...
    def asdict(self): ...

Core URL Manipulation

Path Manipulation

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

class Path:
    def __init__(self, path='', force_absolute=lambda _: False, strict=False): ...
    def load(self, path): ...
    def add(self, path): ...
    def set(self, path): ...
    def remove(self, path): ...
    def normalize(self): ...
    
    @property
    def segments(self): ...  # List of path segments
    @property 
    def isabsolute(self): ...  # Boolean for absolute paths
    @property
    def isdir(self): ...  # Boolean for directory paths
    @property
    def isfile(self): ...  # Boolean for file paths

Path Manipulation

Query Parameters

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

class Query:
    def __init__(self, query='', strict=False): ...
    def load(self, query): ...
    def add(self, args): ...
    def set(self, mapping): ...
    def remove(self, query): ...
    def encode(self, delimiter='&', quote_plus=True, dont_quote=''): ...
    
    @property
    def params(self): ...  # omdict1D of parameters

Query Parameters

Fragment Handling

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

class Fragment:
    def __init__(self, fragment='', strict=False): ...
    def load(self, fragment): ...
    def add(self, path=None, args=None): ...
    def set(self, path=None, args=None, separator=None): ...
    def remove(self, fragment=None, path=None, args=None): ...
    
    @property
    def path(self): ...  # Fragment path object
    @property
    def query(self): ...  # Fragment query object
    @property
    def separator(self): ...  # Separator between path and query

Fragment Handling

Utility Functions

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

def urlsplit(url): ...
def urljoin(base, url): ...
def get_scheme(url): ...
def strip_scheme(url): ...
def set_scheme(url, scheme): ...
def is_valid_scheme(scheme): ...
def is_valid_host(hostname): ...
def is_valid_port(port): ...
def join_path_segments(*args): ...
def remove_path_segments(segments, remove): ...

Utility Functions

Types

# Main URL manipulation class
class furl:
    scheme: str | None
    username: str | None  
    password: str | None
    host: str | None
    port: int | None
    netloc: str
    origin: str
    path: Path
    query: Query
    fragment: Fragment
    url: str
    args: omdict1D  # Alias for query.params

# Path manipulation class
class Path:
    segments: list[str]
    isabsolute: bool
    isdir: bool
    isfile: bool

# Query parameters class  
class Query:
    params: omdict1D

# Fragment class
class Fragment:
    path: Path
    query: Query
    separator: str | None

# Ordered multivalue dictionary
class omdict1D:
    def __init__(self): ...
    def add(self, key, value): ...
    def set(self, key, value): ...
    def getlist(self, key): ...
    def items(self): ...
    def allitems(self): ...

# Package version constants
__title__: str = 'furl'
__version__: str = '2.1.4'
__license__: str = 'Unlicense'
__author__: str = 'Ansgar Grunseid'
__contact__: str = 'grunseid@gmail.com'
__url__: str = 'https://github.com/gruns/furl'
__copyright__: str = 'Copyright Ansgar Grunseid'
__description__: str = 'URL manipulation made simple.'