From 649f13b1dc373ea3ab5d15690b5170d09055cec9 Mon Sep 17 00:00:00 2001 From: Vytautas Liuolia Date: Sun, 22 Sep 2024 14:30:21 +0200 Subject: [PATCH] docs(errors): update keyword-only arg notes --- falcon/errors.py | 257 ++++++++++++++++++++++++------------------- falcon/http_error.py | 9 +- 2 files changed, 151 insertions(+), 115 deletions(-) diff --git a/falcon/errors.py b/falcon/errors.py index d84b8cc43..359ee0cf6 100644 --- a/falcon/errors.py +++ b/falcon/errors.py @@ -223,9 +223,10 @@ class HTTPBadRequest(HTTPError): (See also: RFC 7231, Section 6.5.1) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '400 Bad Request'). @@ -296,9 +297,10 @@ class HTTPUnauthorized(HTTPError): (See also: RFC 7235, Section 3.1) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '401 Unauthorized'). @@ -384,9 +386,10 @@ class HTTPForbidden(HTTPError): (See also: RFC 7231, Section 6.5.4) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '403 Forbidden'). @@ -453,9 +456,10 @@ class HTTPNotFound(HTTPError): (See also: RFC 7231, Section 6.5.3) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Human-friendly error title. If not provided, and @@ -517,9 +521,10 @@ class HTTPRouteNotFound(HTTPNotFound): :class:`~.HTTPRouteNotFound`. Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Human-friendly error title. If not provided, and @@ -570,10 +575,11 @@ class HTTPMethodNotAllowed(HTTPError): (See also: RFC 7231, Section 6.5.5) Note: - ``allowed_methods`` is the only positional argument allowed, the other - arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + `allowed_methods` is the only positional argument allowed, + the other arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Args: allowed_methods (list of str): Allowed HTTP methods for this @@ -654,9 +660,10 @@ class HTTPNotAcceptable(HTTPError): (See also: RFC 7231, Section 6.5.6) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: description (str): Human-friendly description of the error, along with @@ -726,9 +733,10 @@ class HTTPConflict(HTTPError): (See also: RFC 7231, Section 6.5.8) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '409 Conflict'). @@ -803,9 +811,10 @@ class HTTPGone(HTTPError): (See also: RFC 7231, Section 6.5.9) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Human-friendly error title. If not provided, and @@ -869,9 +878,10 @@ class HTTPLengthRequired(HTTPError): (See also: RFC 7231, Section 6.5.10) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '411 Length Required'). @@ -934,9 +944,10 @@ class HTTPPreconditionFailed(HTTPError): (See also: RFC 7232, Section 4.2) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '412 Precondition Failed'). @@ -1001,9 +1012,10 @@ class HTTPPayloadTooLarge(HTTPError): (See also: RFC 7231, Section 6.5.11) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '413 Payload Too Large'). @@ -1080,9 +1092,10 @@ class HTTPUriTooLong(HTTPError): (See also: RFC 7231, Section 6.5.12) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '414 URI Too Long'). @@ -1145,9 +1158,10 @@ class HTTPUnsupportedMediaType(HTTPError): (See also: RFC 7231, Section 6.5.13) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '415 Unsupported Media Type'). @@ -1214,10 +1228,11 @@ class HTTPRangeNotSatisfiable(HTTPError): (See also: RFC 7233, Section 4.4) Note: - ``resource_length`` is the only positional argument allowed, the other - arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + `resource_length` is the only positional argument allowed, + the other arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Args: resource_length: The maximum value for the last-byte-pos of a range @@ -1294,9 +1309,10 @@ class HTTPUnprocessableEntity(HTTPError): (See also: RFC 4918, Section 11.2) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '422 Unprocessable Entity'). @@ -1356,9 +1372,10 @@ class HTTPLocked(HTTPError): (See also: RFC 4918, Section 11.3) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '423 Locked'). @@ -1417,9 +1434,10 @@ class HTTPFailedDependency(HTTPError): (See also: RFC 4918, Section 11.4) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '424 Failed Dependency'). @@ -1486,9 +1504,10 @@ class HTTPPreconditionRequired(HTTPError): (See also: RFC 6585, Section 3) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '428 Precondition Required'). @@ -1552,9 +1571,10 @@ class HTTPTooManyRequests(HTTPError): (See also: RFC 6585, Section 4) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '429 Too Many Requests'). @@ -1629,9 +1649,10 @@ class HTTPRequestHeaderFieldsTooLarge(HTTPError): (See also: RFC 6585, Section 5) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '431 Request Header Fields Too Large'). @@ -1704,9 +1725,10 @@ class HTTPUnavailableForLegalReasons(HTTPError): (See also: RFC 7725, Section 3) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '451 Unavailable For Legal Reasons'). @@ -1764,9 +1786,10 @@ class HTTPInternalServerError(HTTPError): (See also: RFC 7231, Section 6.6.1) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '500 Internal Server Error'). @@ -1831,9 +1854,10 @@ class HTTPNotImplemented(HTTPError): (See also: RFC 7231, Section 6.6.2) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '500 Internal Server Error'). @@ -1894,9 +1918,10 @@ class HTTPBadGateway(HTTPError): (See also: RFC 7231, Section 6.6.3) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '502 Bad Gateway'). @@ -1963,9 +1988,10 @@ class HTTPServiceUnavailable(HTTPError): (See also: RFC 7231, Section 6.6.4) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '503 Service Unavailable'). @@ -2034,9 +2060,10 @@ class HTTPGatewayTimeout(HTTPError): (See also: RFC 7231, Section 6.6.5) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '503 Service Unavailable'). @@ -2101,9 +2128,10 @@ class HTTPVersionNotSupported(HTTPError): (See also: RFC 7231, Section 6.6.6) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '503 Service Unavailable'). @@ -2166,9 +2194,10 @@ class HTTPInsufficientStorage(HTTPError): (See also: RFC 4918, Section 11.5) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '507 Insufficient Storage'). @@ -2228,9 +2257,10 @@ class HTTPLoopDetected(HTTPError): (See also: RFC 5842, Section 7.2) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '508 Loop Detected'). @@ -2302,9 +2332,10 @@ class HTTPNetworkAuthenticationRequired(HTTPError): (See also: RFC 6585, Section 6) Note: - All the arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + All the arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Keyword Args: title (str): Error title (default '511 Network Authentication Required'). @@ -2359,10 +2390,11 @@ class HTTPInvalidHeader(HTTPBadRequest): One of the headers in the request is invalid. Note: - ``msg`` and ``header_name`` are the only positional argument allowed, - the other arguments should be passed as keyword only. Using them as - positional arguments will raise a deprecation warning and will result - in an error in a future version of falcon. + `msg` and `header_name` are the only positional arguments allowed, + the other arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Args: msg (str): A description of why the value is invalid. @@ -2420,10 +2452,11 @@ class HTTPMissingHeader(HTTPBadRequest): A header is missing from the request. Note: - ``header_name`` is the only positional argument allowed, the other - arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + `header_name` is the only positional argument allowed, + the other arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Args: header_name (str): The name of the missing header. @@ -2481,10 +2514,11 @@ class HTTPInvalidParam(HTTPBadRequest): with the request. Note: - ``msg`` and ``param_name`` are the only positional argument allowed, - the other arguments should be passed as keyword only. Using them as - positional arguments will raise a deprecation warning and will result - in an error in a future version of falcon. + `msg` and `param_name` are the only positional arguments allowed, + the other arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Args: msg (str): A description of the invalid parameter. @@ -2544,10 +2578,11 @@ class HTTPMissingParam(HTTPBadRequest): with the request. Note: - ``param_name`` is the only positional argument allowed, the other - arguments should be passed as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + `param_name` is the only positional argument allowed, + the other arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Args: param_name (str): The name of the missing parameter. diff --git a/falcon/http_error.py b/falcon/http_error.py index ac8ad56ba..481121d76 100644 --- a/falcon/http_error.py +++ b/falcon/http_error.py @@ -49,10 +49,11 @@ class HTTPError(Exception): the ``to_xml()`` method. Note: - ``status`` is the only positional argument allowed, the other - arguments should be used as keyword only. Using them as positional - arguments will raise a deprecation warning and will result in an - error in a future version of falcon. + `status` is the only positional argument allowed, + the other arguments are defined as keyword-only. + + Attempting to pass them as positional arguments will make + the interpreter raise an instance of :class:`TypeError`. Args: status (Union[str,int]): HTTP status code or line (e.g.,