Commits

Anonymous committed 375aab1

mimehelper: doc strings, and api refactoring

  • Participants
  • Parent commits 12b581d

Comments (0)

Files changed (1)

webhelpers/mimehelper.py

 import webob
 
 class MIMETypes(object):
+    """MIMETypes registration mapping
+    
+    The MIMETypes object class provides a single point to hold onto all
+    the registered mimetypes, and their association extensions. It's
+    used by the mimetypes function to determine the appropriate content
+    type to return to a client.
+    
+    """
     aliases = {}
     
     def init(cls):
+        """Loads a default mapping of extensions and mimetypes
+        
+        These are suitable for most web applications by default. 
+        Additional types can be added with the using the mimetypes
+        module.
+        
+        """
         mimetypes.init()
     init = classmethod(init)
     
     def add_alias(cls, alias, mimetype):
+        """Creates a MIMEType alias to a full mimetype
+        
+        These aliases may not include /'s. Examples include 
+        html->text/html, xml->application/xml."""
+        if '/' in alias:
+            raise ValueError("MIMEType aliases may not contain '/'")
         cls.aliases[alias] = mimetype
     add_alias = classmethod(add_alias)
     
             self.env['pylons.pylons'].response.content_type = mimetype
         return mimetype
         
-    def mimetype(self, mimetype):
-        if mimetype in MIMETypes.aliases:
-            mimetype = MIMETypes.aliases[mimetype]
+    def mimetype(self, content_type):
+        """Check the PATH_INFO of the current request and clients HTTP Accept 
+        to attempt to use the appropriate mime-type
+    
+        If a content-type is matched, the appropriate response content
+        type is set as well.
+                
+        This works best with URLs that end in extensions that differentiate
+        content-type. Examples: http://example.com/example, 
+        http://example.com/example.xml, http://example.com/example.csv
+                
+        Since browsers generally allow for any content-type, but should be
+        sent HTML when possible, the html mimetype check should always come
+        first, as shown in the example below.
+        
+        Example::
+            # some code likely in environment.py
+            
+            MIMETypes.init()
+            MIMETypes.alias('html', 'text/html')
+            MIMETypes.alias('xml', 'application/xml')
+            MIMETypes.alias('csv', 'text/csv')
+            
+            def somaction(self):
+                # prepare a bunch of data
+                # ......
+                
+                # prepare MIMETypes object
+                m = MIMETypes(request.environ)
+                
+                if m.mimetype('html'):
+                    return render('/some/template.html')
+                elif m.mimetype('atom'):
+                    return render('/some/xml_template.xml')
+                elif m.mimetype('csv'):
+                    # write the data to a csv file
+                    return csvfile
+                else:
+                    abort(404)
+        
+        """
+
+        if content_type in MIMETypes.aliases:
+            content_type = MIMETypes.aliases[content_type]
         path = self.env['PATH_INFO']
         guess_from_url = mimetypes.guess_type(path)[0]
         possible_from_accept_header = None
                 self.env['HTTP_ACCEPT'])
         if has_extension == False:
             if possible_from_accept_header is None:
-                return self._set_responce_conetent_type(mimetype)
+                return self._set_responce_conetent_type(content_type)
             elif mimetype in possible_from_accept_header:
-                return self._set_responce_conetent_type(mimetype)
+                return self._set_responce_conetent_type(content_type)
             else:
                 return False
-        if mimetype == guess_from_url:
+        if content_type == guess_from_url:
             # Guessed same mimetype
-            return self._set_responce_conetent_type(mimetype)
-        elif guess_from_url is None and mimetype in possible_from_accept_header:
-            return self._set_responce_conetent_type(mimetype)
+            return self._set_responce_conetent_type(content_type)
+        elif guess_from_url is None and content_type in possible_from_accept_header:
+            return self._set_responce_conetent_type(content_type)
         else:
             return False