Skip to content

Commit 9930a46

Browse files
committed
Merge remote-tracking branch 'upstream/main' into pythongh-153511
2 parents af8c403 + c98e984 commit 9930a46

8 files changed

Lines changed: 233 additions & 36 deletions

File tree

‎Doc/library/imaplib.rst‎

Lines changed: 54 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -273,10 +273,16 @@ An :class:`IMAP4` instance has the following methods:
273273
mailbox. This is the recommended command before ``LOGOUT``.
274274

275275

276-
.. method:: IMAP4.copy(message_set, new_mailbox)
276+
.. method:: IMAP4.copy(message_set, new_mailbox, *, uid=False)
277277

278278
Copy *message_set* messages onto end of *new_mailbox*.
279279

280+
If *uid* is true, *message_set* is a set of UIDs and the ``UID COPY``
281+
command is used instead of ``COPY``.
282+
283+
.. versionchanged:: next
284+
Added the *uid* parameter.
285+
280286

281287
.. method:: IMAP4.create(mailbox)
282288

@@ -303,19 +309,33 @@ An :class:`IMAP4` instance has the following methods:
303309
The :meth:`enable` method itself, and :RFC:`6855` support.
304310

305311

306-
.. method:: IMAP4.expunge()
312+
.. method:: IMAP4.expunge(message_set=None, *, uid=False)
307313

308314
Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE``
309315
response for each deleted message. Returned data contains a list of ``EXPUNGE``
310316
message numbers in order received.
311317

318+
If *uid* is true, the ``UID EXPUNGE`` command (:rfc:`4315`) is used to remove
319+
only the messages that both are marked as deleted and have a UID in
320+
*message_set*. *message_set* is required in this case, and must be omitted
321+
otherwise.
322+
323+
.. versionchanged:: next
324+
Added the *message_set* and *uid* parameters.
325+
312326

313-
.. method:: IMAP4.fetch(message_set, message_parts)
327+
.. method:: IMAP4.fetch(message_set, message_parts, *, uid=False)
314328

315329
Fetch (parts of) messages. *message_parts* should be a string of message part
316330
names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``. Returned data
317331
are tuples of message part envelope and data.
318332

333+
If *uid* is true, *message_set* is a set of UIDs and the message numbers in
334+
the response are UIDs (``UID FETCH``).
335+
336+
.. versionchanged:: next
337+
Added the *uid* parameter.
338+
319339

320340
.. method:: IMAP4.getacl(mailbox)
321341

@@ -495,12 +515,15 @@ An :class:`IMAP4` instance has the following methods:
495515
Returned data are tuples of message part envelope and data.
496516

497517

498-
.. method:: IMAP4.move(message_set, new_mailbox)
518+
.. method:: IMAP4.move(message_set, new_mailbox, *, uid=False)
499519

500520
Move *message_set* messages onto end of *new_mailbox*.
501521

502522
The server must support the ``MOVE`` capability (:rfc:`6851`).
503523

524+
If *uid* is true, *message_set* is a set of UIDs and the ``UID MOVE``
525+
command is used instead of ``MOVE``.
526+
504527
.. versionadded:: next
505528

506529

@@ -575,7 +598,7 @@ An :class:`IMAP4` instance has the following methods:
575598
code, instead of the usual type.
576599

577600

578-
.. method:: IMAP4.search(charset, criterion[, ...])
601+
.. method:: IMAP4.search(charset, criterion[, ...], *, uid=False)
579602

580603
Search mailbox for matching messages. *charset* may be ``None``, in which case
581604
no ``CHARSET`` will be specified in the request to the server. The IMAP
@@ -584,6 +607,9 @@ An :class:`IMAP4` instance has the following methods:
584607
the ``UTF8=ACCEPT`` capability was enabled using the :meth:`enable`
585608
command.
586609

610+
If *uid* is true, the message numbers in the response are UIDs
611+
(``UID SEARCH``).
612+
587613
Example::
588614

589615
# M is a connected IMAP4 instance...
@@ -592,6 +618,9 @@ An :class:`IMAP4` instance has the following methods:
592618
# or:
593619
typ, msgnums = M.search(None, '(FROM "LDJ")')
594620

621+
.. versionchanged:: next
622+
Added the *uid* parameter.
623+
595624

596625
.. method:: IMAP4.select(mailbox='INBOX', readonly=False)
597626

