diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/zope/contenttype/__init__.py | 32 | ||||
| -rw-r--r-- | src/zope/contenttype/__main__.py | 17 | ||||
| -rw-r--r-- | src/zope/contenttype/parse.py | 35 |
3 files changed, 71 insertions, 13 deletions
diff --git a/src/zope/contenttype/__init__.py b/src/zope/contenttype/__init__.py index 9208bbd..e2bac7f 100644 --- a/src/zope/contenttype/__init__.py +++ b/src/zope/contenttype/__init__.py @@ -21,10 +21,15 @@ find_binary = re.compile(b'[\0-\7]').search def text_type(s): - """Given an unnamed piece of text, try to guess its content type. + """ + Given an unnamed piece of data, try to guess its content type. + + Detects HTML, XML, and plain text. - Detects HTML, XML, and plain text. Returns a MIME type string - such as 'text/html'. + :return: A MIME type string such as 'text/html'. + :rtype: str + + :param bytes s: The binary data to examine. """ # at least the maximum length of any tags we look for max_tags = 14 @@ -50,13 +55,20 @@ def text_type(s): def guess_content_type(name='', body=b'', default=None): - """Given a named piece of content, try to guess its content type. + """ + Given a named piece of content, try to guess its content type. - The implementation relies on the 'mimetypes' standard Python module, - the 'text_type' function also defined in this module, and a simple + The implementation relies on the :mod:`mimetypes` standard Python module, + the :func:`text_type` function also defined in this module, and a simple heuristic for detecting binary data. - Returns a MIME type string such as "text/html". + :return: A tuple of ``(type, encoding)`` like :func:`mimetypes.guess_type`. + + :keyword str name: The file name for the content. This is given priority + when guessing the type. + :keyword bytes body: The binary data of the content. + :keyword str default: If given, and no content type can be guessed, this + will be returned as the ``type`` portion. """ # Attempt to determine the content type (and possibly # content-encoding) based on an an object's name and @@ -76,7 +88,8 @@ def guess_content_type(name='', body=b'', default=None): def add_files(filenames): - """Add the names of MIME type map files to the standard 'mimetypes' module. + """ + Add the names of MIME type map files to the standard :mod:`mimetypes` module. MIME type map files are used for detecting the MIME type of some content based on the content's filename extension. @@ -111,6 +124,3 @@ def main(): items = sorted(items) for item in items: print("%s:\t%s" % item) - -if __name__ == '__main__': - main() diff --git a/src/zope/contenttype/__main__.py b/src/zope/contenttype/__main__.py new file mode 100644 index 0000000..266023c --- /dev/null +++ b/src/zope/contenttype/__main__.py @@ -0,0 +1,17 @@ +############################################################################## +# +# Copyright (c) 2017 Zope Foundation and Contributors. +# All Rights Reserved. +# +# This software is subject to the provisions of the Zope Public License, +# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. +# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED +# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS +# FOR A PARTICULAR PURPOSE. +# +############################################################################## + +if __name__ == '__main__': + import zope.contenttype + zope.contenttype.main() diff --git a/src/zope/contenttype/parse.py b/src/zope/contenttype/parse.py index 0436cc4..8658c34 100644 --- a/src/zope/contenttype/parse.py +++ b/src/zope/contenttype/parse.py @@ -13,8 +13,11 @@ ############################################################################## """MIME Content-Type parsing helper functions. -This supports parsing RFC 1341 Content-Type values, including -quoted-string values as defined in RFC 822. +This supports parsing `RFC 1341`_ Content-Type values, including +quoted-string values as defined in `RFC 822`_. + +.. _RFC 1341: https://tools.ietf.org/html/rfc1341 +.. _RFC 822: https://tools.ietf.org/html/rfc822 """ __docformat__ = "reStructuredText" @@ -27,6 +30,17 @@ import re def parse(string): + """ + Parse the given string as a MIME type. + + This uses :func:`parseOrdered` and can raise the same + exceptions it does. + + :return: A tuple ``(major, minor, params)`` where ``major`` + and ``minor`` are the two parts of the type, and ``params`` + is a dictionary containing any parameters by name. + :param str string: The string to parse. + """ major, minor, params = parseOrdered(string) d = {} for (name, value) in params: @@ -34,6 +48,15 @@ def parse(string): return major, minor, d def parseOrdered(string): + """ + Parse the given string as a MIME type. + + :return: A tuple ``(major, minor, params)`` where ``major`` + and ``minor`` are the two parts of the type, and ``params`` is a + sequence of the parameters in order. + :raises ValueError: If the *string* is malformed. + :param str string: The string to parse. + """ if ";" in string: type, params = string.split(";", 1) params = _parse_params(params) @@ -105,6 +128,14 @@ def _unescape(string): def join(spec): + """ + Given a three-part tuple as produced by :func:`parse` or :func:`parseOrdered`, + return the string representation. + + :returns: The string representation. For example, given ``('text', + 'plain', [('encoding','utf-8')])``, this will produce ``'text/plain;encoding=utf-8'``. + :rtype: str + """ (major, minor, params) = spec pstr = "" try: |