Url

class Url

URL as described using the Uniform Resource Identifier (URI) specification (RFC3986).

Raises RuntimeError on invalid URLs, including those with unicode characters. Unicode characters must be percent escaped by encoding them as hex with % escape. Url components are accessible both as encoded and decoded strings.

Encoded strings use .encoded properties and returns strings exactly as they appear in the URL. Setting components to escaped strings via .set_encoded methods preserve the escapes while still percent-escaping reserved characters in the result.

Otherwise properties and methods operate on decoded strings. Retrieving a decoded string unescapes percent-encoded octects with the corresponding characters. Setting component values to unescaped strings will percent-escape any reserved characters in the result.

Note that an empty component is distinct from no component, however getters will return empty strings for missing components.

Documentation is based on Boost.URL.

Normalization

URL can be normalized using any of the .normalize methods:

• scheme is normalized to lowercase

• other components have percent-encoding triplets normalized to uppercase. Percent-encoded octects that correspond to unreserved characters are decoded.

See Specification for more details.

Members defined in Url (94 members)

	authority	R	Return the authority
	encoded_authority	R	Return the authority.
	encoded_fragment	R	Return the fragment
	encoded_host	R	Return the host
	encoded_host_address	R	Return the host
	encoded_host_and_port	R	Return the host and port
	encoded_host_name	R	Return the host name
	encoded_origin	R	Return the origin
	encoded_params	R	Return the query as a sequence of parameters
	encoded_password	R	Return the password
	encoded_path	R	Return the path
	encoded_query	R	Return the query
	encoded_resource	R	Return the resource
	encoded_target	R	Return the target
	encoded_user	R	Return the user
	encoded_userinfo	R	Return the userinfo
	encoded_zone_id	R	Return the IPv6 Zone ID
	fragment	R	Return the fragment
	has_authority	R	Return true if an authority is present
	has_fragment	R	Return true if a fragment is present
	has_password	R	Return true if a password is present
	has_port	R	Return true if a port is present
	has_query	R	Return true if a query is present
	has_scheme	R	Returns true if a scheme is present
	has_userinfo	R	Return true if a userinfo is present
	host	R	Return the host
	host_address	R	Return the host
	host_ipv4_address	R	Return the host IPv4 address
	host_ipv6_address	R	Return the host IPv6 address
	host_ipvfuture	R	Return the host IPvFuture address
	host_name	R	Return the host name
	host_type	R	Return the host type
	is_path_absolute	R	Return true if the path is absolute
	password	R	Return the password
	path	R	Return the path
	port	R	Return the port
	port_number	R	Return the port
	query	R	Return the query
	scheme	R	Returns the scheme
	scheme_id	R	Return the scheme
	user	R	Return the user
	userinfo	R	Return the userinfo
	zone_id	R	Return the IPv6 Zone ID
	__bool__		Returns true if the url is not empty
	__copy__
	__deepcopy__
	__hash__
	__init__
	__len__		Returns the number of characters in the url
	__repr__
	__str__
	clear		Clear the contents while preserving the capacity
	normalize		Normalize all URL components
	normalize_authority		Normalize the URL authority
	normalize_fragment		Normalize the URL fragment
	normalize_path		Normalize the URL path
	normalize_query		Normalize the URL query
	normalize_scheme		Normalize the URL scheme to lowercase
	params		Return the query as a sequence of parameters
	remove_authority		Remove the authority
	remove_fragment		Remove the fragment
	remove_origin		Removes the origin (scheme and authority)
	remove_password		Remove the password
	remove_port		Remove the port without affecting the rest of the authority
	remove_query		Remove the query
	remove_scheme		Remove the scheme
	remove_userinfo		Remove the userinfo if present, without removing any authority.
	reserve		Adjust the capacity without changing the size
	set_encoded_authority		Set the authority
	set_encoded_fragment		Set the fragment.
	set_encoded_host		Set the host
	set_encoded_host_address		Set the host to an address
	set_encoded_host_name		Set the host to a name
	set_encoded_password		Set the password.
	set_encoded_path		Set the path.
	set_encoded_query		Set the query
	set_encoded_user		Set the user
	set_encoded_userinfo		Set the userinfo.
	set_fragment		Set the fragment.
	set_host		Set the host
	set_host_address		Set the host to an address
	set_host_ipv4		Set the host to an address
	set_host_ipv6		Set the host to an address
	set_host_ipvfuture		Set the host to an address
	set_host_name		Set the host to a name
	set_password		Set the password.
	set_path		Set the path.
	set_port		Set the port
	set_port_number		Set the port
	set_query		Set the query
	set_scheme		Set the scheme
	set_scheme_id		Set the scheme
	set_user		Set the user
	set_userinfo		Set the userinfo

 Attributes

