Functions

  charset_best (inbuf, inlen)
  charset_canon_name (charset)
  charset_iconv_name (charset)
  charset_iso_to_windows (isocharset)
  charset_language (charset)
  charset_locale_name ()
  charset_map_init ()
  charset_map_shutdown ()
  charset_name (charset)
  check_version (major, minor, micro)
  content_encoding_from_string (str)
  content_encoding_to_string (encoding)
  encoding_base64_decode_step (inbuf, inlen, outbuf, state, save)
  encoding_base64_encode_close (inbuf, inlen, outbuf, state, save)
  encoding_base64_encode_step (inbuf, inlen, outbuf, state, save)
  encoding_quoted_decode_step (inbuf, inlen, outbuf, state, save)
  encoding_quoted_encode_close (inbuf, inlen, outbuf, state, save)
  encoding_quoted_encode_step (inbuf, inlen, outbuf, state, save)
  encoding_uudecode_step (inbuf, inlen, outbuf, state, save)
  encoding_uuencode_close (inbuf, inlen, outbuf, uubuf, state, save)
  encoding_uuencode_step (inbuf, inlen, outbuf, uubuf, state, save)
  iconv_init ()
  iconv_locale_to_utf8 (str)
  iconv_locale_to_utf8_length (str, n)
  iconv_shutdown ()
  iconv_utf8_to_locale (str)
  iconv_utf8_to_locale_length (str, n)
  init (flags)
  locale_charset ()
  locale_language ()
  references_append (refs, msgid)
  references_clear (refs)
  set_user_charsets (charsets)
  shutdown ()
  user_charsets ()
  utils_best_encoding (text, len)
  utils_decode_8bit (text)
  utils_decode_message_id (message_id)
  utils_generate_message_id (fqdn)
  utils_header_decode_date (str)
  utils_header_decode_phrase (phrase)
  utils_header_decode_text (text)
  utils_header_encode_phrase (phrase)
  utils_header_encode_text (text)
  utils_header_fold (header)
  utils_header_format_date (date, tz_offset)
  utils_quote_string (str)
  utils_structured_header_fold (header)
  utils_text_is_8bit (text, len)
  utils_unquote_string (str)
  utils_unstructured_header_fold (header)
  ydecode_step (inbuf, inlen, outbuf, state, pcrc, crc)
  yencode_close (inbuf, inlen, outbuf, state, pcrc, crc)
  yencode_step (inbuf, inlen, outbuf, state, pcrc, crc)

Details

GMime.charset_best(inbuf, inlen)
Parameters:
  • inbuf (str) – a UTF-8 text buffer
  • inlen (int) – input buffer length
Returns:

the charset name best suited for the input text or None if it is US-ASCII safe.

Return type:

str

Computes the best charset to use to encode this text buffer.

GMime.charset_canon_name(charset)
Parameters:charset (str) – charset name
Returns:a canonical charset name for charset.
Return type:str

Attempts to find a canonical charset name for charset.

Note: Will normally return the same value as GMime.Charset.iconv_name() unless the system iconv does not use the canonical ISO charset names (such as using ISO8859-1 rather than the canonical form ISO-8859-1).

GMime.charset_iconv_name(charset)
Parameters:charset (str) – charset name
Returns:an iconv-friendly charset name for charset.
Return type:str

Attempts to find an iconv-friendly charset name for charset.

GMime.charset_iso_to_windows(isocharset)
Parameters:isocharset (str) – ISO-8859-# charset
Returns:equivalent Windows charset.
Return type:str

Maps the ISO-8859-# charset to the equivalent Windows-CP125# charset.

GMime.charset_language(charset)
Parameters:charset (str) – charset name
Returns:a language code that is specific to charset, or None on fail.
Return type:str

Attempts to find a specific language code that is specific to charset. Currently only handles CJK and Russian/Ukranian charset->lang mapping. Everything else will return None.

GMime.charset_locale_name()
Returns:the user’s locale charset (or iso-8859-1 by default).
Return type:str

Gets the user’s locale charset (or iso-8859-1 by default).

Note: This function is deprecated. Use GMime.locale_charset() instead.

GMime.charset_map_init()

Initializes character set maps.

Note: GMime.init() calls this routine for you.

GMime.charset_map_shutdown()

Frees internal lookup tables created in GMime.Charset.map_init().

GMime.charset_name(charset)
Parameters:charset (str) – charset name
Returns:an iconv-friendly charset name for charset.
Return type:str

