Skip to content

URL

Fragment

Bases: Encodable

Represents an encodable URL fragment.

Attributes:

Name Type Description
fragment_str str

The fragment string.

__init__(fragment_str)

Initialize the Fragment object.

Parameters:

Name Type Description Default
fragment_str str

The fragment string.

 required

__str__()

Return the fragment string when converting the object to a string.

Returns:

Name Type Description
str str

The fragment string.

encode()

Encode the fragment string.

Returns:

Name Type Description
str str

The encoded fragment string.

set(fragment_str)

Set a new fragment string.

If the provided string is not already encoded, it will be encoded.

Parameters:

Name Type Description Default
fragment_str str

The new fragment string.

 required

Returns:

Name Type Description
Fragment Self

The updated Fragment object.

Netloc

Bases: Encodable

Represents the network location portion of a URL.

Attributes:

Name Type Description
username Optional[str]

The username for authentication.
password Optional[str]

The password for authentication.
host str

The host name or IP address.
port Optional[int]

The port number.

__init__(netloc)

Initialize the Netloc object.

Parameters:

Name Type Description Default
netloc str

The network location string.

 required

encode()

Encode the network location into a string.

Returns:

Name Type Description
str str

The encoded network location string.

from_args(host, username=None, password=None, port=None) classmethod

Create a new Netloc object from individual arguments.

Parameters:

Name Type Description Default
host str

The host name or IP address.

 required
username Optional[str]

The username for authentication.

 None
password Optional[str]

The password for authentication.

 None
port Optional[int]

The port number.

 None

Returns:

Name Type Description
Netloc Self

The created Netloc object.

load(netloc)

Load the network location from the given netloc string.

Parameters:

Name Type Description Default
netloc str

The network location string.

 required

merge(netloc)

Merge the properties of the given Netloc object with the current object.

Parameters:

Name Type Description Default
netloc Netloc

The Netloc object to merge.

 required

Returns:

Name Type Description
Netloc Netloc

The merged Netloc object.

parse(netloc)

Parse the given netloc string and populate the properties of the Netloc object.

Parameters:

Name Type Description Default
netloc str

The netloc string to parse.

 required

set(host=None, username=None, password=None, port=None)

Set the network location properties.

Parameters:

Name Type Description Default
host Optional[str]

The host name or IP address.

 None
username Optional[str]

The username for authentication.

 None
password Optional[str]

The password for authentication.

 None
port Optional[int]

The port number.

 None

Path

Bases: Encodable

Represents a path in a URL.

Attributes:

Name Type Description
segments list[str]

List of path segments.

isdir: bool property

Check if the path represents a directory.

Path is considered a directory if it is empty or ends with a trailing slash.

Returns:

Name Type Description
bool bool

True if the path is a directory, False otherwise.

isfile: bool property

Check if the path represents a file.

Returns:

Name Type Description
bool bool

True if the path is a file, False if it is a directory.

__init__(pathstr)

Initialize a Path object.

Parameters:

Name Type Description Default
pathstr str

The string representation of the path.

 required

add(path)

Add path segments to the existing path.

Parameters:

Name Type Description Default
path Union[str, Path]

The path segments to add. Can be a string or a Path object.

 required

Returns:

Name Type Description
Path Self

The modified Path object.

encode()

Encode the path segments into a URL-encoded string.

Returns:

Name Type Description
str str

The URL-encoded path string.

normalize()

Normalize the path by removing redundant segments.

Returns:

Name Type Description
Path Self

The normalized Path object.

set(path)

Set the path segments to a new value.

Parameters:

Name Type Description Default
path Union[str, Path]

The new path segments. Can be a string or a Path object.

 required

Returns:

Name Type Description
Path Self

The modified Path object.

Query

Bases: Encodable

Represents a query string and provides methods to manipulate and encode it.

Attributes:

Name Type Description
params defaultdict[str, list[str]]

The dictionary containing query parameters.

__getitem__(key)

Retrieves the values of a query parameter using the square bracket syntax.

Parameters:

Name Type Description Default
key str

The parameter key.

 required

Returns:

Type Description
list[str]

list[str]: The list of parameter values.

__init__(querystr)

Initializes the Query object with the provided query string.

Parameters:

Name Type Description Default
querystr str

The input query string to parse.

 required

__setitem__(key, value)

