add hg and python

1 files changed, 561 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/emailmessage.tex b/sys/src/cmd/python/Doc/lib/emailmessage.tex
new file mode 100644
index 000000000..7bd7dd8b3
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/emailmessage.tex
@@ -0,0 +1,561 @@
+\declaremodule{standard}{email.message}
+\modulesynopsis{The base class representing email messages.}
+
+The central class in the \module{email} package is the
+\class{Message} class, imported from the \module{email.message} module.  It is
+the base class for the \module{email} object model.  \class{Message} provides
+the core functionality for setting and querying header fields, and for
+accessing message bodies.
+
+Conceptually, a \class{Message} object consists of \emph{headers} and
+\emph{payloads}.  Headers are \rfc{2822} style field names and
+values where the field name and value are separated by a colon.  The
+colon is not part of either the field name or the field value.
+
+Headers are stored and returned in case-preserving form but are
+matched case-insensitively.  There may also be a single envelope
+header, also known as the \emph{Unix-From} header or the
+\code{From_} header.  The payload is either a string in the case of
+simple message objects or a list of \class{Message} objects for
+MIME container documents (e.g. \mimetype{multipart/*} and
+\mimetype{message/rfc822}).
+
+\class{Message} objects provide a mapping style interface for
+accessing the message headers, and an explicit interface for accessing
+both the headers and the payload.  It provides convenience methods for
+generating a flat text representation of the message object tree, for
+accessing commonly used header parameters, and for recursively walking
+over the object tree.
+
+Here are the methods of the \class{Message} class:
+
+\begin{classdesc}{Message}{}
+The constructor takes no arguments.
+\end{classdesc}
+
+\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
+Return the entire message flatten as a string.  When optional
+\var{unixfrom} is \code{True}, the envelope header is included in the
+returned string.  \var{unixfrom} defaults to \code{False}.
+
+Note that this method is provided as a convenience and may not always format
+the message the way you want.  For example, by default it mangles lines that
+begin with \code{From }.  For more flexibility, instantiate a
+\class{Generator} instance and use its
+\method{flatten()} method directly.  For example:
+
+\begin{verbatim}
+from cStringIO import StringIO
+from email.generator import Generator
+fp = StringIO()
+g = Generator(fp, mangle_from_=False, maxheaderlen=60)
+g.flatten(msg)
+text = fp.getvalue()
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__str__}{}
+Equivalent to \method{as_string(unixfrom=True)}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{is_multipart}{}
+Return \code{True} if the message's payload is a list of
+sub-\class{Message} objects, otherwise return \code{False}.  When
+\method{is_multipart()} returns False, the payload should be a string
+object.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_unixfrom}{unixfrom}
+Set the message's envelope header to \var{unixfrom}, which should be a string.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_unixfrom}{}
+Return the message's envelope header.  Defaults to \code{None} if the
+envelope header was never set.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{attach}{payload}
+Add the given \var{payload} to the current payload, which must be
+\code{None} or a list of \class{Message} objects before the call.
+After the call, the payload will always be a list of \class{Message}
+objects.  If you want to set the payload to a scalar object (e.g. a
+string), use \method{set_payload()} instead.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_payload}{\optional{i\optional{, decode}}}
+Return a reference the current payload, which will be a list of
+\class{Message} objects when \method{is_multipart()} is \code{True}, or a
+string when \method{is_multipart()} is \code{False}.  If the
+payload is a list and you mutate the list object, you modify the
+message's payload in place.
+
+With optional argument \var{i}, \method{get_payload()} will return the
+\var{i}-th element of the payload, counting from zero, if
+\method{is_multipart()} is \code{True}.  An \exception{IndexError}
+will be raised if \var{i} is less than 0 or greater than or equal to
+the number of items in the payload.  If the payload is a string
+(i.e. \method{is_multipart()} is \code{False}) and \var{i} is given, a
+\exception{TypeError} is raised.
+
+Optional \var{decode} is a flag indicating whether the payload should be
+decoded or not, according to the \mailheader{Content-Transfer-Encoding} header.
+When \code{True} and the message is not a multipart, the payload will be
+decoded if this header's value is \samp{quoted-printable} or
+\samp{base64}.  If some other encoding is used, or
+\mailheader{Content-Transfer-Encoding} header is
+missing, or if the payload has bogus base64 data, the payload is
+returned as-is (undecoded).  If the message is a multipart and the
+\var{decode} flag is \code{True}, then \code{None} is returned.  The
+default for \var{decode} is \code{False}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_payload}{payload\optional{, charset}}
+Set the entire message object's payload to \var{payload}.  It is the
+client's responsibility to ensure the payload invariants.  Optional
+\var{charset} sets the message's default character set; see
+\method{set_charset()} for details.
+
+\versionchanged[\var{charset} argument added]{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_charset}{charset}
+Set the character set of the payload to \var{charset}, which can
+either be a \class{Charset} instance (see \refmodule{email.charset}), a
+string naming a character set,
+or \code{None}.  If it is a string, it will be converted to a
+\class{Charset} instance.  If \var{charset} is \code{None}, the
+\code{charset} parameter will be removed from the
+\mailheader{Content-Type} header. Anything else will generate a
+\exception{TypeError}.
+
+The message will be assumed to be of type \mimetype{text/*} encoded with
+\var{charset.input_charset}.  It will be converted to
+\var{charset.output_charset}
+and encoded properly, if needed, when generating the plain text
+representation of the message.  MIME headers
+(\mailheader{MIME-Version}, \mailheader{Content-Type},
+\mailheader{Content-Transfer-Encoding}) will be added as needed.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_charset}{}
+Return the \class{Charset} instance associated with the message's payload.
+\versionadded{2.2.2}
+\end{methoddesc}
+
+The following methods implement a mapping-like interface for accessing
+the message's \rfc{2822} headers.  Note that there are some
+semantic differences between these methods and a normal mapping
+(i.e. dictionary) interface.  For example, in a dictionary there are
+no duplicate keys, but here there may be duplicate message headers.  Also,
+in dictionaries there is no guaranteed order to the keys returned by
+\method{keys()}, but in a \class{Message} object, headers are always
+returned in the order they appeared in the original message, or were
+added to the message later.  Any header deleted and then re-added are
+always appended to the end of the header list.
+
+These semantic differences are intentional and are biased toward
+maximal convenience.
+
+Note that in all cases, any envelope header present in the message is
+not included in the mapping interface.
+
+\begin{methoddesc}[Message]{__len__}{}
+Return the total number of headers, including duplicates.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__contains__}{name}
+Return true if the message object has a field named \var{name}.
+Matching is done case-insensitively and \var{name} should not include the
+trailing colon.  Used for the \code{in} operator,
+e.g.:
+
+\begin{verbatim}
+if 'message-id' in myMessage:
+    print 'Message-ID:', myMessage['message-id']
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__getitem__}{name}
+Return the value of the named header field.  \var{name} should not
+include the colon field separator.  If the header is missing,
+\code{None} is returned; a \exception{KeyError} is never raised.
+
+Note that if the named field appears more than once in the message's
+headers, exactly which of those field values will be returned is
+undefined.  Use the \method{get_all()} method to get the values of all
+the extant named headers.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__setitem__}{name, val}
+Add a header to the message with field name \var{name} and value
+\var{val}.  The field is appended to the end of the message's existing
+fields.
+
+Note that this does \emph{not} overwrite or delete any existing header
+with the same name.  If you want to ensure that the new header is the
+only one present in the message with field name
+\var{name}, delete the field first, e.g.:
+
+\begin{verbatim}
+del msg['subject']
+msg['subject'] = 'Python roolz!'
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{__delitem__}{name}
+Delete all occurrences of the field with name \var{name} from the
+message's headers.  No exception is raised if the named field isn't
+present in the headers.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{has_key}{name}
+Return true if the message contains a header field named \var{name},
+otherwise return false.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{keys}{}
+Return a list of all the message's header field names.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{values}{}
+Return a list of all the message's field values.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{items}{}
+Return a list of 2-tuples containing all the message's field headers
+and values.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get}{name\optional{, failobj}}
+Return the value of the named header field.  This is identical to
+\method{__getitem__()} except that optional \var{failobj} is returned
+if the named header is missing (defaults to \code{None}).
+\end{methoddesc}
+
+Here are some additional useful methods:
+
+\begin{methoddesc}[Message]{get_all}{name\optional{, failobj}}
+Return a list of all the values for the field named \var{name}.
+If there are no such named headers in the message, \var{failobj} is
+returned (defaults to \code{None}).
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{add_header}{_name, _value, **_params}
+Extended header setting.  This method is similar to
+\method{__setitem__()} except that additional header parameters can be
+provided as keyword arguments.  \var{_name} is the header field to add
+and \var{_value} is the \emph{primary} value for the header.
+
+For each item in the keyword argument dictionary \var{_params}, the
+key is taken as the parameter name, with underscores converted to
+dashes (since dashes are illegal in Python identifiers).  Normally,
+the parameter will be added as \code{key="value"} unless the value is
+\code{None}, in which case only the key will be added.
+
+Here's an example:
+
+\begin{verbatim}
+msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+\end{verbatim}
+
+This will add a header that looks like
+
+\begin{verbatim}
+Content-Disposition: attachment; filename="bud.gif"
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{replace_header}{_name, _value}
+Replace a header.  Replace the first header found in the message that
+matches \var{_name}, retaining header order and field name case.  If
+no matching header was found, a \exception{KeyError} is raised.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_content_type}{}
+Return the message's content type.  The returned string is coerced to
+lower case of the form \mimetype{maintype/subtype}.  If there was no
+\mailheader{Content-Type} header in the message the default type as
+given by \method{get_default_type()} will be returned.  Since
+according to \rfc{2045}, messages always have a default type,
+\method{get_content_type()} will always return a value.
+
+\rfc{2045} defines a message's default type to be
+\mimetype{text/plain} unless it appears inside a
+\mimetype{multipart/digest} container, in which case it would be
+\mimetype{message/rfc822}.  If the \mailheader{Content-Type} header
+has an invalid type specification, \rfc{2045} mandates that the
+default type be \mimetype{text/plain}.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_content_maintype}{}
+Return the message's main content type.  This is the
+\mimetype{maintype} part of the string returned by
+\method{get_content_type()}.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_content_subtype}{}
+Return the message's sub-content type.  This is the \mimetype{subtype}
+part of the string returned by \method{get_content_type()}.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_default_type}{}
+Return the default content type.  Most messages have a default content
+type of \mimetype{text/plain}, except for messages that are subparts
+of \mimetype{multipart/digest} containers.  Such subparts have a
+default content type of \mimetype{message/rfc822}.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_default_type}{ctype}
+Set the default content type.  \var{ctype} should either be
+\mimetype{text/plain} or \mimetype{message/rfc822}, although this is
+not enforced.  The default content type is not stored in the
+\mailheader{Content-Type} header.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{,
+    header\optional{, unquote}}}}
+Return the message's \mailheader{Content-Type} parameters, as a list.  The
+elements of the returned list are 2-tuples of key/value pairs, as
+split on the \character{=} sign.  The left hand side of the
+\character{=} is the key, while the right hand side is the value.  If
+there is no \character{=} sign in the parameter the value is the empty
+string, otherwise the value is as described in \method{get_param()} and is
+unquoted if optional \var{unquote} is \code{True} (the default).
+
+Optional \var{failobj} is the object to return if there is no
+\mailheader{Content-Type} header.  Optional \var{header} is the header to
+search instead of \mailheader{Content-Type}.
+
+\versionchanged[\var{unquote} argument added]{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_param}{param\optional{,
+    failobj\optional{, header\optional{, unquote}}}}
+Return the value of the \mailheader{Content-Type} header's parameter
+\var{param} as a string.  If the message has no \mailheader{Content-Type}
+header or if there is no such parameter, then \var{failobj} is
+returned (defaults to \code{None}).
+
+Optional \var{header} if given, specifies the message header to use
+instead of \mailheader{Content-Type}.
+
+Parameter keys are always compared case insensitively.  The return
+value can either be a string, or a 3-tuple if the parameter was
+\rfc{2231} encoded.  When it's a 3-tuple, the elements of the value are of
+the form \code{(CHARSET, LANGUAGE, VALUE)}.  Note that both \code{CHARSET} and
+\code{LANGUAGE} can be \code{None}, in which case you should consider
+\code{VALUE} to be encoded in the \code{us-ascii} charset.  You can
+usually ignore \code{LANGUAGE}.
+
+If your application doesn't care whether the parameter was encoded as in
+\rfc{2231}, you can collapse the parameter value by calling
+\function{email.Utils.collapse_rfc2231_value()}, passing in the return value
+from \method{get_param()}.  This will return a suitably decoded Unicode string
+whn the value is a tuple, or the original string unquoted if it isn't.  For
+example:
+
+\begin{verbatim}
+rawparam = msg.get_param('foo')
+param = email.Utils.collapse_rfc2231_value(rawparam)
+\end{verbatim}
+
+In any case, the parameter value (either the returned string, or the
+\code{VALUE} item in the 3-tuple) is always unquoted, unless
+\var{unquote} is set to \code{False}.
+
+\versionchanged[\var{unquote} argument added, and 3-tuple return value
+possible]{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_param}{param, value\optional{,
+    header\optional{, requote\optional{, charset\optional{, language}}}}}
+
+Set a parameter in the \mailheader{Content-Type} header.  If the
+parameter already exists in the header, its value will be replaced
+with \var{value}.  If the \mailheader{Content-Type} header as not yet
+been defined for this message, it will be set to \mimetype{text/plain}
+and the new parameter value will be appended as per \rfc{2045}.
+
+Optional \var{header} specifies an alternative header to
+\mailheader{Content-Type}, and all parameters will be quoted as
+necessary unless optional \var{requote} is \code{False} (the default
+is \code{True}).
+
+If optional \var{charset} is specified, the parameter will be encoded
+according to \rfc{2231}. Optional \var{language} specifies the RFC
+2231 language, defaulting to the empty string.  Both \var{charset} and
+\var{language} should be strings.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{del_param}{param\optional{, header\optional{,
+    requote}}}
+Remove the given parameter completely from the
+\mailheader{Content-Type} header.  The header will be re-written in
+place without the parameter or its value.  All values will be quoted
+as necessary unless \var{requote} is \code{False} (the default is
+\code{True}).  Optional \var{header} specifies an alternative to
+\mailheader{Content-Type}.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_type}{type\optional{, header}\optional{,
+    requote}}
+Set the main type and subtype for the \mailheader{Content-Type}
+header. \var{type} must be a string in the form
+\mimetype{maintype/subtype}, otherwise a \exception{ValueError} is
+raised.
+
+This method replaces the \mailheader{Content-Type} header, keeping all
+the parameters in place.  If \var{requote} is \code{False}, this
+leaves the existing header's quoting as is, otherwise the parameters
+will be quoted (the default).
+
+An alternative header can be specified in the \var{header} argument.
+When the \mailheader{Content-Type} header is set a
+\mailheader{MIME-Version} header is also added.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
+Return the value of the \code{filename} parameter of the
+\mailheader{Content-Disposition} header of the message.  If the header does
+not have a \code{filename} parameter, this method falls back to looking for
+the \code{name} parameter.  If neither is found, or the header is missing,
+then \var{failobj} is returned.  The returned string will always be unquoted
+as per \method{Utils.unquote()}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_boundary}{\optional{failobj}}
+Return the value of the \code{boundary} parameter of the
+\mailheader{Content-Type} header of the message, or \var{failobj} if either
+the header is missing, or has no \code{boundary} parameter.  The
+returned string will always be unquoted as per
+\method{Utils.unquote()}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{set_boundary}{boundary}
+Set the \code{boundary} parameter of the \mailheader{Content-Type}
+header to \var{boundary}.  \method{set_boundary()} will always quote
+\var{boundary} if necessary.  A \exception{HeaderParseError} is raised
+if the message object has no \mailheader{Content-Type} header.
+
+Note that using this method is subtly different than deleting the old
+\mailheader{Content-Type} header and adding a new one with the new boundary
+via \method{add_header()}, because \method{set_boundary()} preserves the
+order of the \mailheader{Content-Type} header in the list of headers.
+However, it does \emph{not} preserve any continuation lines which may
+have been present in the original \mailheader{Content-Type} header.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_content_charset}{\optional{failobj}}
+Return the \code{charset} parameter of the \mailheader{Content-Type}
+header, coerced to lower case.  If there is no
+\mailheader{Content-Type} header, or if that header has no
+\code{charset} parameter, \var{failobj} is returned.
+
+Note that this method differs from \method{get_charset()} which
+returns the \class{Charset} instance for the default encoding of the
+message body.
+
+\versionadded{2.2.2}
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{get_charsets}{\optional{failobj}}
+Return a list containing the character set names in the message.  If
+the message is a \mimetype{multipart}, then the list will contain one
+element for each subpart in the payload, otherwise, it will be a list
+of length 1.
+
+Each item in the list will be a string which is the value of the
+\code{charset} parameter in the \mailheader{Content-Type} header for the
+represented subpart.  However, if the subpart has no
+\mailheader{Content-Type} header, no \code{charset} parameter, or is not of
+the \mimetype{text} main MIME type, then that item in the returned list
+will be \var{failobj}.
+\end{methoddesc}
+
+\begin{methoddesc}[Message]{walk}{}
+The \method{walk()} method is an all-purpose generator which can be
+used to iterate over all the parts and subparts of a message object
+tree, in depth-first traversal order.  You will typically use
+\method{walk()} as the iterator in a \code{for} loop; each
+iteration returns the next subpart.
+
+Here's an example that prints the MIME type of every part of a
+multipart message structure:
+
+\begin{verbatim}
+>>> for part in msg.walk():
+...     print part.get_content_type()
+multipart/report
+text/plain
+message/delivery-status
+text/plain
+text/plain
+message/rfc822
+\end{verbatim}
+\end{methoddesc}
+
+\versionchanged[The previously deprecated methods \method{get_type()},
+\method{get_main_type()}, and \method{get_subtype()} were removed]{2.5}
+
+\class{Message} objects can also optionally contain two instance
+attributes, which can be used when generating the plain text of a MIME
+message.
+
+\begin{datadesc}{preamble}
+The format of a MIME document allows for some text between the blank
+line following the headers, and the first multipart boundary string.
+Normally, this text is never visible in a MIME-aware mail reader
+because it falls outside the standard MIME armor.  However, when
+viewing the raw text of the message, or when viewing the message in a
+non-MIME aware reader, this text can become visible.
+
+The \var{preamble} attribute contains this leading extra-armor text
+for MIME documents.  When the \class{Parser} discovers some text after
+the headers but before the first boundary string, it assigns this text
+to the message's \var{preamble} attribute.  When the \class{Generator}
+is writing out the plain text representation of a MIME message, and it
+finds the message has a \var{preamble} attribute, it will write this
+text in the area between the headers and the first boundary.  See
+\refmodule{email.parser} and \refmodule{email.generator} for details.
+
+Note that if the message object has no preamble, the
+\var{preamble} attribute will be \code{None}.
+\end{datadesc}
+
+\begin{datadesc}{epilogue}
+The \var{epilogue} attribute acts the same way as the \var{preamble}
+attribute, except that it contains text that appears between the last
+boundary and the end of the message.
+
+\versionchanged[You do not need to set the epilogue to the empty string in
+order for the \class{Generator} to print a newline at the end of the
+file]{2.5}
+\end{datadesc}
+
+\begin{datadesc}{defects}
+The \var{defects} attribute contains a list of all the problems found when
+parsing this message.  See \refmodule{email.errors} for a detailed description
+of the possible parsing defects.
+
+\versionadded{2.4}
+\end{datadesc}