adctk.factory.Factory Class Reference

factory for adctk api objects. More...

Public Member Functions
	__init__ (self)

Static Public Member Functions
builder.Builder	get_builder ()
	Create an empty builder object or subobject for an adctk message.
list[str]	get_publisher_names ()
	Get the names of publishers available.
publisher.Publisher|None	get_publisher (str name, dict[str] options=None)
	Get a configured instance of the named publisher type.
publisher.MultiPublisher	get_multi_publisher (strict=False, str|list[str]|dict|None plugins=None)
	Get a MultiPublisher for use or manually populating.

Static Public Attributes
	API_VERSION = adc_version.AdcVersion()._dict()

Static Protected Attributes
dict	_publishers = {}

Detailed Description

factory for adctk api objects.

Constructor & Destructor Documentation

__init__()

adctk.factory.Factory.__init__

(

self

)

    def __init__(self):
        pass # Factory.__init__ nothing to do

Member Function Documentation

get_builder()

builder.Builder adctk.factory.Factory.get_builder ( )

static

Create an empty builder object or subobject for an adctk message.

Returns

an empty message builder object

    def get_builder() -> builder.Builder:
        """! @brief Create an empty builder object or subobject for an adctk message.
 
            @return an empty message builder object"""
        return builder.Builder()
 

get_multi_publisher()

publisher.MultiPublisher adctk.factory.Factory.get_multi_publisher (   strict = False, str|list[str]|dict|None   plugins = None  )

static

Get a MultiPublisher for use or manually populating.

MultiPublisher provides a convenient way to publish on multiple publishers without duplicate calls to a publish() function. Options:

Parameters

strict

If strict=True, a failure to construct any named publisher will return None instead of a multipublisher, otherwise failed or unknown publishers will be silently ignored.

plugins

can be one of: None, which then constructs plugins using the name list from env("ADC_MULTI_PUBLISHER_NAMES") and their environment-defined or default options. If ADC_MULTI_PUBLISHER_NAMES is unset, an empty MultiPublisher ready to configure is returned. A string naming an alternative environment variable to ADC_MULTI_PUBLISHER_NAMES. E.g. a library foo may use FOO_MULTI_PUBLISHER_NAMES. A list of names from among those returned by get_publisher_names, where each named plugin is configured from environment-defined or default options. An empty list is treated as None. A dictionary of dictionaries, where the top keys are plugin names and the dictionary values are as documented in each plugin.

Empty example: add individual configured publisher to result. mp = get_multi_publisher() mp.add(...)

From environment ADC_MULTI_PUBLISHER_NAMES example m1 = get_multi_publisher(plugins=[]) m1.add(...)

From environment MY_APP_MULTI_PUBLISHER_NAMES example m1 = get_multi_publisher(plugins="MY_APP_MULTI_PUBLISHER_NAMES") m1.add(...)

Configure several plugins using environment m2 = get_multi_publisher(plugins=["stdout","http"])

Configure several plugins using environment and option overrides m3 = get_multi_publisher(plugins={"stdout":{}, "http":{"port": "8443", "url": "localhost"}})

        plugins: str|list[str]|dict|None =None) -> publisher.MultiPublisher:
        """! Get a MultiPublisher for use or manually populating.
 
            MultiPublisher provides a convenient way to publish on multiple
            publishers without duplicate calls to a publish() function.
            Options:
 
            @param strict If strict=True, a failure to construct any named
            publisher will return None instead of a multipublisher, otherwise
            failed or unknown publishers will be silently ignored.
 
            @param plugins can be one of:
            - None, which then constructs plugins using the name list from
              env("ADC_MULTI_PUBLISHER_NAMES") and their environment-defined
              or default options.
              If ADC_MULTI_PUBLISHER_NAMES is unset, an empty MultiPublisher ready
              to configure is returned.
            - A string naming an alternative environment variable to ADC_MULTI_PUBLISHER_NAMES.
                E.g. a library foo may use FOO_MULTI_PUBLISHER_NAMES.
            - A list of names from among those returned by get_publisher_names,
              where each named plugin is configured from environment-defined or
              default options. An empty list is treated as None.
            - A dictionary of dictionaries, where the top keys are plugin names and
              the dictionary values are as documented in each plugin.
 
          Empty example: add individual configured publisher to result.
            mp = get_multi_publisher()
            mp.add(...)
 
          From environment ADC_MULTI_PUBLISHER_NAMES example
            m1 = get_multi_publisher(plugins=[])
            m1.add(...)
 
          From environment MY_APP_MULTI_PUBLISHER_NAMES example
            m1 = get_multi_publisher(plugins="MY_APP_MULTI_PUBLISHER_NAMES")
            m1.add(...)
 
          Configure several plugins using environment
            m2 = get_multi_publisher(plugins=["stdout","http"])
 
          Configure several plugins using environment and option overrides
            m3 = get_multi_publisher(plugins={"stdout":{},
                                              "http":{"port": "8443", "url": "localhost"}})
 
        """
        return publisher.MultiPublisher(strict, plugins)
 

get_publisher()

publisher.Publisher|None adctk.factory.Factory.get_publisher ( str  name, dict[str]   options = None  )

static

Get a configured instance of the named publisher type.

Parameters

name	one of the elements found with get_publisher_names().
options	a map of option names and their values; plugins will silently ignore unused options. publisher.config(options) and initialize will be called unless options is None. To apply a default configuration, give the empty {} instead of None.

Returns

a publisher instance, or None if the name is unavailable.

    def get_publisher(name: str, options: dict[str] =None) -> publisher.Publisher|None:
        """! Get a configured instance of the named publisher type.
 
            @param name one of the elements found with get_publisher_names().
            @param options a map of option names and their values; plugins will
                silently ignore unused options. publisher.config(options)
                and initialize will be called unless options is None.
                To apply a default configuration, give the empty {} instead of None.
            @return a publisher instance, or None if the name is unavailable.
        """
        if name in Factory.get_publisher_names():
            x = Factory._publishers[name]()
            if x:
                if not options:
                    return x
                x.config(options)
                x.initialize()
                return x
        if not isinstance(name, str):
            raise ValueError(f"get_publisher expects a string name: got {name}")
        return None
 

get_publisher_names()

list[str] adctk.factory.Factory.get_publisher_names ( )

static

Get the names of publishers available.

Returns

the names of publishers available. The "none", "stdout", "file", "multifile", "syslog", and "script" publishers are always available in Linux environments.

    def get_publisher_names() -> list[str]:
        """! @brief Get the names of publishers available.
 
            @return the names of publishers available.
        The "none", "stdout", "file", "multifile", "syslog", and "script" publishers
        are always available in Linux environments.
        """
        if not Factory._publishers:
            for cls in _get_subclasses(publisher.Publisher):
                Factory._publishers[cls._name] = cls
        return Factory._publishers.keys()
 

Member Data Documentation

_publishers

dict adctk.factory.Factory._publishers = {}

staticprotected

API_VERSION

adctk.factory.Factory.API_VERSION = adc_version.AdcVersion()._dict()

static

---

The documentation for this class was generated from the following file:

• src/adctk/factory.py