Merge branch 'master' into pr/minrk/3029

.github/workflows/build.yml

@@ -0,0 +1,102 @@
+# The "build" workflow produces wheels (and the sdist) for all python
+# versions/platforms. Where possible (i.e. the build is not a cross-compile),
+# the test suite is also run for the wheel (this test covers fewer
+# configurations than the "test" workflow and tox.ini).
+name: Build
+
+on:
+  push:
+    branches:
+      # Run on release branches. This gives us a chance to detect rot in this
+      # configuration before pushing a tag (which we'd rather not have to undo).
+      - "branch[0-9]*"
+    tags:
+      # The main purpose of this workflow is to build wheels for release tags.
+      # It runs automatically on tags matching this pattern and pushes to pypi.
+      - "v*"
+  workflow_dispatch:
+    # Allow this workflow to be run manually (pushing to testpypi instead of pypi)
+
+env:
+  python-version: '3.9'
+
+jobs:
+  build_sdist:
+    name: Build sdist
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        name: Install Python
+        with:
+          python-version: ${{ env.python-version }}
+
+      - name: Check metadata
+        run: "python setup.py check"
+      - name: Build sdist
+        run: "python setup.py sdist && ls -l dist"
+
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./dist/tornado-*.tar.gz
+
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, windows-2022, macos-12]
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        name: Install Python
+        with:
+          python-version: ${{ env.python-version }}
+      - name: Set up QEMU
+        if: runner.os == 'Linux'
+        uses: docker/setup-qemu-action@v2
+        with:
+          platforms: all
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.12.1
+
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./wheelhouse/*.whl
+
+  upload_pypi_test:
+    name: Upload to PyPI (test)
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-22.04
+    if: github.repository == 'tornadoweb/tornado' && github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          name: artifact
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@v1.5.0
+        with:
+          user: __token__
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+          skip_existing: true
+
+  upload_pypi:
+    name: Upload to PyPI (prod)
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-22.04
+    if: github.repository == 'tornadoweb/tornado' && github.event_name == 'push' && github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          name: artifact
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@v1.5.0
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,77 @@
+# The "test" workflow is run on every PR and runs tests across all
+# supported python versions and a range of configurations
+# specified in tox.ini. Also see the "build" workflow which is only
+# run for release branches and covers platforms other than linux-amd64
+# (Platform-specific issues are rare these days so we don't want to
+# take that time on every build).
+
+name: Test
+
+on: pull_request
+
+jobs:
+  # Before starting the full build matrix, run one test configuration
+  # and the linter (the `black` linter is especially likely to catch
+  # first-time contributors).
+  test_quick:
+    name: Run quick tests
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        name: Install Python
+        with:
+          # Lint python version must be synced with tox.ini
+          python-version: '3.8'
+      - name: Install tox
+        run: python -m pip install tox -c requirements.txt
+
+      - name: Run test suite
+        run: python -m tox -e py38,lint
+
+  test_tox:
+    name: Run full tests
+    needs: test_quick
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        include:
+          - python: '3.8'
+            tox_env: py38-full
+          - python: '3.9'
+            tox_env: py39-full
+          - python: '3.10'
+            tox_env: py310-full
+          - python: '3.10.8'
+            # Early versions of 3.10 and 3.11 had different deprecation
+            # warnings in asyncio. Test with them too to make sure everything
+            # works the same way.
+            tox_env: py310-full
+          - python: '3.11'
+            tox_env: py311-full
+          - python: '3.11.0'
+            tox_env: py311-full
+          - python: '3.12.0-alpha - 3.12'
+            tox_env: py312-full
+          - python: 'pypy-3.8'
+            # Pypy is a lot slower due to jit warmup costs, so don't run the
+            # "full" test config there.
+            tox_env: pypy3
+          - python: '3.8'
+            # Docs python version must be synced with tox.ini
+            tox_env: docs
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        name: Install Python
+        with:
+          python-version: ${{ matrix.python}}
+      - name: Install apt packages
+        run: sudo apt-get update && sudo apt-get install libcurl4-openssl-dev
+      - name: Install tox
+        run: python -m pip install tox -c requirements.txt
+
+      - name: Run test suite
+        run: python -m tox -e ${{ matrix.tox_env }}
+

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+
+sphinx:
+  configuration: docs/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: requirements.txt

MANIFEST.in

@@ -1,4 +1,3 @@
-recursive-include demos *.py *.yaml *.html *.css *.js *.xml *.sql README
 recursive-include docs *
 prune docs/build
 include tornado/py.typed
@@ -19,4 +18,7 @@ include tornado/test/test.crt
 include tornado/test/test.key
 include LICENSE
 include README.rst
+include requirements.in
+include requirements.txt
 include runtests.sh
+include tox.ini

README.rst

@@ -20,8 +20,8 @@ Here is a simple "Hello, world" example web app for Tornado:
 
 .. code-block:: python
 
-    import tornado.ioloop
-    import tornado.web
+    import asyncio
+    import tornado
 
     class MainHandler(tornado.web.RequestHandler):
         def get(self):
@@ -32,10 +32,13 @@ Here is a simple "Hello, world" example web app for Tornado:
             (r"/", MainHandler),
         ])
 
-    if __name__ == "__main__":
+    async def main():
         app = make_app()
         app.listen(8888)
-        tornado.ioloop.IOLoop.current().start()
+        await asyncio.Event().wait()
+
+    if __name__ == "__main__":
+        asyncio.run(main())
 
 This example does not use any of Tornado's asynchronous features; for
 that see this `simple chat room

SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+In general, due to limited maintainer bandwidth, only the latest version of
+Tornado is supported with patch releases. Exceptions may be made depending
+on the severity of the bug and the feasibility of backporting a fix to
+older releases. 
+
+## Reporting a Vulnerability
+
+Tornado uses GitHub's security advisory functionality for private vulnerability
+reports. To make a private report, use the "Report a vulnerability" button on
+https://github.com/tornadoweb/tornado/security/advisories

demos/README.rst

@@ -0,0 +1,40 @@
+Tornado Demo Apps
+-----------------
+
+This directory contains several example apps that illustrate the usage of
+various Tornado features. If you're not sure where to start, try the ``chat``,
+``blog``, or ``websocket`` demos.
+
+.. note::
+
+    These applications require features due to be introduced in Tornado 6.3
+    which is not yet released. Unless you are testing the new release,
+    use the GitHub branch selector to access the ``stable`` branch
+    (or the ``branchX.y`` branch corresponding to the version of Tornado you
+    are using) to get a suitable version of the demos.
+
+    TODO: remove this when 6.3 ships.
+
+Web Applications
+~~~~~~~~~~~~~~~~
+
+- ``blog``: A simple database-backed blogging platform, including
+  HTML templates and authentication.
+- ``chat``: A chat room demonstrating live updates via long polling.
+- ``websocket``: Similar to ``chat`` but with WebSockets instead of
+  long polling.
+- ``helloworld``: The simplest possible Tornado web page.
+- ``s3server``: Implements a basic subset of the Amazon S3 API.
+
+Feature demos
+~~~~~~~~~~~~~
+
+- ``facebook``: Authentication with the Facebook Graph API.
+- ``twitter``: Authentication with the Twitter API.
+- ``file_upload``: Client and server support for streaming HTTP request 
+  payloads.
+- ``tcpecho``: Using the lower-level ``IOStream`` interfaces for non-HTTP
+  networking.
+- ``webspider``: Concurrent usage of ``AsyncHTTPClient``, using queues and
+  semaphores.
+