bpo-36889: Document Stream and StreamServer. by tirkarthi · Pull Request #14203 · python/cpython (original) (raw)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just The function can also be used as an async context manager,
drop where it's automatically awaited.
Technically it's not correct: connect returns an internal undocumented object that can be awaited or used by async with. I don't want to document this object but want to provide a clear vision of how to use connect call.

Maybe two short usage examples can help?
E.g.

Connect to TCP socket on *host* : *port* address, return a read-write :class:`Stream` object.

The function can be used with ``await`` to get a connected stream::
    stream = await asyncio.connect('127.0.0.1', 8888)

Also, ``async with`` form is supported, the stream is closed on exit from the block::

   async with asyncio.connect('127.0.0.1', 8888) as stream:
        ...

   *limit* determines the buffer size limit used by the returned :class:`Stream` instance. By default the limit is set to 64 KiB.

    The rest of the arguments are passed directly to :meth:`loop.create_connection`.

I'm not sure about the exact text but I hope you've got my idea. Documentation is hard.