Skip to content
This repository has been archived by the owner on Aug 10, 2024. It is now read-only.

V2.0.0

Latest
Compare
Choose a tag to compare
@Finistere Finistere released this 31 Aug 21:27
· 1 commit to master since this release

2.0.0

Antidote core has been entirely reworked to be simpler and provide better static typing in addition of several features. The cython had to be dropped though for now by lack of time. It may eventually come back.

Breaking Changes

Important

  • All previously deprecated changes have been removed.
  • The previous Scope concept has been replaced by LifeTime and ScopeGlobalVar.
  • world.test environments API have been reworked. Creating one has a similar API and guarantees, but world.test.factory, world.test.singleton and all of world.test.override have been replaced by a better alternative. See TestContextBuilder.
  • Dependencies cannot be specified through inject({...}) and inject([...]) anymore.
  • QualifiedBy/qualified_by for interface/implementation now relies on equality instead of the id().
  • const API has been reworked. const() and cont.env() have API changes and const.provider has been removed.
  • Thread-safety guarantees from Antidote are now simplified. It now only ensures lifetime consistency and some decorators such as @injectable & @interface provide some thread-safety guarantees.
  • Provider has been entirely reworked. It keeps the same name and purpose but has a different API and guarantees.

Core

  • @inject

    • removed dependencies, strict_validation and auto_provide parameters.
    • removed source parameter from @inject.me
  • Wiring

    • removed dependencies parameter.
    • renamed class_in_localns parameter to class_in_locals in .Wiring.wire().
  • @wire: removed dependencies parameter

  • renamed Get to dependencyOf. Usage of inject[]/inject.get is recommended instead for annotations.

  • world

    • Providers are not dependencies anymore. Use :py.Catalog.providers{.interpreted-text role="attr"}.
    • Providers do not check anymore that a dependency wasn't defined by another one before. They're expected to be independent.
    • Exception during dependency retrieval are not wrapped in DependencyInstantiationError anymore
    • FrozenWorldError has been renamed FrozenCatalogError.
    • world.test.new() now generates a test environment equivalent to a freshly created Catalog with new_catalog. It only impacts those using a custom Provider.
    • Removed dependency cycle detection and DependencyCycleError. It wasn't perfectly accurate and it's not really worth it. world.debug does a better job at detecting and presenting those cycles.
  • validate_injection() and validated_scope() functions have been removed.

  • DependencyGetter, TypedDependencyGetter are not part of the API anymore.

Injectable

  • The first argument klass of @injectable is now positional-only.
  • singleton and scope parameters have been replaced by lifetime.

Interface

  • ImplementationsOf has been renamed to instanceOf.
  • PredicateConstraint protocol is now a callable instead of having an evaluate() method.
  • Classes wrapped by implements are now part of the private catalog by default, if you want them to be available, you'll need to apply @injectable explicitly.
  • @implements.overriding raises a :pyValueError{.interpreted-text role="exc"} instead of :pyRuntimeError{.interpreted-text role="exc"} if the implementation does not exist.
  • The default implementation is now only provided if no other implementations matched. It wasn't the case with all() before.
  • implements.by_default has been renamed to @implements.as_default to be symmetrical with @interface.

Lazy

  • singleton and scope parameters have been replaced by lifetime.
  • call() function was removed from lazy functions, use the __wrapped__ attribute instead.
  • In test contexts such as world.test.empty() and world.test.new(), previously defined lazy/const dependencies will not be available anymore.

