Skip to content

Commit b09f9b3

Browse files
vstinnervstinner
committed
asyncio doc: group transport method by classes
Declare classes because they are mentionned in documentation of other functions
1 parent e91f180 commit b09f9b3

1 file changed

Lines changed: 113 additions & 94 deletions

File tree

‎Doc/library/asyncio.rst‎

Lines changed: 113 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -633,100 +633,116 @@ then call the transport's methods for various purposes.
633633
subprocess pipes. The methods available on a transport depend on
634634
the transport's kind.
635635

636-
Methods common to all transports
637-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
638636

639-
.. method:: BaseTransport.close(self)
637+
Methods common to all transports: BaseTransport
638+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
640639

641-
Close the transport. If the transport has a buffer for outgoing
642-
data, buffered data will be flushed asynchronously. No more data
643-
will be received. After all buffered data is flushed, the
644-
protocol's :meth:`connection_lost` method will be called with
645-
:const:`None` as its argument.
640+
.. class:: BaseTransport
646641

642+
Base class for transports.
647643

648-
.. method:: BaseTransport.get_extra_info(name, default=None)
644+
.. method:: close(self)
649645

650-
Return optional transport information. *name* is a string representing
651-
the piece of transport-specific information to get, *default* is the
652-
value to return if the information doesn't exist.
646+
Close the transport. If the transport has a buffer for outgoing
647+
data, buffered data will be flushed asynchronously. No more data
648+
will be received. After all buffered data is flushed, the
649+
protocol's :meth:`connection_lost` method will be called with
650+
:const:`None` as its argument.
653651

654-
This method allows transport implementations to easily expose
655-
channel-specific information.
656652

657-
Methods of readable streaming transports
658-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
653+
.. method:: get_extra_info(name, default=None)
659654

660-
.. method:: ReadTransport.pause_reading()
655+
Return optional transport information. *name* is a string representing
656+
the piece of transport-specific information to get, *default* is the
657+
value to return if the information doesn't exist.
661658

662-
Pause the receiving end of the transport. No data will be passed to
663-
the protocol's :meth:`data_received` method until meth:`resume_reading`
664-
is called.
659+
This method allows transport implementations to easily expose
660+
channel-specific information.
665661

666-
.. method:: ReadTransport.resume_reading()
667662

668-
Resume the receiving end. The protocol's :meth:`data_received` method
669-
will be called once again if some data is available for reading.
663+
Methods of readable streaming transports: ReadTransport
664+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
670665

671-
Methods of writable streaming transports
672-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
666+
.. class:: ReadTransport
673667

674-
.. method:: WriteTransport.write(data)
668+
Interface for read-only transports.
675669

676-
Write some *data* bytes to the transport.
670+
.. method:: pause_reading()
677671

678-
This method does not block; it buffers the data and arranges for it
679-
to be sent out asynchronously.
672+
Pause the receiving end of the transport. No data will be passed to
673+
the protocol's :meth:`data_received` method until meth:`resume_reading`
674+
is called.
680675

681-
.. method:: WriteTransport.writelines(list_of_data)
676+
.. method:: resume_reading()
682677

683-
Write a list (or any iterable) of data bytes to the transport.
684-
This is functionally equivalent to calling :meth:`write` on each
685-
element yielded by the iterable, but may be implemented more efficiently.
678+
Resume the receiving end. The protocol's :meth:`data_received` method
679+
will be called once again if some data is available for reading.
686680

687-
.. method:: WriteTransport.write_eof()
688681

689-
Close the write end of the transport after flushing buffered data.
690-
Data may still be received.
682+
Methods of writable streaming transports: WriteTransport
683+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
691684

692-
This method can raise :exc:`NotImplementedError` if the transport
693-
(e.g. SSL) doesn't support half-closes.
685+
.. class:: WriteTransport
694686

695-
.. method:: WriteTransport.can_write_eof()
687+
Interface for write-only transports.
696688

697-
Return :const:`True` if the transport supports :meth:`write_eof`,
698-
:const:`False` if not.
689+
.. method:: write(data)
699690

700-
.. method:: WriteTransport.abort()
691+
Write some *data* bytes to the transport.
701692

