asyncio-protocol.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2022, Python Software Foundation
# This file is distributed under the same license as the Python package.
#
# Translators:
msgid ""
msgstr ""
"Project-Id-Version: Python 3.13\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-09-23 07:52+0800\n"
"PO-Revision-Date: 2018-05-23 14:39+0000\n"
"Last-Translator: Adrian Liaw <adrianliaw2000@gmail.com>\n"
"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
"tw)\n"
"Language: zh_TW\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../library/asyncio-protocol.rst:9
msgid "Transports and Protocols"
msgstr "傳輸與協定"

#: ../../library/asyncio-protocol.rst:12
msgid "Preface"
msgstr "前言"

#: ../../library/asyncio-protocol.rst:13
msgid ""
"Transports and Protocols are used by the **low-level** event loop APIs such "
"as :meth:`loop.create_connection`.  They use callback-based programming "
"style and enable high-performance implementations of network or IPC "
"protocols (e.g. HTTP)."
msgstr ""

#: ../../library/asyncio-protocol.rst:18
msgid ""
"Essentially, transports and protocols should only be used in libraries and "
"frameworks and never in high-level asyncio applications."
msgstr ""

#: ../../library/asyncio-protocol.rst:22
msgid "This documentation page covers both `Transports`_ and `Protocols`_."
msgstr ""

#: ../../library/asyncio-protocol.rst:25
msgid "Introduction"
msgstr ""

#: ../../library/asyncio-protocol.rst:26
msgid ""
"At the highest level, the transport is concerned with *how* bytes are "
"transmitted, while the protocol determines *which* bytes to transmit (and to "
"some extent when)."
msgstr ""

#: ../../library/asyncio-protocol.rst:30
msgid ""
"A different way of saying the same thing: a transport is an abstraction for "
"a socket (or similar I/O endpoint) while a protocol is an abstraction for an "
"application, from the transport's point of view."
msgstr ""

#: ../../library/asyncio-protocol.rst:35
msgid ""
"Yet another view is the transport and protocol interfaces together define an "
"abstract interface for using network I/O and interprocess I/O."
msgstr ""

#: ../../library/asyncio-protocol.rst:39
msgid ""
"There is always a 1:1 relationship between transport and protocol objects: "
"the protocol calls transport methods to send data, while the transport calls "
"protocol methods to pass it data that has been received."
msgstr ""

#: ../../library/asyncio-protocol.rst:44
msgid ""
"Most of connection oriented event loop methods (such as :meth:`loop."
"create_connection`) usually accept a *protocol_factory* argument used to "
"create a *Protocol* object for an accepted connection, represented by a "
"*Transport* object. Such methods usually return a tuple of ``(transport, "
"protocol)``."
msgstr ""

#: ../../library/asyncio-protocol.rst:51
msgid "Contents"
msgstr "目錄"

#: ../../library/asyncio-protocol.rst:52
msgid "This documentation page contains the following sections:"
msgstr ""

#: ../../library/asyncio-protocol.rst:54
msgid ""
"The `Transports`_ section documents asyncio :class:`BaseTransport`, :class:"
"`ReadTransport`, :class:`WriteTransport`, :class:`Transport`, :class:"
"`DatagramTransport`, and :class:`SubprocessTransport` classes."
msgstr ""

#: ../../library/asyncio-protocol.rst:59
msgid ""
"The `Protocols`_ section documents asyncio :class:`BaseProtocol`, :class:"
"`Protocol`, :class:`BufferedProtocol`, :class:`DatagramProtocol`, and :class:"
"`SubprocessProtocol` classes."
msgstr ""

#: ../../library/asyncio-protocol.rst:63
msgid ""
"The `Examples`_ section showcases how to work with transports, protocols, "
"and low-level event loop APIs."
msgstr ""

#: ../../library/asyncio-protocol.rst:70
msgid "Transports"
msgstr ""

#: ../../library/asyncio-protocol.rst:72
msgid "**Source code:** :source:`Lib/asyncio/transports.py`"
msgstr "**原始碼：**\\ :source:`Lib/asyncio/transports.py`"

#: ../../library/asyncio-protocol.rst:76
msgid ""
"Transports are classes provided by :mod:`asyncio` in order to abstract "
"various kinds of communication channels."
msgstr ""

#: ../../library/asyncio-protocol.rst:79
msgid ""
"Transport objects are always instantiated by an :ref:`asyncio event loop "
"<asyncio-event-loop>`."
msgstr ""

#: ../../library/asyncio-protocol.rst:82
msgid ""
"asyncio implements transports for TCP, UDP, SSL, and subprocess pipes. The "
"methods available on a transport depend on the transport's kind."
msgstr ""

#: ../../library/asyncio-protocol.rst:85
msgid ""
"The transport classes are :ref:`not thread safe <asyncio-multithreading>`."
msgstr ""

#: ../../library/asyncio-protocol.rst:89
msgid "Transports Hierarchy"
msgstr ""

#: ../../library/asyncio-protocol.rst:93
msgid ""
"Base class for all transports.  Contains methods that all asyncio transports "
"share."
msgstr ""

#: ../../library/asyncio-protocol.rst:98
msgid "A base transport for write-only connections."
msgstr ""

#: ../../library/asyncio-protocol.rst:100
msgid ""
"Instances of the *WriteTransport* class are returned from the :meth:`loop."
"connect_write_pipe` event loop method and are also used by subprocess-"
"related methods like :meth:`loop.subprocess_exec`."
msgstr ""

#: ../../library/asyncio-protocol.rst:107
msgid "A base transport for read-only connections."
msgstr ""

#: ../../library/asyncio-protocol.rst:109
msgid ""
"Instances of the *ReadTransport* class are returned from the :meth:`loop."
"connect_read_pipe` event loop method and are also used by subprocess-related "
"methods like :meth:`loop.subprocess_exec`."
msgstr ""

