A Couple of Documentation Improvements #4285

t-mart · 2019-10-28T11:04:43Z

What do these changes do?

Improve some areas of the documentation that caught me up during development.

Namely:

In faq.rst, the websocket example did not await on the websocket's send_str. Therefore, this coroutine will not function as intended. Also, the example included a psuedocode statement that did not compile, which is inconsistent with the other examples in the docs. I fixed up the psuedocode and added a comment.
In web_advanced.rst, the "simple startup code for serving HTTP site" did not include an long (infinite?) sleep. Without that, your application will stop immediately without any indication as to why. In contrast, web.run_app handles this for you, so switching to the "AppRunner" style could be confusing. This documentation code is also referenced from the whats_new_3_0.rst, so it is probably a common landing point for many readers. I added a while True: await asyncio.sleep(3600) block.

Are there changes in behavior for the user?

No. Just documentation changes.

Checklist

I think the code is well written
Unit tests for the changes exist
Documentation reflects the changes
If you provide code modification, please add yourself to CONTRIBUTORS.txt
- The format is <Name> <Surname>.
- Please keep alphabetical order, the file is sorted by names.
Add a new news fragment into the CHANGES folder
- name it <issue_id>.<type> for example (588.bugfix)
- if you don't have an issue_id change it to the pr id after creating the pr
- ensure type is one of the following:
  - .feature: Signifying a new feature.
  - .bugfix: Signifying a bug fix.
  - .doc: Signifying a documentation improvement.
  - .removal: Signifying a deprecation or removal of public API.
  - .misc: A ticket has been closed, but it is not of interest to users.
- Make sure to use full sentences with correct case and punctuation, for example: "Fix issue with non-ascii contents in doctest text files."

codecov-io · 2019-10-28T11:11:09Z

Codecov Report

Merging #4285 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #4285   +/-   ##
=======================================
  Coverage   97.56%   97.56%           
=======================================
  Files          43       43           
  Lines        8855     8855           
  Branches     1385     1385           
=======================================
  Hits         8639     8639           
  Misses         93       93           
  Partials      123      123

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 33d3244...665f3e3. Read the comment docs.

t-mart · 2019-10-28T11:25:11Z

I'm unclear whether "code modification" in documentation requires a CONTRIBUTORS.txt update. Let me know. Omitting for now.

asvetlov · 2019-10-28T14:41:18Z

Thanks!

CONTRIBUTORS update is up to you.
We like to enumerate all the people who helped the library but don't enforce it.

(cherry picked from commit 1ead89b) Co-authored-by: Tim Martin <tim@timmart.in>

