Automated Documentation

It’s a bird; it’s a plane! No, it’s the chrw module!

chrw is a wrapper for the chr url shortener, and follows all API rules, with included rate limiting.

APIv1

class chrw.v1.wrapper(url, api_key, https=False, user_agent=None, require_200=True)

A wrapper to the chr url shortening service APIv1.

Obeys the 1r/s rule with rate limiting, so you can’t accidentally hammer the API without knowing.

View online @ http://pypi.python.org/pypi/chrw

__init__(url, api_key, https=False, user_agent=None, require_200=True)

Pull together the various settings of the wrapper.

Parameters:
  • url (str) – the chr instance url, minus trailing slash (e.g. chr.so)
  • api_key (str) – your API key, as written in the database
  • https (bool) – are we using https to access this instance?
  • user_agent (str or None) – what user agent will we use to access the API?
  • require_200 (bool) – should we raise an exception on a non-200OK reply?
delete(url, code)

Request a URL be deleted.

This will only work if you supply the valid deletion code.

Parameters:
  • url (str) – the shortened url to delete
  • code (str) – the deletion code given to you on URL shorten
Returns:

the deletion request’s reply dict
Return type:

dict
expand(url)

This will simply expand a shortened url (e.g, +foo) to the larger url (e.g, http://foo.example.com/bar)

Parameters:url (str) – the shortened URL to expand
Returns:the expansion request reply dict
Return type:dict
fetch(*args, **kwargs)

This does the bulk of the work for the wrapper.

It will send a POST request, to the API URL, with all required data, as well as the api_key given, and will handle various replies, raising exceptions as required.

Parameters:
  • url (str) – the url segment to POST to (unbuilt url, e.g., /submit, /expand)
  • pdata (dict) – a dictionary of data to POST
  • store_to_self (bool) – should we store the reply (if any) to self.reply?
Returns:

the API reply data
Return type:

dict
Raises:

chrw.exceptions.ApiDisabled, chrw.exceptions.InvalidApiKey, chrw.exceptions.PartialFormData, chrw.exceptions.NonZeroException
shorten(url, custom=None, give_delete=True)

Sends a URL shorten request to the API.

Parameters:
  • url (str) – the URL to shrink
  • custom (str) – a custom URL to request
  • give_delete (bool) – would we like a deletion key to be returned?
Returns:

the API response JSON dict
Return type:

dict
stats(url)

Request the stats for a given URL.

Parameters:url (str) – the shortened url to get stats for
Returns:the statistics JSON dict for the URL
Return type:dict

Exceptions

chrw.exceptions contains all the exceptions relating to the execution of the chr wrapper.

exception chrw.exceptions.ApiDisabled

The chr API is disabled, so we can’t do anything.

exception chrw.exceptions.ChrwException

Something went wrong when trying to work with the chr API.

exception chrw.exceptions.InvalidApiKey

We sent a request with an invalid API key.

exception chrw.exceptions.InvalidDataReturned

The reply we got didn’t appear to be valid JSON data.

exception chrw.exceptions.NonZeroReply

The reply returned a non-zero reply error number.

exception chrw.exceptions.PartialFormData

Something is missing from the form data.

This might suggest an API update, and incompatibilities.

exception chrw.exceptions.RequestFailed

A POST request we sent didn’t complete as 200 OK.

exception chrw.exceptions.RequestRateTooHigh

We’re attempting to poll the API too darn frequently.

exception chrw.exceptions.TimeIsBackToFront

We somehow traveled back in time, and there was no delorean.