#: ../../library/asyncio-protocol.rst:116
msgid ""
"Interface representing a bidirectional transport, such as a TCP connection."
msgstr ""

#: ../../library/asyncio-protocol.rst:119
msgid ""
"The user does not instantiate a transport directly; they call a utility "
"function, passing it a protocol factory and other information necessary to "
"create the transport and protocol."
msgstr ""

#: ../../library/asyncio-protocol.rst:123
msgid ""
"Instances of the *Transport* class are returned from or used by event loop "
"methods like :meth:`loop.create_connection`, :meth:`loop."
"create_unix_connection`, :meth:`loop.create_server`, :meth:`loop.sendfile`, "
"etc."
msgstr ""

#: ../../library/asyncio-protocol.rst:131
msgid "A transport for datagram (UDP) connections."
msgstr ""

#: ../../library/asyncio-protocol.rst:133
msgid ""
"Instances of the *DatagramTransport* class are returned from the :meth:`loop."
"create_datagram_endpoint` event loop method."
msgstr ""

#: ../../library/asyncio-protocol.rst:139
msgid ""
"An abstraction to represent a connection between a parent and its child OS "
"process."
msgstr ""

#: ../../library/asyncio-protocol.rst:142
msgid ""
"Instances of the *SubprocessTransport* class are returned from event loop "
"methods :meth:`loop.subprocess_shell` and :meth:`loop.subprocess_exec`."
msgstr ""

#: ../../library/asyncio-protocol.rst:148
msgid "Base Transport"
msgstr ""

#: ../../library/asyncio-protocol.rst:152
msgid "Close the transport."
msgstr ""

#: ../../library/asyncio-protocol.rst:154
msgid ""
"If the transport has a buffer for outgoing data, buffered data will be "
"flushed asynchronously.  No more data will be received.  After all buffered "
"data is flushed, the protocol's :meth:`protocol.connection_lost() "
"<BaseProtocol.connection_lost>` method will be called with :const:`None` as "
"its argument. The transport should not be used once it is closed."
msgstr ""

#: ../../library/asyncio-protocol.rst:164
msgid "Return ``True`` if the transport is closing or is closed."
msgstr ""

#: ../../library/asyncio-protocol.rst:168
msgid "Return information about the transport or underlying resources it uses."
msgstr ""

#: ../../library/asyncio-protocol.rst:171
msgid ""
"*name* is a string representing the piece of transport-specific information "
"to get."
msgstr ""

#: ../../library/asyncio-protocol.rst:174
msgid ""
"*default* is the value to return if the information is not available, or if "
"the transport does not support querying it with the given third-party event "
"loop implementation or on the current platform."
msgstr ""

#: ../../library/asyncio-protocol.rst:179
msgid ""
"For example, the following code attempts to get the underlying socket object "
"of the transport::"
msgstr ""

#: ../../library/asyncio-protocol.rst:182
msgid ""
"sock = transport.get_extra_info('socket')\n"
"if sock is not None:\n"
"    print(sock.getsockopt(...))"
msgstr ""
"sock = transport.get_extra_info('socket')\n"
"if sock is not None:\n"
"    print(sock.getsockopt(...))"

#: ../../library/asyncio-protocol.rst:186
msgid "Categories of information that can be queried on some transports:"
msgstr ""

#: ../../library/asyncio-protocol.rst:188
msgid "socket:"
msgstr ""

#: ../../library/asyncio-protocol.rst:190
msgid ""
"``'peername'``: the remote address to which the socket is connected, result "
"of :meth:`socket.socket.getpeername` (``None`` on error)"
msgstr ""

#: ../../library/asyncio-protocol.rst:194
msgid "``'socket'``: :class:`socket.socket` instance"
msgstr ""

#: ../../library/asyncio-protocol.rst:196
msgid ""
"``'sockname'``: the socket's own address, result of :meth:`socket.socket."
"getsockname`"
msgstr ""

#: ../../library/asyncio-protocol.rst:199
msgid "SSL socket:"
msgstr ""

#: ../../library/asyncio-protocol.rst:201
msgid ""
"``'compression'``: the compression algorithm being used as a string, or "
"``None`` if the connection isn't compressed; result of :meth:`ssl.SSLSocket."
"compression`"
msgstr ""

#: ../../library/asyncio-protocol.rst:205
msgid ""
"``'cipher'``: a three-value tuple containing the name of the cipher being "
"used, the version of the SSL protocol that defines its use, and the number "
"of secret bits being used; result of :meth:`ssl.SSLSocket.cipher`"
msgstr ""

#: ../../library/asyncio-protocol.rst:210
msgid ""
"``'peercert'``: peer certificate; result of :meth:`ssl.SSLSocket.getpeercert`"
msgstr ""

#: ../../library/asyncio-protocol.rst:213
msgid "``'sslcontext'``: :class:`ssl.SSLContext` instance"
msgstr ""

#: ../../library/asyncio-protocol.rst:215
msgid ""
"``'ssl_object'``: :class:`ssl.SSLObject` or :class:`ssl.SSLSocket` instance"
msgstr ""

#: ../../library/asyncio-protocol.rst:218
msgid "pipe:"
msgstr ""

#: ../../library/asyncio-protocol.rst:220
msgid "``'pipe'``: pipe object"
msgstr ""

#: ../../library/asyncio-protocol.rst:222
msgid "subprocess:"
msgstr ""

#: ../../library/asyncio-protocol.rst:224
msgid "``'subprocess'``: :class:`subprocess.Popen` instance"
msgstr ""

#: ../../library/asyncio-protocol.rst:228
msgid "Set a new protocol."
msgstr ""

#: ../../library/asyncio-protocol.rst:230
msgid ""
"Switching protocol should only be done when both protocols are documented to "
"support the switch."
msgstr ""

