diff options
| -rw-r--r-- | docs/api.rst | 2 | ||||
| -rw-r--r-- | docs/arguments.rst | 40 | ||||
| -rw-r--r-- | docs/index.rst | 26 |
3 files changed, 49 insertions, 19 deletions
diff --git a/docs/api.rst b/docs/api.rst index c85d4e1..5e0a523 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -5,6 +5,6 @@ .. module:: waitress -.. function:: serve(app, host='0.0.0.0', port=8080, unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1204, recv_bytes=8192, send_bytes=18000, outbuf_overflow=104856, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False) +.. function:: serve(app, listen='0.0.0.0:8080', unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1204, recv_bytes=8192, send_bytes=18000, outbuf_overflow=104856, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False) See :ref:`arguments` for more information. diff --git a/docs/arguments.rst b/docs/arguments.rst index cc74c0c..bc67da4 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -10,9 +10,49 @@ host hostname or IP address (string) on which to listen, default ``0.0.0.0``, which means "all IP addresses on this host". + .. warning:: + May not be used with ``listen`` + + .. deprecated:: 1.0 + port TCP port (integer) on which to listen, default ``8080`` + .. warning:: + May not be used with ``listen`` + + .. deprecated:: 1.0 + +listen + Tell waitress to listen on an host/port combination. When provided on the + command line, one can pass the argument multiple times: + + Example: + + - ``--listen=127.0.0.1:8080`` + - ``--listen=[::1]:8080`` + - ``--listen=*:8080`` + + When used from an application, it has to be provided as a space delineated list of host/port: + + Example: + + - ``listen="127.0.0.1:8080 [::1]:8080"`` + - ``listen="*:8080 *:6543"`` + + A wildcard for the hostname is also supported and will bind to both + IPv4/IPv6 depending on whether they are enabled or disabled. + + IPv6 IP addresses are supported by surrounding the IP address with brackets. + + .. versionadded:: 1.0 + +ipv4 + Enable or disable IPv4 (boolean) + +ipv6 + Enable or disable IPv6 (boolean) + unix_socket Path of Unix socket (string), default is ``None``. If a socket path is specified, a Unix domain socket is made instead of the usual inet domain diff --git a/docs/index.rst b/docs/index.rst index 6a595ad..8963aa8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,17 +15,11 @@ Here's normal usage of the server: .. code-block:: python from waitress import serve - serve(wsgiapp, host='0.0.0.0', port=8080) + serve(wsgiapp, listen='*:8080') -If you want to serve your application on all IP addresses, on port 8080, you -can omit the ``host`` and ``port`` arguments and just call ``serve`` with the -WSGI app as a single argument: +This will run waitress on port 8080 on all available IP addresses, both IPv4 +and IPv6. -.. code-block:: python - - from waitress import serve - serve(wsgiapp) - Press Ctrl-C (or Ctrl-Break on Windows) to exit the server. If you want to serve your application through a UNIX domain socket (to serve @@ -49,8 +43,7 @@ lets you use Waitress's WSGI gateway from a configuration file, e.g.: [server:main] use = egg:waitress#main - host = 127.0.0.1 - port = 8080 + listen = 127.0.0.1:8080 The :term:`PasteDeploy` syntax for UNIX domain sockets is analagous: @@ -67,7 +60,7 @@ Additionally, there is a command line runner called ``waitress-serve``, which can be used in development and in situations where the likes of :term:`PasteDeploy` is not necessary:: - waitress-serve --port=8041 myapp:wsgifunc + waitress-serve --listen=*:8041 myapp:wsgifunc For more information on this, see :ref:`runner`. @@ -153,7 +146,7 @@ You can have the Waitress server use the ``https`` url scheme by default.: .. code-block:: python from waitress import serve - serve(wsgiapp, host='0.0.0.0', port=8080, url_scheme='https') + serve(wsgiapp, listen='0.0.0.0:8080', url_scheme='https') This works if all URLs generated by your application should use the ``https`` scheme. @@ -188,7 +181,7 @@ account.: .. code-block:: python from waitress import serve - serve(wsgiapp, host='0.0.0.0', port=8080, url_prefix='/foo') + serve(wsgiapp, listen='0.0.0.0:8080', url_prefix='/foo') Setting this to any value except the empty string will cause the WSGI ``SCRIPT_NAME`` value to be that value, minus any trailing slashes you add, and @@ -257,8 +250,7 @@ PasteDeploy-style configuration: [server:main] use = egg:waitress#main - host = 127.0.0.1 - port = 8080 + listen = 127.0.0.1:8080 Note that you can also set ``PATH_INFO`` and ``SCRIPT_NAME`` using PrefixMiddleware too (its original purpose, really) instead of using Waitress' @@ -287,8 +279,6 @@ Change History Known Issues ------------ -- Does not yet support IPv6 natively. - - Does not support SSL natively. Support and Development |