V2.0.0

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.