Home

Awesome

Brevity

Build Status

Brevity is the soul of tweet

A small utility to shorten posts to a tweet-length summary. Appends an optional permalink or citation. Also supports autolinking.

Brevity checks URLs against the full list of ICANN TLDs, to avoid linking things that look like web addresses but aren't.

Ports

Usage

Shorten

The primary method brevity.shorten takes a plain text string of arbitrary length returns a shortened string that meets twitter's length requirements (accounting for t.co URL shortening).

>>> import brevity
>>> brevity.shorten("This is the text of a fairly long tweet that will need to be shortened before we can post it to twitter. Since it is longer than 280 characters, it will also include an ellipsis and link to the original note. 123567890 123567890 123567890 123567890 123567890 123567890 123567890 123567890", permalink="http://example.com/2015/03/fairly-long-note")
'This is the text of a fairly long tweet that will need to be shortened before we can post it to twitter. Since it is longer than 280 characters, it will also include an ellipsis and link to the original note. 123567890 123567890 123567890 123567890… http://example.com/2015/03/fairly-long-note'

The permalink, permashortlink, and permashortcitation parameters are all optional and all have slightly different behavior. Permalinks will only be added if the main text needs to be shortened, with the intention that followers can click the link for the full note contents.

To identify all tweets as POSSE copies, you may additionally provide a permashortlink or permashortcitation. If a note is short enough to post to twitter without truncation, the PSL/PSC will be appended to the note text in parentheses.

>>> brevity.shorten("This note is pithy and to the point", permalink="http://example.com/2015/03/to-the-point", permashortlink="http://exm.pl/y1x3")
'This note is pithy and to the point (http://exm.pl/y1x3)'
>>> brevity.shorten("This note is pithy and to the point", permalink="http://example.com/2015/03/to-the-point", permashortcitation="exm.pl y1x3")
'This note is pithy and to the point (exm.pl y1x3)'

If you do not have a URL shortener, but still want to tag all tweets with their permalinks, it is perfectly fine to use the same url for your permalink and permashortlink. It will be appended after an ellipsis for long notes, or in parentheses for short ones.

Note that to be used in a permashortcitation, the bare domain must not be autolinked by Twitter (Otherwise, what should be 5-6 characters will count for 22). This typically means it cannot be a .com, .net, or .org.

Setting the optional parameter format='article' implies that text is the title of a longer article (that can be found at permalink). The composed text will be Article Title: permalink and the permalink will be included regardless of the length of the title. The values of permashortlink and permashortcitation are ignored.

Autolink

The method brevity.autolink, based heavily on CASSIS auto_link, takes a text string, that may contain some HTML, and surrounds web addresses with well-formed <a> tags.

>>> import brevity
>>> brevity.autolink('this links to nebenan.hamburg')
'this links to <a class="auto-link" href="http://nebenan.hamburg">nebenan.hamburg</a>'

Like the CASSIS method it is based on, autolink is idempotent -- applying it to its own output will not change the result. In practice, this means <a> tags in existing HTML will not be affected.

Acknowledgments

Brevity's URL-recognition is based very heavily on Tantek Çelik's excellent CASSIS.

Changes