Reference

Hopscotch only has a few public symbols to be used by other packages. Here’s the API.

Registry

The registry is the central part of Hopscotch. It mimics the registry in wired, Pyramid, and Zope (all 3 of which use Zope’s registry.)

class hopscotch.Registry(parent=None, context=None)

Type-oriented registry with special features.

Parameters

• parent (Optional[hopscotch.registry.Registry]) –

• context (Optional[Any]) –

Return type

None

get(kind, context=None, **kwargs)

Find an appropriate kind class and construct an implementation.

The passed-in keyword args act as “props” which have highest-precedence as arguments used in construction.

Parameters

• kind (Type[hopscotch.registry.T]) –

• context (Optional[Any]) –

• kwargs (dict[str, Any]) –

Return type

hopscotch.registry.T

get_best_match(kind, context_class=None, allow_singletons=True)

Find the best-match registration, if any.

Using the registry is a two-step process: lookup an implementation, then if needed, construct and return. This is the first part.

Parameters

• kind (Type[hopscotch.registry.T]) –

• context_class (Optional[Any]) –

• allow_singletons (bool) –

Return type

Optional[hopscotch.registry.Registration]

inject(registration, props=None)

Use injection to construct and return an instance.

Parameters

• registration (hopscotch.registry.Registration) –

• props (Optional[dict[str, Any]]) –

Return type

hopscotch.registry.T

register(implementation, *, kind=None, context=None)

Use a LIFO list for all the possible implementations.

Note that the implementation must be a subclass of the kind.

Parameters

• implementation (hopscotch.registry.T) –

• kind (Optional[Type[hopscotch.registry.T]]) –

• context (Optional[Any]) –

Return type

None

scan(pkg=None)

Look for decorators that need to be registered.

Parameters

pkg (Optional[Union[module, str]]) –

Return type

None

setup(pkg=None)

Pass the registry to a package which has a setup function.

Parameters

pkg (Optional[Union[module, str]]) –

Return type

None

injectable

This decorator provides a convenient way for the venusian-based scanner in the registry to recursively look for registrations.

class hopscotch.injectable(kind=None, *, context=None)

venusian decorator to register an injectable factory .

Parameters

• kind (Optional[Type[hopscotch.registry.T]]) –

• context (Optional[Optional[Any]]) –

inject_callable

Sometimes you want injection without a registry. As an example, viewdom works both with and without a registry. For the latter, it does a simpler form of injection, but with many of the same rules and machinery.

class hopscotch.inject_callable(registration, props=None, registry=None)

Construct target with or without a registry.

Parameters

• registration (hopscotch.registry.Registration) –

• props (Optional[dict[str, Any]]) –

• registry (Optional[hopscotch.registry.Registry]) –

Return type

hopscotch.registry.T

Registration

When using inject_callable directly, you need to make an object with the introspected registration information. This is the object to use.

class hopscotch.Registration(implementation, kind=None, context=None, field_infos=<factory>, is_singleton=False)

Collect registration and introspection info of a target.

Parameters

• implementation (Union[Callable[[...], object], object]) –

• kind (Optional[Callable[[...], object]]) –

• context (Optional[Callable[[...], object]]) –

• field_infos (list[hopscotch.field_infos.FieldInfo]) –

• is_singleton (bool) –

Return type

None

hopscotch.fixtures

Hopscotch provides some fixtures for use in tests and examples.

DummyOperator

Example objects for tests, examples, and docs.

class hopscotch.fixtures.DummyOperator(arg)

Simulate an operator that looks something up.

Parameters

arg (str) –

Return type

None

Dataclass Examples

Example objects and kinds implemented as dataclasses.

class hopscotch.fixtures.dataklasses.AnotherGreeting(salutation='Another Hello')

A replacement alternative for the default Greeting.

Parameters

salutation (str) –

Return type

None

class hopscotch.fixtures.dataklasses.Customer(first_name)

The person to greet, stored as the registry context.

Parameters

first_name (str) –

Return type

None

class hopscotch.fixtures.dataklasses.FrenchCustomer(first_name)

A different kind of person to greet, stored as the registry context.

Parameters

first_name (str) –

Return type

None

class hopscotch.fixtures.dataklasses.Greeter(greeting)

A dataclass to engage a customer.

Parameters

greeting (hopscotch.fixtures.dataklasses.Greeting) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterAnnotated(greeting)

A dataclass to engage a customer with an annotation.

Parameters

greeting (hopscotch.fixtures.dataklasses.Greeting) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterChildren(children)

A dataclass that is passed a tree of VDOM nodes.

Parameters

children (tuple[str]) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterCustomer(customer)

A dataclass that depends on the registry context.

Parameters

customer (hopscotch.fixtures.dataklasses.Customer) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterFirstName(customer_name)

A dataclass that gets an attribute off a dependency.

Parameters

customer_name (str) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterFrenchCustomer(customer)

A dataclass that depends on a different registry context.

Parameters

customer (hopscotch.fixtures.dataklasses.FrenchCustomer) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterGetAnother(customer_name)

Use an operator to change the type hint of what’s retrieved.

Parameters

customer_name (hopscotch.fixtures.dataklasses.AnotherGreeting) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterKind(greeting)

A dataclass Kind to engage a customer.

Parameters

greeting (hopscotch.fixtures.dataklasses.Greeting) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterOptional(greeting)

A dataclass to engage a customer with optional greeting.

Parameters

greeting (Optional[hopscotch.fixtures.dataklasses.Greeting]) –

Return type

None

class hopscotch.fixtures.dataklasses.GreeterRegistry(registry)

A dataclass that depends on the registry.

Parameters

registry (hopscotch.registry.Registry) –

Return type

None

class hopscotch.fixtures.dataklasses.Greeting(salutation='Hello')

