Skip to main content

Extends Python with useful features.

Project description

🧰 Toolbox

Toolbox is a small (~0.2MB) set of tools that expands the Python Standard Library.


pip install toolbox


Documentation can be found here.



future_lru_cachelru_cache for async functions.
from toolbox import future_lru_cache
import asyncio

async def func():
    await asyncio.sleep(10)
    return 42

async def main():
    await func() # Runs once.
    await func() # Returns cached value.
to_thread — Run a synchronous function in a separate thread.
from toolbox import to_thread
import asyncio
import time

def func():
    return "Hello world"

async def main():
    await to_thread(func)
awaitable — Convert synchronous function to an async function via thread.

Leverages the to_thread function above.

from toolbox import awaitable
import asyncio
import time

def func():
    return "Hello world"

async def main():
    await func()
tls_handshake — Perform TLS handshake with a stream reader & writer.
from toolbox import tls_handshake
import asyncio

async def client():
    reader, writer = await asyncio.open_connection("", 443, ssl=False)
    await tls_handshake(reader=reader, writer=writer)

    # Communication is now encrypted.
CoroutineClass — Class pattern for implementing object-based coroutines.

Pattern for creating a coroutine-like class that has multiple ways to start it.

from toolbox import CoroutineClass
import asyncio

class Coroutine(CoroutineClass):
    def __init__(self, run: bool = False):

    # Default entry function.
    async def entry(self):
        await asyncio.sleep(1)
        return "Hello world"

# Start coroutine outside Python async context.
def iomain():

    # via __init__
    coro = Coroutine(run=True)
    print(coro.result)  # Hello world

    # via .run()
    coro = Coroutine()
    result =
    print(result)  # Hello world

# Start coroutine inside Python async context.
async def aiomain():

    # via __init__
    coro = Coroutine(run=True)
    await asyncio.sleep(1)
    print(coro.result)  # None - because process was stopped before completion.

    # via .run()
    coro = Coroutine()
    await asyncio.sleep(1)
    result = coro.stop()  # None - because coroutine was stopped before completion.
    print(result)  # Hello world

    # via await
    coro = Coroutine()
    result = await coro  # You can also start, and await later.
    print(result)  # Hello World

    # via context manager
    async with Coroutine() as coro:
        result = await coro
    print(result)  # Hello World


classproperty — Decorator for defining a method as a property and classmethod.

Allows access to computed class attributes.

from toolbox import classproperty

class Animal:
    def dog(cls):
        return "whoof!"

print( #  'whoof!'


Item — An interface for type-agnostic operations between different types.
from toolbox import Item

item = Item(100)
print(item == b"100" == "100" == 100) #  True
nestednamedtuple — Creates a nested namedtuple.
from toolbox import nestednamedtuple

nt = nestednamedtuple({"hello": {"ola": "mundo"}})
print(nt)           #  namedtupled(hello=namedtupled(ola='mundo'))
print(nt.hello.ola) #  mundo
fdict — Forces nestednamedtuple to not convert dict to namedtuple.
from toolbox import nestednamedtuple, fdict

d = {"hello": "world"}
nt = nestednamedtuple({"forced": fdict(d), "notforced": d})

print(nt.notforced) #  namedtupled(hello='world')
print(nt.forced)    #  {'hello': 'world'}
BidirectionalDict — Dictionary with two-way capabilities.
from toolbox import BidirectionalDict

d = BidirectionalDict({"hello": "world"})
print(d) #  {'hello': 'world', 'world': 'hello'}
ObjectDict — Dictionary that can be accessed as though it was an object.
from toolbox import ObjectDict

d = ObjectDict({"hello": "world"})
print(d.hello) #  'world'
OverloadedDict — Dictionary that can be added or subtracted to.
from toolbox import OverloadedDict

d1 = OverloadedDict({"hello": "world"})
d2 = OverloadedDict({"ola": "mundo"})

d1 += d2
print(d1) #  {'hello': 'world', 'ola': 'mundo'}

d1 -= d2
print(d1) #  {'hello': 'world'}
UnderscoreAccessDict — Dictionary with underscore access.
from toolbox import UnderscoreAccessDict

d = UnderscoreAccessDict({"hello": "world"})
print(d.hello) #  'world'
FrozenDict — Dictionary that is frozen.
from toolbox import FrozenDict

d = FrozenDict({"hello": "world"})
d["hello"] = "mundo" # KeyError: Cannot set key and value because this is a frozen dictionary.
MultiEntryDict — Dictionary that can have multiple entries for the same key.
from toolbox import MultiEntryDict

d = MultiEntryDict({"hello": "world"})
d["hello"] = "mundo"
print(d) #  {'hello': ['world', 'mundo']}
ItemDict — Dictionary that utilizes Item for key and values.
from toolbox import ItemDict, Item

d = ItemDict({"100": "one hundred"})
print(d[100])                                          #  one hundred
print(d[100] == d['100'] == d[b'100'] == d[Item(100)]) #  True

All *Dict types above can be combined together (as mixins) to create unique dictionary types.


make_config — Stores configuration dictionary in-memory.

Creates a global configuration that can be accessed by other portions of the code via conf or config function calls. Minimizes the need to create Config objects and pass them around different modules, classes, functions, etc.

from toolbox import make_config

config — Access in-memory configuration as dictionary.
from toolbox import config

print(config()['hello']) #  'world'
conf — Access in-memory configuration as nestednametuple.
from toolbox import conf

print(conf().hello) #  'world'


timeout — Decorator to add timeout for synchronous and asychronous functions.

Decorator that adds support for synchronous and asynchronous function timeout. Quits function after an amount of time passes.

from toolbox import timeout
import asyncio
import time

def func():

async def func():
    await asyncio.sleep(15)


sprinkle — Prints the line and file that this function was just called from.
from toolbox.pdb.sprinkle import sprinkle

sprinkle() # >>> 3
sprinkle("hello", "world") # >>> 4 hello world


search_package — Searches for packages installed in the system.
from toolbox import search_package

print(search_package("toolbox", method="is"))
#  {'toolbox': <module 'toolbox' from '.../toolbox/'>}


is_ip — Checks if a string is an IP address.
from toolbox import is_ip

print(is_ip('')) # True
print(is_ip('localhost')) # False


ANSI Formatting — Color formatting.

Check documentation here for further information on all built-in formats.

from toolbox import bold, red

print(red("This text is red!"))
print(bold("This text is bolded!"))
Format — Persistent ANSI formatter that takes a custom ANSI code.
from toolbox import Format

bold = Format(code=1)
print(bold("hello world"))
Style — Persistent ANSI formatter that allows multiple ANSI codes.
from toolbox import Style, red, bold

error = Style(red, bold)
print(error("This is red & bolded error."))
supports_color — Check's if the user's terminal supports color.
from toolbox import supports_color

print(supports_color()) # True
strip_ansi — Removes ANSI codes from string.
from toolbox import strip_ansi

print(strip_ansi("\x1b[1mhello world\x1b[0m")) #  hello world


unindent — Removes indent and white-space from docstrings.
from toolbox import unindent

def test():
    text = """
           hello world
           this is a test

    text = unindent(
        hello world
        this is a test

#           hello world
#           this is a test
# hello world
# this is a test

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

toolbox-1.11.0.tar.gz (33.2 kB view hashes)

Uploaded Source

Built Distribution

toolbox-1.11.0-py3-none-any.whl (24.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page