pip_services3_commons.refer package

Submodules

Module contents

pip_services3_commons.refer.init

Inversion of control design pattern. There exist various implementations, a popular one being “inversion of dependency”. Requires introspection and is implemented differently in different languages. In PipServices, the “location design pattern” is used, which is much simpler than dependency injection and is a simple implementation, that is portable between languages. Used for building various containers, as well as testing objects.

copyright: Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.
license: MIT, see LICENSE for more details.

class pip_services3_commons.refer.DependencyResolver(config: pip_services3_commons.config.ConfigParams.ConfigParams = None, references: pip_services3_commons.refer.IReferences.IReferences = None)

Bases: pip_services3_commons.config.IReconfigurable.IReconfigurable, pip_services3_commons.refer.IReferenceable.IReferenceable

Helper class for resolving component dependencies. The resolver is configured to resolve named dependencies by specific locator. During deployment the dependency locator can be changed.

This mechanism can be used to clarify specific dependency among several alternatives. Typically components are configured to retrieve the first dependency that matches logical group, type and version. But if container contains more than one instance and resolution has to be specific about those instances, they can be given a unique name and dependency resolvers can be reconfigured to retrieve dependencies by their name.

### Configuration parameters ### dependencies:

[dependency name 1]: Dependency 1 locator (descriptor)

…

[dependency name N]: Dependency N locator (descriptor)

References:

References must match configured dependencies.

Example:

class MyComponent(IConfigurable, IReferenceable):
    _dependencyResolver = None
    _persistence = None

    def __init__(self):
        self._dependencyResolver.put("persistence", new Descriptor("mygroup", "persistence", "*", "*", "1.0"))

    def configure(self, config):
        self._dependencyResolver.configure(config)

    def set_references(self, references):
        self._dependencyResolver.setReferences(references)
        self._persistence = self._dependencyResolver.get_one_required("persistence")

    component = MyComponent()
    component.configure(ConfigParams.from_tuples(
    "dependencies.persistence", "mygroup:persistence:*:persistence2:1.0"))

    component.set_references(References.from_tuples(Descriptor("mygroup","persistence","*","persistence1","1.0"),
    MyPersistence(),
    Descriptor("mygroup","persistence","*","persistence2","1.0"), MyPersistence()
    # This dependency shall be set))

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures the component with specified parameters.

Parameters: config – configuration parameters to set.

find(name: str, required: bool) → Optional[List[Any], None]

Finds all matching dependencies by their name.

Parameters

name – the dependency name to locate.
required – true to raise an error when no dependencies are found.

Returns

a list of found dependencies

static from_tuples(*tuples: Any) → pip_services3_commons.refer.DependencyResolver.DependencyResolver 

Creates a new DependencyResolver from a list of key-args pairs called tuples where key is dependency name and args the depedency locator (descriptor).

Parameters: tuples – a list of values where odd elements are dependency name

and the following even elements are dependency locator (descriptor)

Returns: a newly created DependencyResolver.

get_one_optional(name: str) → Any

Gets one optional dependency by its name.

Parameters: name – the dependency name to locate.
Returns: a dependency reference or null of the dependency was not found

get_one_required(name: str) → Any

Gets one __required dependency by its name. At least one dependency must present. If the dependency was found it throws a ReferenceException

Parameters: name – the dependency name to locate.
Returns: a dependency reference

get_optional(name: str) → List[Any]

Gets all optional dependencies by their name.

Parameters: name – the dependency name to locate.
Returns: a list with found dependencies or empty list of no dependencies was found.

get_required(name: str) → List[Any]

Gets all __required dependencies by their name. At least one dependency must be present. If no dependencies was found it throws a ReferenceException

Parameters: name – the dependency name to locate.
Returns: a list with found dependencies.

put(name: str, locator: Any)

Adds a new dependency into this resolver.

Parameters

name – the dependency’s name.
locator – the locator to find the dependency by.

set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets the component references. References must match configured dependencies.

Parameters: references – references to set.

class pip_services3_commons.refer.Descriptor(group: Optional[str, None], type: Optional[str, None], kind: Optional[str, None], name: Optional[str, None], version: Optional[str, None])

Bases: object

Locator type that most often used in PipServices toolkit. It locates components using several fields:

Group: a package or just named group of components like “pip-services”

Type: logical component type that defines it’s contract like “persistence”

Kind: physical implementation type like “mongodb”

Name: unique component name like “default”

Version: version of the component contract like “1.0”

The locator matching can be done by all or only few selected fields. The fields that shall be excluded from the matching must be set to “*” or None. That approach allows to implement many interesting scenarios. For instance:

Locate all loggers (match by type and version)

Locate persistence components for a microservice (match by group and type)

Locate specific component by its name (match by name)

Example:

locator1 = Descriptor("mygroup", "connector", "aws", "default", "1.0")
locator2 = Descriptor.from_string("mygroup:connector:*:*:1.0")

locator1.match(locator2);               // Result: true
locator1.eq(locator2);          // Result: true
locator1.exact_match(locator2); // Result: false

equals(value: Any) → bool 

Compares this descriptor to a args. If args is a Descriptor it tries to match them, otherwise the method returns false.

Parameters: value – the args to match against this descriptor.
Returns: true if the args is matching descriptor and false otherwise.

exact_match(descriptor: pip_services3_commons.refer.Descriptor.Descriptor) → bool 

Matches this descriptor to another descriptor by all fields. No exceptions are made.

Parameters: descriptor – the descriptor to match this one against.
Returns: true if descriptors match and false otherwise.

static from_string(value: str) → Optional[pip_services3_commons.refer.Descriptor.Descriptor, None]

Parses colon-separated list of descriptor fields and returns them as a Descriptor.

Parameters: value – colon-separated descriptor fields to initialize Descriptor.
Returns: a newly created Descriptor.

get_group() → str 

Gets the component’s logical group.

Returns: the component’s logical group

get_kind() → str 

Gets the component’s implementation type.

Returns: the component’s implementation type.

get_name() → str 

Gets the unique component’s name.

Returns: the unique component’s name.

get_type() → str 

Gets the component’s logical type.

Returns: the component’s logical type.

get_version() → str 

Gets the component’s implementation version.

Returns: the component’s implementation version.

is_complete() → bool 

Checks whether all descriptor fields are set. If descriptor has at least one “*” or null field it is considered “incomplete”

Returns: true if all descriptor fields are defined and false otherwise.

match(descriptor: pip_services3_commons.refer.Descriptor.Descriptor) → bool 

Partially matches this descriptor to another descriptor. Fields that contain “*” or null are excluded from the match.

Parameters: descriptor – the descriptor to match this one against.
Returns: true if descriptors match and false otherwise

to_string() → str 

Gets a string representation of the object. The result is a colon-separated list of descriptor fields as “mygroup:connector:aws:default:1.0”

Returns: a string representation of the object.

class pip_services3_commons.refer.IReferenceable

Bases: abc.ABC

Interface for components that depends on obj components. If component requires explicit notification to unset references it shall additionally implement IUnreferenceable interface.

Example:

class MyController(IReferenceable):
    _persistence = None

    def set_references(self, references):
        self._persistence = references.get_one_required(Descriptor("mygroup", "persistence", "*", "*", "1.0"))

set_references(references: <module 'pip_services3_commons.refer.IReferences' from '/pip_services3_commons/refer/IReferences.py'>)

Sets references to dependent components.

Parameters: references – references to locate the component dependencies.

class pip_services3_commons.refer.IReferences

Bases: abc.ABC

Interface for a map that holds component references and passes them to components to establish dependencies with each obj.

Together with IReferenceable and IUnreferenceable interfaces it implements a Locator pattern that is used by PipServices toolkit for Inversion of Control to assign external dependencies to components.

The IReferences object is a simple map, where keys are locators and values are component references. It allows to add, remove and find components by their locators. Locators can be any values like integers, strings or component types. But most often PipServices toolkit uses Descriptor as locators that match by 5 fields: group, type, kind, name and version.

Example:

class MyController(IReferences):
    _persistence = None

    def set_references(self, references):
        self._persistence = references.get_one_required(Descriptor("mygroup", "persistence", "*", "*", "1.0"))

persistence = MyMongoDbPersistence()

references = References.from_tuples(
Descriptor("mygroup", "persistence", "mongodb", "default", "1.0"), persistence,
Descriptor("mygroup", "controller", "default", "default", "1.0"), controller)

controller.set_references(references)

find(locator: Any, required: bool) → List[Any]

Gets all component references that match specified locator.

Parameters

locator – the locator to find a reference by.
required – forces to raise an error if no reference is found.

Returns

a list with matching component references.

Raises

a ReferenceException when __required is set to true but no references found.

get_all() → List[Any]

Gets all component references registered in this reference map.

Returns: a list with component references.

get_all_locators() → List[Any]

Gets locators for all registered component references in this reference map.

Returns: a list with component locators.

get_one_before(reference, locator)

get_one_optional(locator: Any) → Any

Gets an optional component reference that matches specified locator.

Parameters: locator – the locator to find references by.
Returns: a matching component reference or null if nothing was found.

get_one_required(locator: Any) → Any

Gets a __required component reference that matches specified locator.

Parameters: locator – the locator to find a reference by.
Returns: a matching component reference.
Raises: a ReferenceException when no references found.

get_optional(locator: Any) → List[Any]

Gets all component references that match specified locator.

Parameters: locator – the locator to find references by.
Returns: a list with matching component references or empty list if nothing was found.

get_required(locator: Any) → List[Any]

Gets all component references that match specified locator. At least one component reference must be present. If it doesn’t the method throws an error.

Parameters: locator – the locator to find references by.
Returns: a list with matching component references.
Raises: a ReferenceException when no references found.

put(locator: Any = None, reference: Any = None)

Puts a new reference into this reference map.

Parameters

locator – a component reference to be added.
reference – a locator to find the reference by.

remove(locator: Any) → Any

Removes a previously added reference that matches specified locator. If many references match the locator, it removes only the first one. When all references shall be removed, use :func:remove_all method instead.

Parameters: locator – a locator to remove reference
Returns: the removed component reference.

remove_all(locator: Any) → List[Any]

Removes all component references that match the specified locator.

Parameters: locator – a locator to remove reference
Returns: a list, containing all removed references.

class pip_services3_commons.refer.IUnreferenceable

Bases: abc.ABC

Interface for components that require explicit clearing of references to dependent components.

Example:

class MyController(IReferenceable):
    _persistence = None

    def set_references(self, references):
        self._persistence = references.getOneRequired(Descriptor("mygroup", "persistence", "*", "*", "1.0"))

    def unset_references(self):
        self._persistence = None

unset_references(): Unsets (clears) previously set references to dependent components.

class pip_services3_commons.refer.Reference(locator: Any, component: Any)

Bases: object

Contains a reference to a component and locator to find it. It is used by References to store registered component references.

get_component() → Any

Gets the stored component reference.

Returns: the component’s references.

get_locator() → Any

Gets the stored component locator.

Returns: the component’s locator.

match(locator: Any) → bool 

Matches locator to this reference locator. Descriptors are matched using equal method. All obj locator types are matched using direct comparison.

Parameters: locator – the locator to match.
Returns: true if locators are matching and false it they don’t.

exception pip_services3_commons.refer.ReferenceException(correlation_id: Optional[str, None] = None, locator: Any = None)

Bases: pip_services3_commons.errors.InternalException.InternalException

Error when __required component dependency cannot be found.

class pip_services3_commons.refer.Referencer

Bases: object

Helper class that sets and unsets references to components.

static set_references(references: pip_services3_commons.refer.IReferences.IReferences, components: List[Any])

Sets references to multiple components.

To set references components must implement IReferenceable interface. If they don’t the call to this method has no effect.

Parameters

references – the references to be set.
components – a list of components to set the references to.

static set_references_for_one(references: pip_services3_commons.refer.IReferences.IReferences, component: Any)

Sets references to specific component.

To set references components must implement IReferenceable interface. If they don’t the call to this method has no effect.

Parameters

references – the references to be set.
component – the component to set references to.

static unset_references(components: List[Any])

Unsets references in multiple components.

To unset references components must implement IUnreferenceable interface. If they don’t the call to this method has no effect.

Parameters: components – the list of components, whose references must be cleared.

static unset_references_for_one(component: Any)

Unsets references in specific component.

To unset references components must implement IUnreferenceable interface. If they don’t the call to this method has no effect.

Parameters: component – the component to unset references.

class pip_services3_commons.refer.References(tuples: Sequence[Any] = None)

Bases: pip_services3_commons.refer.IReferences.IReferences

The most basic implementation of IReferences to store and locate component references.

Example:

class MyController(IReferenceable):
    _persistence = None

    def set_references(self, references):
        self._persistence = references.getOneRequired(Descriptor("mygroup", "persistence", "*", "*", "1.0"))

persistence = MyMongoDbPersistence()

references = References.from_tuples(
Descriptor("mygroup", "persistence", "mongodb", "default", "1.0"), persistence,
Descriptor("mygroup", "controller", "default", "default", "1.0"), controller)

controller.set_references(references)

find(locator: Any, required: bool) → List[Any]

Gets all component references that match specified locator.

Parameters

locator – the locator to find a reference by.
required – forces to raise an error if no reference is found.

Returns

a list with matching component references.

Raises

a ReferenceException when __required is set to true but no references found.

static from_tuples(*tuples: Any) → pip_services3_commons.refer.References.References 

Creates a new References from a list of key-args pairs called tuples.

Parameters: tuples – a list of values where odd elements are locators and the following even elements are component references
Returns: a newly created References.

get_all() → List[Any]

Gets all component references registered in this reference map.

Returns: a list with component references.

get_all_locators() → List[Any]

Gets locators for all registered component references in this reference map.

Returns: a list with component locators.

get_one_optional(locator: Any) → Any

Gets an optional component reference that matches specified locator.

Parameters: locator – the locator to find references by.
Returns: a matching component reference or null if nothing was found.

get_one_required(locator: Any) → Any

Gets a __required component reference that matches specified locator.

Parameters: locator – the locator to find a reference by.
Returns: a matching component reference.
Raises: a ReferenceException when no references found.

get_optional(locator: Any) → List[Any]

Gets all component references that match specified locator.

Parameters: locator – the locator to find references by.
Returns: a list with matching component references or empty list if nothing was found.

get_required(locator: Any) → List[Any]

Gets all component references that match specified locator. At least one component reference must be present. If it doesn’t the method throws an error.

Parameters: locator – the locator to find references by.
Returns: a list with matching component references.
Raises: a ReferenceException when no references found.

put(locator: Any = None, component: Any = None)

Puts a new reference into this reference map.

Parameters

locator – a component reference to be added.
component – a locator to find the reference by.

remove(locator: Any) → Any

Removes a previously added reference that matches specified locator. If many references match the locator, it removes only the first one. When all references shall be removed, use remove_all() method instead.

Parameters: locator – a locator to remove reference
Returns: the removed component reference.

remove_all(locator: Any) → List[Any]

Removes all component references that match the specified locator.

Parameters: locator – a locator to remove reference by.
Returns: a list, containing all removed references.

pip_services3_commons.refer package

Submodules

Module contents

pip_services3_commons.refer.__init__

pip_services3_commons.refer.init