#: ../../library/asyncio-protocol.rst:235
msgid "Return the current protocol."
msgstr ""

#: ../../library/asyncio-protocol.rst:239
msgid "Read-only Transports"
msgstr ""

#: ../../library/asyncio-protocol.rst:243
msgid "Return ``True`` if the transport is receiving new data."
msgstr ""

#: ../../library/asyncio-protocol.rst:249
msgid ""
"Pause the receiving end of the transport.  No data will be passed to the "
"protocol's :meth:`protocol.data_received() <Protocol.data_received>` method "
"until :meth:`resume_reading` is called."
msgstr ""

#: ../../library/asyncio-protocol.rst:253
msgid ""
"The method is idempotent, i.e. it can be called when the transport is "
"already paused or closed."
msgstr ""

#: ../../library/asyncio-protocol.rst:259
msgid ""
"Resume the receiving end.  The protocol's :meth:`protocol.data_received() "
"<Protocol.data_received>` method will be called once again if some data is "
"available for reading."
msgstr ""

#: ../../library/asyncio-protocol.rst:263
msgid ""
"The method is idempotent, i.e. it can be called when the transport is "
"already reading."
msgstr ""

#: ../../library/asyncio-protocol.rst:269
msgid "Write-only Transports"
msgstr ""

#: ../../library/asyncio-protocol.rst:273
msgid ""
"Close the transport immediately, without waiting for pending operations to "
"complete.  Buffered data will be lost.  No more data will be received. The "
"protocol's :meth:`protocol.connection_lost() <BaseProtocol.connection_lost>` "
"method will eventually be called with :const:`None` as its argument."
msgstr ""

#: ../../library/asyncio-protocol.rst:281
msgid ""
"Return :const:`True` if the transport supports :meth:`~WriteTransport."
"write_eof`, :const:`False` if not."
msgstr ""

#: ../../library/asyncio-protocol.rst:286
msgid "Return the current size of the output buffer used by the transport."
msgstr ""

#: ../../library/asyncio-protocol.rst:290
msgid ""
"Get the *high* and *low* watermarks for write flow control. Return a tuple "
"``(low, high)`` where *low* and *high* are positive number of bytes."
msgstr ""

#: ../../library/asyncio-protocol.rst:294
msgid "Use :meth:`set_write_buffer_limits` to set the limits."
msgstr ""

#: ../../library/asyncio-protocol.rst:300
msgid "Set the *high* and *low* watermarks for write flow control."
msgstr ""

#: ../../library/asyncio-protocol.rst:302
msgid ""
"These two values (measured in number of bytes) control when the protocol's :"
"meth:`protocol.pause_writing() <BaseProtocol.pause_writing>` and :meth:"
"`protocol.resume_writing() <BaseProtocol.resume_writing>` methods are "
"called. If specified, the low watermark must be less than or equal to the "
"high watermark.  Neither *high* nor *low* can be negative."
msgstr ""

#: ../../library/asyncio-protocol.rst:310
msgid ""
":meth:`~BaseProtocol.pause_writing` is called when the buffer size becomes "
"greater than or equal to the *high* value. If writing has been paused, :meth:"
"`~BaseProtocol.resume_writing` is called when the buffer size becomes less "
"than or equal to the *low* value."
msgstr ""

#: ../../library/asyncio-protocol.rst:315
msgid ""
"The defaults are implementation-specific.  If only the high watermark is "
"given, the low watermark defaults to an implementation-specific value less "
"than or equal to the high watermark.  Setting *high* to zero forces *low* to "
"zero as well, and causes :meth:`~BaseProtocol.pause_writing` to be called "
"whenever the buffer becomes non-empty.  Setting *low* to zero causes :meth:"
"`~BaseProtocol.resume_writing` to be called only once the buffer is empty. "
"Use of zero for either limit is generally sub-optimal as it reduces "
"opportunities for doing I/O and computation concurrently."
msgstr ""

#: ../../library/asyncio-protocol.rst:326
msgid "Use :meth:`~WriteTransport.get_write_buffer_limits` to get the limits."
msgstr ""

#: ../../library/asyncio-protocol.rst:331
msgid "Write some *data* bytes to the transport."
msgstr ""

#: ../../library/asyncio-protocol.rst:333
#: ../../library/asyncio-protocol.rst:362
msgid ""
"This method does not block; it buffers the data and arranges for it to be "
"sent out asynchronously."
msgstr ""

#: ../../library/asyncio-protocol.rst:338
msgid ""
"Write a list (or any iterable) of data bytes to the transport. This is "
"functionally equivalent to calling :meth:`write` on each element yielded by "
"the iterable, but may be implemented more efficiently."
msgstr ""

#: ../../library/asyncio-protocol.rst:345
msgid ""
"Close the write end of the transport after flushing all buffered data. Data "
"may still be received."
msgstr ""

#: ../../library/asyncio-protocol.rst:348
msgid ""
"This method can raise :exc:`NotImplementedError` if the transport (e.g. SSL) "
"doesn't support half-closed connections."
msgstr ""

#: ../../library/asyncio-protocol.rst:353
msgid "Datagram Transports"
msgstr ""

#: ../../library/asyncio-protocol.rst:357
msgid ""
"Send the *data* bytes to the remote peer given by *addr* (a transport-"
"dependent target address).  If *addr* is :const:`None`, the data is sent to "
"the target address given on transport creation."
msgstr ""

#: ../../library/asyncio-protocol.rst:365
msgid ""
"This method can be called with an empty bytes object to send a zero-length "
"datagram. The buffer size calculation used for flow control is also updated "
"to account for the datagram header."
msgstr ""

