`pywebio.platform` — Deploy applications¶

The platform module provides support for deploying PyWebIO applications in different web frameworks.

Directory Deploy¶

You can use path_deploy() or path_deploy_http() to deploy the PyWebIO applications from a directory. You can access the application by using the file path as the URL.

pywebio.platform.path_deploy(base, port=0, host='', index=True, static_dir=None, reconnect_timeout=0, cdn=True, debug=True, allowed_origins=None, check_origin=None, websocket_max_message_size=None, websocket_ping_interval=None, websocket_ping_timeout=None, **tornado_app_settings)[source]¶

Deploy the PyWebIO applications from a directory.

The server communicates with the browser using WebSocket protocol.

Parameters

base (str) – Base directory to load PyWebIO application.
port (int) – The port the server listens on.
host (str) – The host the server listens on.
index (bool/callable) –
Whether to provide a default index page when request a directory, default is True. index also accepts a function to custom index page, which receives the requested directory path as parameter and return HTML content in string.

You can override the index page by add a index.py PyWebIO app file to the directory.
static_dir (str) – Directory to store the application static files. The files in this directory can be accessed via http://<host>:<port>/static/files. For example, if there is a A/B.jpg file in http_static_dir path, it can be accessed via http://<host>:<port>/static/A/B.jpg.
reconnect_timeout (int) – The client can reconnect to server within reconnect_timeout seconds after an unexpected disconnection. If set to 0 (default), once the client disconnects, the server session will be closed.

The rest arguments of path_deploy() have the same meaning as for pywebio.platform.tornado.start_server()

pywebio.platform.path_deploy_http(base, port=0, host='', index=True, static_dir=None, cdn=True, debug=True, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, **tornado_app_settings)[source]¶

Deploy the PyWebIO applications from a directory.

The server communicates with the browser using HTTP protocol.

The base, port, host, index, static_dir arguments of path_deploy_http() have the same meaning as for pywebio.platform.path_deploy()

The rest arguments of path_deploy_http() have the same meaning as for pywebio.platform.tornado_http.start_server()

Application Deploy¶

The start_server() functions can start a Python Web server and serve given PyWebIO applications on it.

The webio_handler() and webio_view() functions can be used to integrate PyWebIO applications into existing Python Web project.

Changed in version 1.1: Added the cdn parameter in start_server(), webio_handler() and webio_view().

Changed in version 1.2: Added the static_dir parameter in start_server().

Tornado support¶

There are two protocols (WebSocket and HTTP) can be used to communicates with the browser:

WebSocket¶

pywebio.platform.tornado.start_server(applications, port=0, host='', debug=False, cdn=True, static_dir=None, reconnect_timeout=0, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, websocket_max_message_size=None, websocket_ping_interval=None, websocket_ping_timeout=None, **tornado_app_settings)[source]¶

Start a Tornado server to provide the PyWebIO application as a web service.

The Tornado server communicates with the browser by WebSocket protocol.

Tornado is the default backend server for PyWebIO applications, and start_server can be imported directly using from pywebio import start_server.

Parameters

applications (list/dict/callable) –
PyWebIO application. Can be a task function, a list of functions, or a dictionary.

When it is a dictionary, whose key is task name and value is task function. When it is a list, using function name as task name.

