🔌 A Python lib to consume the most used shorteners APIs (WIP)
Python Makefile
Clone or download
Latest commit a75987e Jul 10, 2018

README.md

pyshorteners

Build Status Number of PyPI downloads Code Health codecov.io

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 git+git@github.com: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))

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))

tiny.cc Shortener

from pyshorteners import Shortener

API_KEY = '<YOUR TINYCC API KEY HERE>'
API_LOGIN = '<YOUR TINYCC LOGIN HERE>'
url = 'http://www.google.com'
shortener = Shortener('Tinycc', api_key=API_KEY, login=API_LOGIN)
print ("My short url is {}".format(shortener.short(url)))

soo.gd Shortener

from pyshorteners import Shortener

url = 'http://www.google.com'
shortener = Shortener('Soogd')
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
  1. If you need to pass extra keyword args like a token or api_key , you will need to handle it on the __init__() method.
  2. Import this shortener on shorteners/__init__.py file
  3. 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)