#: ../../library/asyncio-protocol.rst:372
msgid ""
"Close the transport immediately, without waiting for pending operations to "
"complete.  Buffered data will be lost. No more data will be received.  The "
"protocol's :meth:`protocol.connection_lost() <BaseProtocol.connection_lost>` "
"method will eventually be called with :const:`None` as its argument."
msgstr ""

#: ../../library/asyncio-protocol.rst:382
msgid "Subprocess Transports"
msgstr ""

#: ../../library/asyncio-protocol.rst:386
msgid "Return the subprocess process id as an integer."
msgstr ""

#: ../../library/asyncio-protocol.rst:390
msgid ""
"Return the transport for the communication pipe corresponding to the integer "
"file descriptor *fd*:"
msgstr ""

#: ../../library/asyncio-protocol.rst:393
msgid ""
"``0``: readable streaming transport of the standard input (*stdin*), or :"
"const:`None` if the subprocess was not created with ``stdin=PIPE``"
msgstr ""

#: ../../library/asyncio-protocol.rst:395
msgid ""
"``1``: writable streaming transport of the standard output (*stdout*), or :"
"const:`None` if the subprocess was not created with ``stdout=PIPE``"
msgstr ""

#: ../../library/asyncio-protocol.rst:397
msgid ""
"``2``: writable streaming transport of the standard error (*stderr*), or :"
"const:`None` if the subprocess was not created with ``stderr=PIPE``"
msgstr ""

#: ../../library/asyncio-protocol.rst:399
msgid "other *fd*: :const:`None`"
msgstr ""

#: ../../library/asyncio-protocol.rst:403
msgid ""
"Return the subprocess return code as an integer or :const:`None` if it "
"hasn't returned, which is similar to the :attr:`subprocess.Popen.returncode` "
"attribute."
msgstr ""

#: ../../library/asyncio-protocol.rst:409
msgid "Kill the subprocess."
msgstr ""

#: ../../library/asyncio-protocol.rst:411
msgid ""
"On POSIX systems, the function sends SIGKILL to the subprocess. On Windows, "
"this method is an alias for :meth:`terminate`."
msgstr ""

#: ../../library/asyncio-protocol.rst:414
msgid "See also :meth:`subprocess.Popen.kill`."
msgstr "另請參閱 :meth:`subprocess.Popen.kill`。"

#: ../../library/asyncio-protocol.rst:418
msgid ""
"Send the *signal* number to the subprocess, as in :meth:`subprocess.Popen."
"send_signal`."
msgstr ""

#: ../../library/asyncio-protocol.rst:423
msgid "Stop the subprocess."
msgstr ""

#: ../../library/asyncio-protocol.rst:425
msgid ""
"On POSIX systems, this method sends :py:const:`~signal.SIGTERM` to the "
"subprocess. On Windows, the Windows API function :c:func:`!TerminateProcess` "
"is called to stop the subprocess."
msgstr ""

#: ../../library/asyncio-protocol.rst:429
msgid "See also :meth:`subprocess.Popen.terminate`."
msgstr "另請參閱 :meth:`subprocess.Popen.terminate`。"

#: ../../library/asyncio-protocol.rst:433
msgid "Kill the subprocess by calling the :meth:`kill` method."
msgstr ""

#: ../../library/asyncio-protocol.rst:435
msgid ""
"If the subprocess hasn't returned yet, and close transports of *stdin*, "
"*stdout*, and *stderr* pipes."
msgstr ""

#: ../../library/asyncio-protocol.rst:442
msgid "Protocols"
msgstr ""

#: ../../library/asyncio-protocol.rst:444
msgid "**Source code:** :source:`Lib/asyncio/protocols.py`"
msgstr "**原始碼：**\\ :source:`Lib/asyncio/protocols.py`"

#: ../../library/asyncio-protocol.rst:448
msgid ""
"asyncio provides a set of abstract base classes that should be used to "
"implement network protocols.  Those classes are meant to be used together "
"with :ref:`transports <asyncio-transport>`."
msgstr ""

#: ../../library/asyncio-protocol.rst:452
msgid ""
"Subclasses of abstract base protocol classes may implement some or all "
"methods.  All these methods are callbacks: they are called by transports on "
"certain events, for example when some data is received. A base protocol "
"method should be called by the corresponding transport."
msgstr ""

#: ../../library/asyncio-protocol.rst:459
msgid "Base Protocols"
msgstr ""

#: ../../library/asyncio-protocol.rst:463
msgid "Base protocol with methods that all protocols share."
msgstr ""

#: ../../library/asyncio-protocol.rst:467
msgid ""
"The base class for implementing streaming protocols (TCP, Unix sockets, etc)."
msgstr ""

#: ../../library/asyncio-protocol.rst:472
msgid ""
"A base class for implementing streaming protocols with manual control of the "
"receive buffer."
msgstr ""

#: ../../library/asyncio-protocol.rst:477
msgid "The base class for implementing datagram (UDP) protocols."
msgstr ""

#: ../../library/asyncio-protocol.rst:481
msgid ""
"The base class for implementing protocols communicating with child processes "
"(unidirectional pipes)."
msgstr ""

#: ../../library/asyncio-protocol.rst:486
msgid "Base Protocol"
msgstr ""

#: ../../library/asyncio-protocol.rst:488
msgid "All asyncio protocols can implement Base Protocol callbacks."
msgstr ""

#: ../../library/asyncio-protocol.rst:491
msgid "Connection Callbacks"
msgstr ""

#: ../../library/asyncio-protocol.rst:492
msgid ""
"Connection callbacks are called on all protocols, exactly once per a "
"successful connection.  All other protocol callbacks can only be called "
"between those two methods."
msgstr ""

#: ../../library/asyncio-protocol.rst:498
msgid "Called when a connection is made."
msgstr ""

