Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 658cef0

Browse files
freddrakefreddrake
committed
Preliminary mhlib and telnetlib documents from Skip Montanaro -- thanks, Skip!
1 parent 8387af6 commit 658cef0

3 files changed

Lines changed: 321 additions & 0 deletions

File tree

‎Doc/lib/lib.tex‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,7 @@ \chapter*{Front Matter\label{front}}
177177
\input{libimaplib}
178178
\input{libnntplib}
179179
\input{libsmtplib}
180+
\input{libtelnetlib}
180181
\input{liburlparse}
181182
\input{libsocksvr}
182183
\input{libbasehttp}
@@ -199,6 +200,7 @@ \chapter*{Front Matter\label{front}}
199200
\input{libbase64}
200201
\input{libquopri}
201202
\input{libmailbox}
203+
\input{libmhlib}
202204
\input{libmimify}
203205
\input{libnetrc}
204206

‎Doc/lib/libmhlib.tex‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
% LaTeX'ized from the comments in the module by Skip Montanaro
2+
% <[email protected]>.
3+
4+
\section{\module{mhlib} ---
5+
Object-oriented access to MH mailboxes}
6+
7+
\declaremodule{standard}{mhlib}
8+
\modulesynopsis{Manipulate MH mailboxes from Python.}
9+
10+
11+
The \module{mhlib} module provides a Python interface to MH folders and
12+
their contents.
13+
14+
The module contains three basic classes, \class{MH}, which represents a
15+
particular collection of folders, \class{Folder}, which represents a single
16+
folder, and \class{Message}, which represents a single message.
17+
18+
19+
\begin{classdesc}{MH}{\optional{path\optional{, profile}}}
20+
\class{MH} represents a collection of MH folders.
21+
\end{classdesc}
22+
23+
\begin{classdesc}{Folder}{mh, name}
24+
The \class{Folder} class represents a single folder and its messages.
25+
\end{classdesc}
26+
27+
\begin{classdesc}{Message}{folder, number\optional{, name}}
28+
\class{Message} objects represent individual messages in a folder. The
29+
Message class is derived from \class{mimetools.Message}.
30+
\end{classdesc}
31+
32+
33+
\subsection{MH Objects \label{mh-objects}}
34+
35+
\class{MH} instances have the following methods:
36+
37+
38+
\begin{methoddesc}[MH]{error}{format\optional{, ...}}
39+
Print an error message -- can be overridden.
40+
\end{methoddesc}
41+
42+
\begin{methoddesc}[MH]{getprofile}{key}
43+
Return a profile entry (\code{None} if not set).
44+
\end{methoddesc}
45+
46+
\begin{methoddesc}[MH]{getpath}{}
47+
Return the mailbox pathname.
48+
\end{methoddesc}
49+
50+
\begin{methoddesc}[MH]{getcontext}{}
51+
Return the current folder name.
52+
\end{methoddesc}
53+
54+
\begin{methoddesc}[MH]{setcontext}{name}
55+
Set the current folder name.
56+
\end{methoddesc}
57+
58+
\begin{methoddesc}[MH]{listfolders}{}
59+
Return a list of top-level folders.
60+
\end{methoddesc}
61+
62+
\begin{methoddesc}[MH]{listallfolders}{}
63+
Return a list of all folders.
64+
\end{methoddesc}
65+
66+
\begin{methoddesc}[MH]{listsubfolders}{name}
67+
Return a list of direct subfolders of the given folder.
68+
\end{methoddesc}
69+
70+
\begin{methoddesc}[MH]{listallsubfolders}{name}
71+
Return a list of all subfolders of the given folder.
72+
\end{methoddesc}
73+
74+
\begin{methoddesc}[MH]{makefolder}{name}
75+
Create a new folder.
76+
\end{methoddesc}
77+
78+
\begin{methoddesc}[MH]{deletefolder}{name}
79+
Delete a folder -- must have no subfolders.
80+
\end{methoddesc}
81+
82+
\begin{methoddesc}[MH]{openfolder}{name}
83+
Return a new open folder object.
84+
\end{methoddesc}
85+
86+
87+
88+
\subsection{Folder Objects \label{mh-folder-objects}}
89+
90+
\class{Folder} instances represent open folders and have the following
91+
methods:
92+
93+
94+
\begin{methoddesc}[Folder]{error}{format\optional{, ...}}
95+
Print an error message -- can be overridden.
96+
\end{methoddesc}
97+
98+
\begin{methoddesc}[Folder]{getfullname}{}
99+
Return the folder's full pathname.
100+
\end{methoddesc}
101+
102+
\begin{methoddesc}[Folder]{getsequencesfilename}{}
103+
Return the full pathname of the folder's sequences file.
104+
\end{methoddesc}
105+
106+
\begin{methoddesc}[Folder]{getmessagefilename}{n}
107+
Return the full pathname of message \var{n} of the folder.
108+
\end{methoddesc}
109+
110+
\begin{methoddesc}[Folder]{listmessages}{}
111+
Return a list of messages in the folder (as numbers).
112+
\end{methoddesc}
113+
114+
\begin{methoddesc}[Folder]{getcurrent}{}
115+
Return the current message number.
116+
\end{methoddesc}
117+
118+
\begin{methoddesc}[Folder]{setcurrent}{n}
119+
Set the current message number to \var{n}.
120+
\end{methoddesc}
121+
122+
\begin{methoddesc}[Folder]{parsesequence}{seq}
123+
Parse msgs syntax into list of messages.
124+
\end{methoddesc}
125+
126+
\begin{methoddesc}[Folder]{getlast}{}
127+
Get last message, or \code{0} if no messages are in the folder.
128+
\end{methoddesc}
129+
130+
\begin{methoddesc}[Folder]{setlast}{n}
131+
Set last message (internal use only).
132+
\end{methoddesc}
133+
134+
\begin{methoddesc}[Folder]{getsequences}{}
135+
Return dictionary of sequences in folder. The sequence names are used
136+
as keys, and the values are the lists of message numbers in the
137+
sequences.
138+
\end{methoddesc}
139+
140+
\begin{methoddesc}[Folder]{putsequences}{dict}
141+
Return dictionary of sequences in folder {name: list}.
142+
\end{methoddesc}
143+
144+
\begin{methoddesc}[Folder]{removemessages}{list}
145+
Remove messages in list from folder.
146+
\end{methoddesc}
147+
148+
\begin{methoddesc}[Folder]{refilemessages}{list, tofolder}
149+
Move messages in list to other folder.
150+
\end{methoddesc}
151+
152+
\begin{methoddesc}[Folder]{movemessage}{n, tofolder, ton}
153+
Move one message to a given destination in another folder.
154+
\end{methoddesc}
155+
156+
\begin{methoddesc}[Folder]{copymessage}{n, tofolder, ton}
157+
Copy one message to a given destination in another folder.
158+
\end{methoddesc}
159+
160+
161+
\subsection{Message Objects \label{mh-message-objects}}
162+
163+
\begin{methoddesc}[Message]{openmessage}{n}
164+
Return a new open message object (costs a file descriptor).
165+
\end{methoddesc}