property authority: str

Return the authority

property encoded_authority: str

Return the authority.

property encoded_fragment: str

Return the fragment

property encoded_host: str

Return the host

property encoded_host_address: str

Return the host

property encoded_host_and_port: str

Return the host and port

If an authority is present, this returns the host and optional port as a string, which may be empty. Otherwise it returns an empty string.

property encoded_host_name: str

Return the host name

If the host type is Name, this returns the name as a string. Otherwise, returns an empty string.

property encoded_origin: str

Return the origin

If an authority is present, this returns the scheme and authority portion of the url. Otherwise, an empty string is returned.

property encoded_params: list[tuple[str, str | None]]

Return the query as a sequence of parameters

This returns a bidirectional sequence of key/value pairs over the query. Strings returned when iterating the range may contain percent escapes. Changes to the container are not reflected in the underlying URL.

property encoded_password: str

Return the password

This returns the password portion of the userinfo as a percent-encoded string.

property encoded_path: str

Return the path

property encoded_query: str

Return the query

property encoded_resource: str

Return the resource

This returns the resource, which is the portion of the url that includes only the path, query, and fragment.

property encoded_target: str

Return the target

This returns the target, which is the portion of the url that includes only the path and query.

property encoded_user: str

Return the user

property encoded_userinfo: str

Return the userinfo

property encoded_zone_id: str

Return the IPv6 Zone ID

If the host type is IPv6, this returns the Zone ID as a string. Otherwise an empty string is returned.

property fragment: str

Return the fragment

