Repository files navigation

Brevity is the soul of tweet

A small utility to shortenposts to atweet-length summary. Appends an optional permalink or citation. Alsosupports autolinking.

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

• PHP:https://github.com/kylewm/brevity-php
• #"https://github.com/kylewm/brevity-js">https://github.com/kylewm/brevity-js

The primary methodbrevity.shorten takes aplain text string ofarbitrary length returns a shortened string that meets twitter's lengthrequirements (accounting for t.co URL shortening).

>>>importbrevity>>>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 alloptional and all have slightly different behavior. Permalinks willonly be added if the main text needs to be shortened, with theintention that followers can click the link for the full note contents.

To identifyall tweets asPOSSEcopies, you may additionally provide apermashortlink orpermashortcitation. If anote is short enough to post to twitter without truncation, the PSL/PSCwill 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 tweetswith their permalinks, it is perfectly fine to use the same url for yourpermalink and permashortlink. It will be appended after an ellipsis forlong notes, or in parentheses for short ones.

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

Setting the optional parameterformat='article' implies thattext is the title of a longer article (that can be found atpermalink). The composed text will beArticle Title: permalink andthe permalink will be included regardless of the length of the title.The values ofpermashortlink andpermashortcitation are ignored.

The methodbrevity.autolink, based heavily onCASSIS auto_link, takes a textstring, that may contain some HTML, and surrounds web addresses withwell-formed <a> tags.

>>>importbrevity>>>brevity.autolink('this links to nebenan.hamburg')'this links to <a 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.

Brevity's URL-recognition is based very heavily onTantek Çelik's excellentCASSIS.

• 0.2.18 - unreleased: shorten: add newellipsis andpunctuation kwargs,supportlink_length=None to mean links count as normal characters.
• 0.2.17 - 2018-03-15: Twitter's API no longer has a special carve-out forccTLDs; they count as 23 characters like every other URL. Simplified thelogic and updated the tests to match
• 0.2.16 - Fix character-counting bug that caused index out of range error.
• 0.2.15 - Implement Twitter's newweighted character countingintroduced on 2017-11-07.
• 0.2.14 - 2017-04-23: Fix crash when given very long tokens
• 0.2.13 - 2017-04-23: Account for leading special characters like /, @, and $
• 0.2.12 - 2017-01-03: Update list of TLDs
• 0.2.11 - 2016-09-25: Remove special formatting for media attachmentssince Twitter no longer counts them against us!
• 0.2.10 - 2016-09-05: Rearrange link regex so that TLDsare validated by the regex instead of after the fact. Makesthe shortener behave more like Twitter's.
• 0.2.9 - 2016-05-26: Bugfix: when trimming trailing charactersfrom a URL, fixes an issue where characters after the firstwould be included several times.
• 0.2.8 - 2016-04-19: Add support for article+media where textrepresents the title of an article and includes an image.
• 0.2.7 - 2016-02-14: Bugfix: make sure check for ccTLDs iscase-insensitive, so that we know Twitter won't autolink e.g.,Gogs.io
• 0.2.6 - 2016-02-01: Change shorten() parameter format_as_title toformat, and allow different format styles, including note with media(to account for extra characters used by Twitter for an attachment)
• 0.2.5 - 2016-01-28: Added ports to to php and js
• 0.2.4 - 2016-01-28: Changed license from BSD to CC0. Extract testcases into reusable tests.json file. Fix bug where permalinkcitations were counted as text rather than links.
• 0.2.3 - 2015-11-19: when truncating to the nearest word, striptrailing delimiters, so there's no punctuation before the ellipsis
• 0.2.2 - 2015-11-19: addformat_as_title parameter to shortento support formatting article titles instead of note posts
• 0.2.1 - 2015-10-25: all links default to 23 characters now thatTwitter serves all t.co links over https
• 0.2.0 - 2015-09-20: added autolink function
• 0.1.6 - 2015-06-05: move data text file into brevity.py for easierdistribution/reuse.
• 0.1.5 - 2015-06-05: match all TLDs recognized by IANA; ignorethings that look like domains but aren't.
• 0.1.4 - 2015-04-22: match URLs that include exclamation points.
• 0.1.3 - 2015-03-29: improved description in pypi.
• 0.1.0 - 2015-02-15: initial check-in.