Attempts to find an iconv-friendly charset name for charset.

Note: This function is deprecated. Use GMime.Charset.iconv_name() instead.

GMime.check_version(major, minor, micro)
Parameters:
  • major (int) – Minimum major version
  • minor (int) – Minimum minor version
  • micro (int) – Minimum micro version
Returns:

True if the requirement is met or False otherwise.

Return type:

bool

Checks that the GMime library version meets the requirements of the required version.

GMime.content_encoding_from_string(str)
Parameters:str (str) – a string representing a Content-Transfer-Encoding value
Returns:the GMime.ContentEncoding specified by str or GMime.ContentEncoding.DEFAULT on error.
Return type:GMime.ContentEncoding

Gets the appropriate GMime.ContentEncoding enumeration value based on the input string.

GMime.content_encoding_to_string(encoding)
Parameters:encoding (GMime.ContentEncoding) – a GMime.ContentEncoding
Returns:the encoding type as a string or None on error. Available values for the encoding are: GMime.ContentEncoding.DEFAULT, GMime.ContentEncoding._7BIT, GMime.ContentEncoding._8BIT, GMime.ContentEncoding.BINARY, GMime.ContentEncoding.BASE64, GMime.ContentEncoding.QUOTEDPRINTABLE and GMime.ContentEncoding.UUENCODE.
Return type:str

Gets the string value of the content encoding.

