Hopscotch

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.

Features

• 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.

Requirements

• Python 3.9+.
• venusian (for decorators)

Installation

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
@dataclass
class Greeter:
    """A simple greeter."""

    greeting: str = "Hello!"


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

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

@injectable()
@dataclass
class Greeter:
    """A simple greeter."""

    greeting: str = "Hello!"


registry = Registry()
registry.scan()
# 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.
@injectable(kind=Greeter)
@dataclass
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)
@dataclass
class FrenchGreeter:
    """Provide a different ``Greeter`` in this site."""

    greeting: str = "Bonjour!"

# Much later
child_registry = Registry(
    parent=parent_registry,
    context=french_customer
)
greeter2 = child_registry.get(Greeter)
# greeter2.greeting == "Bonjour!"

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

@injectable()
@dataclass
class SiteConfig:
    punctuation: str = "!"


@injectable()
@dataclass
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.

Contributing

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

License

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

Issues

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

Credits

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