A dataclass to give a greeting.

Parameters

salutation (str) –

Return type

None

class hopscotch.fixtures.dataklasses.GreetingFactory(salutation)

Use the __hopscotch_factory__ protocol to control creation.

Parameters

salutation (str) –

Return type

None

class hopscotch.fixtures.dataklasses.GreetingFieldDefault(salutation='Default Argument')

A dataclass with a field using a default argument.

Parameters

salutation (str) –

Return type

None

class hopscotch.fixtures.dataklasses.GreetingFieldDefaultFactory(salutation=<factory>)

A dataclass with a field using a default factory.

Parameters

salutation (list) –

Return type

None

class hopscotch.fixtures.dataklasses.GreetingInitFalse

A dataclass with a field that inits to false.

Return type

None

class hopscotch.fixtures.dataklasses.GreetingNoDefault(salutation)

A dataclass to give a greeting with no default value.

Parameters

salutation (str) –

Return type

None

class hopscotch.fixtures.dataklasses.GreetingOperator(greeter)

A dataclass to give a greeting via an operator.

Parameters

greeter (hopscotch.fixtures.dataklasses.Greeting) –

Return type

None

class hopscotch.fixtures.dataklasses.GreetingPath(location)

A dataclass to give a builtin Path.

Parameters

location (pathlib.Path) –

Return type

None

class hopscotch.fixtures.dataklasses.GreetingTuple(salutation)

A dataclass to give a sequence of greetings.

Parameters

salutation (tuple[str, ...]) –

Return type

None

Function Examples

Example objects and kinds implemented as functions.

hopscotch.fixtures.functions.Greeter(greeting)

A function to engage a customer.

Parameters

greeting (str) –

Return type

str

hopscotch.fixtures.functions.GreeterAnnotated(customer_name)

A function to engage a customer with an Annotated.

Parameters

customer_name (str) –

Return type

str

hopscotch.fixtures.functions.GreeterChildren(children)

A function that is passed a tree of VDOM nodes.

Parameters

children (tuple[str]) –

Return type

tuple[str]

hopscotch.fixtures.functions.GreeterOptional(greeting)

A function to engage a customer with optional greeting.

Parameters

greeting (Optional[str]) –

Return type

Optional[str]

hopscotch.fixtures.functions.Greeting(salutation='Hello')

A function to give a greeting.

Parameters

salutation (str) –

Return type

str

hopscotch.fixtures.functions.GreetingDefaultNoHint(salutation='Hello')

A function to with a parameter having no hint.

Return type

str

hopscotch.fixtures.functions.GreetingNoDefault(salutation)

A function to give a greeting without a default.

Parameters

salutation (str) –

Return type

str

NamedTuple Examples

Example objects and kinds implemented as NamedTuple.

Note that, since typing.NamedTuple doesn’t really do inheritance, we can’t implement a Kind as a NamedTuple.

class hopscotch.fixtures.named_tuples.Greeter(greeting)

A NamedTuple to engage a customer.

Parameters

greeting (hopscotch.fixtures.named_tuples.Greeting) –

greeting: hopscotch.fixtures.named_tuples.Greeting

Alias for field number 0

class hopscotch.fixtures.named_tuples.GreeterAnnotated(greeting)

A NamedTuple to engage a customer with an annotation.

Parameters

greeting (hopscotch.fixtures.named_tuples.Greeting) –

greeting: hopscotch.fixtures.named_tuples.Greeting

Alias for field number 0

class hopscotch.fixtures.named_tuples.GreeterChildren(children)

A NamedTuple that is passed a tree of VDOM nodes.

Parameters

children (tuple[str]) –

children: tuple[str]

Alias for field number 0

class hopscotch.fixtures.named_tuples.GreeterOptional(greeting)

A NamedTuple to engage a customer with optional greeting.

Parameters

greeting (Optional[hopscotch.fixtures.named_tuples.Greeting]) –

greeting: Optional[hopscotch.fixtures.named_tuples.Greeting]

Alias for field number 0

class hopscotch.fixtures.named_tuples.Greeting(salutation='Hello')

A NamedTuple to give a greeting.

Parameters

salutation (str) –

salutation: str

Alias for field number 0

class hopscotch.fixtures.named_tuples.GreetingNoDefault(salutation)

A NamedTuple to give a greeting without a default.

Parameters

salutation (str) –

salutation: str

Alias for field number 0

Plain Old Class Examples

Example objects and kinds implemented as plain classes.

class hopscotch.fixtures.plain_classes.Greeter(greeting)

A plain-old-class to engage a customer.

Parameters

greeting (hopscotch.fixtures.plain_classes.Greeting) –

class hopscotch.fixtures.plain_classes.GreeterAnnotated(greeting)

A plain-old-class to engage a customer with an annotation.

Parameters

greeting (hopscotch.fixtures.plain_classes.Greeting) –

class hopscotch.fixtures.plain_classes.GreeterChildren(children)

A plain-old-class that is passed a tree of VDOM nodes.

Parameters

children (tuple[str]) –

class hopscotch.fixtures.plain_classes.GreeterKind(greeting)

A plain-old-class Kind to engage a customer.

Parameters

greeting (hopscotch.fixtures.plain_classes.Greeting) –

class hopscotch.fixtures.plain_classes.GreeterOptional(greeting)

A plain-old-class to engage a customer with optional greeting.

Parameters

greeting (Optional[hopscotch.fixtures.plain_classes.Greeting]) –

class hopscotch.fixtures.plain_classes.Greeting

A plain-old-class to give a greeting.

class hopscotch.fixtures.plain_classes.GreetingNoDefault(salutation)

A plain-old-class to give a greeting without a default.

Parameters

salutation (str) –