Metadata-Version: 2.0
Name: icemac.truncatetext
Version: 1.1
Summary: Nice, intelligent truncation of text.
Home-page: https://bitbucket.org/icemac/icemac.truncatetext
Author: Michael Howitz
Author-email: icemac@gmx.net
License: MIT
Keywords: text truncate string intelligent
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: German
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: setuptools

Nice, intelligent truncation of text.

Fork me on: https://bitbucket.org/icemac/icemac.truncatetext

.. contents::

Nicely truncate text
====================

Intelligent truncation of text means that truncation does not take
place inside a word but only between words. So the required length is
only an approximation. The result text might be a bit longer than the
required length:

  >>> from icemac.truncatetext import truncate
  >>> 'I was here.'[:3]
  'I w'
  >>> truncate('I was here.', 3)
  'I was ...'

What can get truncated?
-----------------------

Only instances of ``basestring`` (``str`` on Python 3) can be truncated:

  >>> truncate(3, 3)
  Traceback (most recent call last):
  ValueError: 3 is no instance of basestring or None
  >>> print(truncate(u'Lorem ipsum', 5))
  Lorem ...

``None`` is handled nicely:

  >>> truncate(None, 4)
  ''

What is returned?
-----------------

Always at least one word is returned even when it is longer than the
required length:

  >>> truncate('Lorem ipsum', 1)
  'Lorem ...'

If the text contains only of one word which is longer than the desired
length it is returned without an ellipsis:

  >>> truncate('The-really-long-word', 5)
  'The-really-long-word'

If the text is shorter than the desired length it is returned without
the ellipsis, too:

  >>> truncate('Lorem ipsum', 11)
  'Lorem ipsum'

Where gets the text truncated?
------------------------------

Truncation also takes place at tabs and linebreaks:

  >>> truncate("I was here.\nNow I'm away", 11)
  'I was here. ...'
  >>> truncate("I was here.\rNow I'm away", 12)
  'I was here.\rNow ...'
  >>> truncate("I was here.\tNow I'm away", 11)
  'I was here. ...'

I do not want `...` as ellipsis.
--------------------------------

``truncate`` takes an optional argument which defines the ellipsis string:

  >>> print(truncate(u'Lorem ipsum', 5, ellipsis=u':::'))
  Lorem :::



Changelog
=========

1.1 (2018-11-15)
----------------

- Add support for Python 3.7.


1.0.post1 (2017-06-22)
----------------------

- Fix the `description` so PyPI accepts it.


1.0 (2017-05-13)
----------------

- Add support for Python 3.4 up to 3.6, PyPy2 and PyPy3.

- Drop support for Python 2.5 and 2.6.

- Change license from ZPL to MIT.


0.3 (2012-11-13)
----------------

- Moved sources to bitbucket.org.

- Added Travis-CI.

- Dropped official support for Python 2.3 and Python 2.4. (Although these
  rather old Python versions still might be used with this release.)


0.2.1 (2011-07-28)
------------------

- Updated categories: Python 2.7 is supported, too.


0.2 (2009-09-26)
----------------

- Added ability pass a string used as ellipsis string.


0.1 (2009-01-31)
----------------

- Initial public release.



Hacking
=======

Fork me on `bitbucket.org`_ or put your issues to the `issue tracker`_.

.. .. image:: https://secure.travis-ci.org/icemac/icemac.truncatetext.png

.. _`bitbucket.org` : https://bitbucket.org/icemac/icemac.truncatetext
.. _`issue tracker` : https://bitbucket.org/icemac/icemac.truncatetext/issues