702-
Close the transport immediately, without waiting for pending operations
703-
to complete. Buffered data will be lost. No more data will be received.
704-
The protocol's :meth:`connection_lost` method will eventually be
705-
called with :const:`None` as its argument.
693+
This method does not block; it buffers the data and arranges for it
694+
to be sent out asynchronously.
706695

707-
.. method:: WriteTransport.set_write_buffer_limits(high=None, low=None)
696+
.. method:: writelines(list_of_data)
708697

709-
Set the *high*- and *low*-water limits for write flow control.
698+
Write a list (or any iterable) of data bytes to the transport.
699+
This is functionally equivalent to calling :meth:`write` on each
700+
element yielded by the iterable, but may be implemented more efficiently.
710701

711-
These two values control when call the protocol's
712-
:meth:`pause_writing` and :meth:`resume_writing` methods are called.
713-
If specified, the low-water limit must be less than or equal to the
714-
high-water limit. Neither *high* nor *low* can be negative.
702+
.. method:: write_eof()
703+
704+
Close the write end of the transport after flushing buffered data.
705+
Data may still be received.
715706

716-
The defaults are implementation-specific. If only the
717-
high-water limit is given, the low-water limit defaults to a
718-
implementation-specific value less than or equal to the
719-
high-water limit. Setting *high* to zero forces *low* to zero as
720-
well, and causes :meth:`pause_writing` to be called whenever the
721-
buffer becomes non-empty. Setting *low* to zero causes
722-
:meth:`resume_writing` to be called only once the buffer is empty.
723-
Use of zero for either limit is generally sub-optimal as it
724-
reduces opportunities for doing I/O and computation
725-
concurrently.
707+
This method can raise :exc:`NotImplementedError` if the transport
708+
(e.g. SSL) doesn't support half-closes.
726709

727-
.. method:: WriteTransport.get_write_buffer_size()
710+
.. method:: can_write_eof()
711+
712+
Return :const:`True` if the transport supports :meth:`write_eof`,
713+
:const:`False` if not.
714+
715+
.. method:: abort()
716+
717+
Close the transport immediately, without waiting for pending operations
718+
to complete. Buffered data will be lost. No more data will be received.
719+
The protocol's :meth:`connection_lost` method will eventually be
720+
called with :const:`None` as its argument.
721+
722+
.. method:: set_write_buffer_limits(high=None, low=None)
723+
724+
Set the *high*- and *low*-water limits for write flow control.
725+
726+
These two values control when call the protocol's
727+
:meth:`pause_writing` and :meth:`resume_writing` methods are called.
728+
If specified, the low-water limit must be less than or equal to the
729+
high-water limit. Neither *high* nor *low* can be negative.
730+
731+
The defaults are implementation-specific. If only the
732+
high-water limit is given, the low-water limit defaults to a
733+
implementation-specific value less than or equal to the
734+
high-water limit. Setting *high* to zero forces *low* to zero as
735+
well, and causes :meth:`pause_writing` to be called whenever the
736+
buffer becomes non-empty. Setting *low* to zero causes
737+
:meth:`resume_writing` to be called only once the buffer is empty.
738+
Use of zero for either limit is generally sub-optimal as it
739+
reduces opportunities for doing I/O and computation
740+
concurrently.
741+
742+
.. method:: get_write_buffer_size()
743+
744+
Return the current size of the output buffer used by the transport.
728745

729-
Return the current size of the output buffer used by the transport.
730746

731747
Methods of datagram transports
732748
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -747,47 +763,50 @@ Methods of datagram transports
747763
The protocol's :meth:`connection_lost` method will eventually be
748764
called with :const:`None` as its argument.
749765

766+
750767
Methods of subprocess transports
751768
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
752769

753-
.. method:: BaseSubprocessTransport.get_pid()
770+
.. class:: BaseSubprocessTransport
771+
772+
.. method:: get_pid()
754773

755-
Return the subprocess process id as an integer.
774+
Return the subprocess process id as an integer.
756775

757-
.. method:: BaseSubprocessTransport.get_returncode()
776+
.. method:: get_returncode()
758777