@@ -636,7 +665,7 @@ An :class:`IMAP4` instance has the following methods:
636665
Returns socket instance used to connect to server.
637666

638667

639-
.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])
668+
.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...], *, uid=False)
640669

641670
The ``sort`` command is a variant of ``search`` with sorting semantics for the
642671
results. Returned data contains a space separated list of matching message
@@ -651,8 +680,13 @@ An :class:`IMAP4` instance has the following methods:
651680
the interpretation of strings in the searching criteria. It then returns the
652681
numbers of matching messages.
653682

683+
If *uid* is true, the message numbers in the response are UIDs (``UID SORT``).
684+
654685
This is an ``IMAP4rev1`` extension command.
655686

687+
.. versionchanged:: next
688+
Added the *uid* parameter.
689+
656690

657691
.. method:: IMAP4.starttls(ssl_context=None)
658692

@@ -681,12 +715,15 @@ An :class:`IMAP4` instance has the following methods:
681715
Request named status conditions for *mailbox*.
682716

683717

684-
.. method:: IMAP4.store(message_set, command, flag_list)
718+
.. method:: IMAP4.store(message_set, command, flag_list, *, uid=False)
685719

686720
Alters flag dispositions for messages in mailbox. *command* is specified by
687721
section 6.4.6 of :rfc:`3501` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
688722
optionally with a suffix of ".SILENT".
689723

724+
If *uid* is true, *message_set* is a set of UIDs and the ``UID STORE``
725+
command is used instead of ``STORE``.
726+
690727
For example, to set the delete flag on all messages::
691728

692729
typ, data = M.search(None, 'ALL')
@@ -706,12 +743,15 @@ An :class:`IMAP4` instance has the following methods:
706743
Python 3.6, handles them if they are sent from the server, since this
707744
improves real-world compatibility.
708745

746+
.. versionchanged:: next
747+
Added the *uid* parameter.
748+
709749
.. method:: IMAP4.subscribe(mailbox)
710750

711751
Subscribe to new mailbox.
712752

713753

714-
.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])
754+
.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...], *, uid=False)
715755

716756
The ``thread`` command is a variant of ``search`` with threading semantics for
717757
the results. Returned data contains a space separated list of thread members.
@@ -729,8 +769,14 @@ An :class:`IMAP4` instance has the following methods:
729769
returns the matching messages threaded according to the specified threading
730770
algorithm.
731771

772+
If *uid* is true, the message numbers in the response are UIDs
773+
(``UID THREAD``).
774+
732775
This is an ``IMAP4rev1`` extension command.
733776

777+
.. versionchanged:: next
778+
Added the *uid* parameter.
779+
734780

735781
.. method:: IMAP4.uid(command, arg[, ...])
736782

‎Doc/using/windows.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1174,9 +1174,9 @@ on using nuget. What follows is a summary that is sufficient for Python
11741174
developers.
11751175

11761176
The ``nuget.exe`` command line tool may be downloaded directly from
1177-
``https://aka.ms/nugetclidl``, for example, using curl or PowerShell. With the
1178-
tool, the latest version of Python for 64-bit or 32-bit machines is installed
1179-
using::
1177+
``https://dist.nuget.org/win-x86-commandline/latest/nuget.exe``, for example,
1178+
using curl or PowerShell. With the tool, the latest version of Python for
1179+
64-bit or 32-bit machines is installed using::
11801180

11811181
nuget.exe install python -ExcludeVersion -OutputDirectory .
11821182
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

‎Doc/whatsnew/3.16.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,15 @@ imaplib
267267
as ordinary :class:`str`.
268268
(Contributed by Serhiy Storchaka in :gh:`49555`.)
269269

270+
* The :meth:`~imaplib.IMAP4.copy`, :meth:`~imaplib.IMAP4.move`,
271+
:meth:`~imaplib.IMAP4.fetch`, :meth:`~imaplib.IMAP4.store`,
272+
:meth:`~imaplib.IMAP4.search`, :meth:`~imaplib.IMAP4.sort`,
273+
:meth:`~imaplib.IMAP4.thread` and :meth:`~imaplib.IMAP4.expunge` methods
274+
now accept a keyword-only *uid* argument that selects the corresponding
275+
``UID`` command, as a more convenient alternative to
276+
:meth:`~imaplib.IMAP4.uid`.
277+
(Contributed by Serhiy Storchaka in :gh:`153502`.)
278+
270279

271280
ipaddress
272281
---------

0 commit comments

Comments
 (0)