Welcome to Gimme That’s documentation!¶
API reference¶
Main API¶
- gimme.add(obj, deep=True)¶
Add an object to the
Repository
after which it will be available for dependent classes when resolving their dependencies.By default, the object will be registered for both its own class as well as any subclasses (up to and including
object
). Settingdeep=False
switches this off, and the object will only be registered for its own class- Parameters
obj (
Any
) – The object to add to theRepository
deep (
bool
) – Whether to also register obj for all base classes of obj
- gimme.add_resolver(resolver)¶
Add a custom
Resolver
to theRepository
- gimme.context()¶
return a context manager that adds a repository to the stack and yields it
- gimme.dependency(cls)¶
Deprecated since version 0.1.2: Use
gimme.register()
instead.
- gimme.later(cls_or_str, lazy=True)¶
Use this as a descriptor in your class definition when dealing with circular dependencies. Normally, having circular dependencies would prevent instantiating these classes.
By default, using this descriptor to specify a dependency defers the resolution of this dependency until the first time it is used.
- Parameters
cls_or_str (
Union
[type
,str
]) – The type of which to retrieve an objectlazy (
bool
) – When set toFalse
, the dependency is resolved immediately the first time the dependent class is instantiated. This precludes the use ofgimme.later
for resolving circular dependencies, but instead now it works the same way of using type annotations for specifying dependencies. If you don’t like using type annotations, you may usegimme.later
withlazy=False
to get the same behaviour.
- gimme.pop_context()¶
Pops the current repository from the repository stack, effectively resetting the state of the repository to a previous state
- gimme.register(cls=None, factory=None, info=None, store=True, kwargs=None)¶
Register a class in the
Repository
. This makes the class available for identification by string (seegimme.that()
andgimme.later()
) and allows for additional control over class instantiation.Alternatively, instead of giving a class (and optional parameters), you can also give a
DependencyInfo
object directly that contains the configuration.- Parameters
cls (
Optional
[type
]) – The class to register in the repository.factory (
Optional
[Callable
]) – Optional factory to create an instance, if not specified, use the class’ constructor instead (ie.cls.__init__
)info (
Optional
[DependencyInfo
]) – An object that contains the class instantiation configuration. Only provide this when nocls
parameter is givenstore (
bool
) – Whether to store an instantiated class in theRepository
. The default effectively makes every class a singleton, but if you want to change this behaviour, setstore=False
kwargs (
Optional
[dict
]) – Additional keyword arguments to pass to the factory (orcls.__init__
) for construction
- gimme.setup(objects=None, types=None, resolvers=None)¶
Setup and configure your
Repository
- Parameters
objects (
Optional
[Iterable
[Any
]]) – Any objects to add to theRepository
types (
Optional
[Iterable
[Union
[type
,DependencyInfo
]]]) – Any types / classes to registerresolvers (
Optional
[Iterable
[Resolver
]]) – Any additionalResolvers
to add for dependency resolution
- gimme.that(kind, **kwargs)¶
Request an object from the
Repository
by type. If it does not exist in theRepository
yet, it will be created, and any dependencies of the class will be resolved recursively. If the class has been registered with a specific factory function, that function will be used to create the object.Alternatively, a callable, such as function, may be given as the kind. In this case,
gimme.that
tries to resolve all input parameters of the function, runs the function with the input parameters and returns the result. In this case the result is never stored in theRepository
. However, any dependencies that are created when resolving the input parameters, may be stored.Optionally, if the class has been registered using the
gimme.dependency()
decorator orgimme.register()
function, the object type may also be specified using class name as a string.- Parameters
kind (
Union
[Type
[~T],str
,callable
]) – either a class, identified by the type-object itself or a string, or acallable
- Return type
~T
- gimme.get(cls_or_str)¶
An alias for
gimme.that()
. Use this if you do not like the default cute names
- gimme.attribute(cls_or_str)¶
An alias for
gimme.later()
. Use this if you do not like the default cute names
gimme.repository¶
gimme.resolvers¶
- class gimme.resolvers.Resolver¶
Base class for creating extensions to the dependency resolution system. Subclass this class and add instances of your class to the repository using
gimme.add_resolver()
orgimme.setup()
- get_dependencies(factory, repository, kwargs=None)¶
Override this to customize how to resolve the dependencies of a specific class / factory function. This method will be called with the following arguments:
- Parameters
factory (t.Callable) – The class / factory function to determine the dependencies for
repository (LayeredRepository) – The current
Repository
can be used for requesting dependencieskwargs (dict) – Any user specified keyword arguments (see
gimme.register()
). These will have preference over any keyword arguments this function supplies
Your
Resolver
may do one of three things:Return a dictionary of keyword arguments to supply to the factory upon instantiation
Raise
CannotResolve
if yourResolver
cannot return an instantiated object and the nextResolver
should be triedRaise
PartiallyResolved
if yourResolver
did resolve some, but not all of the dependencies
gimme.helpers¶
- gimme.helpers.parse_type_hint(hint)¶
Get the constructor for iterable/sequence type hints: returns the concrete type belonging to the type hint, ie set for typing.Set for the abstract type hints typing.Iterable :param hint: A Generic Type hint :returns: TypeHintInfo, or None if it could not be parsed into a list-like collection of type. eg for nested generic types (List[List[int]])
gimme.exceptions¶
- exception gimme.exceptions.CannotResolve¶
Raised when a
Resolver
cannot resolve the dependencies of a class, and therefore cannot provide an instance
- exception gimme.exceptions.CircularDependency¶
Raised when a circular dependency is detected and the requested class cannot be instantiated