classification
Title: Deprecation of multifile inappropriate or incomplete
Type: behavior Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, docs@python, r.david.murray, terry.reedy, tseaver
Priority: normal Keywords:

Created on 2010-04-05 17:42 by tseaver, last changed 2013-03-10 20:04 by terry.reedy. This issue is now closed.

Messages (7)
msg102390 - (view) Author: Tres Seaver (tseaver) * Date: 2010-04-05 17:42
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
msg102397 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-04-05 19:21
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 :)
msg102399 - (view) Author: Tres Seaver (tseaver) * Date: 2010-04-05 19:42
> [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.
msg102404 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-04-05 20:03
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.
msg102429 - (view) Author: Tres Seaver (tseaver) * Date: 2010-04-06 02:22
> 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
msg106810 - (view) Author: Tres Seaver (tseaver) * Date: 2010-05-31 20:39
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.
msg112906 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-04 21:55
Multifile *is* gone in 3.x; done deal.

If you want 2.7 docs improved, submit suggested change, even as text in message.
History
Date User Action Args
2013-03-10 20:04:00terry.reedysetstage: needs patch -> resolved
2013-03-10 20:03:53terry.reedysetstatus: open -> closed
resolution: out of date
2010-08-04 21:55:11terry.reedysetversions: - Python 2.6, Python 2.5
nosy: + docs@python, terry.reedy

messages: + msg112906

assignee: docs@python
components: + Documentation, - Library (Lib)
2010-05-31 20:39:58tseaversetmessages: + msg106810
2010-04-06 02:22:15tseaversetmessages: + msg102429
2010-04-05 20:03:34r.david.murraysetmessages: + msg102404
2010-04-05 19:42:33tseaversetmessages: + msg102399
2010-04-05 19:21:03r.david.murraysetpriority: normal

nosy: + r.david.murray
messages: + msg102397

type: behavior
stage: needs patch
2010-04-05 17:42:00tseavercreate