#: ../../library/asyncio-protocol.rst:500
msgid ""
"The *transport* argument is the transport representing the connection.  The "
"protocol is responsible for storing the reference to its transport."
msgstr ""

#: ../../library/asyncio-protocol.rst:506
msgid "Called when the connection is lost or closed."
msgstr ""

#: ../../library/asyncio-protocol.rst:508
msgid ""
"The argument is either an exception object or :const:`None`. The latter "
"means a regular EOF is received, or the connection was aborted or closed by "
"this side of the connection."
msgstr ""

#: ../../library/asyncio-protocol.rst:514
msgid "Flow Control Callbacks"
msgstr ""

#: ../../library/asyncio-protocol.rst:515
msgid ""
"Flow control callbacks can be called by transports to pause or resume "
"writing performed by the protocol."
msgstr ""

#: ../../library/asyncio-protocol.rst:518
msgid ""
"See the documentation of the :meth:`~WriteTransport.set_write_buffer_limits` "
"method for more details."
msgstr ""

#: ../../library/asyncio-protocol.rst:523
msgid "Called when the transport's buffer goes over the high watermark."
msgstr ""

#: ../../library/asyncio-protocol.rst:527
msgid "Called when the transport's buffer drains below the low watermark."
msgstr ""

#: ../../library/asyncio-protocol.rst:529
msgid ""
"If the buffer size equals the high watermark, :meth:`~BaseProtocol."
"pause_writing` is not called: the buffer size must go strictly over."
msgstr ""

#: ../../library/asyncio-protocol.rst:533
msgid ""
"Conversely, :meth:`~BaseProtocol.resume_writing` is called when the buffer "
"size is equal or lower than the low watermark.  These end conditions are "
"important to ensure that things go as expected when either mark is zero."
msgstr ""

#: ../../library/asyncio-protocol.rst:540
msgid "Streaming Protocols"
msgstr ""

#: ../../library/asyncio-protocol.rst:542
msgid ""
"Event methods, such as :meth:`loop.create_server`, :meth:`loop."
"create_unix_server`, :meth:`loop.create_connection`, :meth:`loop."
"create_unix_connection`, :meth:`loop.connect_accepted_socket`, :meth:`loop."
"connect_read_pipe`, and :meth:`loop.connect_write_pipe` accept factories "
"that return streaming protocols."
msgstr ""

#: ../../library/asyncio-protocol.rst:550
msgid ""
"Called when some data is received.  *data* is a non-empty bytes object "
"containing the incoming data."
msgstr ""

#: ../../library/asyncio-protocol.rst:553
msgid ""
"Whether the data is buffered, chunked or reassembled depends on the "
"transport.  In general, you shouldn't rely on specific semantics and instead "
"make your parsing generic and flexible. However, data is always received in "
"the correct order."
msgstr ""

#: ../../library/asyncio-protocol.rst:558
msgid ""
"The method can be called an arbitrary number of times while a connection is "
"open."
msgstr ""

#: ../../library/asyncio-protocol.rst:561
msgid ""
"However, :meth:`protocol.eof_received() <Protocol.eof_received>` is called "
"at most once.  Once ``eof_received()`` is called, ``data_received()`` is not "
"called anymore."
msgstr ""

#: ../../library/asyncio-protocol.rst:567
msgid ""
"Called when the other end signals it won't send any more data (for example "
"by calling :meth:`transport.write_eof() <WriteTransport.write_eof>`, if the "
"other end also uses asyncio)."
msgstr ""

#: ../../library/asyncio-protocol.rst:572
msgid ""
"This method may return a false value (including ``None``), in which case the "
"transport will close itself.  Conversely, if this method returns a true "
"value, the protocol used determines whether to close the transport. Since "
"the default implementation returns ``None``, it implicitly closes the "
"connection."
msgstr ""

#: ../../library/asyncio-protocol.rst:578
msgid ""
"Some transports, including SSL, don't support half-closed connections, in "
"which case returning true from this method will result in the connection "
"being closed."
msgstr ""

#: ../../library/asyncio-protocol.rst:583
#: ../../library/asyncio-protocol.rst:641
msgid "State machine:"
msgstr ""

#: ../../library/asyncio-protocol.rst:585
msgid ""
"start -> connection_made\n"
"    [-> data_received]*\n"
"    [-> eof_received]?\n"
"-> connection_lost -> end"
msgstr ""
"start -> connection_made\n"
"    [-> data_received]*\n"
"    [-> eof_received]?\n"
"-> connection_lost -> end"

#: ../../library/asyncio-protocol.rst:594
msgid "Buffered Streaming Protocols"
msgstr ""

#: ../../library/asyncio-protocol.rst:598
msgid ""
"Buffered Protocols can be used with any event loop method that supports "
"`Streaming Protocols`_."
msgstr ""

#: ../../library/asyncio-protocol.rst:601
msgid ""
"``BufferedProtocol`` implementations allow explicit manual allocation and "
"control of the receive buffer.  Event loops can then use the buffer provided "
"by the protocol to avoid unnecessary data copies.  This can result in "
"noticeable performance improvement for protocols that receive big amounts of "
"data.  Sophisticated protocol implementations can significantly reduce the "
"number of buffer allocations."
msgstr ""

#: ../../library/asyncio-protocol.rst:608
msgid ""
"The following callbacks are called on :class:`BufferedProtocol` instances:"
msgstr ""

#: ../../library/asyncio-protocol.rst:613
msgid "Called to allocate a new receive buffer."
msgstr ""

#: ../../library/asyncio-protocol.rst:615
msgid ""
"*sizehint* is the recommended minimum size for the returned buffer.  It is "
"acceptable to return smaller or larger buffers than what *sizehint* "
"suggests.  When set to -1, the buffer size can be arbitrary. It is an error "
"to return a buffer with a zero size."
msgstr ""

