CODEWITHSUNDEEP
pythonimapimaplib
Stephen Bosch
Stephen Bosch

Reputation: 273

What purpose did the IMAP4.Literal attribute serve and how was it used?

I am handling connections to an IMAP server using the Python standard imaplib library.

I create an IMAP4 object like this:

import imaplib

M = imaplib.IMAP4_SSL('imap.gmail.com') # Open imaplib connection

The resulting object has these methods and attributes:

>>> dir(M)
['Literal',
 'PROTOCOL_VERSION',
 'Untagged_status',
 '_CRAM_MD5_AUTH',
 '__class__',
 '__delattr__',
 '__dict__',
 '__dir__',
 '__doc__',
 '__enter__',
 '__eq__',
 '__exit__',
 '__format__',
 '__ge__',
 '__getattr__',
 '__getattribute__',
 '__gt__',
 '__hash__',
 '__init__',
 '__init_subclass__',
 '__le__',
 '__lt__',
 '__module__',
 '__ne__',
 '__new__',
 '__reduce__',
 '__reduce_ex__',
 '__repr__',
 '__setattr__',
 '__sizeof__',
 '__str__',
 '__subclasshook__',
 '__weakref__',
 '_append_untagged',
 '_check_bye',
 '_cmd_log',
 '_cmd_log_idx',
 '_cmd_log_len',
 '_command',
 '_command_complete',
 '_connect',
 '_create_socket',
 '_dump_ur',
 '_encoding',
 '_get_capabilities',
 '_get_line',
 '_get_response',
 '_get_tagged_response',
 '_log',
 '_match',
 '_mesg',
 '_mode_ascii',
 '_mode_utf8',
 '_new_tag',
 '_quote',
 '_simple_command',
 '_tls_established',
 '_untagged_response',
 'abort',
 'append',
 'authenticate',
 'capabilities',
 'capability',
 'certfile',
 'check',
 'close',
 'continuation_response',
 'copy',
 'create',
 'debug',
 'delete',
 'deleteacl',
 'enable',
 'error',
 'expunge',
 'fetch',
 'file',
 'getacl',
 'getannotation',
 'getquota',
 'getquotaroot',
 'host',
 'is_readonly',
 'keyfile',
 'list',
 'literal',
 'login',
 'login_cram_md5',
 'logout',
 'lsub',
 'mo',
 'myrights',
 'namespace',
 'noop',
 'open',
 'partial',
 'port',
 'print_log',
 'proxyauth',
 'read',
 'readline',
 'readonly',
 'recent',
 'rename',
 'response',
 'search',
 'select',
 'send',
 'setacl',
 'setannotation',
 'setquota',
 'shutdown',
 'sock',
 'socket',
 'sort',
 'ssl_context',
 'starttls',
 'state',
 'status',
 'store',
 'subscribe',
 'tagged_commands',
 'tagnum',
 'tagpre',
 'tagre',
 'thread',
 'uid',
 'unselect',
 'unsubscribe',
 'untagged_responses',
 'utf8_enabled',
 'welcome',
 'xatom']

By default, the Literal attribute contains a re (regular expression) object:

>>> type(M.Literal)
re.Pattern
>>> print(M.Literal)
re.compile(b'.*{(?P<size>\\d+)}$', re.ASCII)

In the source code for imaplib.py, the attribute is defined on lines 113-114:

# Literal is no longer used; kept for backward compatibility.
Literal = re.compile(br'.*{(?P<size>\d+)}$', re.ASCII)

What was it used for and how, and what, if anything, replaced it?

Upvotes: 0

Views: 83

Answers (1)

chepner
chepner

Reputation: 531738

That comment was added in commit a6429db4b837dc49eb1bee42617798aebd7b43d4, which defined a similar constant _Literal that was used to define an instance attribute named Literal that is now used in place of the original global Literal.

So the pattern is still used, just not via a module global.

Before:

$ git checkout a6429db4b837dc49eb1bee42617798aebd7b43d4\^
$ grep Literal Lib/imaplib.py
Literal = re.compile(br'.*{(?P<size>\d+)}$', re.ASCII)
            while self._match(Literal, dat):

After:

$ git checkout a6429db4b837dc49eb1bee42617798aebd7b43d4
$ grep Literal Lib/imaplib.py
# Literal is no longer used; kept for backward compatibility.
Literal = re.compile(br'.*{(?P<size>\d+)}$', re.ASCII)
_Literal = br'.*{(?P<size>\d+)}$'
        self.Literal = re.compile(_Literal, re.ASCII)
        self.Literal = re.compile(_Literal)
            while self._match(self.Literal, dat):

Upvotes: 1

Related Questions