From 294aa60aa60ef635d8b1178a6b0b2357766d47ea Mon Sep 17 00:00:00 2001 From: pgjones Date: Mon, 17 Aug 2020 08:30:18 +0100 Subject: [PATCH] Clarify Optional meaning This clarifies that optional implies the key is missing, not that the key is present with a value of say None (as optional means in the Python typing context). --- specs/lifespan.rst | 6 +- specs/www.rst | 144 ++++++++++++++++++++++++--------------------- 2 files changed, 81 insertions(+), 69 deletions(-) diff --git a/specs/lifespan.rst b/specs/lifespan.rst index 47b290fc..d47c5830 100644 --- a/specs/lifespan.rst +++ b/specs/lifespan.rst @@ -41,7 +41,7 @@ The scope information passed in ``scope`` contains basic metadata: * ``type`` (*Unicode string*) -- ``"lifespan"``. * ``asgi["version"]`` (*Unicode string*) -- The version of the ASGI spec. * ``asgi["spec_version"]`` (*Unicode string*) -- The version of this spec being - used. Optional; defaults to ``"1.0"``. + used. Optional; if missing defaults to ``"1.0"``. If an exception is raised when calling the application callable with a ``lifespan.startup`` message or a ``scope`` with type ``lifespan``, @@ -84,7 +84,7 @@ sees this it should log/print the message provided and then exit. Keys: * ``type`` (*Unicode string*) -- ``"lifespan.startup.failed"``. -* ``message`` (*Unicode string*) -- Optional; defaults to ``""``. +* ``message`` (*Unicode string*) -- Optional; if missing defaults to ``""``. Shutdown - ``receive`` event @@ -118,7 +118,7 @@ sees this it should log/print the message provided and then terminate. Keys: * ``type`` (*Unicode string*) -- ``"lifespan.shutdown.failed"``. -* ``message`` (*Unicode string*) -- Optional; defaults to ``""``. +* ``message`` (*Unicode string*) -- Optional; if missing defaults to ``""``. Version History diff --git a/specs/www.rst b/specs/www.rst index a1a9b809..df928d83 100644 --- a/specs/www.rst +++ b/specs/www.rst @@ -70,9 +70,9 @@ The *connection scope* information passed in ``scope`` contains: * ``asgi["version"]`` (*Unicode string*) -- Version of the ASGI spec. -* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI HTTP spec - this server understands; one of ``"2.0"`` or ``"2.1"``. Optional; if missing - assume ``2.0``. +* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI + HTTP spec this server understands; one of ``"2.0"`` or + ``"2.1"``. Optional; if missing assume ``2.0``. * ``http_version`` (*Unicode string*) -- One of ``"1.0"``, ``"1.1"`` or ``"2"``. @@ -85,16 +85,17 @@ The *connection scope* information passed in ``scope`` contains: string, with percent-encoded sequences and UTF-8 byte sequences decoded into characters. -* ``raw_path`` (*byte string*) -- The original HTTP path component unmodified - from the bytes that were received by the web server. Some web server - implementations may be unable to provide this. Optional; defaults to ``None``. +* ``raw_path`` (*byte string*) -- The original HTTP path component + unmodified from the bytes that were received by the web server. Some + web server implementations may be unable to provide this. Optional; + if missing defaults to ``None``. * ``query_string`` (*byte string*) -- URL portion after the ``?``, percent-encoded. * ``root_path`` (*Unicode string*) -- The root path this application - is mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; defaults - to ``""``. + is mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; if missing + defaults to ``""``. * ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of ``[name, value]`` two-item iterables, where ``name`` is the header name, and @@ -106,13 +107,15 @@ The *connection scope* information passed in ``scope`` contains: the iterable with ``host`` as the header name or replace any existing host header already present. -* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable of - ``[host, port]``, where ``host`` is the remote host's IPv4 or IPv6 address, and - ``port`` is the remote port as an integer. Optional; defaults to ``None``. +* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable + of ``[host, port]``, where ``host`` is the remote host's IPv4 or + IPv6 address, and ``port`` is the remote port as an + integer. Optional; if missing defaults to ``None``. -* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable of - ``[host, port]``, where ``host`` is the listening address for this server, - and ``port`` is the integer listening port. Optional; defaults to ``None``. +* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable + of ``[host, port]``, where ``host`` is the listening address for + this server, and ``port`` is the integer listening port. Optional; + if missing defaults to ``None``. Servers are responsible for handling inbound and outbound chunked transfer encodings. A request with a ``chunked`` encoded body should be automatically @@ -137,15 +140,15 @@ Keys: * ``type`` (*Unicode string*) -- ``"http.request"``. -* ``body`` (*byte string*) -- Body of the request. Optional; defaults to - ``b""``. If ``more_body`` is set, treat as start of body and concatenate - on further chunks. +* ``body`` (*byte string*) -- Body of the request. Optional; if + missing defaults to ``b""``. If ``more_body`` is set, treat as start + of body and concatenate on further chunks. * ``more_body`` (*bool*) -- Signifies if there is additional content to come (as part of a Request message). If ``True``, the consuming - application should wait until it gets a chunk with this set to ``False``. If - ``False``, the request is complete and should be processed. Optional; - defaults to ``False``. + application should wait until it gets a chunk with this set to + ``False``. If ``False``, the request is complete and should be + processed. Optional; if missing defaults to ``False``. Response Start - ``send`` event @@ -171,10 +174,11 @@ Keys: * ``status`` (*int*) -- HTTP status code. -* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of - ``[name, value]`` two-item iterables, where ``name`` is the header name, and - ``value`` is the header value. Order must be preserved in the HTTP response. - Header names must be lowercased. Optional; defaults to an empty list. Pseudo +* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable + of ``[name, value]`` two-item iterables, where ``name`` is the + header name, and ``value`` is the header value. Order must be + preserved in the HTTP response. Header names must be + lowercased. Optional; if missing defaults to an empty list. Pseudo headers (present in HTTP/2 and HTTP/3) must not be present. @@ -190,14 +194,15 @@ Keys: * ``type`` (*Unicode string*) -- ``"http.response.body"``. -* ``body`` (*byte string*) -- HTTP body content. Concatenated onto any previous - ``body`` values sent in this connection scope. Optional; defaults to - ``b""``. +* ``body`` (*byte string*) -- HTTP body content. Concatenated onto any + previous ``body`` values sent in this connection scope. Optional; if + missing defaults to ``b""``. * ``more_body`` (*bool*) -- Signifies if there is additional content - to come (as part of a Response Body message). If ``False``, response will - be taken as complete and closed, and any further messages on the channel - will be ignored. Optional; defaults to ``False``. + to come (as part of a Response Body message). If ``False``, response + will be taken as complete and closed, and any further messages on + the channel will be ignored. Optional; if missing defaults to + ``False``. Disconnect - ``receive`` event @@ -243,12 +248,12 @@ metadata (mostly from the HTTP request line and headers): * ``asgi["version"]`` (*Unicode string*) -- The version of the ASGI spec. -* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI HTTP spec - this server understands; one of ``"2.0"`` or ``"2.1"``. Optional; if missing - assume ``"2.0"``. +* ``asgi["spec_version"]`` (*Unicode string*) -- Version of the ASGI + HTTP spec this server understands; one of ``"2.0"`` or + ``"2.1"``. Optional; if missing assume ``"2.0"``. -* ``http_version`` (*Unicode string*) -- One of ``"1.1"`` or ``"2"``. Optional; - default is ``"1.1"``. +* ``http_version`` (*Unicode string*) -- One of ``"1.1"`` or + ``"2"``. Optional; if missing default is ``"1.1"``. * ``scheme`` (*Unicode string*) -- URL scheme portion (likely ``"ws"`` or ``"wss"``). Optional (but must not be empty); default is ``"ws"``. @@ -257,16 +262,17 @@ metadata (mostly from the HTTP request line and headers): string, with percent-encoded sequences and UTF-8 byte sequences decoded into characters. -* ``raw_path`` (*byte string*) -- The original HTTP path component unmodified - from the bytes that were received by the web server. Some web server - implementations may be unable to provide this. Optional; defaults to ``None``. +* ``raw_path`` (*byte string*) -- The original HTTP path component + unmodified from the bytes that were received by the web server. Some + web server implementations may be unable to provide this. Optional; + if missing defaults to ``None``. -* ``query_string`` (*byte string*) -- URL portion after the ``?``. Optional; - default is empty string. +* ``query_string`` (*byte string*) -- URL portion after the + ``?``. Optional; if missing default is empty string. -* ``root_path`` (*byte string*) -- The root path this application - is mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; defaults - to empty string. +* ``root_path`` (*byte string*) -- The root path this application is + mounted at; same as ``SCRIPT_NAME`` in WSGI. Optional; if missing + defaults to empty string. * ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of ``[name, value]`` two-item iterables, where ``name`` is the header name and @@ -277,16 +283,18 @@ metadata (mostly from the HTTP request line and headers): must be added to the start of the iterable with ``host`` as the header name or replace any existing host header already present. -* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable of - ``[host, port]``, where ``host`` is the remote host's IPv4 or IPv6 address, - and ``port`` is the remote port. Optional; defaults to ``None``. +* ``client`` (*Iterable[Unicode string, int]*) -- A two-item iterable + of ``[host, port]``, where ``host`` is the remote host's IPv4 or + IPv6 address, and ``port`` is the remote port. Optional; if missing + defaults to ``None``. -* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable of - ``[host, port]``, where ``host`` is the listening address for this server, - and ``port`` is the integer listening port. Optional; defaults to ``None``. +* ``server`` (*Iterable[Unicode string, int]*) -- A two-item iterable + of ``[host, port]``, where ``host`` is the listening address for + this server, and ``port`` is the integer listening port. Optional; + if missing defaults to ``None``. -* ``subprotocols`` (*Iterable[Unicode string]*) -- Subprotocols the client - advertised. Optional; defaults to empty list. +* ``subprotocols`` (*Iterable[Unicode string]*) -- Subprotocols the + client advertised. Optional; if missing defaults to empty list. Connect - ``receive`` event @@ -314,16 +322,18 @@ Sent by the application when it wishes to accept an incoming connection. * ``type`` (*Unicode string*) -- ``"websocket.accept"``. -* ``subprotocol`` (*Unicode string*) -- The subprotocol the server wishes to - accept. Optional; defaults to ``None``. +* ``subprotocol`` (*Unicode string*) -- The subprotocol the server + wishes to accept. Optional; if missing defaults to ``None``. -* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable of - ``[name, value]`` two-item iterables, where ``name`` is the header name, and - ``value`` is the header value. Order must be preserved in the HTTP response. - Header names must be lowercased. Must not include a header named - ``sec-websocket-protocol``; use the ``subprotocol`` key instead. Optional; - defaults to an empty list. *Added in spec version 2.1*. Pseudo headers - (present in HTTP/2 and HTTP/3) must not be present. +* ``headers`` (*Iterable[[byte string, byte string]]*) -- An iterable + of ``[name, value]`` two-item iterables, where ``name`` is the + header name, and ``value`` is the header value. Order must be + preserved in the HTTP response. Header names must be + lowercased. Must not include a header named + ``sec-websocket-protocol``; use the ``subprotocol`` key + instead. Optional; if missing defaults to an empty list. *Added in + spec version 2.1*. Pseudo headers (present in HTTP/2 and HTTP/3) + must not be present. Receive - ``receive`` event @@ -335,11 +345,13 @@ Keys: * ``type`` (*Unicode string*) -- ``"websocket.receive"``. -* ``bytes`` (*byte string*) -- The message content, if it was binary mode, or - ``None``. Optional; if missing, it is equivalent to ``None``. +* ``bytes`` (*byte string*) -- The message content, if it was binary + mode, or ``None``. Optional; if missing, it is equivalent to + ``None``. -* ``text`` (*Unicode string*) -- The message content, if it was text mode, or - ``None``. Optional; if missing, it is equivalent to ``None``. +* ``text`` (*Unicode string*) -- The message content, if it was text + mode, or ``None``. Optional; if missing, it is equivalent to + ``None``. Exactly one of ``bytes`` or ``text`` must be non-``None``. One or both keys may be present, however. @@ -395,8 +407,8 @@ with the close code passed in the message (or 1000 if none is specified). * ``type`` (*Unicode string*) -- ``"websocket.close"``. -* ``code`` (*int*) -- The WebSocket close code, as per the WebSocket spec. - Optional; defaults to ``1000``. +* ``code`` (*int*) -- The WebSocket close code, as per the WebSocket + spec. Optional; if missing defaults to ``1000``. WSGI Compatibility