Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(5)

Delta Between Two Patch Sets: Doc/library/imaplib.rst

Issue 4972: context managerment support in imaplib, smtplib, ftplib
Left Patch Set: Created 7 years ago
Right Patch Set: Created 5 years, 7 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Doc/whatsnew/3.5.rst » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`imaplib` --- IMAP4 protocol client 1 :mod:`imaplib` --- IMAP4 protocol client
2 ======================================== 2 ========================================
3 3
4 .. module:: imaplib 4 .. module:: imaplib
5 :synopsis: IMAP4 protocol client (requires sockets). 5 :synopsis: IMAP4 protocol client (requires sockets).
6 .. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au> 6 .. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
7 .. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au> 7 .. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
8 .. revised by ESR, January 2000 8 .. revised by ESR, January 2000
9 .. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002 9 .. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
10 .. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>, 10 .. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
(...skipping 24 matching lines...) Expand all
35 This class implements the actual IMAP4 protocol. The connection is created a nd 35 This class implements the actual IMAP4 protocol. The connection is created a nd
36 protocol version (IMAP4 or IMAP4rev1) is determined when the instance is 36 protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
37 initialized. If *host* is not specified, ``''`` (the local host) is used. If 37 initialized. If *host* is not specified, ``''`` (the local host) is used. If
38 *port* is omitted, the standard IMAP4 port (143) is used. 38 *port* is omitted, the standard IMAP4 port (143) is used.
39 39
40 The :class:`IMAP4` class supports the :keyword:`with` statement. When used 40 The :class:`IMAP4` class supports the :keyword:`with` statement. When used
41 like this, the IMAP4 ``LOGOUT`` command is issued automatically when the 41 like this, the IMAP4 ``LOGOUT`` command is issued automatically when the
42 :keyword:`with` statement exits. E.g.:: 42 :keyword:`with` statement exits. E.g.::
43 43
44 >>> from imaplib import IMAP4 44 >>> from imaplib import IMAP4
45 >>> with IMAP4("domain.org") as M: 45 >>> with IMAP4("domain.org") as imap:
46 ... M.noop() 46 ... imap.noop()
47 ... 47 ...
48 ('OK', [b'Nothing Accomplished. d25if65hy903weo.87']) 48 ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
49 >>> 49
50 50 .. versionchanged:: 3.5
51 .. versionchanged:: 3.4
52 Support for the :keyword:`with` statement was added. 51 Support for the :keyword:`with` statement was added.
53 52
54 Three exceptions are defined as attributes of the :class:`IMAP4` class: 53 Three exceptions are defined as attributes of the :class:`IMAP4` class:
55 54
56 55
57 .. exception:: IMAP4.error 56 .. exception:: IMAP4.error
58 57
59 Exception raised on any errors. The reason for the exception is passed to th e 58 Exception raised on any errors. The reason for the exception is passed to th e
60 constructor as a string. 59 constructor as a string.
61 60
(...skipping 14 matching lines...) Expand all
76 75
77 76
78 There's also a subclass for secure connections: 77 There's also a subclass for secure connections:
79 78
80 79
81 .. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None) 80 .. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None)
82 81
83 This is a subclass derived from :class:`IMAP4` that connects over an SSL 82 This is a subclass derived from :class:`IMAP4` that connects over an SSL
84 encrypted socket (to use this class you need a socket module that was compile d 83 encrypted socket (to use this class you need a socket module that was compile d
85 with SSL support). If *host* is not specified, ``''`` (the local host) is us ed. 84 with SSL support). If *host* is not specified, ``''`` (the local host) is us ed.
86 If *port* is omitted, the standard IMAP4-over-SSL port (993) is used. *keyfi le* 85 If *port* is omitted, the standard IMAP4-over-SSL port (993) is used.
87 and *certfile* are also optional - they can contain a PEM formatted private k ey 86 *ssl_context* is a :class:`ssl.SSLContext` object which allows bundling
88 and certificate chain file for the SSL connection. *ssl_context* parameter is a 87 SSL configuration options, certificates and private keys into a single
89 :class:`ssl.SSLContext` object which allows bundling SSL configuration 88 (potentially long-lived) structure. Please read :ref:`ssl-security` for
90 options, certificates and private keys into a single (potentially long-lived) 89 best practices.
91 structure. Note that the *keyfile*/*certfile* parameters are mutually exclusi ve with *ssl_context*, 90
92 a :class:`ValueError` is raised if *keyfile*/*certfile* is provided along wit h *ssl_context*. 91 *keyfile* and *certfile* are a legacy alternative to *ssl_context* - they
92 can point to PEM-formatted private key and certificate chain files for
93 the SSL connection. Note that the *keyfile*/*certfile* parameters are
94 mutually exclusive with *ssl_context*, a :class:`ValueError` is raised
95 if *keyfile*/*certfile* is provided along with *ssl_context*.
93 96
94 .. versionchanged:: 3.3 97 .. versionchanged:: 3.3
95 *ssl_context* parameter added. 98 *ssl_context* parameter added.
96 99
100 .. versionchanged:: 3.4
101 The class now supports hostname check with
102 :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
103 :data:`ssl.HAS_SNI`).
97 104
98 The second subclass allows for connections created by a child process: 105 The second subclass allows for connections created by a child process:
99 106
100 107
101 .. class:: IMAP4_stream(command) 108 .. class:: IMAP4_stream(command)
102 109
103 This is a subclass derived from :class:`IMAP4` that connects to the 110 This is a subclass derived from :class:`IMAP4` that connects to the
104 ``stdin/stdout`` file descriptors created by passing *command* to 111 ``stdin/stdout`` file descriptors created by passing *command* to
105 ``subprocess.Popen()``. 112 ``subprocess.Popen()``.
106 113
(...skipping 85 matching lines...) Expand 10 before | Expand all | Expand 10 after
192 199
193 Authenticate command --- requires response processing. 200 Authenticate command --- requires response processing.
194 201
195 *mechanism* specifies which authentication mechanism is to be used - it shoul d 202 *mechanism* specifies which authentication mechanism is to be used - it shoul d
196 appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism ``. 203 appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism ``.
197 204
198 *authobject* must be a callable object:: 205 *authobject* must be a callable object::
199 206
200 data = authobject(response) 207 data = authobject(response)
201 208
202 It will be called to process server continuation responses. It should return 209 It will be called to process server continuation responses; the *response*
203 ``data`` that will be encoded and sent to server. It should return ``None`` i f 210 argument it is passed will be ``bytes``. It should return ``bytes`` *data*
204 the client abort response ``*`` should be sent instead. 211 that will be base64 encoded and sent to the server. It should return
212 ``None`` if the client abort response ``*`` should be sent instead.
205 213
206 214
207 .. method:: IMAP4.check() 215 .. method:: IMAP4.check()
208 216
209 Checkpoint mailbox on server. 217 Checkpoint mailbox on server.
210 218
211 219
212 .. method:: IMAP4.close() 220 .. method:: IMAP4.close()
213 221
214 Close currently selected mailbox. Deleted messages are removed from writable 222 Close currently selected mailbox. Deleted messages are removed from writable
(...skipping 101 matching lines...) Expand 10 before | Expand all | Expand 10 after
316 324
317 .. method:: IMAP4.noop() 325 .. method:: IMAP4.noop()
318 326
319 Send ``NOOP`` to server. 327 Send ``NOOP`` to server.
320 328
321 329
322 .. method:: IMAP4.open(host, port) 330 .. method:: IMAP4.open(host, port)
323 331
324 Opens socket to *port* at *host*. This method is implicitly called by 332 Opens socket to *port* at *host*. This method is implicitly called by
325 the :class:`IMAP4` constructor. The connection objects established by this 333 the :class:`IMAP4` constructor. The connection objects established by this
326 method will be used in the ``read``, ``readline``, ``send``, and ``shutdown`` 334 method will be used in the :meth:`IMAP4.read`, :meth:`IMAP4.readline`,
327 methods. You may override this method. 335 :meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods. You may override
336 this method.
328 337
329 338
330 .. method:: IMAP4.partial(message_num, message_part, start, length) 339 .. method:: IMAP4.partial(message_num, message_part, start, length)
331 340
332 Fetch truncated part of a message. Returned data is a tuple of message part 341 Fetch truncated part of a message. Returned data is a tuple of message part
333 envelope and data. 342 envelope and data.
334 343
335 344
336 .. method:: IMAP4.proxyauth(user) 345 .. method:: IMAP4.proxyauth(user)
337 346
(...skipping 100 matching lines...) Expand 10 before | Expand all | Expand 10 after
438 the interpretation of strings in the searching criteria. It then returns the 447 the interpretation of strings in the searching criteria. It then returns the
439 numbers of matching messages. 448 numbers of matching messages.
440 449
441 This is an ``IMAP4rev1`` extension command. 450 This is an ``IMAP4rev1`` extension command.
442 451
443 452
444 .. method:: IMAP4.starttls(ssl_context=None) 453 .. method:: IMAP4.starttls(ssl_context=None)
445 454
446 Send a ``STARTTLS`` command. The *ssl_context* argument is optional 455 Send a ``STARTTLS`` command. The *ssl_context* argument is optional
447 and should be a :class:`ssl.SSLContext` object. This will enable 456 and should be a :class:`ssl.SSLContext` object. This will enable
448 encryption on the IMAP connection. 457 encryption on the IMAP connection. Please read :ref:`ssl-security` for
458 best practices.
449 459
450 .. versionadded:: 3.2 460 .. versionadded:: 3.2
461
462 .. versionchanged:: 3.4
463 The method now supports hostname check with
464 :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
465 :data:`ssl.HAS_SNI`).
451 466
452 467
453 .. method:: IMAP4.status(mailbox, names) 468 .. method:: IMAP4.status(mailbox, names)
454 469
455 Request named status conditions for *mailbox*. 470 Request named status conditions for *mailbox*.
456 471
457 472
458 .. method:: IMAP4.store(message_set, command, flag_list) 473 .. method:: IMAP4.store(message_set, command, flag_list)
459 474
460 Alters flag dispositions for messages in mailbox. *command* is specified by 475 Alters flag dispositions for messages in mailbox. *command* is specified by
(...skipping 79 matching lines...) Expand 10 before | Expand all | Expand 10 after
540 M = imaplib.IMAP4() 555 M = imaplib.IMAP4()
541 M.login(getpass.getuser(), getpass.getpass()) 556 M.login(getpass.getuser(), getpass.getpass())
542 M.select() 557 M.select()
543 typ, data = M.search(None, 'ALL') 558 typ, data = M.search(None, 'ALL')
544 for num in data[0].split(): 559 for num in data[0].split():
545 typ, data = M.fetch(num, '(RFC822)') 560 typ, data = M.fetch(num, '(RFC822)')
546 print('Message %s\n%s\n' % (num, data[0][1])) 561 print('Message %s\n%s\n' % (num, data[0][1]))
547 M.close() 562 M.close()
548 M.logout() 563 M.logout()
549 564
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+