khvilaboa / pyshorteners

:electric_plug: A Python lib to consume the most used shorteners APIs (WIP)

pyshorteners

Description

A simple URL shortening Python Lib, implementing the most famous shorteners.

Installing

You can install pythorteners by pip or cloning/forking the repository and just typing

Installing via pip

pip install pyshorteners

Installing with the cloned/downloaded code

git clone https://github.com/ellisonleao/pyshorteners.git
cd pyshorteners
python setup.py install

Installing latest without cloning

pip install -e [e-mail]:ellisonleao/pyshorteners.git#egg=pyshorteners

Testing

make test

Usage

Create a Shortener instance passing the engine as an argument. Google Shortener is the default engine if no engine param is passed.

Goo.gl Shortener

api_key needed on kwargs

from pyshorteners import Shortener

url = 'http://www.google.com'
api_key = 'YOUR_API_KEY'
shortener = Shortener('Google', api_key=api_key)
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://goo.gl/SsadY'
print "My long url is {}".format(shortener.expand(url))

Bit.ly Shortener

bitly_token needed on kwargs

from pyshorteners import Shortener

# For Bit.ly you HAVE to provide the login and api key
access_token = 'MY_ACCESS_TOKEN'

url = 'http://www.google.com'
shortener = Shortener('Bitly', bitly_token=access_token)
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://bit.ly/AvGsb'
print "My long url is {}".format(shortener.expand(url))

TinyURL.com Shortener

No login or api key needed

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Tinyurl')
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://tinyurl.com/ycus76'
print "My long url is {}".format(shortener.expand(url))

Adf.ly Shortener

uid and api_key needed, Banner type optional (int or banner). No expanding for this shortener

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Adfly')
print "My short url is {}".format(shortener.short(url, uid=UID,
                                  api_key=API_KEY, type='int'))

Is.gd Shortener

No login or api key needed

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Isgd')
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://is.gd/SsaC'
print "My long url is {}".format(shortener.expand(url))

Senta.la Shortener

No login or api key needed

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Sentala')
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://senta.la/urubu'
print "My long url is {}".format(shortener.expand(url))

Qr.cx Shortener

No login or api key needed

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('QrCx')
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://qr.cx/XsC'
print "My long url is {}".format(shortener.expand(url))

Readbility Shortener

No login or api key needed

from pyshorteners import Shortener

url = 'http://blog.arc90.com/2010/11/30/silence-is-golden/'
shortener = Shortener('Readbility')
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://rdd.me/ycus76'
print "My long url is {}".format(shortener.expand(url))

Ow.ly Shortener

api_key needed on kwargs

from pyshorteners import Shortener

# For Ow.ly you HAVE to provide the login and api key
api_key = 'MY_API_KEY'

url = 'http://www.google.com'
shortener = Shortener('Owly',api_key=api_key)
print "My short url is {}".format(shortener.short(url))

### expanding
url = 'http://ow.ly/AvGsb'
print "My long url is {}".format(shortener.expand(url))

Osdb.link Shortener

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Osdb')
print "My short url is {}".format(shortener.short(url))

da.gd Shortener

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Dagd')
print "My short url is {}".format(shortener.short(url))

Generating QR Code

You can have the QR Code for your url by calling the qr_code method after shortening your url.

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Tinyurl')
shortener.short(url)
print shortener.qrcode()

Output
http://chart.apis.google.com/chart?cht=qr&chl=http://tinyurl.com/1c2&chs=120x120

Image:

Creating your own Shortener

To create your shortener handler you will need to:

1. Create a new file on shorteners/ folder (e.g shorteners/myshort.py)
2. Create a MyShortShortener class implementing short, expand and optionally total_clicks methods:

class MyShortShortener(BaseShortener):
	api_url = 'http://myapishortener.com/api'

	def short(self, url):
		pass

	def expand(self, url):
		pass

	def total_clicks(self, url):
		pass

3. If you need to pass extra keyword args like a token or api_key , you will need to handle it on the __init__() method.
4. Import this shortener on shorteners/__init__.py file
5. Send a PR with a test included

Passing a custom Shortener dynamically

You can create custome shorteners by implementig a class that provides a mandatory short method:

class MyCustomShortenerClass(object):

	def short(self, url):
		pass

shortener = Shortener(engine=MyCustomShortenerClass) # That's it)