werkzeug.urls

Convert an IRI to a URI. All non-ASCII and unsafe characters are quoted. If the URL has a domain, it is encoded to Punycode. >>> iri_to_uri('http://\u2603.net/p\xe5th?q=\xe8ry%DF') 'http://xn--n3h.net/p%C3%A5th?q=%C3%A8ry%DF' :param iri: The IRI to convert. :param charset: The encoding of the IRI. :param errors: Error handler to use during ``bytes.encode``. :param safe_conversion: Return the URL unchanged if it only contains ASCII characters and no whitespace. See the explanation below. There is a general problem with IRI conversion with some protocols that are in violation of the URI specification. Consider the following two IRIs:: magnet:?xt=uri:whatever itms-services://?action=download-manifest After parsing, we don't know if the scheme requires the ``//``, which is dropped if empty, but conveys different meanings in the final URL if it's present or not. In this case, you can use ``safe_conversion``, which will return the URL unchanged if it only contains ASCII characters and no whitespace. This can result in a URI with unquoted characters if it was not already quoted correctly, but preserves the URL's semantics. Werkzeug uses this for the ``Location`` header for redirects. .. versionchanged:: 0.15 All reserved characters remain unquoted. Previously, only some reserved characters were left unquoted. .. versionchanged:: 0.9.6 The ``safe_conversion`` parameter was added. .. versionadded:: 0.6

Convert a URI to an IRI. All valid UTF-8 characters are unquoted, leaving all reserved and invalid characters quoted. If the URL has a domain, it is decoded from Punycode. >>> uri_to_iri("http://xn--n3h.net/p%C3%A5th?q=%C3%A8ry%DF") 'http://\u2603.net/p\xe5th?q=\xe8ry%DF' :param uri: The URI to convert. :param charset: The encoding to encode unquoted bytes with. :param errors: Error handler to use during ``bytes.encode``. By default, invalid bytes are left quoted. .. versionchanged:: 0.15 All reserved and invalid characters remain quoted. Previously, only some reserved characters were preserved, and invalid bytes were replaced instead of left quoted. .. versionadded:: 0.6

Parse a query string and return it as a :class:`MultiDict`. :param s: The query string to parse. :param charset: Decode bytes to string with this charset. If not given, bytes are returned as-is. :param include_empty: Include keys with empty values in the dict. :param errors: Error handling behavior when decoding bytes. :param separator: Separator character between pairs. :param cls: Container to hold result instead of :class:`MultiDict`. .. versionchanged:: 2.0 The ``decode_keys`` parameter is deprecated and will be removed in Werkzeug 2.1. .. versionchanged:: 0.5 In previous versions ";" and "&" could be used for url decoding. Now only "&" is supported. If you want to use ";", a different ``separator`` can be provided. .. versionchanged:: 0.5 The ``cls`` parameter was added.

Works like :func:`url_decode` but decodes a stream. The behavior of stream and limit follows functions like :func:`~werkzeug.wsgi.make_line_iter`. The generator of pairs is directly fed to the `cls` so you can consume the data while it's parsed. :param stream: a stream with the encoded querystring :param charset: the charset of the query string. If set to `None` no decoding will take place. :param include_empty: Set to `False` if you don't want empty values to appear in the dict. :param errors: the decoding error behavior. :param separator: the pair separator to be used, defaults to ``&`` :param cls: an optional dict class to use. If this is not specified or `None` the default :class:`MultiDict` is used. :param limit: the content length of the URL data. Not necessary if a limited stream is provided. .. versionchanged:: 2.0 The ``decode_keys`` and ``return_iterator`` parameters are deprecated and will be removed in Werkzeug 2.1. .. versionadded:: 0.8

URL encode a dict/`MultiDict`. If a value is `None` it will not appear in the result string. Per default only values are encoded into the target charset strings. :param obj: the object to encode into a query string. :param charset: the charset of the query string. :param sort: set to `True` if you want parameters to be sorted by `key`. :param separator: the separator to be used for the pairs. :param key: an optional function to be used for sorting. For more details check out the :func:`sorted` documentation. .. versionchanged:: 2.0 The ``encode_keys`` parameter is deprecated and will be removed in Werkzeug 2.1. .. versionchanged:: 0.5 Added the ``sort``, ``key``, and ``separator`` parameters.

Like :meth:`url_encode` but writes the results to a stream object. If the stream is `None` a generator over all encoded pairs is returned. :param obj: the object to encode into a query string. :param stream: a stream to write the encoded object into or `None` if an iterator over the encoded pairs should be returned. In that case the separator argument is ignored. :param charset: the charset of the query string. :param sort: set to `True` if you want parameters to be sorted by `key`. :param separator: the separator to be used for the pairs. :param key: an optional function to be used for sorting. For more details check out the :func:`sorted` documentation. .. versionchanged:: 2.0 The ``encode_keys`` parameter is deprecated and will be removed in Werkzeug 2.1. .. versionadded:: 0.8

Sometimes you get an URL by a user that just isn't a real URL because it contains unsafe characters like ' ' and so on. This function can fix some of the problems in a similar way browsers handle data entered by the user: >>> url_fix('http://de.wikipedia.org/wiki/Elf (Begriffskl\xe4rung)') 'http://de.wikipedia.org/wiki/Elf%20(Begriffskl%C3%A4rung)' :param s: the string with the URL to fix. :param charset: The target charset for the URL if the url was given as a string.

Join a base URL and a possibly relative URL to form an absolute interpretation of the latter. :param base: the base URL for the join operation. :param url: the URL to join. :param allow_fragments: indicates whether fragments should be allowed.

Parses a URL from a string into a :class:`URL` tuple. If the URL is lacking a scheme it can be provided as second argument. Otherwise, it is ignored. Optionally fragments can be stripped from the URL by setting `allow_fragments` to `False`. The inverse of this function is :func:`url_unparse`. :param url: the URL to parse. :param scheme: the default schema to use if the URL is schemaless. :param allow_fragments: if set to `False` a fragment will be removed from the URL.

URL encode a single string with a given encoding. :param s: the string to quote. :param charset: the charset to be used. :param safe: an optional sequence of safe characters. :param unsafe: an optional sequence of unsafe characters. .. versionadded:: 0.9.2 The `unsafe` parameter was added.

URL encode a single string with the given encoding and convert whitespace to "+". :param s: The string to quote. :param charset: The charset to be used. :param safe: An optional sequence of safe characters.

The reverse operation to :meth:`url_parse`. This accepts arbitrary as well as :class:`URL` tuples and returns a URL as a string. :param components: the parsed URL as tuple which should be converted into a URL string.

URL decode a single string with a given encoding. If the charset is set to `None` no decoding is performed and raw bytes are returned. :param s: the string to unquote. :param charset: the charset of the query string. If set to `None` no decoding will take place. :param errors: the error handling for the charset decoding.

URL decode a single string with the given `charset` and decode "+" to whitespace. Per default encoding errors are ignored. If you want a different behavior you can set `errors` to ``'replace'`` or ``'strict'``. :param s: The string to unquote. :param charset: the charset of the query string. If set to `None` no decoding will take place. :param errors: The error handling for the `charset` decoding.