Usage¶
Installation¶
$ pip install yourls
Overview¶
yourls is a Python client for your YOURLS server. The API is fairly simple, and API errors are turned into Python exceptions.
The main functionality is shown here:
>>> from yourls import YOURLSClient
>>> yourls = YOURLSClient('http://example.com/yourls-api.php', signature='6f344c2a8p')
>>> shorturl = yourls.shorten('http://google.com')
>>> shorturl
ShortenedURL(
shorturl='http://example.com/abcde',
url='http://google.com',
title='Google',
date=datetime.datetime(2015, 10, 31, 14, 31, 4),
ip='203.0.113.0',
clicks=0,
keyword='abcde')
>>> yourls.expand('abcde')
'http://google.com'
>>> yourls.expand('http://example.com/abcde')
'http://google.com'
>>> yourls.url_stats('abcde')
ShortenedURL(
shorturl='http://example.com/abcde',
url='http://google.com',
title='Google',
date=datetime.datetime(2015, 10, 31, 14, 31, 4),
ip='203.0.113.0',
clicks=0,
keyword='abcde')
>>> links, stats = yourls.stats(filter='random', limit=2)
>>> links
[ShortenedURL(
shorturl='http://example.com/abcde',
url='http://google.com',
title='Google',
date=datetime.datetime(2015, 10, 31, 14, 31, 4),
ip='203.0.113.0',
clicks=2,
keyword='abcde'),
ShortenedURL(
shorturl='http://example.com/gd65t',
url='http://www.youtube.com',
title='YouTube',
date=datetime.datetime(2015, 10, 31, 11, 34, 5),
ip='203.0.113.0',
clicks=567,
keyword='gd65t')]
>>> stats
DBStats(total_clicks=1234, total_links=5678)
>>> yourls.db_stats()
DBStats(total_clicks=1234, total_links=5678)
Exception Handling¶
The YOURLSClient
methods can raise several exceptions. With the
exception of YOURLSURLExistsError
and
YOURLSKeywordExistsError
, they all inherit from
requests.HTTPError
, so it’s not necessary to catch all the
exceptions individually if you just want to display the error to the user:
try:
shorturl = yourls.shorten(url, keyword=keyword)
except YOURLSURLExistsError as exc:
shorturl = exc.url
except YOURLSKeywordExistsError as exc:
print("Keyword '{}' already exists.".format(exc.keyword))
except requests.HTTPError as exc:
print(exc.args[0])
See also
Requests itself can raise more exceptions, so you might want to catch
requests.exceptions.RequestException
.
- Errors and Exceptions:
In the event of a network problem (e.g. DNS failure, refused connection, etc), Requests will raise a
ConnectionError
exception.In the rare event of an invalid HTTP response, Requests will raise an
HTTPError
exception.If a request times out, a
Timeout
exception is raised.If a request exceeds the configured number of maximum redirections, a
TooManyRedirects
exception is raised.All exceptions that Requests explicitly raises inherit from
requests.exceptions.RequestException
.
Logging¶
Logging is disabled by default. Let’s enable the logger and set up a logbook handler.
from logbook import StderrHandler
from yourls import YOURLSClient, logger
logger.disabled = False
yourls = YOURLSClient('http://example.com/yourls-api.php', signature='6f344c2a8p')
with StderrHandler():
yourls.shorten('http://www.google.com')
Here, logger is an instance of logbook.Logger
. By default, the
level is set to logbook.NOTSET
(i.e. everything is logged).
In our example, we would see the following output:
[2015-11-01 17:15:57.899368] DEBUG: yourls: Received <Response [200]> with JSON {'message': 'http://www.google.com added to database', 'url': {'keyword': 'abcde', 'title': 'Google', 'date': '2015-11-01 17:15:57', 'url': 'http://www.google.com', 'ip': '203.0.113.0'}, 'status': 'success', 'shorturl': 'http://example.com/abcde', 'title': 'Google', 'statusCode': 200}
API Plugins¶
If you want to support YOURLS plugins that add API methods (e.g. API Delete), the following is the recommended way to do so.
from yourls import YOURLSClientBase, YOURLSAPIMixin
class YOURLSDeleteMixin(object):
def delete(short):
data = dict(action='delete', shorturl=short)
self._api_request(params=data)
class YOURLSClient(YOURLSDeleteMixin, YOURLSAPIMixin, YOURLSClientBase):
"""YOURLS client with API delete support."""