#: ../../library/asyncio-protocol.rst:620
msgid ""
"``get_buffer()`` must return an object implementing the :ref:`buffer "
"protocol <bufferobjects>`."
msgstr ""

#: ../../library/asyncio-protocol.rst:625
msgid "Called when the buffer was updated with the received data."
msgstr ""

#: ../../library/asyncio-protocol.rst:627
msgid "*nbytes* is the total number of bytes that were written to the buffer."
msgstr ""

#: ../../library/asyncio-protocol.rst:631
msgid ""
"See the documentation of the :meth:`protocol.eof_received() <Protocol."
"eof_received>` method."
msgstr ""

#: ../../library/asyncio-protocol.rst:635
msgid ""
":meth:`~BufferedProtocol.get_buffer` can be called an arbitrary number of "
"times during a connection.  However, :meth:`protocol.eof_received() "
"<Protocol.eof_received>` is called at most once and, if called, :meth:"
"`~BufferedProtocol.get_buffer` and :meth:`~BufferedProtocol.buffer_updated` "
"won't be called after it."
msgstr ""

#: ../../library/asyncio-protocol.rst:643
msgid ""
"start -> connection_made\n"
"    [-> get_buffer\n"
"        [-> buffer_updated]?\n"
"    ]*\n"
"    [-> eof_received]?\n"
"-> connection_lost -> end"
msgstr ""
"start -> connection_made\n"
"    [-> get_buffer\n"
"        [-> buffer_updated]?\n"
"    ]*\n"
"    [-> eof_received]?\n"
"-> connection_lost -> end"

#: ../../library/asyncio-protocol.rst:654
msgid "Datagram Protocols"
msgstr ""

#: ../../library/asyncio-protocol.rst:656
msgid ""
"Datagram Protocol instances should be constructed by protocol factories "
"passed to the :meth:`loop.create_datagram_endpoint` method."
msgstr ""

#: ../../library/asyncio-protocol.rst:661
msgid ""
"Called when a datagram is received.  *data* is a bytes object containing the "
"incoming data.  *addr* is the address of the peer sending the data; the "
"exact format depends on the transport."
msgstr ""

#: ../../library/asyncio-protocol.rst:667
msgid ""
"Called when a previous send or receive operation raises an :class:"
"`OSError`.  *exc* is the :class:`OSError` instance."
msgstr ""

#: ../../library/asyncio-protocol.rst:670
msgid ""
"This method is called in rare conditions, when the transport (e.g. UDP) "
"detects that a datagram could not be delivered to its recipient. In many "
"conditions though, undeliverable datagrams will be silently dropped."
msgstr ""

#: ../../library/asyncio-protocol.rst:677
msgid ""
"On BSD systems (macOS, FreeBSD, etc.) flow control is not supported for "
"datagram protocols, because there is no reliable way to detect send failures "
"caused by writing too many packets."
msgstr ""

#: ../../library/asyncio-protocol.rst:681
msgid ""
"The socket always appears 'ready' and excess packets are dropped. An :class:"
"`OSError` with ``errno`` set to :const:`errno.ENOBUFS` may or may not be "
"raised; if it is raised, it will be reported to :meth:`DatagramProtocol."
"error_received` but otherwise ignored."
msgstr ""

#: ../../library/asyncio-protocol.rst:690
msgid "Subprocess Protocols"
msgstr ""

#: ../../library/asyncio-protocol.rst:692
msgid ""
"Subprocess Protocol instances should be constructed by protocol factories "
"passed to the :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell` "
"methods."
msgstr ""

#: ../../library/asyncio-protocol.rst:698
msgid ""
"Called when the child process writes data into its stdout or stderr pipe."
msgstr ""

#: ../../library/asyncio-protocol.rst:701
msgid "*fd* is the integer file descriptor of the pipe."
msgstr ""

#: ../../library/asyncio-protocol.rst:703
msgid "*data* is a non-empty bytes object containing the received data."
msgstr ""

#: ../../library/asyncio-protocol.rst:707
msgid ""
"Called when one of the pipes communicating with the child process is closed."
msgstr ""

#: ../../library/asyncio-protocol.rst:710
msgid "*fd* is the integer file descriptor that was closed."
msgstr ""

#: ../../library/asyncio-protocol.rst:714
msgid "Called when the child process has exited."
msgstr ""

#: ../../library/asyncio-protocol.rst:716
msgid ""
"It can be called before :meth:`~SubprocessProtocol.pipe_data_received` and :"
"meth:`~SubprocessProtocol.pipe_connection_lost` methods."
msgstr ""

#: ../../library/asyncio-protocol.rst:721
msgid "Examples"
msgstr "範例"

#: ../../library/asyncio-protocol.rst:726
msgid "TCP Echo Server"
msgstr ""

#: ../../library/asyncio-protocol.rst:728
msgid ""
"Create a TCP echo server using the :meth:`loop.create_server` method, send "
"back received data, and close the connection::"
msgstr ""

#: ../../library/asyncio-protocol.rst:731
msgid ""
"import asyncio\n"
"\n"
"\n"
"class EchoServerProtocol(asyncio.Protocol):\n"
"    def connection_made(self, transport):\n"
"        peername = transport.get_extra_info('peername')\n"
"        print('Connection from {}'.format(peername))\n"
"        self.transport = transport\n"
"\n"
"    def data_received(self, data):\n"
"        message = data.decode()\n"
"        print('Data received: {!r}'.format(message))\n"
"\n"
"        print('Send: {!r}'.format(message))\n"
"        self.transport.write(data)\n"
"\n"
"        print('Close the client socket')\n"
"        self.transport.close()\n"
"\n"
"\n"
"async def main():\n"
"    # Get a reference to the event loop as we plan to use\n"
"    # low-level APIs.\n"
"    loop = asyncio.get_running_loop()\n"
"\n"
"    server = await loop.create_server(\n"
"        EchoServerProtocol,\n"
"        '127.0.0.1', 8888)\n"
"\n"
"    async with server:\n"
"        await server.serve_forever()\n"
"\n"
"\n"
"asyncio.run(main())"
msgstr ""