759-
Return the subprocess returncode as an integer or :const:`None`
760-
if it hasn't returned, similarly to the
761-
:attr:`subprocess.Popen.returncode` attribute.
778+
Return the subprocess returncode as an integer or :const:`None`
779+
if it hasn't returned, similarly to the
780+
:attr:`subprocess.Popen.returncode` attribute.
762781

763-
.. method:: BaseSubprocessTransport.get_pipe_transport(fd)
782+
.. method:: get_pipe_transport(fd)
764783

765-
Return the transport for the communication pipe correspondong to the
766-
integer file descriptor *fd*. The return value can be a readable or
767-
writable streaming transport, depending on the *fd*. If *fd* doesn't
768-
correspond to a pipe belonging to this transport, :const:`None` is
769-
returned.
784+
Return the transport for the communication pipe correspondong to the
785+
integer file descriptor *fd*. The return value can be a readable or
786+
writable streaming transport, depending on the *fd*. If *fd* doesn't
787+
correspond to a pipe belonging to this transport, :const:`None` is
788+
returned.
770789

771-
.. method:: BaseSubprocessTransport.send_signal(signal)
790+
.. method:: send_signal(signal)
772791

773-
Send the *signal* number to the subprocess, as in
774-
:meth:`subprocess.Popen.send_signal`.
792+
Send the *signal* number to the subprocess, as in
793+
:meth:`subprocess.Popen.send_signal`.
775794

776-
.. method:: BaseSubprocessTransport.terminate()
795+
.. method:: terminate()
777796

778-
Ask the subprocess to stop, as in :meth:`subprocess.Popen.terminate`.
779-
This method is an alias for the :meth:`close` method.
797+
Ask the subprocess to stop, as in :meth:`subprocess.Popen.terminate`.
798+
This method is an alias for the :meth:`close` method.
780799

781-
On POSIX systems, this method sends SIGTERM to the subprocess.
782-
On Windows, the Windows API function TerminateProcess() is called to
783-
stop the subprocess.
800+
On POSIX systems, this method sends SIGTERM to the subprocess.
801+
On Windows, the Windows API function TerminateProcess() is called to
802+
stop the subprocess.
784803

785-
.. method:: BaseSubprocessTransport.kill(self)
804+
.. method:: kill(self)
786805

787-
Kill the subprocess, as in :meth:`subprocess.Popen.kill`
806+
Kill the subprocess, as in :meth:`subprocess.Popen.kill`
788807

789-
On POSIX systems, the function sends SIGKILL to the subprocess.
790-
On Windows, this method is an alias for :meth:`terminate`.
808+
On POSIX systems, the function sends SIGKILL to the subprocess.
809+
On Windows, this method is an alias for :meth:`terminate`.
791810

792811

793812
Task functions
@@ -843,12 +862,12 @@ Task functions
843862

844863
Return ``True`` if *obj* is a coroutine object.
845864

846-
.. function:: sleep(delay, result=None, *, loop=None)
865+
.. function:: sleep(delay, result=None, \*, loop=None)
847866

848867
Create a :ref:`coroutine <coroutine>` that completes after a given time
849868
(in seconds).
850869

851-
.. function:: shield(arg, *, loop=None)
870+
.. function:: shield(arg, \*, loop=None)
852871

853872
Wait for a future, shielding it from cancellation.
854873

@@ -879,7 +898,7 @@ Task functions
879898
Task
880899
----
881900

882-
.. class:: Task(coro, *, loop=None)
901+
.. class:: Task(coro, \*, loop=None)
883902

884903
A coroutine wrapped in a :class:`~concurrent.futures.Future`.
885904

@@ -893,7 +912,7 @@ Task
893912

894913
Cancel the task.
895914

896-
.. method:: get_stack(self, *, limit=None)
915+
.. method:: get_stack(self, \*, limit=None)
897916

898917
Return the list of stack frames for this task's coroutine.
899918

@@ -913,7 +932,7 @@ Task
913932
For reasons beyond our control, only one stack frame is returned for a
914933
suspended coroutine.
915934

916-
.. method:: print_stack(*, limit=None, file=None)
935+
.. method:: print_stack(\*, limit=None, file=None)
917936

918937
Print the stack or traceback for this task's coroutine.
919938

0 commit comments

Comments
 (0)