Skip to main content

Type-oriented registry with dependency injection.

Project description


Coverage Status Documentation Status Code style: black PyPI Python Version PyPI - Downloads License Test Status pre-commit black

Writing a decoupled application -- a "pluggable app" -- in Python is a common practice. Looking for a modern registry that scales from simple use, up to rich dependency injection (DI)? hopscotch is a registry and DI package for Python 3.9+, written to support research into component-driven development for Python's web story.

I expect a lot of skepticism.
In fact, I don't expect a lot of adoption.
Instead, I'm using this to learn and write articles.


  • Simple to complex. The easy stuff for a simple registry is easy, but rich, replaceable systems are in scope also.
  • Better DX. Improve developer experience through deep embrace of static analysis and usage of symbols instead of magic names.
  • Hierarchical. A cascade of parent registries helps model request lifecycles.
  • Tested and documented. High test coverage and quality docs with lots of (tested) examples.- Extensible.
  • Great with components. When used with viewdom, everything is wired up and you can just work in templates.

Hopscotch takes its history from wired, which came from Pyramid, which came from Zope.


  • Python 3.9+.
  • venusian (for decorators)


You can install Hopscotch via pip from PyPI:

$ pip install hopscotch

Quick Examples

Let's look at: a hello world, same but with a decorator, replacement, and multiple choice.

Here's a registry with one "kind of thing" in it:

# One kind of thing
class Greeter:
    """A simple greeter."""

    greeting: str = "Hello!"

registry = Registry()
# Later
greeter = registry.get(Greeter)
# greeter.greeting == "Hello!"

That's manual registration -- let's try with a decorator:

class Greeter:
    """A simple greeter."""

    greeting: str = "Hello!"

registry = Registry()
# Later
greeter = registry.get(Greeter)
# greeter.greeting == "Hello!"

You're building a pluggable app where people can replace builtins:

# Some site might want to change a built-in.
class CustomGreeter:
    """Provide a different ``Greeter`` in this site."""

    greeting: str = "Howdy!"

Sometimes you want a Greeter but sometimes you want a FrenchGreeter -- for example, based on the row of data a request is processing:

@injectable(kind=Greeter, context=FrenchCustomer)
class FrenchGreeter:
    """Provide a different ``Greeter`` in this site."""

    greeting: str = "Bonjour!"

# Much later
child_registry = Registry(
greeter2 = child_registry.get(Greeter)
# greeter2.greeting == "Bonjour!"

Finally, have your data constructed for you in rich ways, including custom field "operators":

class SiteConfig:
    punctuation: str = "!"

class Greeter:
    """A simple greeter."""

    punctuation: str = get(SiteConfig, attr="punctuation")
    greeting: str = "Hello"

    def greet(self) -> str:
        """Provide a greeting."""
        return f"{self.greeting}{self.punctuation}"

The full code for these examples are in the docs, with more explanation (and many more examples.)

And don't worry, dataclasses aren't required. Some support is available for plain-old classes, NamedTuple, and even functions.


Contributions are very welcome. To learn more, see the contributor's guide.


Distributed under the terms of the MIT license, Hopscotch is free and open source software.


If you encounter any problems, please file an issue along with a detailed description.


This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.

Project details

Download files

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

Files for hopscotch, version 0.1.3
Filename, size File type Python version Upload date Hashes
Filename, size hopscotch-0.1.3-py3-none-any.whl (16.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size hopscotch-0.1.3.tar.gz (15.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page