#: ../../library/asyncio-protocol.rst:769
msgid ""
"The :ref:`TCP echo server using streams <asyncio-tcp-echo-server-streams>` "
"example uses the high-level :func:`asyncio.start_server` function."
msgstr ""

#: ../../library/asyncio-protocol.rst:775
msgid "TCP Echo Client"
msgstr ""

#: ../../library/asyncio-protocol.rst:777
msgid ""
"A TCP echo client using the :meth:`loop.create_connection` method, sends "
"data, and waits until the connection is closed::"
msgstr ""

#: ../../library/asyncio-protocol.rst:780
msgid ""
"import asyncio\n"
"\n"
"\n"
"class EchoClientProtocol(asyncio.Protocol):\n"
"    def __init__(self, message, on_con_lost):\n"
"        self.message = message\n"
"        self.on_con_lost = on_con_lost\n"
"\n"
"    def connection_made(self, transport):\n"
"        transport.write(self.message.encode())\n"
"        print('Data sent: {!r}'.format(self.message))\n"
"\n"
"    def data_received(self, data):\n"
"        print('Data received: {!r}'.format(data.decode()))\n"
"\n"
"    def connection_lost(self, exc):\n"
"        print('The server closed the connection')\n"
"        self.on_con_lost.set_result(True)\n"
"\n"
"\n"
"async def main():\n"
"    # Get a reference to the event loop as we plan to use\n"
"    # low-level APIs.\n"
"    loop = asyncio.get_running_loop()\n"
"\n"
"    on_con_lost = loop.create_future()\n"
"    message = 'Hello World!'\n"
"\n"
"    transport, protocol = await loop.create_connection(\n"
"        lambda: EchoClientProtocol(message, on_con_lost),\n"
"        '127.0.0.1', 8888)\n"
"\n"
"    # Wait until the protocol signals that the connection\n"
"    # is lost and close the transport.\n"
"    try:\n"
"        await on_con_lost\n"
"    finally:\n"
"        transport.close()\n"
"\n"
"\n"
"asyncio.run(main())"
msgstr ""

#: ../../library/asyncio-protocol.rst:825
msgid ""
"The :ref:`TCP echo client using streams <asyncio-tcp-echo-client-streams>` "
"example uses the high-level :func:`asyncio.open_connection` function."
msgstr ""

#: ../../library/asyncio-protocol.rst:832
msgid "UDP Echo Server"
msgstr ""

#: ../../library/asyncio-protocol.rst:834
msgid ""
"A UDP echo server, using the :meth:`loop.create_datagram_endpoint` method, "
"sends back received data::"
msgstr ""

#: ../../library/asyncio-protocol.rst:837
msgid ""
"import asyncio\n"
"\n"
"\n"
"class EchoServerProtocol:\n"
"    def connection_made(self, transport):\n"
"        self.transport = transport\n"
"\n"
"    def datagram_received(self, data, addr):\n"
"        message = data.decode()\n"
"        print('Received %r from %s' % (message, addr))\n"
"        print('Send %r to %s' % (message, addr))\n"
"        self.transport.sendto(data, addr)\n"
"\n"
"\n"
"async def main():\n"
"    print(\"Starting UDP server\")\n"
"\n"
"    # Get a reference to the event loop as we plan to use\n"
"    # low-level APIs.\n"
"    loop = asyncio.get_running_loop()\n"
"\n"
"    # One protocol instance will be created to serve all\n"
"    # client requests.\n"
"    transport, protocol = await loop.create_datagram_endpoint(\n"
"        EchoServerProtocol,\n"
"        local_addr=('127.0.0.1', 9999))\n"
"\n"
"    try:\n"
"        await asyncio.sleep(3600)  # Serve for 1 hour.\n"
"    finally:\n"
"        transport.close()\n"
"\n"
"\n"
"asyncio.run(main())"
msgstr ""

#: ../../library/asyncio-protocol.rst:876
msgid "UDP Echo Client"
msgstr ""

#: ../../library/asyncio-protocol.rst:878
msgid ""
"A UDP echo client, using the :meth:`loop.create_datagram_endpoint` method, "
"sends data and closes the transport when it receives the answer::"
msgstr ""

#: ../../library/asyncio-protocol.rst:881
msgid ""
"import asyncio\n"
"\n"
"\n"
"class EchoClientProtocol:\n"
"    def __init__(self, message, on_con_lost):\n"
"        self.message = message\n"
"        self.on_con_lost = on_con_lost\n"
"        self.transport = None\n"
"\n"
"    def connection_made(self, transport):\n"
"        self.transport = transport\n"
"        print('Send:', self.message)\n"
"        self.transport.sendto(self.message.encode())\n"
"\n"
"    def datagram_received(self, data, addr):\n"
"        print(\"Received:\", data.decode())\n"
"\n"
"        print(\"Close the socket\")\n"
"        self.transport.close()\n"
"\n"
"    def error_received(self, exc):\n"
"        print('Error received:', exc)\n"
"\n"
"    def connection_lost(self, exc):\n"
"        print(\"Connection closed\")\n"
"        self.on_con_lost.set_result(True)\n"
"\n"
"\n"
"async def main():\n"
"    # Get a reference to the event loop as we plan to use\n"
"    # low-level APIs.\n"
"    loop = asyncio.get_running_loop()\n"
"\n"
"    on_con_lost = loop.create_future()\n"
"    message = \"Hello World!\"\n"
"\n"
"    transport, protocol = await loop.create_datagram_endpoint(\n"
"        lambda: EchoClientProtocol(message, on_con_lost),\n"
"        remote_addr=('127.0.0.1', 9999))\n"
"\n"
"    try:\n"
"        await on_con_lost\n"
"    finally:\n"
"        transport.close()\n"
"\n"
"\n"
"asyncio.run(main())"
msgstr ""

