Author brandon-rhodes
Recipients asvetlov, brandon-rhodes, giampaolo.rodola, jcea, kristjan.jonsson, pitrou
Date 2013-06-25.01:05:36
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1372122337.56.0.229188578813.issue16487@psf.upfronthosting.co.za>
In-reply-to
Content
Kristj√°n, you are certainly correct that a single-argument that can be either a filename or a cert is inappropriate; we should not be peeking inside of strings to guess what they contain.

And I think you also have a good point about Pythonic-ness when it comes to polymorphism; routines that are sensitive to object type have been going more and more out of style for the past twenty years, and for good reason.

But, having ceded those points, I still think string-or-file-like-object is the correct approach here, simply because it is the overwhelming approach of the Standard Library; everyone is used to it, and will already "know the ropes" of that approach; and it prevents noisying up the interface with redundant arguments. Were we doing this over again, we would simply not allow a filename at all, and let the user open the file if they needed to. But since a filename is allowed, it feels like the Official Standard Library Approach to also allow a file-like object.

Some examples:

zipfile.ZipFile: "Open a ZIP file, where file can be either a path to a file (a string) or a file-like object."

http://docs.python.org/2/library/zipfile#zipfile.ZipFile

binhex.hexbin: "Decode a binhex file input. input may be a filename or a file-like object supporting read() and close() methods."

http://docs.python.org/release/2.7.5/library/binhex.html#binhex.hexbin

xml.dom.minidom.parse: "filename_or_file may be either a file name, or a file-like object."

http://docs.python.org/2/library/xml.dom.minidom.html#xml.dom.minidom.parse

mailbox.Mailbox.add: "Parameter message may be a Message instance, an email.message.Message instance, a string, or a file-like object (which should be open in text mode)."

http://docs.python.org/2/library/mailbox.html#mailbox.Mailbox.add

pickletools.dis: "pickle can be a string or a file-like object."

http://docs.python.org/2/library/pickletools.html#pickletools.dis

I suggest that these precedents, along with others that I believe we could find with a more exhaustive search of the Standard Library, are sufficient to suggest that in this case the least-surprise approach is a single argument that's either a filename or file-like object. I would suggest reviewing quickly the code for the above examples and following their example for how to distinguish most cleanly between a filename and file-like object; I wonder if they call any common code to get the contents out, or each do it completely by themselves? :)

Thanks again for wanting to add this to the SSL module, it will be a *great* addition that solves an important use case!
History
Date User Action Args
2013-06-25 01:05:37brandon-rhodessetrecipients: + brandon-rhodes, jcea, pitrou, kristjan.jonsson, giampaolo.rodola, asvetlov
2013-06-25 01:05:37brandon-rhodessetmessageid: <1372122337.56.0.229188578813.issue16487@psf.upfronthosting.co.za>
2013-06-25 01:05:37brandon-rhodeslinkissue16487 messages
2013-06-25 01:05:36brandon-rhodescreate