hydrotools._restclient.urllib module¶

class hydrotools._restclient.urllib.Url(url: str | ~hydrotools._restclient.urllib.Url, *, quote_treatment: ~hydrotools._restclient.urllib_types.Quote = <object object>, safe: str = <object object>, quote_overide_map: ~typing.Dict[str, str] = {})¶

Bases: UserString, str

Treat urls analogous to pathlib.Path’s treatment of paths.

Examples

Concatenate urls using the forward slash operator (see equivalent Url.joinurl) >>> url = Url(”https://www.test.gov”) / “api” / “feature” >>> print(url) >>> https://www.test.gov/api/feature

Append url query using the plus operator (see equivalent Url.add method) >>> url = url + {“format”: “json”, “sites”: [1,2,3]} >>> print(url) >>> https://www.test.gov/api/feature?format=json&sites=1&sites=2&sites=3

Automagically unquote urls >>> o = Url(”https://www.test.gov/?quoted=%27args%27”) >>> print(o) >>> https://www.test.gov/?quoted=’args’ >>> # Re-quote the url >>> print(o.quote_url) >>> https://www.test.gov/?quoted=%27args%27

Supports comparing quoted and unquoted urls >>> o = Url(”https://www.test.gov/?quoted=%27args%27”) >>> o2 = Url(”https://www.test.gov/?quoted=’args’”) >>> assert o == o2 # True

Note: By default, the “/” is treated as a safe character that is not escaped in url path’s and query’s. This can be changed with the safe key word argument. Likewise, url path’s and query’s are quoted using urllib.parse.quote_plus, where spaces are replaced with +`s to support building queries. Urls are unquoted using urllib.parse.unquote_plus to mirror the behavior when unquoting. To change this behavior, use the `quote_treatment keyword argument and pass a member from the hydrotools._restclient.Quote enum. Options are Quote.QUOTE, Quote.QUOTE_PLUS, or Quote.QUOTE_FROM_BYTES. The quote_overide_map option allows explicit remapping of a character or set of characters in the encoded form of the url. An example use of quote_overide_map is to remap + to %2B, its escaped literal form. This behavior is not supported in urllib.parse which either does not escape + or escapes it as %20. Url instances passed to Url (e.g. Url(Url(“http://www.test.gov”, quote_treatment=Quote.QUOTE, safe=”/+”)) retain non-default quote and safe options unless a non-default quote_treatment / safe / quote_overide_map value is specified respectively.

urls are unquoted at construction time for Url object comparison sake equivalency and readability.

url query parameter values passed as either a list or tuple are represented with individual key=value pairs each seperated by the & (i.e. {“key”: [“v_0”, “v_1”]} -> key=v_0&key=v_1).

_abc_impl = <_abc._abc_data object>¶

static _build_parse_result(url: ParseResult, *, scheme=None, netloc=None, path=None, params=None, query=None, fragment=None) → ParseResult¶

static _build_parse_result_cast_to_url(url: ~urllib.parse.ParseResult, *, quote_treatment: ~hydrotools._restclient.urllib_types.Quote = <object object>, safe: str = <object object>, quote_overide_map: ~typing.Dict[str, str] = {}, **kwargs) → Url¶

static _clean_parse_result(url: ParseResult, unquote_treatment: Quote = Quote.QUOTE_PLUS) → ParseResult¶

static _validate_construction(url: ParseResult)¶

add(b: Dict[str, PRIMITIVE | List[PRIMITIVE]]) → Url¶

Add/append query parameters to Url object url via a dictionary. Dictionary values are either specified as either a primitive or list of primitives. Url query parameter values passed in list are represented with individual key=value pairs each seperated by the & (i.e. {“key”: [“v_0”, “v_1”]} -> key=v_0&key=v_1).

Parameters:: b (Dict[str, Union[PRIMITIVE, List[PRIMITIVE]]]) – mapping of query keywords to query values
Returns:: New Url instance including provided query parameters
Return type:: Url

Example

>>> url = Url("https://www.test.gov") / "api" / "feature"
>>> url = url.add({"format": "json", "sites": [1,2,3]})
>>> # or equivalently
>>> url = url + {"format": "json", "sites": [1,2,3]}
>>> print(url)
>>> https://www.test.gov/api/feature?format=json&sites=1&sites=2&sites=3

joinurl(b: str) → Url¶

Append path to Url url. Erronenous /`s are automatically removed. A single trailing `/ is respected if desired but will not be included if not specified.

Urls can also be joined using the / opporator. This is equivalent to calling the Url.joinurl method. As such, it is recommended to use the more idiomatic / opporator.

Parameters:: b (str) – url path to append
Returns:: New Url instance with appended path, b.
Return type:: Url

Example

>>> url = Url("https://www.test.gov")
>>> url.joinurl("api")
>>> # or equivalently
>>> url = url / "api"
>>> print(url)
>>> https://www.test.gov/api

property quote_treatment: str¶: Method for handling quoted characters

property quote_url: str¶: Quoted string representation of url. Urls quoted using urllib.parse.quote_plus.

property url: str¶: Unquoted string representation of url

class hydrotools._restclient.urllib.Variadic(values: List | Tuple, *, delimeter: str = ',')¶

Bases: UserString, str

join list or tuple on some delimeter. The is useful when specifying arguments in a URL that do not conform to the &key=value&key=value2 convention.

Example

>>> from hydrotools.restclient import ClientSession, Url, Variadic
>>> url = Url("https://www.test.gov")
>>> url = url + {"this": Variadic(["that", "the", "other"])}
>>> print(url.url)
>>> https://www.test.gov/?this=that,the,other

_abc_impl = <_abc._abc_data object>¶

encode(encoding: str = Ellipsis, errors: str = Ellipsis) → bytes¶

Encode the string using the codec registered for encoding.

encoding: The encoding in which to encode the string.
errors: The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.