This calculates the fragment of the url, with percent escapes decoded and without the leading pound sign (‘#’) whose presence indicates that the url contains a fragment.

property has_authority: bool

Return true if an authority is present

This returns true if the url contains an authority. The presence of an authority is denoted by a double slash (“//”) at the beginning or after the scheme.

property has_fragment: bool

Return true if a fragment is present

property has_password: bool

Return true if a password is present

This returns true if the userinfo is present and contains a password.

property has_port: bool

Return true if a port is present

This returns true if an authority is present and contains a port.

property has_query: bool

Return true if a query is present

This returns true if this contains a query.

property has_scheme: bool

Returns true if a scheme is present

property has_userinfo: bool

Return true if a userinfo is present

property host: str

Return the host

property host_address: str

Return the host

property host_ipv4_address: syside.IPv4Address

Return the host IPv4 address

If the host type is IPv4, this returns the address. Otherwise, returns a default-constructed value which is equal to the unspecified address “0.0.0.0”.

property host_ipv6_address: syside.IPv6Address

Return the host IPv6 address

If the host type is IPv6, this returns the address. Otherwise, returns a default-constructed value which is equal to the unspecified address “0:0:0:0:0:0:0:0”.

property host_ipvfuture: str

Return the host IPvFuture address

If the host type is IPvFuture, this returns the address as a string. Otherwise, returns an empty string.

property host_name: str

Return the host name

If the host type is Name, this returns the name as a string. Otherwise, returns an empty string.

property host_type: syside.HostType

Return the host type

This returns one of the following constants representing the type of host present.

• HostType.IPv4

• HostType.IPv6

• HostType.IPvFuture

• HostType.Name

• HostType.none

When has_authority is false, the host type is HostType.none.

property is_path_absolute: bool

Return true if the path is absolute

This returns true if the path begins with a forward slash (‘/’)

property password: str

Return the password

property path: str

Return the path

property port: str

Return the port

property port_number: int

Return the port

If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned.

property query: str

Return the query

When plus signs appear in the query portion of the url, they are converted to spaces automatically upon decoding.

property scheme: str

Returns the scheme

property scheme_id: syside.Scheme

Return the scheme

This returns a value which depends on the scheme in the url:

• If the scheme is a well-known scheme, corresponding value from the enumeration Scheme is returned.

• If a scheme is present but is not a well-known scheme, the value returned is Scheme.Unknown.

• Otherwise, the value returned is Scheme.none.

property user: str

Return the user

property userinfo: str

Return the userinfo

property zone_id: str

Return the IPv6 Zone ID

If the host type is IPv6, this returns the Zone ID as a string. Otherwise an empty string is returned.

 Methods

__bool__() → bool

Returns true if the url is not empty

__copy__() → syside.Url

__deepcopy__() → syside.Url

__hash__() → int

__init__() → None

__init__(arg: str, /) → None

__len__() → int

Returns the number of characters in the url

__repr__() → str

__str__() → str

clear() → None

Clear the contents while preserving the capacity

normalize() → syside.Url

Normalize all URL components

normalize_authority() → syside.Url

Normalize the URL authority

normalize_fragment() → syside.Url

Normalize the URL fragment

normalize_path() → syside.Url

Normalize the URL path

normalize_query() → syside.Url

Normalize the URL query

normalize_scheme() → syside.Url

Normalize the URL scheme to lowercase

params(options: syside.EncodingOpts = ...) → list[tuple[str, str | None]]

Return the query as a sequence of parameters

This function returns a bidirectional sequence of key/value pairs over the query. Any percent-escapes in strings returned when iterating the view are decoded first. Changes to the container are not reflected in the underlying URL.

remove_authority() → syside.Url

Remove the authority

This function removes the authority, which includes the userinfo, host, and a port if present.

remove_fragment() → syside.Url

Remove the fragment

remove_origin() → syside.Url

Removes the origin (scheme and authority)

remove_password() → syside.Url

Remove the password

This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect.

Note

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.

remove_port() → syside.Url

Remove the port without affecting the rest of the authority

remove_query() → syside.Url

Remove the query

remove_scheme() → syside.Url

Remove the scheme

remove_userinfo() → syside.Url

Remove the userinfo if present, without removing any authority.

reserve(arg: int, /) → None

Adjust the capacity without changing the size

set_encoded_authority(arg: str, /) → syside.Url

Set the authority

set_encoded_fragment(arg: str, /) → syside.Url

Set the fragment.

set_encoded_host(arg: str, /) → syside.Url

Set the host

Depending on the contents of the passed string, this function sets the host:

• If the string is a valid IPv4 address, then the host is set to the address.

• If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address.

• If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address.

• Otherwise, the host name is set to the string.

In all cases, when this function returns, the URL contains an authority.

set_encoded_host_address(arg: str, /) → syside.Url

Set the host to an address

Depending on the contents of the passed string, this function sets the host:

• If the string is a valid IPv4 address, then the host is set to the address.

• If the string is a valid IPv6 address, then the host is set to that address.

• If the string is a valid IPvFuture, then the host is set to that address.

• Otherwise, the host name is set to the string.

In all cases, when this function returns, the URL contains an authority.

set_encoded_host_name(arg: str, /) → syside.Url

Set the host to a name

set_encoded_password(arg: str, /) → syside.Url

Set the password.

Note

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.

set_encoded_path(arg: str, /) → syside.Url

Set the path.

set_encoded_query(arg: str, /) → syside.Url

Set the query

set_encoded_user(arg: str, /) → syside.Url

Set the user

set_encoded_userinfo(arg: str, /) → syside.Url

Set the userinfo.

The effects on the user and password depend on the presence of a colon (‘:’) in the string:

• If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

• If there is no colon, the user is set to the string. has_password returns false.

Note

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.

set_fragment(arg: str, /) → syside.Url

Set the fragment.

set_host(arg: str, /) → syside.Url

Set the host

Depending on the contents of the passed string, this function sets the host:

• If the string is a valid IPv4 address, then the host is set to the address.

• If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address.

• If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address.

• Otherwise, the host name is set to the string, which may be empty.

In all cases, when this function returns, the URL contains an authority.

set_host_address(arg: str, /) → syside.Url

Set the host to an address

Depending on the contents of the passed string, this function sets the host:

• If the string is a valid IPv4 address, then the host is set to the address.

• If the string is a valid IPv6 address, then the host is set to that address.

• If the string is a valid IPvFuture, then the host is set to that address.

• Otherwise, the host name is set to the string.

In all cases, when this function returns, the URL contains an authority.

set_host_ipv4(arg: syside.IPv4Address, /) → syside.Url

Set the host to an address

The host is set to the specified IPv4 address.

set_host_ipv6(arg: syside.IPv6Address, /) → syside.Url

Set the host to an address

The host is set to the specified IPv6 address.

set_host_ipvfuture(arg: str, /) → syside.Url

Set the host to an address

The host is set to the specified IPvFuture string.

set_host_name(arg: str, /) → syside.Url

Set the host to a name

set_password(arg: str, /) → syside.Url

Set the password.

Note

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.

set_path(arg: str, /) → syside.Url

Set the path.

Note

The library may adjust the final result to ensure that no other parts of the url are semantically affected.

Note

This function does not encode ‘/’ chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded ‘/’s to differentiate it from path separators, the function set_encoded_path should be used instead.

set_port(arg: str, /) → syside.Url

Set the port

This port is set to the string, which must contain only digits or be empty.

set_port_number(arg: int, /) → syside.Url

Set the port

The port is set to the specified integer.

set_query(arg: str, /) → syside.Url

Set the query

set_scheme(arg: str, /) → syside.Url

Set the scheme

The scheme is set to the specified string, which must contain a valid scheme without any trailing colon (‘:’). Note that schemes are case-insensitive, and the canonical form is lowercased.

set_scheme_id(arg: syside.Scheme, /) → syside.Url

Set the scheme

This function sets the scheme to the specified known scheme id, which may not be Unknown or else an error is raide. If the id is none, this function behaves as if remove_scheme were called.

set_user(arg: str, /) → syside.Url

Set the user

set_userinfo(arg: str, /) → syside.Url

Set the userinfo

The effects on the user and password depend on the presence of a colon (‘:’) in the string:

• If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

• If there is no colon, the user is set to the string. has_password returns false.

Note

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.

 Used in

• syside

  • decode_path

  • make_file_url

• syside.BasicDocument

  • url

• syside.DiagnosticContext

  • __init__

  • related_sources

• syside.DiagnosticRelatedInformation

  • __init__

  • uri

• syside.Document

  • create_mt

  • create_st

• syside.DocumentOptions

  • __init__

  • url

• syside.IOSchedule

  • add_source

• syside.TextDocument

  • create_mt

  • create_st

  • url

• syside.TextDocumentData

  • __init__

  • url

• syside.TextDocuments

  • __getitem__

  • change_content

  • close

  • find_or_open

  • move

  • open

  • save

  • visit

  • visit_urls

  • will_save

  • will_save_wait_until

• syside.Url

  • __copy__

  • __deepcopy__

  • normalize

  • normalize_authority

  • normalize_fragment

  • normalize_path

  • normalize_query

  • normalize_scheme

  • remove_authority

  • remove_fragment

  • remove_origin

  • remove_password

  • remove_port

  • remove_query

  • remove_scheme

  • remove_userinfo

  • set_encoded_authority

  • set_encoded_fragment

  • set_encoded_host

  • set_encoded_host_address

  • set_encoded_host_name

  • set_encoded_password

  • set_encoded_path

  • set_encoded_query

  • set_encoded_user

  • set_encoded_userinfo

  • set_fragment

  • set_host

  • set_host_address

  • set_host_ipv4

  • set_host_ipv6

  • set_host_ipvfuture

  • set_host_name

  • set_password

  • set_path

  • set_port

  • set_port_number

  • set_query

  • set_scheme

  • set_scheme_id

  • set_user

  • set_userinfo

• syside.json

  • JsonSourceNew

  • loads