This fixes py-yarl in pkgsrc being too new for py-aiohttp. 3.7.0 (2020-10-24) ================== Features -------- - Response headers are now prepared prior to running ``on_response_prepare`` hooks, directly before headers are sent to the client. `#1958 <https://github.com/aio-libs/aiohttp/issues/1958>`_ - Add a ``quote_cookie`` option to ``CookieJar``, a way to skip quotation wrapping of cookies containing special characters. `#2571 <https://github.com/aio-libs/aiohttp/issues/2571>`_ - Call ``AccessLogger.log`` with the current exception available from ``sys.exc_info()``. `#3557 <https://github.com/aio-libs/aiohttp/issues/3557>`_ - `web.UrlDispatcher.add_routes` and `web.Application.add_routes` return a list of registered `AbstractRoute` instances. `AbstractRouteDef.register` (and all subclasses) return a list of registered resources registered resource. `#3866 <https://github.com/aio-libs/aiohttp/issues/3866>`_ - Added properties of default ClientSession params to ClientSession class so it is available for introspection `#3882 <https://github.com/aio-libs/aiohttp/issues/3882>`_ - Don't cancel web handler on peer disconnection, raise `OSError` on reading/writing instead. `#4080 <https://github.com/aio-libs/aiohttp/issues/4080>`_ - Implement BaseRequest.get_extra_info() to access a protocol transports' extra info. `#4189 <https://github.com/aio-libs/aiohttp/issues/4189>`_ - Added `ClientSession.timeout` property. `#4191 <https://github.com/aio-libs/aiohttp/issues/4191>`_ - allow use of SameSite in cookies. `#4224 <https://github.com/aio-libs/aiohttp/issues/4224>`_ - Use ``loop.sendfile()`` instead of custom implementation if available. `#4269 <https://github.com/aio-libs/aiohttp/issues/4269>`_ - Apply SO_REUSEADDR to test server's socket. `#4393 <https://github.com/aio-libs/aiohttp/issues/4393>`_ - Use .raw_host instead of slower .host in client API `#4402 <https://github.com/aio-libs/aiohttp/issues/4402>`_ - Allow configuring the buffer size of input stream by passing ``read_bufsize`` argument. `#4453 <https://github.com/aio-libs/aiohttp/issues/4453>`_ - Pass tests on Python 3.8 for Windows. `#4513 <https://github.com/aio-libs/aiohttp/issues/4513>`_ - Add `method` and `url` attributes to `TraceRequestChunkSentParams` and `TraceResponseChunkReceivedParams`. `#4674 <https://github.com/aio-libs/aiohttp/issues/4674>`_ - Add ClientResponse.ok property for checking status code under 400. `#4711 <https://github.com/aio-libs/aiohttp/issues/4711>`_ - Don't ceil timeouts that are smaller than 5 seconds. `#4850 <https://github.com/aio-libs/aiohttp/issues/4850>`_ - TCPSite now listens by default on all interfaces instead of just IPv4 when `None` is passed in as the host. `#4894 <https://github.com/aio-libs/aiohttp/issues/4894>`_ - Bump ``http_parser`` to 2.9.4 `#5070 <https://github.com/aio-libs/aiohttp/issues/5070>`_ Bugfixes -------- - Fix keepalive connections not being closed in time `#3296 <https://github.com/aio-libs/aiohttp/issues/3296>`_ - Fix failed websocket handshake leaving connection hanging. `#3380 <https://github.com/aio-libs/aiohttp/issues/3380>`_ - Fix tasks cancellation order on exit. The run_app task needs to be cancelled first for cleanup hooks to run with all tasks intact. `#3805 <https://github.com/aio-libs/aiohttp/issues/3805>`_ - Don't start heartbeat until _writer is set `#4062 <https://github.com/aio-libs/aiohttp/issues/4062>`_ - Fix handling of multipart file uploads without a content type. `#4089 <https://github.com/aio-libs/aiohttp/issues/4089>`_ - Preserve view handler function attributes across middlewares `#4174 <https://github.com/aio-libs/aiohttp/issues/4174>`_ - Fix the string representation of ``ServerDisconnectedError``. `#4175 <https://github.com/aio-libs/aiohttp/issues/4175>`_ - Raising RuntimeError when trying to get encoding from not read body `#4214 <https://github.com/aio-libs/aiohttp/issues/4214>`_ - Remove warning messages from noop. `#4282 <https://github.com/aio-libs/aiohttp/issues/4282>`_ - Raise ClientPayloadError if FormData re-processed. `#4345 <https://github.com/aio-libs/aiohttp/issues/4345>`_ - Fix a warning about unfinished task in ``web_protocol.py`` `#4408 <https://github.com/aio-libs/aiohttp/issues/4408>`_ - Fixed 'deflate' compression. According to RFC 2616 now. `#4506 <https://github.com/aio-libs/aiohttp/issues/4506>`_ - Fixed OverflowError on platforms with 32-bit time_t `#4515 <https://github.com/aio-libs/aiohttp/issues/4515>`_ - Fixed request.body_exists returns wrong value for methods without body. `#4528 <https://github.com/aio-libs/aiohttp/issues/4528>`_ - Fix connecting to link-local IPv6 addresses. `#4554 <https://github.com/aio-libs/aiohttp/issues/4554>`_ - Fix a problem with connection waiters that are never awaited. `#4562 <https://github.com/aio-libs/aiohttp/issues/4562>`_ - Always make sure transport is not closing before reuse a connection. Reuse a protocol based on keepalive in headers is unreliable. For example, uWSGI will not support keepalive even it serves a HTTP 1.1 request, except explicitly configure uWSGI with a ``--http-keepalive`` option. Servers designed like uWSGI could cause aiohttp intermittently raise a ConnectionResetException when the protocol poll runs out and some protocol is reused. `#4587 <https://github.com/aio-libs/aiohttp/issues/4587>`_ - Handle the last CRLF correctly even if it is received via separate TCP segment. `#4630 <https://github.com/aio-libs/aiohttp/issues/4630>`_ - Fix the register_resource function to validate route name before splitting it so that route name can include python keywords. `#4691 <https://github.com/aio-libs/aiohttp/issues/4691>`_ - Improve typing annotations for ``web.Request``, ``aiohttp.ClientResponse`` and ``multipart`` module. `#4736 <https://github.com/aio-libs/aiohttp/issues/4736>`_ - Fix resolver task is not awaited when connector is cancelled `#4795 <https://github.com/aio-libs/aiohttp/issues/4795>`_ - Fix a bug "Aiohttp doesn't return any error on invalid request methods" `#4798 <https://github.com/aio-libs/aiohttp/issues/4798>`_ - Fix HEAD requests for static content. `#4809 <https://github.com/aio-libs/aiohttp/issues/4809>`_ - Fix incorrect size calculation for memoryview `#4890 <https://github.com/aio-libs/aiohttp/issues/4890>`_ - Add HTTPMove to _all__. `#4897 <https://github.com/aio-libs/aiohttp/issues/4897>`_ - Fixed the type annotations in the ``tracing`` module. `#4912 <https://github.com/aio-libs/aiohttp/issues/4912>`_ - Fix typing for multipart ``__aiter__``. `#4931 <https://github.com/aio-libs/aiohttp/issues/4931>`_ - Fix for race condition on connections in BaseConnector that leads to exceeding the connection limit. `#4936 <https://github.com/aio-libs/aiohttp/issues/4936>`_ - Add forced UTF-8 encoding for ``application/rdap+json`` responses. `#4938 <https://github.com/aio-libs/aiohttp/issues/4938>`_ - Fix inconsistency between Python and C http request parsers in parsing pct-encoded URL. `#4972 <https://github.com/aio-libs/aiohttp/issues/4972>`_ - Fix connection closing issue in HEAD request. `#5012 <https://github.com/aio-libs/aiohttp/issues/5012>`_ - Fix type hint on BaseRunner.addresses (from ``List[str]`` to ``List[Any]``) `#5086 <https://github.com/aio-libs/aiohttp/issues/5086>`_ - Make `web.run_app()` more responsive to Ctrl+C on Windows for Python < 3.8. It slightly increases CPU load as a side effect. `#5098 <https://github.com/aio-libs/aiohttp/issues/5098>`_ Improved Documentation ---------------------- - Fix example code in client quick-start `#3376 <https://github.com/aio-libs/aiohttp/issues/3376>`_ - Updated the docs so there is no contradiction in ``ttl_dns_cache`` default value `#3512 <https://github.com/aio-libs/aiohttp/issues/3512>`_ - Add 'Deploy with SSL' to docs. `#4201 <https://github.com/aio-libs/aiohttp/issues/4201>`_ - Change typing of the secure argument on StreamResponse.set_cookie from ``Optional[str]`` to ``Optional[bool]`` `#4204 <https://github.com/aio-libs/aiohttp/issues/4204>`_ - Changes ``ttl_dns_cache`` type from int to Optional[int]. `#4270 <https://github.com/aio-libs/aiohttp/issues/4270>`_ - Simplify README hello word example and add a documentation page for people coming from requests. `#4272 <https://github.com/aio-libs/aiohttp/issues/4272>`_ - Improve some code examples in the documentation involving websockets and starting a simple HTTP site with an AppRunner. `#4285 <https://github.com/aio-libs/aiohttp/issues/4285>`_ - Fix typo in code example in Multipart docs `#4312 <https://github.com/aio-libs/aiohttp/issues/4312>`_ - Fix code example in Multipart section. `#4314 <https://github.com/aio-libs/aiohttp/issues/4314>`_ - Update contributing guide so new contributors read the most recent version of that guide. Update command used to create test coverage reporting. `#4810 <https://github.com/aio-libs/aiohttp/issues/4810>`_ - Spelling: Change "canonize" to "canonicalize". `#4986 <https://github.com/aio-libs/aiohttp/issues/4986>`_ - Add ``aiohttp-sse-client`` library to third party usage list. `#5084 <https://github.com/aio-libs/aiohttp/issues/5084>`_ Misc ---- - `#2856 <https://github.com/aio-libs/aiohttp/issues/2856>`_, `#4218 <https://github.com/aio-libs/aiohttp/issues/4218>`_, `#4250 <https://github.com/aio-libs/aiohttp/issues/4250>`_

