v1.0.0

.coveragerc

@@ -0,0 +1,8 @@
+[run]
+branch = false
+omit =
+    readtime/__about__.py
+[report]
+omit =
+    readtime/__about__.py
+    */python?.?/*

.gitignore

@@ -0,0 +1,39 @@
+*.py[cod]
+
+# C extensions
+*.so
+
+# Packages
+*.egg
+*.egg-info
+dist
+build
+eggs
+parts
+bin
+var
+sdist
+develop-eggs
+.installed.cfg
+lib
+lib64
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+.coverage
+.tox
+nosetests.xml
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+virtualenv
+venv
+.DS_Store

.travis.yml

@@ -0,0 +1,19 @@
+language: python
+python:
+    - "2.6"
+    - "2.7"
+    - "3.3"
+    - "3.4"
+    - "3.5"
+# command to install dependencies
+install: 
+    - if [[ $TRAVIS_PYTHON_VERSION == '2.6' ]]; then travis_retry pip install unittest2; fi
+    - travis_retry pip install -r dev-requirements.txt
+    - travis_retry pip install coveralls
+# use new travis-ci container-based infrastructure
+sudo: false
+# command to run tests
+script: nosetests
+# command to run after tests
+after_success:
+    - coveralls

AUTHORS

@@ -0,0 +1,13 @@
+readtime is written and maintained by Alan Hamlett and
+various contributors:
+
+
+Development Lead
+----------------
+
+- Alan Hamlett <[email protected]>
+
+
+Patches and Suggestions
+-----------------------
+

HISTORY.rst

@@ -0,0 +1,9 @@
+
+History
+-------
+
+
+1.0.0 (2016-10-23)
+++++++++++++++++++
+
+- Birth.

LICENSE

@@ -0,0 +1,28 @@
+BSD License
+===========
+
+Copyright (c) 2016 by the respective authors (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer
+  in the documentation and/or other materials provided
+  with the distribution.
+
+THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,2 @@
+include README.rst LICENSE HISTORY.rst requirements.txt
+recursive-include readtime *.py

README.rst

@@ -0,0 +1,67 @@
+readtime
+========
+
+.. image:: https://travis-ci.org/alanhamlett/readtime.svg?branch=master
+    :target: https://travis-ci.org/alanhamlett/readtime
+    :alt: Tests
+
+.. image:: https://coveralls.io/repos/github/alanhamlett/readtime/badge.svg?branch=master
+    :target: https://coveralls.io/github/alanhamlett/readtime?branch=master
+    :alt: Coverage
+
+Calculates the time some text takes the average human to read, based on
+Medium's `read time forumula <https://help.medium.com/hc/en-us/articles/214991667-Read-time>`_.
+
+
+Installation
+------------
+
+::
+
+    virtualenv venv
+    . venv/bin/activate
+    pip install readtime
+
+Or if you like to live dangerously::
+
+    sudo pip install readtime
+
+
+Usage
+-----
+
+Import ``readtime`` and pass it some text, HTML, or Markdown to get back the
+time it takes to read::
+
+    >>> import readtime
+    >>> result = readtime.of_text('The shortest blog post in the world!')
+    >>> result.seconds
+    2
+    >>> result.text
+    u'1 min'
+
+The result can also be used as a string::
+
+    >>> str(readtime.of_text('The shortest blog post in the world!'))
+    u'1 min read'
+
+To calculate read time of Markdown::
+
+    readtime.of_markdown('This is **Markdown**')
+
+To calculate read time of HTML::
+
+    readtime.of_html('This is <strong>HTML</strong>')
+
+
+Contributing
+------------
+
+Before contributing a pull request, make sure tests pass::
+
+    virtualenv venv
+    . venv/bin/activate
+    pip install tox
+    tox
+
+Many thanks to all `contributors <https://github.com/alanhamlett/readtime/blob/master/AUTHORS>`_!

dev-requirements.txt

@@ -0,0 +1,7 @@
+-r requirements.txt
+
+coverage==4.2
+nose==1.3.7
+nose-capturestderr==1.2
+tox==2.3.1
+-e git://github.com/alanhamlett/nose-exclude.git@f8ad6b1111e3927ecfaafd26f6952745c4b8df0c#egg=nose-exclude

readtime/__about__.py

@@ -0,0 +1,10 @@
+__title__ = 'readtime'
+__description__ = 'Calculates the time some text takes the average human to ' \
+                  'read, based on Medium\'s read time forumula'
+__url__ = 'https://github.com/alanhamlett/readtime'
+__version_info__ = ('1', '0', '0')
+__version__ = '.'.join(__version_info__)
+__author__ = 'Alan Hamlett'
+__author_email__ = '[email protected]'
+__license__ = 'BSD'
+__copyright__ = 'Copyright 2016 Alan Hamlett'

readtime/__init__.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""
+    readtime
+    ~~~~~~~~
+
+    Calculates the time some text takes the average human to read.
+
+    :copyright: (c) 2016 Alan Hamlett.
+    :license: BSD, see LICENSE for more details.
+"""
+
+
+from .api import (
+    of_text,
+    of_html,
+    of_markdown,
+)

readtime/_compat.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+"""
+    readtime.compat
+    ~~~~~~~~~~~~~~~
+
+    For working with Python2 and Python3.
+
+    :copyright: (c) 2016 Alan Hamlett.
+    :license: BSD, see LICENSE for more details.
+"""
+
+
+import sys
+
+
+IS_PY2 = sys.version_info[0] == 2
+
+
+if IS_PY2:  # pragma: nocover
+
+    def u(text):
+        if text is None:
+            return None
+        try:
+            return text.decode('utf-8')
+        except:
+            try:
+                return text.decode(sys.getdefaultencoding())
+            except:
+                try:
+                    return unicode(text)
+                except:
+                    return text
+
+else:  # pragma: nocover
+
+    def u(text):
+        if text is None:
+            return None
+        if isinstance(text, bytes):
+            try:
+                return text.decode('utf-8')
+            except:
+                try:
+                    return text.decode(sys.getdefaultencoding())
+                except:
+                    pass
+        try:
+            return str(text)
+        except:
+            return text

readtime/api.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""
+    readtime.api
+    ~~~~~~~~~~~~
+
+    Contains public methods.
+
+    :copyright: (c) 2016 Alan Hamlett.
+    :license: BSD, see LICENSE for more details.
+"""
+
+
+from . import utils
+
+
+def of_text(text):
+    """Get the read time of some text.
+
+    :param text:  String of text (Assumes utf-8).
+    """
+
+    return utils.read_time(text, format='text')
+
+
+def of_html(html):
+    """Get the read time of some HTML.
+
+    :param html:  String of HTML.
+    """
+
+    return utils.read_time(html, format='html')
+
+
+def of_markdown(markdown):
+    """Get the read time of some Markdown.
+
+    :param markdown:  String of Markdown.
+    """
+
+    return utils.read_time(markdown, format='markdown')

readtime/result.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""
+    readtime.result
+    ~~~~~~~~~~~~~~~
+
+    For returning read time results.
+
+    :copyright: (c) 2016 Alan Hamlett.
+    :license: BSD, see LICENSE for more details.
+"""
+
+
+from __future__ import division
+
+from ._compat import u
+
+
+class Result(object):
+    seconds = None
+    minutes = None
+    text = None
+
+    def __init__(self, seconds):
+        self.seconds = seconds
+        self.minutes = int(round(seconds / 60))
+        if self.minutes < 1:
+            self.minutes = 1
+        self.text = u('{0} min').format(self.minutes)
+
+    def __repr__(self):
+        return self.text + ' read'
+
+    def __unicode__(self):
+        return self.__repr__()  # pragma: nocover