tessl/pypi-furl

URL manipulation made simple.

1.58x

Overview

Eval results

Files

Core URL Manipulation

Name: tessl/pypi-furl
Rating: 0.65 (1 reviews)
Author: tessl

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.

Capabilities

URL Construction and Parsing

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

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):
        """
        Initialize a furl object.
        
        Args:
            url (str): Complete URL string to parse
            args (dict): Query parameters dictionary  
            path (str): URL path component
            fragment (str): URL fragment component
            scheme (str): URL scheme (http, https, etc.)
            netloc (str): Network location (host:port)
            origin (str): Origin (scheme://host:port)
            fragment_path (str): Fragment path component
            fragment_args (dict): Fragment query parameters
            fragment_separator (str): Fragment separator character
            host (str): Host/domain name
            port (int): Port number
            query (str): Query string
            query_params (dict): Query parameters dictionary
            username (str): Username for authentication
            password (str): Password for authentication
            strict (bool): Enable strict parsing mode
        """

    def load(self, url):
        """
        Load and parse a URL string into the furl object.
        
        Args:
            url (str): URL string to parse
            
        Returns:
            furl: Self for method chaining
        """

Usage:

from furl import furl

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

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

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

Component Access and Modification

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

class furl:
    @property
    def scheme(self) -> str | None:
        """URL scheme (http, https, ftp, etc.) or None"""
        
    @scheme.setter
    def scheme(self, scheme: str | None):
        """Set URL scheme with validation"""
        
    username: str | None
        """Username for authentication or None (direct attribute)"""
        
    password: str | None
        """Password for authentication or None (direct attribute)"""
        
    @property
    def host(self) -> str | None:
        """Host/domain name or None"""
        
    @host.setter
    def host(self, host: str | None):
        """Set host with IDNA encoding support"""
        
    @property
    def port(self) -> int | None:
        """Port number or default port for scheme"""
        
    @port.setter
    def port(self, port: int | None):
        """Set port number with validation"""
        
    @property
    def netloc(self) -> str:
        """Network location (username:password@host:port)"""
        
    @netloc.setter
    def netloc(self, netloc: str):
        """Set network location string"""
        
    @property
    def origin(self) -> str:
        """Origin (scheme://host:port)"""
        
    @origin.setter
    def origin(self, origin: str):
        """Set origin string"""
        
    @property
    def url(self) -> str:
        """Complete URL string"""
        
    @url.setter
    def url(self, url: str):
        """Load new URL (alias for load())"""
        
    @property
    def path(self) -> Path:
        """Path object for path manipulation"""
        
    @property
    def query(self) -> Query:
        """Query object for query parameter manipulation"""
        
    @property
    def fragment(self) -> Fragment:
        """Fragment object for fragment manipulation"""
        
    @property
    def args(self) -> omdict1D:
        """Alias for query.params (deprecated, use query.params)"""
        
    @property
    def pathstr(self) -> str:
        """DEPRECATED: String representation of path (use str(furl.path))"""
        
    @property
    def querystr(self) -> str:
        """DEPRECATED: String representation of query (use str(furl.query))"""
        
    @property
    def fragmentstr(self) -> str:
        """DEPRECATED: String representation of fragment (use str(furl.fragment))"""

Usage:

f = furl('http://example.com/path?key=value')

# Access components
print(f.scheme)    # 'http'
print(f.host)      # 'example.com'
print(f.port)      # 80 (default for http)
print(f.netloc)    # 'example.com'
print(f.origin)    # 'http://example.com'

# Modify components
f.scheme = 'https'
f.host = 'secure.example.com'
f.port = 443
print(f.url)  # 'https://secure.example.com/path?key=value'

URL Manipulation Methods

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