Const

  • To specify a type for .Const.env use the convert() argument.

  • When defining static constant values such as HOST = const('localhost'), it's NOT possible to:

    • define the type (const[str]('localhost))
    • define a default value
    • not provide value at all anymore
  • const.provider has been removed. Use @lazy.method instead. The only difference is that the const provider would return different objects even with the same arguments, while the lazy method won't.

Features

Core

  • AEP1: Instead of hack of module/functions world is now a proper instance of PublicCatalog. Alternative catalogs can be created and included in one another. Dependencies can also now be private or public. The main goal is for now to expose a whole group of dependencies through a custom catalog.

    from antidote import new_catalog, inject, injectable, world
    
    # Includes by default all of Antidote
    catalog = new_catalog()
    
    
    # Only accessible from providers by default.
    @injectable(catalog=catalog.private)
    class PrivateDummy:
        ...
    
    
    @injectable(catalog=catalog)  # if catalog is not specified, world is used.
    class Dummy:
        def __init__(self, private_dummy: PrivateDummy = inject.me()) -> None:
            self.private_dummy = private_dummy
    
    
    # Not directly accessible
    assert PrivateDummy not in catalog
    assert isinstance(catalog[Dummy], Dummy)
    
    
    # app_catalog is propagated downwards for all @inject that don't specify it.
    @inject(app_catalog=catalog)
    def f(dummy: Dummy = inject.me()) -> Dummy:
        return dummy
    
    
    assert f() is catalog[Dummy]
    
    # Not inside world yet
    assert Dummy not in world
    world.include(catalog)
    assert world[Dummy] is catalog[Dummy]
  • AEP2 (reworked): Antidote now defines a ScopeGlobalVar which has a similar interface to ContextVar and three kind of lifetimes to replace scopes:

    • 'singleton': instantiated only once
    • 'transient': instantiated on every request
    • 'scoped': used by dependencies depending on one or multiple ScopeGlobalVar. When any of them changes, the value is re-computed otherwise it's cached.

    ScopeGlobalVar isn't a ContextVar though, it's a global variable. It's planned to add a ScopeContextVar.

    from antidote import inject, lazy, ScopeGlobalVar, world
    
    counter = ScopeGlobalVar(default=0)
    
    # Until update, the value stays the same.
    assert world[counter] == 0
    assert world[counter] == 0
    token = counter.set(1)
    assert world[counter] == 1
    
    
    @lazy(lifetime='scoped')
    def dummy(count: int = inject[counter]) -> str:
        return f"Version {count}"
    
    
    # dummy will not be re-computed until counter changes.
    assert world[dummy()] == 'Version 1'
    assert world[dummy()] == 'Version 1'
    counter.reset(token)  # same interface as ContextVar
    assert world[dummy()] == 'Version 0'
  • Catalogs, such as world and @inject, expose a dict-like read-only API. Typing has also been improved:

    from typing import Optional
    
    from antidote import const, inject, injectable, world
    
    
    class Conf:
        HOST = const('localhost')
        STATIC = 1
    
    
    assert Conf.HOST in world
    assert Conf.STATIC not in world
    assert world[Conf.HOST] == 'localhost'
    assert world.get(Conf.HOST) == 'localhost'
    assert world.get(Conf.STATIC) is None
    assert world.get(Conf.STATIC, default=12) == 12
    
    try:
        world[Conf.STATIC]
    except KeyError:
        pass
    
    
    @injectable
    class Dummy:
        pass
    
    
    assert isinstance(world[Dummy], Dummy)
    assert isinstance(world.get(Dummy), Dummy)
    
    
    @inject
    def f(host: str = inject[Conf.HOST]) -> str:
        return host
    
    
    @inject
    def g(host: Optional[int] = inject.get(Conf.STATIC)) -> Optional[int]:
        return host
    
    
    assert f() == 'localhost'
    assert g() is None
  • Testing has a simplified dict-like write-only API:

    from antidote import world
    
    with world.test.new() as overrides:
        # add a singleton / override existing dependency
        overrides['hello'] = 'world'
        # add multiple singletons
        overrides.update({'second': object()})
        # delete a dependency
        del overrides['x']
    
    
        # add a factory
        @overrides.factory('greeting')
        def build() -> str:
            return "Hello!"
  • Added @inject.method which will inject the first argument, commonly self of a method with the dependency defined by the class. It won't inject when used as instance method though.

    from antidote import inject, injectable, world
    
    
    @injectable
    class Dummy:
        @inject.method
        def method(self) -> 'Dummy':
            return self
    
    
    assert Dummy.method() is world[Dummy]
    dummy = Dummy()
    assert dummy.method() is dummy
  • @inject now supports wrapping function with *args.

  • @inject has now kwargs and fallback keywords to replace the old dependencies. kwargs takes priority over alternative injections styles and fallback is used in the same way as dependencies, after defaults and type hints.

Interface

  • @interface now supports function and @lazy calls. It also supports defining the interface as the default function with @interface.as_default:

    from antidote import interface, world, implements
    
    
    @interface
    def callback(x: int) -> int:
        ...
    
    
    @implements(callback)
    def callback_impl(x: int) -> int:
        return x * 2
    
    
    assert world[callback] is callback_impl
    assert world[callback.single()] is callback_impl
    
    
    @interface.lazy.as_default
    def template(name: str) -> str:
        return f"Template {name!r}"
    
    
    assert world[template(name='test')] == "Template 'test'"
    
    
    @implements.lazy(template)
    def template_impl(name: str) -> str:
        return f"Alternative template {name!r}"
    
    
    assert world[template.all()(name='root')] == ["Alternative template 'root'"]
  • Better API for Protocol static typing:

    from typing import Protocol
    
    from antidote import implements, instanceOf, interface, world
    
    
    @interface
    class Dummy(Protocol):
        ...
    
    
    @implements.protocol[Dummy]()
    class MyDummy:
        ...
    
    
    assert isinstance(world[instanceOf[Dummy]()], MyDummy)
    assert isinstance(world[instanceOf[Dummy]().single()], MyDummy)
  • QualifiedBy relies on equality instead of the id of the objects now. Limitations on the type of qualifiers has also been removed.

    from antidote import implements, interface
    
    
    @interface
    class Dummy:
        ...
    
    
    @implements(Dummy).when(qualified_by='a')
    class A(Dummy):
        ...
    
    
    @implements(Dummy).when(qualified_by='b')
    class B(Dummy):
        ...
  • implements has a wiring argument to prevent any wiring.

Lazy

  • @lazy can now wrap (static-)methods and define values/properties:

    from antidote import injectable, lazy, world
    
    
    @lazy.value
    def name() -> str:
        return "John"
    
    
    @injectable  # required for lazy.property & lazy.method
    class Templates:
        @lazy.property
        def main(self) -> str:
            return "Lazy Main Template"
    
        @lazy.method
        def load(self, name: str) -> name:  # has access to self
            return f"Lazy Method Template {name}"
    
        @staticmethod
        @lazy
        def static_load(name: str) -> str:
            return f"Lazy Static Template {name}"
    
    
    world[name]
    world[Templates.main]
    world[Templates.load(name='Alice')]
    world[Templates.static_load(name='Bob')]
  • @lazy has now an inject argument which can be used to prevent any injection.