[Documentation](http://python_toolbox.readthedocs.org)

- And many, *many* more! The Python Toolbox contains **100+** useful little

Please keep in mind that Python Toolbox is still in alpha stage, and that backward compatibility would *not* be maintained in this phase.

The Python Toolbox supports Python versions 2.5, 2.6 and 2.7.

It also supports PyPy 1.8. (Which runs Python 2.7.)

..

ref/index

This documentation is still incomplete. If you have any questions or feedback,

say hello on the `mailing list`_!

-------------------------------------------------------------------------------

The Python Toolbox repository is at: https://github.com/cool-RR/python_toolbox

Feel free to fork and send pull requests!

.. * :ref:`modindex`

..

Copyright 2009-2012 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-abc-tools:

:mod:`abc_tools` - documentation not written

======================================

..

Copyright 2009-2012 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-address-tools:

:mod:`address_tools` - documentation not written

======================================

..

Copyright 2009-2012 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-arguments-profile:

:mod:`arguments_profile` - documentation not written

======================================

..

Copyright 2009-2012 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-binary-search:

:mod:`binary_search` - documentation not written

======================================

..

Copyright 2009-2012 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-caching-cache:

:func:`caching.cache`

====================

A caching decorator that understands arguments

----------------------------------------------

The idea of a caching decorator is very cool. You decorate your function with a

caching decorator:

>>> from python_toolbox import caching

>>>

>>> @caching.cache

... def f(x):

... print('Calculating...')

... return x ** x # Some long expensive computation

And then, every time you call it, it'll cache the results for next time:

>>> f(4)

Calculating...

256

>>> f(5)

Calculating...

3125

>>> f(5)

3125

>>> f(5)

3125

As you can see, after the first time we calculate ``f(5)`` the result gets

saved to a cache and every time we'll call ``f(5)`` Python will return the

result from the cache instead of calculating it again. This prevents making

redundant performance-expensive calculations.

Now, depending on the function, there can be many different ways to make the same call. For example, if you have a function defined like this::

def g(a, b=2, **kwargs):

return whatever

Then ``g(1)``, ``g(1, 2)``, ``g(b=2, a=1)`` and even ``g(1, 2, **{})`` are all equivalent. They give the exact same arguments, just in different ways. Most caching decorators out there don't understand that. If you call ``g(1)`` and then ``g(1, 2)``, they will calculate the function again, because they don't understand that it's exactly the same call and they could use the cached result.

Enter :func:`caching.cache`:

>>> @caching.cache()

... def g(a, b=2, **kwargs):

... print('Calculating')

... return (a, b, kwargs)

...

>>> g(1)

Calculating

(1, 2, {})

>>> g(1, 2) # Look ma, no calculating:

(1, 2, {})

>>> g(b=2, a=1) # No calculating again:

(1, 2, {})

>>> g(1, 2, **{}) # No calculating here either:

(1, 2, {})

>>> g('something_else') # Now calculating for different arguments:

Calculating

('something_else', 2, {})

As you can see above, :func:`caching.cache` analyzes the function and understands

that calls like ``g(1)`` and ``g(1, 2)`` are identical and therefore should be

cached together.

Both limited and unlimited cache

--------------------------------

By default, the cache size will be unlimited. If you want to limit the cache size, pass in the ``max_size`` argument:

>>> @caching.cache(max_size=7)

... def f(): pass

If and when the cache size reaches the limit (7 in this case), old values will

get thrown away according to a `LRU order`_.

Sleekrefs

----------

:func:`caching.cache` arguments with sleekrefs. Sleekrefs are a more robust variation of `weakrefs`_. They are basically a gracefully-degrading version of weakrefs, so you can use them on un-weakreff-able objects like :class:`int`\, and they will just use regular references.

The usage of sleekrefs prevents memory leaks when using potentially-heavy arguments.

.. _LRU order: http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used

.. _weakrefs: http://docs.python.org/library/weakref.html

..

Copyright 2009-2012 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-caching-cached-property:

:class:`caching.CachedProperty`

===============================

A cached property

-----------------

Oftentimes you have a :class:`property` on a class that never gets changed and

needs to be calculated only once. This is a good situation to use

:class:`caching.CachedProperty` in order to have that property be calculated

only one time per instance. Any future accesses to the property will use the

cached value.

Example::

>>> import time

>>> from python_toolbox import caching

>>>

>>> class MyObject(object):

... # ... Regular definitions here

... def _get_personality(self):

... print('Calculating personality...')

... time.sleep(5) # Time consuming process...

... return 'Nice person'

... personality = caching.CachedProperty(_get_personality)

Now we create an object and calculate its "personality":

>>> my_object = MyObject()

>>> my_object.personality

'Nice person'

>>> # We had to wait 5 seconds for the calculation!

Consecutive calls will be instantaneous:

>>> my_object.personality

'Nice person'

>>> # That one was cached and therefore instantaneous!

..

Copyright 2009-2012 Ram Rachum. This work is licensed under a Creative

Commons Attribution-ShareAlike 3.0 Unported License, with attribution to

"Ram Rachum at ram.rachum.com" including link. The license may be obtained

at http://creativecommons.org/licenses/by-sa/3.0/

.. _topics-caching-cached-type:

:class:`caching.CachedType`

===========================

A class that automatically caches its instances

-----------------------------------------------

Sometimes you define classes whose instances hold absolutely no state on them,

and are completey determined by the arguments passed to them. In these cases

using :class:`caching.CachedType` as a metaclass would cache class instances,

preventing more than one of them from being created:

>>> from python_toolbox import caching

>>>

>>> class A(object):

... __metaclass__ = caching.CachedType

... def __init__(self, a=1, b=2):

... self.a = a

... self.b = b

Now every time you create an instance, it'll be cached:

>>> my_instance = A(b=3)

And the next time you'll create an instance with the same arguments:

>>> another_instance = A(b=3)

No instance will be actually created; the same instance from before will be used:

>>> assert another_instance is my_instance