#: ../../library/asyncio-protocol.rst:933
msgid "Connecting Existing Sockets"
msgstr ""

#: ../../library/asyncio-protocol.rst:935
msgid ""
"Wait until a socket receives data using the :meth:`loop.create_connection` "
"method with a protocol::"
msgstr ""

#: ../../library/asyncio-protocol.rst:938
msgid ""
"import asyncio\n"
"import socket\n"
"\n"
"\n"
"class MyProtocol(asyncio.Protocol):\n"
"\n"
"    def __init__(self, on_con_lost):\n"
"        self.transport = None\n"
"        self.on_con_lost = on_con_lost\n"
"\n"
"    def connection_made(self, transport):\n"
"        self.transport = transport\n"
"\n"
"    def data_received(self, data):\n"
"        print(\"Received:\", data.decode())\n"
"\n"
"        # We are done: close the transport;\n"
"        # connection_lost() will be called automatically.\n"
"        self.transport.close()\n"
"\n"
"    def connection_lost(self, exc):\n"
"        # The socket has been closed\n"
"        self.on_con_lost.set_result(True)\n"
"\n"
"\n"
"async def main():\n"
"    # Get a reference to the event loop as we plan to use\n"
"    # low-level APIs.\n"
"    loop = asyncio.get_running_loop()\n"
"    on_con_lost = loop.create_future()\n"
"\n"
"    # Create a pair of connected sockets\n"
"    rsock, wsock = socket.socketpair()\n"
"\n"
"    # Register the socket to wait for data.\n"
"    transport, protocol = await loop.create_connection(\n"
"        lambda: MyProtocol(on_con_lost), sock=rsock)\n"
"\n"
"    # Simulate the reception of data from the network.\n"
"    loop.call_soon(wsock.send, 'abc'.encode())\n"
"\n"
"    try:\n"
"        await protocol.on_con_lost\n"
"    finally:\n"
"        transport.close()\n"
"        wsock.close()\n"
"\n"
"asyncio.run(main())"
msgstr ""

#: ../../library/asyncio-protocol.rst:989
msgid ""
"The :ref:`watch a file descriptor for read events "
"<asyncio_example_watch_fd>` example uses the low-level :meth:`loop."
"add_reader` method to register an FD."
msgstr ""

#: ../../library/asyncio-protocol.rst:993
msgid ""
"The :ref:`register an open socket to wait for data using streams "
"<asyncio_example_create_connection-streams>` example uses high-level streams "
"created by the :func:`open_connection` function in a coroutine."
msgstr ""

#: ../../library/asyncio-protocol.rst:1000
msgid "loop.subprocess_exec() and SubprocessProtocol"
msgstr ""

#: ../../library/asyncio-protocol.rst:1002
msgid ""
"An example of a subprocess protocol used to get the output of a subprocess "
"and to wait for the subprocess exit."
msgstr ""

#: ../../library/asyncio-protocol.rst:1005
msgid "The subprocess is created by the :meth:`loop.subprocess_exec` method::"
msgstr ""

#: ../../library/asyncio-protocol.rst:1007
msgid ""
"import asyncio\n"
"import sys\n"
"\n"
"class DateProtocol(asyncio.SubprocessProtocol):\n"
"    def __init__(self, exit_future):\n"
"        self.exit_future = exit_future\n"
"        self.output = bytearray()\n"
"        self.pipe_closed = False\n"
"        self.exited = False\n"
"\n"
"    def pipe_connection_lost(self, fd, exc):\n"
"        self.pipe_closed = True\n"
"        self.check_for_exit()\n"
"\n"
"    def pipe_data_received(self, fd, data):\n"
"        self.output.extend(data)\n"
"\n"
"    def process_exited(self):\n"
"        self.exited = True\n"
"        # process_exited() method can be called before\n"
"        # pipe_connection_lost() method: wait until both methods are\n"
"        # called.\n"
"        self.check_for_exit()\n"
"\n"
"    def check_for_exit(self):\n"
"        if self.pipe_closed and self.exited:\n"
"            self.exit_future.set_result(True)\n"
"\n"
"async def get_date():\n"
"    # Get a reference to the event loop as we plan to use\n"
"    # low-level APIs.\n"
"    loop = asyncio.get_running_loop()\n"
"\n"
"    code = 'import datetime; print(datetime.datetime.now())'\n"
"    exit_future = asyncio.Future(loop=loop)\n"
"\n"
"    # Create the subprocess controlled by DateProtocol;\n"
"    # redirect the standard output into a pipe.\n"
"    transport, protocol = await loop.subprocess_exec(\n"
"        lambda: DateProtocol(exit_future),\n"
"        sys.executable, '-c', code,\n"
"        stdin=None, stderr=None)\n"
"\n"
"    # Wait for the subprocess exit using the process_exited()\n"
"    # method of the protocol.\n"
"    await exit_future\n"
"\n"
"    # Close the stdout pipe.\n"
"    transport.close()\n"
"\n"
"    # Read the output which was collected by the\n"
"    # pipe_data_received() method of the protocol.\n"
"    data = bytes(protocol.output)\n"
"    return data.decode('ascii').rstrip()\n"
"\n"
"date = asyncio.run(get_date())\n"
"print(f\"Current date: {date}\")"
msgstr ""

#: ../../library/asyncio-protocol.rst:1065
msgid ""
"See also the :ref:`same example <asyncio_example_create_subprocess_exec>` "
"written using high-level APIs."
msgstr ""