feat: Make it easier to set content-type (#1058)

Add constants for common media types.

falcon/__init__.py

@@ -36,12 +36,10 @@ HTTP_METHODS = (
     'TRACE',
 )
 
-DEFAULT_MEDIA_TYPE = 'application/json; charset=UTF-8'
-
-
 # Hoist classes and functions into the falcon namespace
 from falcon.version import __version__  # NOQA
-from falcon.api import API, DEFAULT_MEDIA_TYPE  # NOQA
+from falcon.constants.media_types import *  # NOQA
+from falcon.api import API  # NOQA
 from falcon.status_codes import *  # NOQA
 from falcon.errors import *  # NOQA
 from falcon.redirects import *  # NOQA

falcon/api.py

@@ -36,6 +36,7 @@ class API(object):
     Args:
         media_type (str, optional): Default media type to use as the value for
             the Content-Type header on responses (default 'application/json').
+            It is possible to use default types like falcon.MEDIA_YAML, falcon.MEDIA_XML etc.
         middleware(object or list, optional): One or more objects
             (instantiated classes) that implement the following middleware
             component interface::

falcon/constants/media_types.py

@@ -0,0 +1,11 @@
+MEDIA_JSON = 'application/json; charset=UTF-8'
+MEDIA_HTML = 'text/html; charset=utf-8'
+MEDIA_JS = 'text/javascript; charset=utf-8'
+MEDIA_XML = 'application/xml'
+MEDIA_TEXT = 'text/plain; charset=utf-8'
+MEDIA_JPEG = 'image/jpeg'
+MEDIA_PNG = 'image/png'
+MEDIA_YAML = 'application/yaml'
+MEDIA_MSGPACK = 'application/msgpack'
+
+DEFAULT_MEDIA_TYPE = MEDIA_JSON

falcon/response.py

@@ -642,7 +642,14 @@ class Response(object):
 
     content_type = header_property(
         'Content-Type',
-        'Set the Content-Type header.')
+        """Sets the Content-Type header.
+
+        Note:
+            You can use the following predefined content types: ``falcon.MEDIA_JSON``,
+            ``falcon.MEDIA_HTML``, ``falcon.MEDIA_JS``, ``falcon.MEDIA_XML``,
+            ``falcon.MEDIA_TEXT``, ``falcon.MEDIA_JPEG``, ``falcon.MEDIA_PNG``,
+            ``falcon.MEDIA_YAML`` and ``MEDIA_MSGPACK``
+        """)
 
     etag = header_property(
         'ETag',
@@ -713,6 +720,23 @@ class Response(object):
 
         """)
 
+    def _set_media_type(self, media_type=None):
+        """Wrapper around set_header to set a content-type.
+
+        Args:
+            media_type: Media type to use for the Content-Type
+                header.
+
+        """
+
+        # PERF(kgriffs): Using "in" like this is faster than using
+        # dict.setdefault (tested on py27).
+        set_content_type = (media_type is not None and
+                            'content-type' not in self._headers)
+
+        if set_content_type:
+            self.set_header('content-type', media_type)
+
     def _wsgi_headers(self, media_type=None, py2=PY2):
         """Convert headers into the format expected by WSGI servers.
 
@@ -723,14 +747,7 @@ class Response(object):
         """
 
         headers = self._headers
-
-        # PERF(kgriffs): Using "in" like this is faster than using
-        # dict.setdefault (tested on py27).
-        set_content_type = (media_type is not None and
-                            'content-type' not in headers)
-
-        if set_content_type:
-            headers['content-type'] = media_type
+        self._set_media_type(media_type)
 
         if py2:
             # PERF(kgriffs): Don't create an extra list object if

tests/test_response.py

@@ -0,0 +1,13 @@
+import falcon
+from falcon import MEDIA_TEXT
+
+
+def test_response_set_content_type_set():
+    resp = falcon.Response()
+    resp._set_media_type(MEDIA_TEXT)
+    assert resp._headers['content-type'] == MEDIA_TEXT
+
+
+def test_response_set_content_type_not_set():
+    resp = falcon.Response()
+    assert 'content-type' not in resp._headers