websocket: Allow open to be a coroutine

Fixes #2358

websocket: Improve subprotocol support

- Add client-side subprotocol option
- Add selected_subprotocol attribute to client and server objects
- Call select_subprotocol exactly once instead of only on non-empty
- Fix bug in previous select_subprotocol change when multiple
  subprotocols are offered
- Add tests

Updates #2281

Merge pull request #2378 from bdarnell/docs-510

docs: Start release notes for 5.1

concurrent: Fully deprecate return_future

It relies on ExceptionStackContext, so it should go away completely
instead of just losing its callback argument.

docs: Update examples to modern interfaces

Get rid of most uses of callbacks and convert most coroutines to
native form. The sphinx doctests now require python 3.

docs: Start release notes for 5.1

Merge pull request #2377 from bdarnell/wsgi-deprecation

wsgi: Deprecate WSGIAdapter and WSGIApplication

wsgi: Document workaround for asyncio on multithreaded WSGI containers

Fixes #2371

wsgi: Deprecate WSGIAdapter and WSGIApplication

It's already kind of broken on Python 3 for multithreaded WSGI
containers, and it's going to be more difficult to maintain as we move
to native coroutines.

Updates #2371

Merge pull request #2375 from bdarnell/web-deprecation

Deprecate web.asynchronous, stack_context, and more

Merge pull request #2374 from a-pertsev/master

Use `log_exception` method in WebSocketProtocol instead of custom logging

Use `log_exception` method in WebSocketProtocol instead of
custom logging. It is usefull if we need to add some custom
handlers for all unexpected exceptions for example.

twisted: Deprecate TornadoReactor

This is unnecessary when the asyncio event loop can be used instead.

testing: Deprecate stop/wait

Don't mark them for deletion in 6.0. They're used extensively in the
test suite and it's fairly harmless to keep them around.

stack_context: Deprecate ExceptionStackContext

Take extra care with the deprecation warnings since a few modules need
to continue using ExceptionStackContext for backwards compatibility
even though it is not needed in most cases and should not generate
warnings unless it is relied upon.

simple_httpclient: Initial refactoring into coroutines

Eliminates the use of ExceptionStackContext.

simple_httpclient: Move _on_connect next to its caller

Pure cut-and-paste, will make the next diff more readable

stack_context: Deprecate StackContext class

web: Deprecate callback argument to RequestHandler.flush

Also deprecates callback arguments in httputil and http1connection

web: Deprecate asynchronous decorator

web: Add RequestHandler.detach

This method eliminates the need to use the asynchronous decorator on
handlers that may call detach.

Merge pull request #2361 from bdarnell/ioloop-deprecation

iostream: Deprecate callback-based interfaces

iostream: Deprecate callback argument to wait_for_handshake

iostream: Deprecate callback argument to connect()

iostream: Document the non-deprecation of set_close_callback

iostream: Deprecated callback argument to write()

websocket: Refactor implementation to use coroutines

This avoids the deprecated IOStream interfaces and simplifies things a
bit.

iostream: Deprecate streaming_callback arguments

Currently, mixing futures and streaming_callback does not guarantee
ordering (so the returned future could become ready before the last
streaming_callback fires). Specifically, this happens with
test_streaming_read_until_close_after_close if that test is modified
to not use the callback argument. This would cause problems when we
remove the callback argument if we left streaming_callback in place.

These problems are solvable, but probably not worth it since
partial=True is an alternative (and used internally instead of
streaming_callback).

iostream: Deprecate callback arguments to read methods

This requires a lot of mechanical changes throughout the test suite.
tornado.websocket is currently still using the deprecated interfaces
and suppressing the warning.

ioloop: Deprecate some asyncio-incompatible methods

Merge pull request #2360 from bdarnell/httpserver-deprecation

httputil: Deprecate some server-side HTTP interfaces

httputil: Deprecate old interfaces

This is mainly preparation for HTTP/2: request.write was designed to
mix headers and bodies in a way that is no longer supported.

http1connection: Un-deprecate set_close_callback