t-mart added 2 commits October 28, 2019 05:37

Document "await" for websocket send_str

92c6be9

Document sleep after site.start

22de941

t-mart requested review from asvetlov and webknjaz as code owners October 28, 2019 11:04

Add fragment in CHANGES

a63eb3d

psf-chronographer bot added the bot:chronographer:provided There is a change note present in this PR label Oct 28, 2019

Add trailing newline to CHANGES file

665f3e3

asvetlov approved these changes Oct 28, 2019

View reviewed changes

asvetlov merged commit 1ead89b into aio-libs:master Oct 28, 2019

asvetlov pushed a commit that referenced this pull request Oct 28, 2019

[3.7] A Couple of Documentation Improvements (#4285)

5171230

(cherry picked from commit 1ead89b) Co-authored-by: Tim Martin <tim@timmart.in>

asvetlov added a commit that referenced this pull request Oct 28, 2019

[3.7] A Couple of Documentation Improvements (#4285) (#4288)

7bc5c49

(cherry picked from commit 1ead89b) Co-authored-by: Tim Martin <tim@timmart.in>

t-mart deleted the doc-improvements branch October 28, 2019 20:40

asvetlov pushed a commit that referenced this pull request Oct 16, 2020

A Couple of Documentation Improvements (#4285)

a204341

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A Couple of Documentation Improvements #4285

A Couple of Documentation Improvements #4285

t-mart commented Oct 28, 2019 •

edited

Loading

codecov-io commented Oct 28, 2019 •

edited

Loading

t-mart commented Oct 28, 2019 •

edited

Loading

asvetlov commented Oct 28, 2019

A Couple of Documentation Improvements #4285

A Couple of Documentation Improvements #4285

Conversation

t-mart commented Oct 28, 2019 • edited Loading

What do these changes do?

Are there changes in behavior for the user?

Checklist

codecov-io commented Oct 28, 2019 • edited Loading

Codecov Report

t-mart commented Oct 28, 2019 • edited Loading

asvetlov commented Oct 28, 2019

t-mart commented Oct 28, 2019 •

edited

Loading

codecov-io commented Oct 28, 2019 •

edited

Loading

t-mart commented Oct 28, 2019 •

edited

Loading