Bambu URL Shortener
===================

This package generates short URLs when given longer ones. These can be
generated by the app, with a 7 (by default) character short-name, or by
an external provider, like bit.ly.

About Bambu Tools 2.0
---------------------

This is part of a toolset called Bambu Tools. It's being moved from a
namespace of ``bambu`` to its own 'root-level' package, along with all
the other tools in the set. If you're upgrading from a version prior to
2.0, please make sure to update your code to use ``bambu_urlshortener``
rather than ``bambu.urlshortener``.

Installation
------------

Install the package via Pip:

::

    pip install bambu-urlshortener

Add it to your ``INSTALLED_APPS`` list:

::

    INSTALLED_APPS = (
        ...
        'bambu_urlshortener'
    )

To use internal URL shortening - rather than a service like bit.ly - add
the middleware to your settings:

::

    MIDDLEWARE_CLASSES = (
        ...
        'bambu_urlshortener.middleware.ShortURLFallbackMiddleware'
    )

This should be added as close to the end of your middleware list as
possible, as it looks for 404 responses and tries to find a URL
short-name corresponding to the requested path.

Run ``manage.py syncdb`` or ``manage.py migrate`` to setup the database
tables.

Basic usage
-----------

Simply call ``bambu_urlshortener.shorten``, passing in the long URL.

Providers
---------

There are two in-built shortening providers:

``bambu_urlshortener.providers.db.DatabaseProvider``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This default option, coupled with the middleware allows a web app to
provide its own short URLs.

``bambu_urlshortener.providers.bitly.BitlyProvider``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Calls the bit.ly API and returns a short URL. Specify the API key via
the ``SHORTURL_TOKEN`` setting. Optionally set the ``SHORTURL_DOMAIN``
setting if you want to use a custom domain name.

Todo
----

-  Write more tests

Questions or suggestions?
-------------------------

Find me on Twitter (@iamsteadman) or `visit my blog <http://steadman.io/>`_.