You can select the task to run through the app URL parameter (for example, visit http://host:port/?app=foo to run the foo task), By default, the index task function is used. When the index task does not exist, PyWebIO will provide a default index home page. See also Server mode

When the task function is a coroutine function, use Coroutine-based session implementation, otherwise, use thread-based session implementation.
port (int) – The port the server listens on. When set to 0, the server will automatically select a available port.
host (str) – The host the server listens on. host may be either an IP address or hostname. If it’s a hostname, the server will listen on all IP addresses associated with the name. host may be an empty string or None to listen on all available interfaces.
debug (bool) – Tornado Server’s debug mode. If enabled, the server will automatically reload for code changes. See tornado doc for more detail.
cdn (bool/str) – Whether to load front-end static resources from CDN, the default is True. Can also use a string to directly set the url of PyWebIO static resources.
static_dir (str) – The directory to store the application static files. The files in this directory can be accessed via http://<host>:<port>/static/files. For example, if there is a A/B.jpg file in http_static_dir path, it can be accessed via http://<host>:<port>/static/A/B.jpg.
reconnect_timeout (int) – The client can reconnect to server within reconnect_timeout seconds after an unexpected disconnection. If set to 0 (default), once the client disconnects, the server session will be closed.
allowed_origins (list) –
The allowed request source list. (The current server host is always allowed) The source contains the protocol, domain name, and port part. Can use Unix shell-style wildcards:
- * matches everything
- ? matches any single character
- [seq] matches any character in seq
- [!seq] matches any character not in seq
Such as: https://*.example.com 、 *://*.example.com

For detail, see Python Doc
check_origin (callable) – The validation function for request source. It receives the source string (which contains protocol, host, and port parts) as parameter and return True/False to indicate that the server accepts/rejects the request. If check_origin is set, the allowed_origins parameter will be ignored.
auto_open_webbrowser (bool) – Whether or not auto open web browser when server is started (if the operating system allows it) .
websocket_max_message_size (int/str) – Max bytes of a message which Tornado can accept. Messages larger than the websocket_max_message_size (default 10MB) will not be accepted. websocket_max_message_size can be a integer indicating the number of bytes, or a string ending with K / M / G (representing kilobytes, megabytes, and gigabytes, respectively). E.g: 500, '40K', '3M'
websocket_ping_interval (int) – If set to a number, all websockets will be pinged every n seconds. This can help keep the connection alive through certain proxy servers which close idle connections, and it can detect if the websocket has failed without being properly closed.
websocket_ping_timeout (int) – If the ping interval is set, and the server doesn’t receive a ‘pong’ in this many seconds, it will close the websocket. The default is three times the ping interval, with a minimum of 30 seconds. Ignored if websocket_ping_interval is not set.
tornado_app_settings – Additional keyword arguments passed to the constructor of tornado.web.Application. For details, please refer: https://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings

pywebio.platform.tornado.webio_handler(applications, cdn=True, reconnect_timeout=0, allowed_origins=None, check_origin=None)[source]¶

Get the RequestHandler class for running PyWebIO applications in Tornado. The RequestHandler communicates with the browser by WebSocket protocol.

The arguments of webio_handler() have the same meaning as for pywebio.platform.tornado.start_server()

HTTP¶

pywebio.platform.tornado_http.start_server(applications, port=8080, host='', debug=False, cdn=True, static_dir=None, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, session_expire_seconds=None, session_cleanup_interval=None, websocket_max_message_size=None, websocket_ping_interval=None, websocket_ping_timeout=None, **tornado_app_settings)[source]¶

Start a Tornado server to provide the PyWebIO application as a web service.

The Tornado server communicates with the browser by HTTP protocol.

Parameters

session_expire_seconds (int) – Session expiration time, in seconds(default 60s). If no client message is received within session_expire_seconds, the session will be considered expired.
session_cleanup_interval (int) – Session cleanup interval, in seconds(default 120s). The server will periodically clean up expired sessions and release the resources occupied by the sessions.

The rest arguments of start_server() have the same meaning as for pywebio.platform.tornado.start_server()

New in version 1.2.

pywebio.platform.tornado_http.webio_handler(applications, cdn=True, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)[source]¶

Get the RequestHandler class for running PyWebIO applications in Tornado. The RequestHandler communicates with the browser by HTTP protocol.

The arguments of webio_handler() have the same meaning as for pywebio.platform.tornado_http.start_server()

New in version 1.2.

Flask support¶

When using the Flask as PyWebIO backend server, you need to install Flask by yourself and make sure the version is not less than 0.10. You can install it with the following command:

pip3 install -U flask>=0.10

pywebio.platform.flask.webio_view(applications, cdn=True, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)[source]¶

Get the view function for running PyWebIO applications in Flask. The view communicates with the browser by HTTP protocol.

The arguments of webio_view() have the same meaning as for pywebio.platform.flask.start_server()

pywebio.platform.flask.start_server(applications, port=8080, host='', cdn=True, static_dir=None, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, debug=False, **flask_options)[source]¶

Start a Flask server to provide the PyWebIO application as a web service.

Parameters

session_expire_seconds (int) – Session expiration time, in seconds(default 600s). If no client message is received within session_expire_seconds, the session will be considered expired.
session_cleanup_interval (int) – Session cleanup interval, in seconds(default 300s). The server will periodically clean up expired sessions and release the resources occupied by the sessions.
debug (bool) – Flask debug mode. If enabled, the server will automatically reload for code changes.
flask_options – Additional keyword arguments passed to the flask.Flask.run. For details, please refer: https://flask.palletsprojects.com/en/1.1.x/api/#flask.Flask.run

The arguments of start_server() have the same meaning as for pywebio.platform.tornado.start_server()

Django support¶

When using the Django as PyWebIO backend server, you need to install Django by yourself and make sure the version is not less than 2.2. You can install it with the following command:

pip3 install -U django>=2.2

pywebio.platform.django.webio_view(applications, cdn=True, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)[source]¶

Get the view function for running PyWebIO applications in Django. The view communicates with the browser by HTTP protocol.

The arguments of webio_view() have the same meaning as for pywebio.platform.flask.webio_view()

pywebio.platform.django.start_server(applications, port=8080, host='', cdn=True, static_dir=None, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, debug=False, **django_options)[source]¶

Start a Django server to provide the PyWebIO application as a web service.

Parameters

debug (bool) – Django debug mode. See Django doc for more detail.
django_options – Additional settings to django server. For details, please refer: https://docs.djangoproject.com/en/3.0/ref/settings/ . Among them, DEBUG, ALLOWED_HOSTS, ROOT_URLCONF, SECRET_KEY are set by PyWebIO and cannot be specified in django_options.

The rest arguments of start_server() have the same meaning as for pywebio.platform.flask.start_server()

aiohttp support¶

When using the aiohttp as PyWebIO backend server, you need to install aiohttp by yourself and make sure the version is not less than 3.1. You can install it with the following command:

pip3 install -U aiohttp>=3.1

pywebio.platform.aiohttp.webio_handler(applications, cdn=True, allowed_origins=None, check_origin=None, websocket_settings=None)[source]¶

Get the Request Handler coroutine for running PyWebIO applications in aiohttp. The handler communicates with the browser by WebSocket protocol.

The arguments of webio_handler() have the same meaning as for pywebio.platform.aiohttp.start_server()

Returns: aiohttp Request Handler

pywebio.platform.aiohttp.start_server(applications, port=0, host='', debug=False, cdn=True, static_dir=None, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, websocket_settings=None, **aiohttp_settings)[source]¶

Start a aiohttp server to provide the PyWebIO application as a web service.

Parameters

websocket_settings (dict) – The parameters passed to the constructor of aiohttp.web.WebSocketResponse. For details, please refer: https://docs.aiohttp.org/en/stable/web_reference.html#websocketresponse
aiohttp_settings – Additional keyword arguments passed to the constructor of aiohttp.web.Application. For details, please refer: https://docs.aiohttp.org/en/stable/web_reference.html#application

The rest arguments of start_server() have the same meaning as for pywebio.platform.tornado.start_server()

Other¶

pywebio.platform.seo(title, description=None, app=None)[source]¶

Set the SEO information of the PyWebIO application (web page information provided when indexed by search engines)

Parameters

title (str) – Application title
description (str) – Application description
app (callable) – PyWebIO task function

If not seo() is not used, the docstring of the task function will be regarded as SEO information by default.

seo() can be used in 2 ways: direct call and decorator:

@seo("title", "description")
def foo():
    pass

def bar():
    pass

def hello():
    """Application title

    Application description...
    (A empty line is used to separate the description and title)
    """

start_server([
    foo,
    hello,
    seo("title", "description", bar),
])

New in version 1.1.

pywebio.platform.run_event_loop(debug=False)[source]¶

run asyncio event loop

Parameters: debug – Set the debug mode of the event loop. See also: https://docs.python.org/3/library/asyncio-dev.html#asyncio-debug-mode

pywebio.platform — Deploy applications¶

Directory Deploy¶

Application Deploy¶

Tornado support¶

WebSocket¶

HTTP¶

Flask support¶

Django support¶

aiohttp support¶

Other¶

`pywebio.platform` — Deploy applications¶