Update docs and tests for ff4869b.

Callers don't need to be updated: all of them catch Exception.

Author: aaugustin

src/websockets/http11.py

@@ -115,6 +115,8 @@ def parse(
 
         The request method, path, and headers are expected to contain only ASCII
         characters. The request path isn't URL-decoded or validated in any way.
+        Non-ASCII header values are decoded as ISO-8859-1, which has been
+        historically allowed, but is now deprecated.
 
         :meth:`parse` doesn't read the request body because WebSocket handshake
         requests don't have one. If the request contains a body, it may be read
@@ -127,6 +129,7 @@ def parse(
         Raises:
             EOFError: If the connection is closed without a full HTTP request.
             SecurityError: If the request exceeds a security limit.
+            UnicodeDecodeError: If the request method or path isn't ASCII.
             ValueError: If the request isn't well formatted.
 
         """
@@ -224,8 +227,9 @@ def parse(
 
         This is a generator-based coroutine.
 
-        The reason phrase and headers are expected to contain only ASCII
-        characters. Other characters are represented with surrogate escapes.
+        The reason phrase and header values are expected to contain only ASCII
+        characters. Non-ASCII values are decoded as ISO-8859-1, which has been
+        historically allowed, but is now deprecated.
 
         Args:
             read_line: Generator-based coroutine that reads a LF-terminated
@@ -339,7 +343,9 @@ def parse_headers(
     """
     Parse HTTP headers.
 
-    Non-ASCII characters are represented with surrogate escapes.
+    Header values are expected to contain only ASCII characters. Non-ASCII
+    values are decoded as ISO-8859-1, which has been historically allowed,
+    but is now deprecated.
 
     Args:
         read_line: Generator-based coroutine that reads a LF-terminated line

tests/test_http11.py

@@ -39,6 +39,16 @@ def test_parse_non_get_method(self):
         self.assertEqual(request.method, "OPTIONS")
         self.assertEqual(request.path, "*")
 
+    def test_parse_non_ascii_method(self):
+        self.reader.feed_data(b"G\xc9T /chat HTTP/1.1\r\n\r\n")
+        with self.assertRaises(UnicodeDecodeError):
+            next(self.parse())
+
+    def test_parse_non_ascii_path(self):
+        self.reader.feed_data(b"GET /caf\xe9 HTTP/1.1\r\n\r\n")
+        with self.assertRaises(UnicodeDecodeError):
+            next(self.parse())
+
     def test_parse_empty(self):
         self.reader.feed_eof()
         with self.assertRaises(EOFError) as raised:
@@ -201,6 +211,11 @@ def test_parse_non_three_digit_status(self):
             str(raised.exception), "invalid status code; expected 100–599; got 007"
         )
 
+    def test_parse_iso_8859_1_reason(self):
+        self.reader.feed_data(b"HTTP/1.1 200 \xd8K\r\nContent-Length: 0\r\n\r\n")
+        response = self.assertGeneratorReturns(self.parse())
+        self.assertEqual(response.reason_phrase, "ØK")
+
     def test_parse_invalid_reason(self):
         self.reader.feed_data(b"HTTP/1.1 200 \x7f\r\n\r\n")
         with self.assertRaises(ValueError) as raised: