URI utilities.
This module provides utility functions to parse, encode, decode, and otherwise manipulate a URI. These functions are not available directly in the falcon
module, and so must be explicitly imported:
from falcon import uri name, port = uri.parse_host('example.org:8080')
falcon.uri.encode(uri)
Encodes a full or relative URI according to RFC 3986.
RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters. This function escapes all other “disallowed” characters by percent-encoding them.
Note
This utility is faster in the average case than the similar quote
function found in urlib
. It also strives to be easier to use by assuming a sensible default of allowed characters.
Parameters: |
uri (str) – URI or part of a URI to encode. If this is a wide string (i.e., six.text_type ), it will be encoded to a UTF-8 byte array and any multibyte sequences will be percent-encoded as-is. |
---|---|
Returns: | An escaped version of uri , where all disallowed characters have been percent-encoded. |
Return type: | str |
falcon.uri.encode_value(uri)
Encodes a value string according to RFC 3986.
Disallowed characters are percent-encoded in a way that models urllib.parse.quote(safe="~")
. However, the Falcon function is faster in the average case than the similar quote
function found in urlib. It also strives to be easier to use by assuming a sensible default of allowed characters.
All reserved characters are lumped together into a single set of “delimiters”, and everything in that set is escaped.
Note
RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters.
Parameters: |
uri (str) – URI fragment to encode. It is assumed not to cross delimiter boundaries, and so any reserved URI delimiter characters included in it will be escaped. If value is a wide string (i.e., six.text_type ), it will be encoded to a UTF-8 byte array and any multibyte sequences will be percent-encoded as-is. |
---|---|
Returns: | An escaped version of uri , where all disallowed characters have been percent-encoded. |
Return type: | str |
falcon.uri.decode(encoded_uri)
[source]
Decodes percent-encoded characters in a URI or query string.
This function models the behavior of urllib.unquote_plus
, but is faster. It is also more robust, in that it will decode escaped UTF-8 mutibyte sequences.
Parameters: | encoded_uri (str) – An encoded URI (full or partial). |
---|---|
Returns: | A decoded URL. Will be of type unicode on Python 2 IFF the URL contained escaped non-ASCII characters, in which case UTF-8 is assumed per RFC 3986. |
Return type: | str |
falcon.uri.parse_host(host, default_port=None)
[source]
Parse a canonical ‘host:port’ string into parts.
Parse a host string (which may or may not contain a port) into parts, taking into account that the string may contain either a domain name or an IP address. In the latter case, both IPv4 and IPv6 addresses are supported.
Parameters: | host (str) – Host string to parse, optionally containing a port number. |
---|---|
Keyword Arguments: | |
default_port (int) – Port number to return when the host string does not contain one (default None ). | |
Returns: | A parsed (host, port) tuple from the given host string, with the port converted to an int . If the host string does not specify a port, default_port is used instead. |
Return type: | tuple |
falcon.uri.parse_query_string(query_string, keep_blank_qs_values=False, parse_qs_csv=True)
[source]
Parse a query string into a dict.
Query string parameters are assumed to use standard form-encoding. Only parameters with values are returned. For example, given ‘foo=bar&flag’, this function would ignore ‘flag’ unless the keep_blank_qs_values
option is set.
Note
In addition to the standard HTML form-based method for specifying lists by repeating a given param multiple times, Falcon supports a more compact form in which the param may be given a single time but set to a list
of comma-separated elements (e.g., ‘foo=a,b,c’).
When using this format, all commas uri-encoded will not be treated by Falcon as a delimiter. If the client wants to send a value as a list, it must not encode the commas with the values.
The two different ways of specifying lists may not be mixed in a single query string for the same parameter.
Parameters: |
|
---|---|
Returns: |
A dictionary of (name, value) pairs, one per query parameter. Note that value may be a single |
Return type: | |
Raises: |
|
falcon.uri.unquote_string(quoted)
[source]
Unquote an RFC 7320 “quoted-string”.
Parameters: | quoted (str) – Original quoted string |
---|---|
Returns: | unquoted string |
Return type: | str |
Raises: |
TypeError – quoted was not a str . |
falcon.deprecated(instructions)
[source]
Flags a method as deprecated.
This function returns a decorator which can be used to mark deprecated functions. Applying this decorator will result in a warning being emitted when the function is used.
Parameters: | instructions (str) – Specific guidance for the developer, e.g.: ‘Please migrate to add_proxy(…)’‘ |
---|
falcon.http_now()
[source]
Returns the current UTC time as an IMF-fixdate.
Returns: | The current UTC time as an IMF-fixdate, e.g., ‘Tue, 15 Nov 1994 12:45:26 GMT’. |
---|---|
Return type: | str |
falcon.dt_to_http(dt)
[source]
Converts a datetime
instance to an HTTP date string.
Parameters: |
dt (datetime) – A datetime instance to convert, assumed to be UTC. |
---|---|
Returns: | An RFC 1123 date string, e.g.: “Tue, 15 Nov 1994 12:45:26 GMT”. |
Return type: | str |
falcon.http_date_to_dt(http_date, obs_date=False)
[source]
Converts an HTTP date string to a datetime instance.
Parameters: | http_date (str) – An RFC 1123 date string, e.g.: “Tue, 15 Nov 1994 12:45:26 GMT”. |
---|---|
Keyword Arguments: | |
obs_date (bool) – Support obs-date formats according to RFC 7231, e.g.: “Sunday, 06-Nov-94 08:49:37 GMT” (default False ). | |
Returns: | A UTC datetime instance corresponding to the given HTTP date. |
Return type: | datetime |
Raises: |
ValueError – http_date doesn’t match any of the available time formats |
falcon.to_query_str(params, comma_delimited_lists=True, prefix=True)
[source]
Converts a dictionary of parameters to a query string.
Parameters: |
|
---|---|
Returns: |
A URI query string, including the ‘?’ prefix (unless |
Return type: |
falcon.get_http_status(status_code, default_reason='Unknown')
[source]
Gets both the http status code and description from just a code
Parameters: |
|
---|---|
Returns: |
status code e.g. “404 Not Found” |
Return type: | |
Raises: |
|
falcon.get_bound_method(obj, method_name)
[source]
Get a bound method of the given object by name.
Parameters: |
|
---|---|
Returns: |
Bound method, or |
Raises: |
|
class falcon.TimezoneGMT
[source]
GMT timezone class implementing the datetime.tzinfo
interface.
dst(dt)
[source]
Return the daylight saving time (DST) adjustment.
Parameters: | dt (datetime.datetime) – Ignored |
---|---|
Returns: | DST adjustment for GMT, which is always 0. |
Return type: | datetime.timedelta |
tzname(dt)
[source]
Get the name of this timezone.
Parameters: | dt (datetime.datetime) – Ignored |
---|---|
Returns: | “GMT” |
Return type: | str |
utcoffset(dt)
[source]
Get the offset from UTC.
Parameters: | dt (datetime.datetime) – Ignored |
---|---|
Returns: | GMT offset, which is equivalent to UTC and so is aways 0. |
Return type: | datetime.timedelta |
© 2012–2017 by Rackspace Hosting, Inc. and other contributors
Licensed under the Apache License, Version 2.0.
https://falcon.readthedocs.io/en/1.4.1/api/util.html