Skip to content

Commit 750d74f

Browse files
joernheesorsenthil
authored andcommitted
bpo-12910: update and correct quote docstring (#2568)
Fixes some mistakes and misleadings in the quote function docstring: - reserved chars are never actually used by quote code, unreserved chars are - reserved chars were wrong and incomplete - mentioned that use-case is not minimal quoting wrt. RFC, but cautious quoting
1 parent 63b5fc5 commit 750d74f

File tree

1 file changed

+20
-13
lines changed

1 file changed

+20
-13
lines changed

Lib/urllib/parse.py

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -785,25 +785,32 @@ def quote(string, safe='/', encoding=None, errors=None):
785785
"""quote('abc def') -> 'abc%20def'
786786
787787
Each part of a URL, e.g. the path info, the query, etc., has a
788-
different set of reserved characters that must be quoted.
788+
different set of reserved characters that must be quoted. The
789+
quote function offers a cautious (not minimal) way to quote a
790+
string for most of these parts.
789791
790-
RFC 3986 Uniform Resource Identifiers (URI): Generic Syntax lists
791-
the following reserved characters.
792+
RFC 3986 Uniform Resource Identifier (URI): Generic Syntax lists
793+
the following (un)reserved characters.
792794
793-
reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
794-
"$" | "," | "~"
795+
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
796+
reserved = gen-delims / sub-delims
797+
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
798+
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
799+
/ "*" / "+" / "," / ";" / "="
795800
796-
Each of these characters is reserved in some component of a URL,
801+
Each of the reserved characters is reserved in some component of a URL,
797802
but not necessarily in all of them.
798803
799-
Python 3.7 updates from using RFC 2396 to RFC 3986 to quote URL strings.
800-
Now, "~" is included in the set of reserved characters.
804+
The quote function %-escapes all characters that are neither in the
805+
unreserved chars ("always safe") nor the additional chars set via the
806+
safe arg.
807+
808+
The default for the safe arg is '/'. The character is reserved, but in
809+
typical usage the quote function is being called on a path where the
810+
existing slash characters are to be preserved.
801811
802-
By default, the quote function is intended for quoting the path
803-
section of a URL. Thus, it will not encode '/'. This character
804-
is reserved, but in typical usage the quote function is being
805-
called on a path where the existing slash characters are used as
806-
reserved characters.
812+
Python 3.7 updates from using RFC 2396 to RFC 3986 to quote URL strings.
813+
Now, "~" is included in the set of unreserved characters.
807814
808815
string and safe may be either str or bytes objects. encoding and errors
809816
must not be specified if string is a bytes object.

0 commit comments

Comments
 (0)