This method is not actually redundant with
HTTPMessageDelegate.on_connection_close (maybe there is a useful
refactoring that would make it so, but for now it's still useful)

Merge pull request #2359 from bdarnell/multi-content-length-test

test: Reinstate a test that was mistakenly left disabled

appveyor: Upgrade pip with 'python -m pip'

This reportedly works around https://github.com/pypa/pip/issues/5240

test: Reinstate a test that was mistakenly left disabled

This test required some refactoring to construct invalid headers that
we no longer allow handlers to return directly.

Merge pull request #2355 from sinwar/doc-patch

docs: Remove repeated lines.

Merge pull request #2349 from Rookout/FallbackHandler.on_finish

Added RequestHandler.on_finish() to FallbackHandler.preapre()

Merge pull request #2351 from wildfoundry/flow

Add flow control to websocket client

docs: Remove repeated lines.

It removes repeated lines in
docs for release 5.0.0

Support jitter in PeriodicCallback (#2330)

reduces likelihood of alignment with many similar timers

Remove unused import

read queue of 1 message

Merge pull request #2350 from bdarnell/httpclient-deprecation

httpclient: Deprecate fetch callback, narrow `raise_error`

test: Fix some rot in lesser-used test configs

caresresolver: Use non-deprecated interfaces

This code is currently not exercised in CI.

simple_httpclient: Add HTTPError subclasses to bury 599 response code

httpclient: Rename HTTPError to HTTPClientError

This avoids collisions in code that must deal with both
httpclient.HTTPError and web.HTTPError.

testing: Add raise_error argument to AsyncHTTPTestCase.fetch

Give it the same deprecation behavior as AsyncHTTPClient.fetch

httpclient: Deprecation warning for narrowed scope of raise_error=False

httpclient: Deprecate fetch callback

Added RequestHandler.on_finish() to FallbackHandler.preapre()

Fix typo on release notes page

Release notes for 5.0.2

Merge pull request #2338 from bdarnell/periodic-callback

ioloop: Fix PeriodicCallback when system clock moves backwards

ioloop: Fix PeriodicCallback when system clock moves backwards

If the clock moves backwards a little bit, we could run a
PeriodicCallback twice in a row prior to this change.

Due to implementation differences between the Tornado and asyncio
event loops, this is most common when using the asyncio event loop on
windows (where in some environments differences between time.time()
and time.monotonic() can result in behavior that looks like small
backwards time jumps on every iteration), although it can in principle
occur in any environment.

Fixes #2333

ioloop: Factor out the math of PeriodicCallback for easier testing

This permits it to be tested separately from the (now python 2.7-only)
IOLoop configuration.

Merge pull request #2326 from bdarnell/httpclient-leak

asyncio: Fix a leak when event loops are created and destroyed

httpclient: Document inability to use sync HTTPClient in async app

Eliminate a confusing error message when this occurs.

Fixes #2325

asyncio: Fix a leak when event loops are created and destroyed

The WeakKeyDictionary in IOLoop wasn't doing its job because of
reference cycles. This was easiest to see with the synchronous
HTTPClient.

Fixes #2321

Merge pull request #2327 from bdarnell/test-dont-close

testing: Don't close the event loop if we didn't create it

testing: Don't close the event loop if we didn't create it

This improves compatibility with asyncio test frameworks like
pytest-asyncio.

Fixes #2324

Merge pull request #2319 from bdarnell/gen-deprecation

gen: Deprecate legacy interfaces

gen_test: Port some tests to non-deprecated interfaces

This temporarily duplicates the tests, but the versions using the
deprecated interfaces will be gone in 6.0

gen: Doc touchups

gen: Deprecate Task

gen: Deprecate YieldPoint and its subclasses

gen: Deprecate callback argument to coroutines

gen: Deprecate gen.engine

Merge pull request #2318 from bdarnell/concurrent-deprecation

concurrent: Add deprecation warning

escape: Fix doc formatting

concurrent: Deprecate callback argument with run_on_executor

Merge pull request #2317 from bdarnell/auth-deprecation

auth: Add deprecation warnings for callback-based interfaces

auth: Touch up docs

auth: Accept native coroutines in _oauth_get_user_future

auth: Deprecated _oauth_get_user

concurrent,auth: Add deprecation warnings to concurrent.return_future

auth: Add deprecation warnings for anything using auth_return_future

Merge pull request #2316 from bdarnell/work

Maintainer dependency updates

websocket_test: Wrap a long line

flake8 just started complaining about this line for some reason.

Update warning for missing C compiler on macOS

Run new autopep8

Bump maint requirements

Merge remote-tracking branch 'origin/branch5.0'

Merge pull request #2315 from bdarnell/release-501

Set version to 5.0.1

Set version to 5.0.1

Merge pull request #2310 from pcrespov/patch-1

Update running.rst

Update running.rst

minor type

Merge pull request #2307 from bdarnell/work

concurrent,httputil,websocket: small bug fixes

httputil: Clean up error handling in HTTPHeaders.parse

Fixes #2280

concurrent: run_on_executor returns async futures, not concurrent ones

Fixes #2276

websocket: Make ping() argument optional

Also accept both bytes and str, and add a client-side ping() method.

Fixes #2295

Merge pull request #2306 from bdarnell/cherrypick-jessie-compatibility

cherrypick-5.0: asyncio: Support Python 3.4.2 for compatibility with Debian jessie

asyncio: Support Python 3.4.2 for compatibility with Debian jessie

The ensure_future function was not introduced until 3.4.4, and
some exceptions were changed from AssertionError to RuntimeError in
3.4.3.

Fixes #2301

Merge pull request #2305 from bdarnell/jessie-compatibility

asyncio: Support Python 3.4.2 for compatibility with Debian jessie

Merge pull request #2282 from staticglobal/master

Only invoke select_subprotocol() when the client requests it

asyncio: Support Python 3.4.2 for compatibility with Debian jessie

The ensure_future function was not introduced until 3.4.4, and
some exceptions were changed from AssertionError to RuntimeError in
3.4.3.

Fixes #2301

Bump master version to 5.1.dev1

Merge pull request #2300 from bdarnell/release-5.0

Final release notes and version bump for 5.0

Final release notes and version bump for 5.0