## Longingly ##

Longingly is a python library that allows high performance, high reliability URL un-shortening by balancing requests across multiple services. It aims to be simple to use out of the box, but highly configurable to serve a variety uses.

Longingly is currently in alpha and there is no stable release. Use at your own risk. A "stable" release will be tagged upon the closing of all fatal issues in the issue tracker.

## Features
	* Supports massive list of url shorteners
	* Properly supports batch processing to minimize API calls
	* Dynamically tracks and updates performance of services to select the best one
	* Pluggable caching
	* Easy to add more services
	* Pluggable logging
	* Supports multiple environments
		* Full python standard install
		* Google app engine


## Basic usage

from longingly.expander import Expander

Expander().expand('http://bit.ly/cUpI7Q') 
# -> ParseResult(scheme=u'http', netloc=u'github.com', path=u'/', params='', query='', fragment='')


## Configured usage

from longingly.expander import Expander
from longingly.services import Bitly
from longingly.servuces import LongURL

exp = Expander(
	services = { 
		Bitly: {
			'priority': 1,
			'login': 'your_bitly_login',
			'api_key': 'your_bitly_api_key'
		},
		LongURL: {
			'priority': 0
		}
	}
)

exp.expand('http://bit.ly/cUpI7Q')
# -> ParseResult(scheme=u'http', netloc=u'github.com', path=u'/', params='', query='', fragment='')


## Custom Caching
# By default, an in-memory per-expander cache is used. In order to create a custom cache:
# subclass longingly.caching.AbstractCache, register class on expander construction

from longingly.caching import AbstractCache
from longingly.expander import Expander

class CustomCache(AbstractCache):
	
	def __init__(self):
		
		# Initialize data store connection here

	def has_key(self, key):
		
		# Query data store here
	
	def get(self, key):

		# Query data store here
	
	def put(self, key, value):

		# Insert into data store here

exp = Expander(cache = CustomCache)
exp.expand('http://bit.ly/cUpI7Q')
# -> ParseResult(scheme=u'http', netloc=u'github.com', path=u'/', params='', query='', fragment='')


## App Engine Mode

from longingly.expander import Expander
from longingly.fetcher import GoogleAppEngineFetcher

Expander(fetcher = GoogleAppEngineFetcher).expand('http://bit.ly/cUpI7Q')
# -> ParseResult(scheme=u'http', netloc=u'github.com', path=u'/', params='', query='', fragment='')