[Checkins] SVN: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/ Add more docstrings, hide somewhat "internal" MIMEType class that should not be used directly.
Dan Korostelev
nadako at gmail.com
Wed Feb 18 11:21:55 EST 2009
Log message for revision 96704:
Add more docstrings, hide somewhat "internal" MIMEType class that should not be used directly.
Changed:
U Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/README.txt
U Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/interfaces.py
U Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/magic.py
U Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/mimetype.py
U Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/tests/test_doc.py
U Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/util.py
U Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/utility.py
-=-
Modified: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/README.txt
===================================================================
--- Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/README.txt 2009-02-18 15:27:47 UTC (rev 96703)
+++ Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/README.txt 2009-02-18 16:21:55 UTC (rev 96704)
@@ -25,26 +25,24 @@
>>> verifyObject(IMIMETypesUtility, util)
True
-It has three methods for getting mime type. The mime type is the
-IMIMEType object.
+It has three methods for getting mime type. Those three methods are
+``getTypeByFileName``, ``getTypeByContents`` and ``getType``. We will
+describe them in that order, but for applications, it's reccommended to
+use the latter, ``getType`` method as it's most generic and easy-to use.
- >>> from zope.interface.verify import verifyClass
- >>> from z3c.mimetype.mimetype import MIMEType
- >>> from z3c.mimetype.interfaces import IMIMEType
-
- >>> verifyClass(IMIMEType, MIMEType)
- True
-
-Those three methods are ``getTypeByFileName``, ``getTypeByContents`` and
-``getType``. We will describe them in that order, but for applications,
-it's reccommended to use the latter, ``getType`` method as it's most
-generic and easy-to use.
-
The simpliest method is ``getTypeByFileName`` that looks up the type by
filename.
>>> mt = util.getTypeByFileName('example.doc')
+The mime type is the object implementing IMIMEType interface.
+
+ >>> from zope.interface.verify import verifyObject
+ >>> from z3c.mimetype.interfaces import IMIMEType
+
+ >>> verifyObject(IMIMEType, mt)
+ True
+
>>> mt.media
'application'
Modified: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/interfaces.py
===================================================================
--- Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/interfaces.py 2009-02-18 15:27:47 UTC (rev 96703)
+++ Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/interfaces.py 2009-02-18 16:21:55 UTC (rev 96704)
@@ -11,7 +11,8 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-'''
+'''MIME type guessing framework interface definitions
+
$Id$
'''
from zope.interface import Interface
Modified: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/magic.py
===================================================================
--- Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/magic.py 2009-02-18 15:27:47 UTC (rev 96703)
+++ Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/magic.py 2009-02-18 16:21:55 UTC (rev 96704)
@@ -11,7 +11,8 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-'''
+'''Magic type guessing utility classes
+
$Id$
'''
from z3c.mimetype.mimetype import lookup
Modified: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/mimetype.py
===================================================================
--- Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/mimetype.py 2009-02-18 15:27:47 UTC (rev 96703)
+++ Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/mimetype.py 2009-02-18 16:21:55 UTC (rev 96704)
@@ -11,7 +11,8 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-'''
+'''MIME type helper objects
+
$Id$
'''
import os
@@ -31,8 +32,24 @@
mimeTypesTranslationDomain = SimpleTranslationDomain('shared-mime-info')
-class MIMEType(object):
+def lookup(media, subtype=None):
+ '''Lookup a MIMEType object using either two arguments (media and subtype)
+ or one argument in ``media/subtype`` form.
+ '''
+
+ if subtype is None and '/' in media:
+ media, subtype = media.split('/', 1)
+ if (media, subtype) not in MIME_TYPES:
+ MIME_TYPES[(media, subtype)] = _MIMEType(media, subtype)
+ return MIME_TYPES[(media, subtype)]
+class _MIMEType(object):
+ '''Single MIME type representation
+
+ Never create these objects using this class, use the ``lookup`` function
+ defined above instead.
+ '''
+
implements(IMIMEType)
_title = None
@@ -62,10 +79,3 @@
def __str__(self):
return self.media + '/' + self.subtype
-
-def lookup(media, subtype=None):
- if subtype is None and '/' in media:
- media, subtype = media.split('/', 1)
- if (media, subtype) not in MIME_TYPES:
- MIME_TYPES[(media, subtype)] = MIMEType(media, subtype)
- return MIME_TYPES[(media, subtype)]
Modified: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/tests/test_doc.py
===================================================================
--- Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/tests/test_doc.py 2009-02-18 15:27:47 UTC (rev 96703)
+++ Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/tests/test_doc.py 2009-02-18 16:21:55 UTC (rev 96704)
@@ -11,7 +11,8 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-'''
+'''Tests for z3c.mimetype functionality.
+
$Id$
'''
import os
Modified: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/util.py
===================================================================
--- Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/util.py 2009-02-18 15:27:47 UTC (rev 96703)
+++ Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/util.py 2009-02-18 16:21:55 UTC (rev 96704)
@@ -11,7 +11,8 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-'''
+'''Utility functions
+
$Id$
'''
import os
@@ -20,6 +21,8 @@
XDG_DATA_DIRS = [XDG_DATA_HOME] + [dir for dir in os.environ.get('XDG_DATA_DIRS', '/usr/local/share:/usr/share').split(':') if dir]
def iterDataPaths(*resource):
+ '''Iterate over all ``data`` paths as defined by XDG standard'''
+
resource = os.path.join(*resource)
for data_dir in XDG_DATA_DIRS:
path = os.path.join(data_dir, resource)
Modified: Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/utility.py
===================================================================
--- Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/utility.py 2009-02-18 15:27:47 UTC (rev 96703)
+++ Sandbox/nadako/z3c.mimetype/src/z3c/mimetype/utility.py 2009-02-18 16:21:55 UTC (rev 96704)
@@ -11,7 +11,9 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-'''
+'''The actual MIME type guessing utility class and global object (see the end
+of file). You want to use the guessing via this utility. :-)
+
$Id$
'''
import re
@@ -28,6 +30,7 @@
findBinary = re.compile('[\0-\7]').search
class MIMETypesUtility(object):
+ '''MIME type guessing utility'''
implements(IMIMETypesUtility)
@@ -70,6 +73,8 @@
self._literals[pattern] = mtype
def getTypeByFileName(self, filename):
+ '''Return type guessed by filename'''
+
if filename in self._literals:
return self._literals[filename]
@@ -104,9 +109,13 @@
return None
def getTypeByContents(self, file, min_priority=0, max_priority=100):
+ '''Return type guessed by data. Accepts file-like object'''
+
return self._magicDB.match(file, min_priority, max_priority)
def getType(self, filename=None, file=None):
+ '''Try to guess content type either by file name or contents or both'''
+
if (filename is None) and (file is None):
raise TypeError('Either filename or file should be provided or both of them')
More information about the Checkins
mailing list