client¶
Telnet Client API for the ‘telnetlib3’ python package.
-
class
TelnetClient
(term='unknown', cols=80, rows=25, tspeed=(38400, 38400), xdisploc='', *args, **kwargs)[source]¶ Bases:
telnetlib3.client_base.BaseClient
Telnet client that supports all common options.
This class is useful for automation, it appears to be a virtual terminal to the remote end, but does not require an interactive terminal to run.
-
DEFAULT_LOCALE
= 'en_US'¶ On
send_env()
, the value of ‘LANG’ will be ‘C’ for binary transmission. When encoding is specified (utf8 by default), the LANG variable must also contain a locale, this value is used, providing a full default LANG value of ‘en_US.utf8’
-
send_env
(keys)[source]¶ Callback for responding to NEW_ENVIRON requests.
Parameters: keys (dict) – Values are requested for the keys specified. When empty, all environment values that wish to be volunteered should be returned. Returns: dictionary of environment values requested, or an empty string for keys not available. A return value must be given for each key requested. Return type: dict
-
send_charset
(offered)[source]¶ Callback for responding to CHARSET requests.
Receives a list of character encodings offered by the server as
offered
such as('LATIN-1', 'UTF-8')
, for which the client may return a value agreed to use, or None to disagree to any available offers. Server offerings may be encodings or codepages.The default implementation selects any matching encoding that python is capable of using, preferring any that matches
encoding
if matched in the offered list.Parameters: offered (list) – list of CHARSET options offered by server. Returns: character encoding agreed to be used. Return type: str or None
-
send_naws
()[source]¶ Callback for responding to NAWS requests.
Return type: (int, int) Returns: client window size as (rows, columns).
-
encoding
(outgoing=None, incoming=None)[source]¶ Return encoding for the given stream direction.
Parameters: Raises: TypeError – when a direction argument, either
outgoing
orincoming
, was not setTrue
.Returns: 'US-ASCII'
for the directions indicated, unlessBINARY
RFC 856 has been negotiated for the direction indicated or :attr`force_binary` is setTrue
.Return type:
-
begin_negotiation
()¶ Begin on-connect negotiation.
A Telnet client is expected to send only a minimal amount of client session options immediately after connection, it is generally the server which dictates server option support.
Deriving implementations should always call
super().begin_negotiation()
.
-
begin_shell
(result)¶
-
check_negotiation
(final=False)¶ Callback, return whether negotiation is complete.
Parameters: final (bool) – Whether this is the final time this callback will be requested to answer regarding protocol negotiation. Returns: Whether negotiation is over (client end is satisfied). Return type: bool Method is called on each new command byte processed until negotiation is considered final, or after
connect_maxwait
has elapsed, setting the_waiter_connected
attribute to valueself
when complete.This method returns False until
connect_minwait
has elapsed, ensuring the server may batch telnet negotiation demands without prematurely entering the callback shell.Ensure
super().check_negotiation()
is called and conditionally combined when derived.
-
connection_lost
(exc)¶ Called when the connection is lost or closed.
Parameters: exc (Exception) – exception. None
indicates a closing EOF sent by this end.
-
data_received
(data)¶ Process bytes received by transport.
-
duration
¶ Time elapsed since client connected, in seconds as float.
-
eof_received
()¶ Called when the other end calls write_eof() or equivalent.
-
get_extra_info
(name, default=None)¶ Get optional client protocol or transport information.
-
idle
¶ Time elapsed since data last received, in seconds as float.
-
pause_writing
()¶ Called when the transport’s buffer goes over the high-water mark.
Pause and resume calls are paired – pause_writing() is called once when the buffer goes strictly over the high-water mark (even if subsequent writes increases the buffer size even more), and eventually resume_writing() is called once when the buffer size reaches the low-water mark.
Note that if the buffer size equals the high-water mark, pause_writing() is not called – it must go strictly over. Conversely, resume_writing() is called when the buffer size is equal or lower than the low-water mark. These end conditions are important to ensure that things go as expected when either mark is zero.
NOTE: This is the only Protocol callback that is not called through EventLoop.call_soon() – if it were, it would have no effect when it’s most needed (when the app keeps writing without yielding until pause_writing() is called).
-
resume_writing
()¶ Called when the transport’s buffer drains below the low-water mark.
See pause_writing() for details.
-
-
class
TelnetTerminalClient
(term='unknown', cols=80, rows=25, tspeed=(38400, 38400), xdisploc='', *args, **kwargs)[source]¶ Bases:
telnetlib3.client.TelnetClient
Telnet client for sessions with a network virtual terminal (NVT).
-
send_naws
()[source]¶ Callback replies to request for window size, NAWS RFC 1073.
Return type: (int, int) Returns: window dimensions by lines and columns
-
send_env
(keys)[source]¶ Callback replies to request for env values, NEW_ENVIRON RFC 1572.
Return type: dict Returns: super class value updated with window LINES and COLUMNS.
-
DEFAULT_LOCALE
= 'en_US'¶
-
begin_negotiation
()¶ Begin on-connect negotiation.
A Telnet client is expected to send only a minimal amount of client session options immediately after connection, it is generally the server which dictates server option support.
Deriving implementations should always call
super().begin_negotiation()
.
-
begin_shell
(result)¶
-
check_negotiation
(final=False)¶ Callback, return whether negotiation is complete.
Parameters: final (bool) – Whether this is the final time this callback will be requested to answer regarding protocol negotiation. Returns: Whether negotiation is over (client end is satisfied). Return type: bool Method is called on each new command byte processed until negotiation is considered final, or after
connect_maxwait
has elapsed, setting the_waiter_connected
attribute to valueself
when complete.This method returns False until
connect_minwait
has elapsed, ensuring the server may batch telnet negotiation demands without prematurely entering the callback shell.Ensure
super().check_negotiation()
is called and conditionally combined when derived.
-
connection_lost
(exc)¶ Called when the connection is lost or closed.
Parameters: exc (Exception) – exception. None
indicates a closing EOF sent by this end.
-
connection_made
(transport)¶ Callback for connection made to server.
-
data_received
(data)¶ Process bytes received by transport.
-
duration
¶ Time elapsed since client connected, in seconds as float.
-
encoding
(outgoing=None, incoming=None)¶ Return encoding for the given stream direction.
Parameters: Raises: TypeError – when a direction argument, either
outgoing
orincoming
, was not setTrue
.Returns: 'US-ASCII'
for the directions indicated, unlessBINARY
RFC 856 has been negotiated for the direction indicated or :attr`force_binary` is setTrue
.Return type:
-
eof_received
()¶ Called when the other end calls write_eof() or equivalent.
-
get_extra_info
(name, default=None)¶ Get optional client protocol or transport information.
-
idle
¶ Time elapsed since data last received, in seconds as float.
-
pause_writing
()¶ Called when the transport’s buffer goes over the high-water mark.
Pause and resume calls are paired – pause_writing() is called once when the buffer goes strictly over the high-water mark (even if subsequent writes increases the buffer size even more), and eventually resume_writing() is called once when the buffer size reaches the low-water mark.
Note that if the buffer size equals the high-water mark, pause_writing() is not called – it must go strictly over. Conversely, resume_writing() is called when the buffer size is equal or lower than the low-water mark. These end conditions are important to ensure that things go as expected when either mark is zero.
NOTE: This is the only Protocol callback that is not called through EventLoop.call_soon() – if it were, it would have no effect when it’s most needed (when the app keeps writing without yielding until pause_writing() is called).
-
resume_writing
()¶ Called when the transport’s buffer drains below the low-water mark.
See pause_writing() for details.
-
send_charset
(offered)¶ Callback for responding to CHARSET requests.
Receives a list of character encodings offered by the server as
offered
such as('LATIN-1', 'UTF-8')
, for which the client may return a value agreed to use, or None to disagree to any available offers. Server offerings may be encodings or codepages.The default implementation selects any matching encoding that python is capable of using, preferring any that matches
encoding
if matched in the offered list.Parameters: offered (list) – list of CHARSET options offered by server. Returns: character encoding agreed to be used. Return type: str or None
-
send_tspeed
()¶ Callback for responding to TSPEED requests.
-
send_ttype
()¶ Callback for responding to TTYPE requests.
-
send_xdisploc
()¶ Callback for responding to XDISPLOC requests.
-
-
open_connection
(host=None, port=23, *, client_factory=None, family=0, flags=0, local_addr=None, encoding='utf8', encoding_errors='replace', force_binary=False, term='unknown', cols=80, rows=25, tspeed=(38400, 38400), xdisploc='', shell=None, connect_minwait=2.0, connect_maxwait=3.0, waiter_closed=None, _waiter_connected=None, limit=None)[source]¶ Connect to a TCP Telnet server as a Telnet client.
Parameters: - host (str) – Remote Internet TCP Server host.
- port (int) – Remote Internet host TCP port.
- client_factory (client_base.BaseClient) – Client connection class
factory. When
None
,TelnetTerminalClient
is used when stdin is attached to a terminal,TelnetClient
otherwise. - family (int) – Same meaning as
asyncio.loop.create_connection()
. - flags (int) – Same meaning as
asyncio.loop.create_connection()
. - local_addr (tuple) – Same meaning as
asyncio.loop.create_connection()
. - encoding (str) –
The default assumed encoding, or
False
to disable unicode support. This value is used for decoding bytes received by and encoding bytes transmitted to the Server. These values are preferred in response to NEW_ENVIRON RFC 1572 as environment valueLANG
, and by CHARSET RFC 2066 negotiation.The server’s attached
reader, writer
streams accept and return unicode, unless this value explicitly setFalse
. In that case, the attached streams interfaces are bytes-only. - encoding_errors (str) – Same meaning as
codecs.Codec.encode()
. - term (str) – Terminal type sent for requests of TTYPE, RFC 930 or as Environment value TERM by NEW_ENVIRON negotiation, RFC 1672.
- cols (int) – Client window dimension sent as Environment value COLUMNS by NEW_ENVIRON negotiation, RFC 1672 or NAWS RFC 1073.
- rows (int) – Client window dimension sent as Environment value LINES by NEW_ENVIRON negotiation, RFC 1672 or NAWS RFC 1073.
- tspeed (tuple) – Tuple of client BPS line speed in form
(rx, tx
) for receive and transmit, respectively. Sent when requested by TSPEED, RFC 1079. - xdisploc (str) – String transmitted in response for request of XDISPLOC, RFC 1086 by server (X11).
- shell – A async function that is called after negotiation completes,
receiving arguments
(reader, writer)
. The reader is aTelnetReader
instance, the writer is aTelnetWriter
instance. - connect_minwait (float) –
The client allows any additional telnet negotiations to be demanded by the server within this period of time before launching the shell. Servers should assert desired negotiation on-connect and in response to 1 or 2 round trips.
A server that does not make any telnet demands, such as a TCP server that is not a telnet server will delay the execution of
shell
for exactly this amount of time. - connect_maxwait (float) – If the remote end is not complaint, or otherwise confused by our demands, the shell continues anyway after the greater of this value has elapsed. A client that is not answering option negotiation will delay the start of the shell by this amount.
- limit (int) – The buffer limit for reader stream.
Return (reader, writer): The reader is a
TelnetReader
instance, the writer is aTelnetWriter
instance.