GMime.encoding_base64_decode_step(inbuf, inlen, outbuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been decoded
Returns:

the number of bytes decoded (which have been dumped in outbuf).

Return type:

int

Decodes a chunk of base64 encoded data.

GMime.encoding_base64_encode_close(inbuf, inlen, outbuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded.

Return type:

int

Base64 encodes the input stream to the output stream. Call this when finished encoding data with GMime.Encoding.base64_encode_step() to flush off the last little bit.

GMime.encoding_base64_encode_step(inbuf, inlen, outbuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded.

Return type:

int

Base64 encodes a chunk of data. Performs an ‘encode step’, only encodes blocks of 3 characters to the output at a time, saves left-over state in state and save (initialise to 0 on first invocation).

GMime.encoding_quoted_decode_step(inbuf, inlen, outbuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been decoded
Returns:

the number of bytes decoded.

Return type:

int

Decodes a block of quoted-printable encoded data. Performs a ‘decode step’ on a chunk of QP encoded data.

GMime.encoding_quoted_encode_close(inbuf, inlen, outbuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded.

Return type:

int

Quoted-printable encodes a block of text. Call this when finished encoding data with GMime.Encoding.quoted_encode_step() to flush off the last little bit.

GMime.encoding_quoted_encode_step(inbuf, inlen, outbuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded.

Return type:

int

Quoted-printable encodes a block of text. Performs an ‘encode step’, saves left-over state in state and save (initialise to -1 on first invocation).

GMime.encoding_uudecode_step(inbuf, inlen, outbuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been decoded
Returns:

the number of bytes decoded.

Return type:

int

Uudecodes a chunk of data. Performs a ‘decode step’ on a chunk of uuencoded data. Assumes the “begin mode filename” line has been stripped off.

GMime.encoding_uuencode_close(inbuf, inlen, outbuf, uubuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • uubuf (int) – temporary buffer of 60 bytes
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded.

Return type:

int

Uuencodes a chunk of data. Call this when finished encoding data with GMime.Encoding.uuencode_step() to flush off the last little bit.

GMime.encoding_uuencode_step(inbuf, inlen, outbuf, uubuf, state, save)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output stream
  • uubuf (int) – temporary buffer of 60 bytes
  • state (int) – holds the number of bits that are stored in save
  • save (int) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded.

Return type:

int

Uuencodes a chunk of data. Performs an ‘encode step’, only encodes blocks of 45 characters to the output at a time, saves left-over state in uubuf, state and save (initialize to 0 on first invocation).

GMime.iconv_init()

Initialize GMime’s iconv cache. This *MUST* be called before any gmime-iconv interfaces will work correctly.

Note: this function is called for you by GMime.init().

GMime.iconv_locale_to_utf8(str)
Parameters:str (str) – string in locale charset
Returns:a new string buffer containing str converted to UTF-8.
Return type:str

Allocates a new string buffer containing str in UTF-8.

GMime.iconv_locale_to_utf8_length(str, n)
Parameters:
  • str (str) – string in locale charset
  • n (int) – number of bytes to convert
Returns:

a new string buffer containing the first n bytes of str converted to UTF-8.

Return type:

str

Allocates a new string buffer containing the first n bytes of str converted to UTF-8.

GMime.iconv_shutdown()

Frees internal iconv caches created in GMime.iconv_init().

Note: this function is called for you by GMime.shutdown().

GMime.iconv_utf8_to_locale(str)
Parameters:str (str) – string in UTF-8 charset
Returns:a new string buffer containing str converted to the user’s locale charset.
Return type:str

Allocates a new string buffer containing str converted to the user’s locale charset.

GMime.iconv_utf8_to_locale_length(str, n)
Parameters:
  • str (str) – string in UTF-8 charset
  • n (int) – number of bytes to convert
Returns:

a new string buffer containing the first n bytes of str converted to the user’s locale charset.

Return type:

str

Allocates a new string buffer containing the first n bytes of str converted to the user’s locale charset.

GMime.init(flags)
Parameters:flags (int) – initialization flags

Initializes GMime.

Note: Calls GMime.Charset.map_init() and GMime.iconv_init() as well.

GMime.locale_charset()
Returns:the user’s locale charset (or iso-8859-1 by default).
Return type:str

Gets the user’s locale charset (or iso-8859-1 by default).

GMime.locale_language()
Returns:the user’s locale language code (or None by default).
Return type:str

Gets the user’s locale language code (or None by default).

GMime.references_append(refs, msgid)
Parameters:

Appends a reference to msgid to the list of references.

GMime.references_clear(refs)
Parameters:refs (GMime.References) – address of a GMime.References list

Clears the GMime.References list and resets it to None.

GMime.set_user_charsets(charsets)
Parameters:charsets (str) – an array of user-preferred charsets

Set a list of charsets for GMime to use as a hint for encoding and decoding headers. The charset list should be in order of preference (e.g. most preferred first, least preferred last).

GMime.shutdown()

Frees internally allocated tables created in GMime.init(). Also calls GMime.Charset.map_shutdown() and GMime.iconv_shutdown().

GMime.user_charsets()
Returns:an array of user-set charsets or None if none set.
Return type:[str]

Get the list of user-preferred charsets set with GMime.set_user_charsets().

GMime.utils_best_encoding(text, len)
Parameters:
  • text (int) – text to encode
  • len (int) – text length
Returns:

a GMime.ContentEncoding that is determined to be the best encoding type for the specified block of text. (“best” in this particular case means smallest output size)

Return type:

GMime.ContentEncoding

Determines the best content encoding for the first len bytes of text.

GMime.utils_decode_8bit(text)
Parameters:text (bytes) – input text in unknown 8bit/multibyte character set
Returns:a UTF-8 string representation of text.
Return type:str

Attempts to convert text in an unknown 8bit/multibyte charset into UTF-8 by finding the charset which will convert the most bytes into valid UTF-8 characters as possible. If no exact match can be found, it will choose the best match and convert invalid byte sequences into question-marks (?) in the returned string buffer.

GMime.utils_decode_message_id(message_id)
Parameters:message_id (str) – string containing a message-id
Returns:the addr-spec portion of the msg-id.
Return type:str

Decodes a msg-id as defined by rfc822.

GMime.utils_generate_message_id(fqdn)
Parameters:fqdn (str) – Fully qualified domain name
Returns:a unique string in an addr-spec format suitable for use as a Message-Id.
Return type:str

Generates a unique Message-Id.

GMime.utils_header_decode_date(str)
Parameters:str (str) – input date string
Returns:the time_t representation of the date string specified by str or (time_t) %0 on error. If tz_offset is non-None, the value of the timezone offset will be stored.
tz_offset:timezone offset
Return type:(int, tz_offset: int)

Decodes the rfc822 date string and saves the GMT offset into tz_offset if non-None.

GMime.utils_header_decode_phrase(phrase)
Parameters:phrase (str) – header to decode
Returns:a newly allocated UTF-8 string representing the the decoded header.
Return type:str

Decodes an rfc2047 encoded ‘phrase’ header.

Note: See GMime.set_user_charsets() for details on how charset conversion is handled for unencoded 8bit text and/or wrongly specified rfc2047 encoded-word tokens.

GMime.utils_header_decode_text(text)
Parameters:text (str) – header text to decode
Returns:a newly allocated UTF-8 string representing the the decoded header.
Return type:str

Decodes an rfc2047 encoded ‘text’ header.

Note: See GMime.set_user_charsets() for details on how charset conversion is handled for unencoded 8bit text and/or wrongly specified rfc2047 encoded-word tokens.

GMime.utils_header_encode_phrase(phrase)
Parameters:phrase (str) – phrase to encode
Returns:the encoded ‘phrase’. Useful for encoding internet addresses.
Return type:str

Encodes a ‘phrase’ header according to the rules in rfc2047.

GMime.utils_header_encode_text(text)
Parameters:text (str) – text to encode
Returns:the encoded header. Useful for encoding headers like “Subject”.
Return type:str

Encodes a ‘text’ header according to the rules in rfc2047.

GMime.utils_header_fold(header)
Parameters:header (str) – header field and value string
Returns:an allocated string containing the folded header.

WARNING: This function is obsolete. Use GMime.utils_structured_header_fold() instead.

Return type:str

Folds a structured header according to the rules in rfc822.

GMime.utils_header_format_date(date, tz_offset)
Parameters:
  • date (int) – time_t date representation
  • tz_offset (int) – Timezone offset
Returns:

a valid string representation of the date.

Return type:

str

Allocates a string buffer containing the rfc822 formatted date string represented by time and tz_offset.

GMime.utils_quote_string(str)
Parameters:str (str) – input string
Returns:an allocated string containing the escaped and quoted (if needed to be) input string. The decision to quote the string is based on whether or not the input string contains any ‘tspecials’ as defined by rfc2045.
Return type:str

Quotes string as needed according to the rules in rfc2045.

GMime.utils_structured_header_fold(header)
Parameters:header (str) – header field and value string
Returns:an allocated string containing the folded header.
Return type:str

Folds a structured header according to the rules in rfc822.

GMime.utils_text_is_8bit(text, len)
Parameters:
  • text (int) – text to check for 8bit chars
  • len (int) – text length
Returns:

True if the text contains 8bit characters or False otherwise.

Return type:

bool

Determines if text contains 8bit characters within the first len bytes.

GMime.utils_unquote_string(str)
Parameters:str (str) – input string

Unquotes and unescapes a string.

GMime.utils_unstructured_header_fold(header)
Parameters:header (str) – header field and value string
Returns:an allocated string containing the folded header.
Return type:str

Folds an unstructured header according to the rules in rfc822.

GMime.ydecode_step(inbuf, inlen, outbuf, state, pcrc, crc)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – ydecode state
  • pcrc (int) – part crc state
  • crc (int) – crc state
Returns:

the number of bytes decoded.

Return type:

int

Performs a ‘decode step’ on a chunk of yEncoded data of length inlen pointed to by inbuf and writes to outbuf. Assumes the =ybegin and =ypart lines have already been stripped off.

To get the crc32 value of the part, use #GMIME_YENCODE_CRC_FINAL (pcrc). If there are more parts, you should reuse crc without re-initializing. Once all parts have been decoded, you may get the combined crc32 value of all the parts using #GMIME_YENCODE_CRC_FINAL (crc).

GMime.yencode_close(inbuf, inlen, outbuf, state, pcrc, crc)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – yencode state
  • pcrc (int) – part crc state
  • crc (int) – crc state
Returns:

the number of bytes encoded.

Return type:

int

Call this function when finished encoding data with GMime.yencode_step() to flush off the remaining state.

#GMIME_YENCODE_CRC_FINAL (pcrc) will give you the crc32 of the encoded “part”. If there are more “parts” to encode, you should re-use crc when encoding the next “parts” and then use #GMIME_YENCODE_CRC_FINAL (crc) to get the combined crc32 value of all the parts.

GMime.yencode_step(inbuf, inlen, outbuf, state, pcrc, crc)
Parameters:
  • inbuf (int) – input buffer
  • inlen (int) – input buffer length
  • outbuf (int) – output buffer
  • state (int) – yencode state
  • pcrc (int) – part crc state
  • crc (int) – crc state
Returns:

the number of bytes encoded.

Return type:

int

Performs an yEncode ‘encode step’ on a chunk of raw data of length inlen pointed to by inbuf and writes to outbuf.

state should be initialized to GMime.YENCODE_STATE_INIT before beginning making the first call to this function. Subsequent calls should reuse state.

Along the same lines, pcrc and crc should be initialized to GMime.YENCODE_CRC_INIT before using.