‎Doc/lib/libtelnetlib.tex‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
% LaTeX'ized from the comments in the module by Skip Montanaro
2+
% <[email protected]>.
3+
4+
\section{\module{telnetlib} ---
5+
Telnet client}
6+
7+
\declaremodule{standard}{telnetlib}
8+
\modulesynopsis{Telnet client class.}
9+
10+
11+
The \module{telnetlib} module provides a \class{Telnet} class that
12+
implements the Telnet protocol. See \rfc{854} for details about the
13+
protocol.
14+
15+
16+
\begin{classdesc}{Telnet}{\optional{host\optional{, port=0}}}
17+
\class{Telnet} represents a connection to a telnet server. The
18+
instance is initially not connected; the \method{open()} method must
19+
be used to establish a connection. Alternatively, the host name and
20+
optional port number can be passed to the constructor, too.
21+
22+
Do not reopen an already connected instance.
23+
24+
This class has many \method{read_*()} methods. Note that some of them
25+
raise \exception{EOFError} when the end of the connection is read,
26+
because they can return an empty string for other reasons. See the
27+
individual doc strings.
28+
\end{classdesc}
29+
30+
31+
\subsection{Telnet Objects \label{telnet-objects}}
32+
33+
\class{Telnet} instances have the following methods:
34+
35+
36+
\begin{methoddesc}[Telnet]{read_until}{expected\optional{, timeout}}
37+
Read until a given string is encountered or until timeout.
38+
39+
When no match is found, return whatever is available instead,
40+
possibly the empty string. Raise \exception{EOFError} if the connection
41+
is closed and no cooked data is available.
42+
\end{methoddesc}
43+
44+
\begin{methoddesc}[Telnet]{read_all}{}
45+
Read all data until EOF; block until connection closed.
46+
\end{methoddesc}
47+
48+
\begin{methoddesc}[Telnet]{read_some}{}
49+
Read at least one byte of cooked data unless EOF is hit.
50+
51+
Return \code{''} if EOF is hit. Block if no data is immediately available.
52+
\end{methoddesc}
53+
54+
\begin{methoddesc}[Telnet]{read_very_eager}{}
55+
Read everything that's possible without blocking in I/O (eager).
56+
57+
Raise \exception{EOFError} if connection closed and no cooked data
58+
available. Return \code{''} if no cooked data available otherwise.
59+
Don't block unless in the midst of an IAC sequence.
60+
\end{methoddesc}
61+
62+
\begin{methoddesc}[Telnet]{read_eager}{}
63+
Read readily available data.
64+
65+
Raise \exception{EOFError} if connection closed and no cooked data
66+
available. Return \code{''} if no cooked data available otherwise.
67+
Don't block unless in the midst of an IAC sequence.
68+
\end{methoddesc}
69+
70+
\begin{methoddesc}[Telnet]{read_lazy}{}
71+
Process and return data that's already in the queues (lazy).
72+
73+
Raise \exception{EOFError} if connection closed and no data available.
74+
Return \code{''} if no cooked data available otherwise. Don't block
75+
unless in the midst of an IAC sequence.
76+
\end{methoddesc}
77+
78+
\begin{methoddesc}[Telnet]{read_very_lazy}{}
79+
Return any data available in the cooked queue (very lazy).
80+
81+
Raise \exception{EOFError} if connection closed and no data available.
82+
Return \code{''} if no cooked data available otherwise. Don't block.
83+
\end{methoddesc}
84+
85+
\begin{methoddesc}[Telnet]{open}{host\optional{, port=0}}
86+
Connect to a host.
87+
88+
The optional second argument is the port number, which
89+
defaults to the standard telnet port (23).
90+
91+
Don't try to reopen an already connected instance.
92+
\end{methoddesc}
93+
94+
\begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}}
95+
Print a debug message, when the debug level is > 0.
96+
97+
If extra arguments are present, they are substituted in the
98+
message using the standard string formatting operator.
99+
\end{methoddesc}
100+
101+
\begin{methoddesc}[Telnet]{set_debuglevel}{debuglevel}
102+
Set the debug level.
103+
104+
The higher it is, the more debug output you get (on sys.stdout).
105+
\end{methoddesc}
106+
107+
\begin{methoddesc}[Telnet]{close}{}
108+
Close the connection.
109+
\end{methoddesc}
110+
111+
\begin{methoddesc}[Telnet]{get_socket}{}
112+
Return the socket object used internally.
113+
\end{methoddesc}
114+
115+
\begin{methoddesc}[Telnet]{fileno}{}
116+
Return the fileno() of the socket object used internally.
117+
\end{methoddesc}
118+
119+
\begin{methoddesc}[Telnet]{write}{buffer}
120+
Write a string to the socket, doubling any IAC characters.
121+
122+
Can block if the connection is blocked. May raise
123+
socket.error if the connection is closed.
124+
\end{methoddesc}
125+
126+
\begin{methoddesc}[Telnet]{interact}{}
127+
Interaction function, emulates a very dumb telnet client.
128+
\end{methoddesc}
129+
130+
\begin{methoddesc}[Telnet]{mt_interact}{}
131+
Multithreaded version of \method{interact}.
132+
\end{methoddesc}
133+
134+
\begin{methoddesc}[Telnet]{expect}{list, timeout=None}
135+
Read until one from a list of a regular expressions matches.
136+
137+
The first argument is a list of regular expressions, either
138+
compiled (\class{re.RegexObject} instances) or uncompiled (strings).
139+
The optional second argument is a timeout, in seconds; default
140+
is no timeout.
141+
142+
Return a tuple of three items: the index in the list of the
143+
first regular expression that matches; the match object
144+
returned; and the text read up till and including the match.
145+
146+
If end of file is found and no text was read, raise
147+
\exception{EOFError}. Otherwise, when nothing matches, return
148+
\code{(-1, None, \var{text})} where \var{text} is the text received so
149+
far (may be the empty string if a timeout happened).
150+
151+
If a regular expression ends with a greedy match (e.g. \regexp{.*})
152+
or if more than one expression can match the same input, the
153+
results are undeterministic, and may depend on the I/O timing.
154+
\end{methoddesc}

0 commit comments

Comments
 (0)