class furl:
    def add(self, args=None, path=None, fragment_path=None, 
            fragment_args=None, query_params=None):
        """
        Add components to the URL.
        
        Args:
            args (dict): Query parameters to add
            path (str): Path segments to add
            fragment_path (str): Fragment path segments to add
            fragment_args (dict): Fragment query parameters to add
            query_params (dict): Alias for args
            
        Returns:
            furl: Self for method chaining
        """
        
    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, query_params=None,
            fragment_path=None, fragment_args=None, fragment_separator=None):
        """
        Set URL components, replacing existing values.
        
        Args:
            args (dict): Query parameters to set
            path (str): Path to set
            fragment (str): Fragment to set
            query (str): Query string to set
            scheme (str): Scheme to set
            username (str): Username to set
            password (str): Password to set
            host (str): Host to set
            port (int): Port to set
            netloc (str): Network location to set
            origin (str): Origin to set
            query_params (dict): Alias for args
            fragment_path (str): Fragment path to set
            fragment_args (dict): Fragment query parameters to set
            fragment_separator (str): Fragment separator to set
            
        Returns:
            furl: Self for method chaining
        """
        
    def remove(self, args=None, path=None, fragment=None, query=None,
               scheme=False, username=False, password=False, 
               host=False, port=False, netloc=False, origin=False,
               query_params=None, fragment_path=None, fragment_args=None):
        """
        Remove URL components.
        
        Args:
            args (list): Query parameter keys to remove
            path (str|bool): Path segments to remove or True for all
            fragment (bool): Remove entire fragment if True
            query (bool): Remove entire query if True
            scheme (bool): Remove scheme if True
            username (bool): Remove username if True
            password (bool): Remove password if True
            host (bool): Remove host if True
            port (bool): Remove port if True
            netloc (bool): Remove netloc if True
            origin (bool): Remove origin if True
            query_params (list): Alias for args
            fragment_path (str): Fragment path segments to remove
            fragment_args (list): Fragment query parameter keys to remove
            
        Returns:
            furl: Self for method chaining
        """

Usage:

f = furl('http://example.com/')

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

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

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

# Method chaining
result = (furl('http://example.com/')
          .add({'step': '1'})
          .set(path='/process')
          .add({'step': '2'}))
print(result.url)  # 'http://example.com/process?step=1&step=2'

URL String Generation

Convert furl objects to URL strings with customizable formatting options.

class furl:
    def tostr(self, query_delimiter='&', query_quote_plus=True,
              query_dont_quote=''):
        """
        Convert furl object to URL string.
        
        Args:
            query_delimiter (str): Delimiter for query parameters
            query_quote_plus (bool): Use '+' for spaces in query values
            query_dont_quote (str): Characters not to percent-encode
            
        Returns:
            str: Complete URL string
        """
        
    def __str__(self):
        """String representation of the URL"""
        
    def __unicode__(self):
        """Unicode representation of the URL"""

Usage:

f = furl('http://example.com/path?key=value&other=data')

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

# Custom formatting
custom_url = f.tostr(query_delimiter=';', query_quote_plus=False)
print(custom_url)  # Different query parameter formatting

URL Joining and Copying

Join URLs and create copies of furl objects.

class furl:
    def join(self, *urls):
        """
        Join the current URL with one or more additional URLs.
        
        Args:
            *urls: URL strings to join
            
        Returns:
            furl: Self for method chaining
        """
        
    def copy(self):
        """
        Create a deep copy of the furl object.
        
        Returns:
            furl: New furl object with identical components
        """
        
    def __truediv__(self, path):
        """
        Path division operator (/) for adding path segments.
        
        Args:
            path (str): Path segment to add
            
        Returns:
            furl: New furl object with added path
        """
        
    def asdict(self):
        """
        Convert furl object to dictionary representation.
        
        Returns:
            dict: Dictionary with all URL components
        """

Usage:

base = furl('http://example.com/api')

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

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

# Create copy
backup = base.copy()
base.add(args={'token': 'secret'})
# backup remains unchanged

# Convert to dictionary
components = base.asdict()
print(components['scheme'])  # 'http'
print(components['host'])    # 'example.com'

Error Handling

The furl class handles various error conditions:

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

Install with Tessl CLI

npx tessl i tessl/pypi-furl

tessl/pypi-furl

core-url.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Core URL Manipulation

Capabilities

URL Construction and Parsing

Component Access and Modification

URL Manipulation Methods

URL String Generation

URL Joining and Copying

Error Handling

core-url.mddocs/