Sets a query parameter using the square bracket syntax.

Parameters:

Name Type Description Default
key str

The parameter key.

 required
value str

The parameter value.

 required

add(args=None, /, **params)

Adds query parameters to the Query object.

Parameters:

Name Type Description Default
args Optional[Mapping[str, str]]

Additional query parameters as a mapping object.

 None
**params str

Additional query parameters as keyword arguments.

 {}

Returns:

Name Type Description
Query Self

The modified Query object.

encode()

Encodes the query object into a string representation.

Returns:

Name Type Description
str str

The encoded query string.

omit_empty_equal()

Encodes the query object into a string representation, omitting the equal sign if a value is empty.

Returns:

Name Type Description
str str

The encoded query string.

remove(*keys)

Removes query parameters from the Query object.

Parameters:

Name Type Description Default
keys str

The parameter keys to remove.

 ()

Returns:

Name Type Description
Query Self

The modified Query object.

set(args=None, /, **params)

Sets the query parameters, replacing any existing parameters.

Parameters:

Name Type Description Default
args Optional[Mapping[str, str]]

New query parameters as a mapping object.

 None
**params str

New query parameters as keyword arguments.

 {}

Returns:

Name Type Description
Query Self

The modified Query object.

sort()

Sorts the query parameters in lexicographic order based on the parameter names.

Returns:

Name Type Description
Query Self

The modified Query object.

URL

Bases: Encodable

Class representing a URL object.

Attributes:

Name Type Description
scheme str

The URL scheme.
netloc Netloc

The URL netloc.
path Path

The URL path.
query Query

The URL query parameters.
fragment Fragment

The URL fragment.

__init__(val)

Initialize a URL object.

Parameters:

Name Type Description Default
val str

The URL string.

 required

add(queryasdict=None, /, path=None, query=None, fragment=None, netloc=None, netloc_obj=None, scheme=None)

Add components to the URL.

Parameters:

Name Type Description Default
queryasdict Optional[Mapping[str, str]]

Dictionary-like object representing query parameters.

 None
path Optional[str]

Path string to add to the URL.

 None
query Optional[Mapping[str, str]]

Dictionary-like object representing additional query parameters.

 None
fragment Optional[str]

Fragment string to set for the URL.

 None
netloc Optional[str]

Netloc string to set for the URL.

 None
netloc_obj Optional[Netloc]

Netloc object to merge with the existing netloc.

 None
scheme Optional[str]

Scheme to set for the URL.

 None

Returns:

Name Type Description
URL Self

The updated URL object.

copy()

Create a copy of the URL object.

Returns:

Name Type Description
URL Self

The copied URL object.

encode(append_empty_equal=True)

Encode the URL object as a URL string.

Parameters:

Name Type Description Default
append_empty_equal bool

Whether to append empty values with an equal sign in the query string.

 True

Returns:

Name Type Description
str str

The encoded URL string.

from_netloc(netloc=None, *, username=None, password=None, host=None, port=None) classmethod

Create a URL object from a netloc.

Parameters:

Name Type Description Default
netloc Optional[Netloc]

Netloc object to set for the URL.

 None
username Optional[str]

Username for the netloc.

 None
password Optional[str]

Password for the netloc.

 None
host Optional[str]

Host for the netloc.

 None
port Optional[int]

Port for the netloc.

 None

Returns:

Name Type Description
URL Self

The URL object created from the netloc.

load(val)

Parse the given URL string and populate the properties of the URL object.

Parameters:

Name Type Description Default
val str

The URL string.

 required

set(queryasdict=None, /, path=None, query=None, fragment=None, netloc=None, netloc_obj=None, scheme=None)

Set components of the URL.

Parameters:

Name Type Description Default
queryasdict Optional[Mapping[str, str]]

Dictionary-like object representing query parameters.

 None
path Optional[str]

Path string to set for the URL.

 None
query Optional[Mapping[str, str]]

Dictionary-like object representing query parameters.

 None
fragment Optional[str]

Fragment string to set for the URL.

 None
netloc Optional[str]

Netloc string to set for the URL.

 None
netloc_obj Optional[Netloc]

Netloc object to set as the netloc.

 None
scheme Optional[str]

Scheme to set for the URL.

 None

Returns:

Name Type Description
URL Self

The updated URL object.