Import of the multifile module emits a DeprecationWarning, but the
warning is either incomplete:

- The documentation[1] states that the 'email' module is to be
  preferred, but doesn't describe what APIs should be used from that
  module.

- In fact, the 'email' module doesn't appear to provide an equivalent
  API to the 'multifile' module.

or perhaps inappropriate, as not all handling of 'multipart' MIME is
email related (e.g., processing HTTP form POSTs which include file uploads).

At a minimum, the docs for 'multifile' should include examples showing
the "preferred" way to implement its own native examples using
the'email' module's APIs.


[1] http://docs.python.org/library/multifile.html

It's not inappropriate, since the facilities *in* the email package are supposed to support other MIME use cases (such as HTML).  That it isn't clear how to convert is certainly a doc bug at the very least.  However, I wouldn't be entirely surprised to find that there are things you can do with multifile that you can't (yet) do with the facilities from the email package.  If so, these will most likely be considered bugs in the email package.

(Now, whether or not 'email' is an appropriate package name for this bundle of facilities is a different question, and not one I'm going to address :)

> [T]here [may be] things you can do with multifile that you can't (yet)
> do with the facilities from the email package.  If so, these will most > likely be considered bugs in the email package.

Surely the presence of such a feature would make the deprecation premature.

Depending on the feature, I might agree with that, but I wasn't involved in that decision.

If email only supports something structured with proper MIME headers and multifile is more general (which I *think* is the case, but I haven't actually tried to run any tests to confirm it), does that mean we should have kept multifile in py3?  I'm inclined to say no.  Should we make email support the more general case?  I'll at least keep it in the back of my mind as I/we work on email6.

Multifile is still there in 2.7, at the moment.

I presume you have a use case for the multifile module.  Could you do me a favor and add that use case the set of use cases in the email wiki?
(http://wiki.python.org/moin/Email%20SIG/UseCases).  It would be a good idea to mention there that email is supposed to supersede multifile.

> Could you do me a favor and add that use case the set of use cases in
> the email wiki?

Done.  The code in Zope which still uses 'multifile' is in the tests
for HTTP 'Range' support:

  http://svn.zope.org/*checkout*/Zope/trunk/src/OFS/tests/testRanges.py?content-type=text%2Fplain

For the sake of completeness:  the Zope2 trunk and its current stable
branch now no longer use the multifile module, thanks to the following
patch:

 http://svn.zope.org/Zope/trunk/src/OFS/tests/testRanges.py?rev=110704&r1=110402&r2=110704

That diff might serve as fodder for updating the docs for the deprecation.

Multifile *is* gone in 3.x; done deal.

If you want 2.7 docs improved, submit suggested change, even as text in message.