Inheritance diagram for adctk.publisher.Publisher:

[legend]

Classes
class	Mode
	For plugins managing external resources (files, pipes), this enum is used to track where in the lifecycle they are. More...

class	State
	For plugins where the output target becomes unrecoverable, state == ERR means no further output will be attempted. More...

Public Member Functions
	__init__ (self)

str	name (self)
	Get the name which a factory or error message should use.

str	version (self)

dict[str, str]	get_option_defaults (self)

int	config (self, **kwargs)
	Configure the plugin with the options given.

int	initialize (self)
	Set up any resources needed for reuse in publish().

int	publish (self, builder.Builder b)
	Publish json extracted from builder.

None	finalize (self)
	Clean up any resources set up in initialize (files, pipes, etc).

None	pause (self)
	Cause publish calls to be ignored until resume is called.

None	resume (self)
	Cancel an prior calls to pause.

int	publish_str (self, str json_string)

int	publish_obj (self, obj)

Static Public Member Functions
tuple[float]	get_timeout_defaults ()
	Get the adc server connect and response timeouts defined in the environment ADC_SERVER_CONNECT_TIMEOUT and ADC_SERVER_POST_TIMEOUT as a tuple or default values if not defined.

str	get_url_default ()
	Get the alleged adc server url base from environment ADC_SERVER_URL or the default if it is not present.

str	get_port_default ()
	Get the adc server port number to use if it is properly defined in the environment ADC_SERVER_PORT or the default if it is not.

Public Attributes
	defaults

	plugin_prefix

	paused

	state

	mode

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

Protected Member Functions
str	_get (self, dict[str, str] opts, str field)

bool	_get_bool (self, dict[str, str] opts, str field)

Static Protected Attributes
str	_name = "unknown"

str	_version = "0.0.0"

Detailed Description

 The API for various implementations which publish Builder objects.
    Subclasses need to implement __init__, config, initialize, publish, finalize only.
    In subclass __init__, data items
        self.defaults: dict[str,str]
        self.plugin_prefix: str
    need to be set for the plugin.
    In each subclass, data members
        _name: str
        _version: str
    need to be reassigned.
Particularly simple subclasses may not need to use data items: state, mode.

@ingroup pub_impl

Constructor & Destructor Documentation

◆ init()

adctk.publisher.Publisher.__init__ ( self )

Reimplemented in adctk.file_publisher.FilePublisher, adctk.http_publisher.HttpPublisher, adctk.ldms_publisher.LDMSPipePublisher, adctk.ldms_publisher.LDMSSystemPublisher, adctk.ldms_publisher.LDMSPipeMessagePublisher, adctk.ldms_publisher.LDMSSystemMessagePublisher, adctk.multifile_publisher.MultiFilePublisher, adctk.none_publisher.NonePublisher, adctk.stdout_publisher.StdoutPublisher, adctk.syslog_publisher.SyslogPublisher, and adctk.debug_file_publisher.DebugFilePublisher.

    def __init__(self):
        self.defaults = None
        self.plugin_prefix = None
        self.paused = False
        self.state = Publisher.State.OK
        self.mode = Publisher.Mode.CONFIG
 

Member Function Documentation

◆ _get()

str adctk.publisher.Publisher._get	(		self,
		dict[str,str]	opts,
		str	field
	)

protected

 Check for short option named by field in opts and return if present.
    (In most cases the short name is in all capitals.)
    When named field is not present, use opts[env_prefix]
    (or if opts[env_prefix] is not present, then self.plugin_prefix)
    to search for env(prefix+field) and return that value if present.
    If no environment value found, return self.defaults[field].

    def _get(self, opts: dict[str,str], field: str) -> str:
        """ Check for short option named by field in opts and return if present.
            (In most cases the short name is in all capitals.)
            When named field is not present, use opts[env_prefix]
            (or if opts[env_prefix] is not present, then self.plugin_prefix)
            to search for env(prefix+field) and return that value if present.
            If no environment value found, return self.defaults[field]."""
        if field in opts:
            return opts[field]
        if "env_prefix" in opts:
            prefix = opts["env_prefix"]
        else:
            prefix = self.plugin_prefix
        env_name = prefix + field
        env_val = os.getenv(env_name)
        if not env_val:
            return self.defaults[field]
        return env_val
 

◆ _get_bool()

bool adctk.publisher.Publisher._get_bool	(		self,
		dict[str,str]	opts,
		str	field
	)

protected

    def _get_bool(self, opts: dict[str,str], field: str) -> bool:
        s = self._get(opts, field)
        if s in ["TRUE", "true", "True", "1", "t", "T", "y", "Yes", "YES"]:
            return True
        return False
 

◆ config()

int adctk.publisher.Publisher.config	(		self,
		**	kwargs
	)

Configure the plugin with the options given.

For plugin QQQ, Environment variables ADC_QQQ_PLUGIN_<key> will override the plugin default for any key not defined in kwargs. Here QQQ is plugin.name().upper(). Generic options:

Parameters

kwargs	If env_prefix is included in kwargs, replaces plugin environment variables with those which are prefixed using env_prefix.
env_prefix	Typically, env_prefix is set to "PPP_ADC_QQQ_PLUGIN_" if application PPP wants to override the defaults of adctk plugin QQQ. Here QQQ is plugin.name().upper(). If no prefixed version of the variable is present, the plugin default is used. kwargs takes precedence over environment variables. Plugin defaults are used if not overridden by kwargs or an environment variable.

Returns: int non-zero if configuration cannot be completed using the arguments, environment, and default.

Reimplemented in adctk.debug_file_publisher.DebugFilePublisher, adctk.file_publisher.FilePublisher, adctk.http_publisher.HttpPublisher, adctk.ldms_publisher.LDMSPipePublisher, adctk.ldms_publisher.LDMSSystemPublisher, adctk.ldms_publisher.LDMSPipeMessagePublisher, adctk.ldms_publisher.LDMSSystemMessagePublisher, adctk.multifile_publisher.MultiFilePublisher, adctk.none_publisher.NonePublisher, adctk.stdout_publisher.StdoutPublisher, and adctk.syslog_publisher.SyslogPublisher.

    def config(self, **kwargs) -> int:
        """! @brief Configure the plugin with the options given.
        For plugin QQQ, Environment variables ADC_QQQ_PLUGIN_<key> will override the plugin
        default for any key not defined in kwargs. Here QQQ is plugin.name().upper().
        Generic options:
 
        @param kwargs If env_prefix is included in kwargs, replaces plugin environment variables
        with those which are prefixed using env_prefix.
 
        @param env_prefix Typically, env_prefix is set to "PPP_ADC_QQQ_PLUGIN_" if application PPP wants to
        override the defaults of adctk plugin QQQ. Here QQQ is plugin.name().upper().
        If no prefixed version of the variable is present, the plugin default is used.
        kwargs takes precedence over environment variables. Plugin defaults are used
        if not overridden by kwargs or an environment variable.
 
        @return int non-zero if configuration cannot be completed using the arguments,
        environment, and default.
        """
        raise NotImplementedError("Publisher.config not implemented")
 

◆ finalize()

None adctk.publisher.Publisher.finalize ( self )

Clean up any resources set up in initialize (files, pipes, etc).

Reimplemented in adctk.debug_file_publisher.DebugFilePublisher, adctk.file_publisher.FilePublisher, adctk.http_publisher.HttpPublisher, adctk.ldms_publisher.LDMSPipePublisher, adctk.ldms_publisher.LDMSPipeMessagePublisher, adctk.multifile_publisher.MultiFilePublisher, adctk.none_publisher.NonePublisher, adctk.stdout_publisher.StdoutPublisher, and adctk.syslog_publisher.SyslogPublisher.

    def finalize(self) -> None:
        """! Clean up any resources set up in initialize (files, pipes, etc)."""
        raise NotImplementedError("Publisher.finalize not implemented")
 

◆ get_option_defaults()

dict[str,str] adctk.publisher.Publisher.get_option_defaults ( self )

Returns: modifiable copy of publisher option defaults

    def get_option_defaults(self) -> dict[str,str]:
        """! @return modifiable copy of publisher option defaults"""
        return copy.deepcopy(self.defaults)
 

◆ get_port_default()

str adctk.publisher.Publisher.get_port_default ( )

static

Get the adc server port number to use if it is properly defined in the environment ADC_SERVER_PORT or the default if it is not.

    def get_port_default() -> str:
        """! Get the adc server port number to use if it is properly
        defined in the environment ADC_SERVER_PORT or the default
        if it is not."""
        env_name = _ENV_PREFIX + "PORT"
        env_val = os.getenv(env_name)
        if not env_val:
            return _PORT_DEFAULT
        try:
            i = int(env_val)
        except ValueError:
            i = int(_PORT_DEFAULT)
        return str(i)
 

◆ get_timeout_defaults()

tuple[float] adctk.publisher.Publisher.get_timeout_defaults ( )

static

Get the adc server connect and response timeouts defined in the environment ADC_SERVER_CONNECT_TIMEOUT and ADC_SERVER_POST_TIMEOUT as a tuple or default values if not defined.

    def get_timeout_defaults() -> tuple[float]:
        """! Get the adc server connect and response timeouts
        defined in the environment ADC_SERVER_CONNECT_TIMEOUT and
        ADC_SERVER_POST_TIMEOUT as a tuple or default values if not
        defined.
        """
        env_name = _ENV_PREFIX + "CONNECT_TIMEOUT"
        env_val = os.getenv(env_name)
        if env_val:
            try:
                ct = float(env_val)
            except ValueError:
                log.logger.error("adctk.Publisher.get_timeout_defaults: unable to "\
                        "convert %s to float from %s", env_val, env_name)
        else:
            ct = _CONNECT_TIMEOUT_DEFAULT
        env_name = _ENV_PREFIX + "POST_TIMEOUT"
        env_val = os.getenv(env_name)
        if env_val:
            try:
                pt = float(env_val)
            except ValueError:
                log.logger.error("adctk.Publisher.get_timeout_defaults: unable to "\
                        "convert %s to float from %s", env_val, env_name)
        else:
            pt = _POST_TIMEOUT_DEFAULT
        return (ct, pt)
 

◆ get_url_default()

str adctk.publisher.Publisher.get_url_default ( )

static

Get the alleged adc server url base from environment ADC_SERVER_URL or the default if it is not present.

    def get_url_default() -> str:
        """! Get the alleged adc server url base from environment ADC_SERVER_URL
        or the default if it is not present."""
        env_name = _ENV_PREFIX + "URL"
        env_val = os.getenv(env_name)
        if not env_val:
            return _SERVER_DEFAULT
        return env_val
 

◆ initialize()

int adctk.publisher.Publisher.initialize ( self )

Set up any resources needed for reuse in publish().

Reimplemented in adctk.debug_file_publisher.DebugFilePublisher, adctk.file_publisher.FilePublisher, adctk.http_publisher.HttpPublisher, adctk.ldms_publisher.LDMSPipePublisher, adctk.ldms_publisher.LDMSPipeMessagePublisher, adctk.multifile_publisher.MultiFilePublisher, adctk.none_publisher.NonePublisher, adctk.stdout_publisher.StdoutPublisher, and adctk.syslog_publisher.SyslogPublisher.

    def initialize(self) -> int:
        """! Set up any resources needed for reuse in publish()."""
        raise NotImplementedError("Publisher.initialize not implemented")
 

◆ name()

str adctk.publisher.Publisher.name ( self )

Get the name which a factory or error message should use.

    def name(self) ->str:
        """! Get the name which a factory or error message should use."""
        return self._name
 

◆ pause()

None adctk.publisher.Publisher.pause ( self )

Cause publish calls to be ignored until resume is called.

    def pause(self) -> None:
        """! Cause publish calls to be ignored until resume is called."""
        self.paused = True
 

◆ publish()

int adctk.publisher.Publisher.publish	(		self,
		builder.Builder	b
	)

Publish json extracted from builder.

Reimplemented in adctk.http_publisher.HttpPublisher, adctk.debug_file_publisher.DebugFilePublisher, adctk.file_publisher.FilePublisher, adctk.ldms_publisher.LDMSPipePublisher, adctk.ldms_publisher.LDMSPipeMessagePublisher, adctk.multifile_publisher.MultiFilePublisher, adctk.none_publisher.NonePublisher, adctk.stdout_publisher.StdoutPublisher, and adctk.syslog_publisher.SyslogPublisher.

    def publish(self, b: builder.Builder) -> int:
        """! Publish json extracted from builder"""
        raise NotImplementedError("Publisher.publish not implemented")
 

◆ publish_obj()

int adctk.publisher.Publisher.publish_obj	(	self,
		obj
	)

 Deprecated function. Call publish_str with the result of json.dumps(obj), if possible.
Returns EINVAL when dumps fails.
Use of this method is discouraged

Reimplemented in adctk.debug_file_publisher.DebugFilePublisher, and adctk.http_publisher.HttpPublisher.

    def publish_obj(self, obj) -> int:
        """ Deprecated function. Call publish_str with the result of json.dumps(obj), if possible.
        Returns EINVAL when dumps fails.
        Use of this method is discouraged"""
        try:
            js = json.dumps(obj)
            return self.publish_str(js)
        except TypeError:
            return errno.EINVAL
        return 0
 

◆ publish_str()

int adctk.publisher.Publisher.publish_str	(		self,
		str	json_string
	)

 Deprecated function; prefer publish() Publish json string supplied by user,
by creating a Builder and
defining the application block to contain the string given as a single
field. Use of this method is discouraged, as it hides important
datatype information from downstream consumers and it must generate
an application name.

Reimplemented in adctk.debug_file_publisher.DebugFilePublisher, and adctk.http_publisher.HttpPublisher.

    def publish_str(self, json_string: str) -> int:
        """ Deprecated function; prefer publish() Publish json string supplied by user,
        by creating a Builder and
        defining the application block to contain the string given as a single
        field. Use of this method is discouraged, as it hides important
        datatype information from downstream consumers and it must generate
        an application name."""
        from . import factory # break import loop
        if json_string is None:
            return errno.ENODATA
        af = factory.Factory()
        b = af.get_builder()
        # make header
        app = f"{getpass.getuser()}.publish_str"
        b.add_header_section(app)
        # make 'application' section
        ads = factory.Factory.get_builder()
        ads.add_json_string("payload", json_string)
        ads.add("argv", sys.argv)
        b.add_app_data_section(ads)
        # send the composed message
        self.publish(builder)
        return 0
 

◆ resume()

None adctk.publisher.Publisher.resume ( self )

Cancel an prior calls to pause.

    def resume(self) -> None:
        """! Cancel an prior calls to pause."""
        self.paused = False
 

◆ version()

str adctk.publisher.Publisher.version ( self )

Returns: publisher version

    def version(self) ->str:
        """! @return publisher version"""
        return self._version
 

Member Data Documentation

◆ _name

str adctk.publisher.Publisher._name = "unknown"

staticprotected

◆ _version

str adctk.publisher.Publisher._version = "0.0.0"

staticprotected

◆ API_VERSION

adctk.publisher.Publisher.API_VERSION = adc_version.AdcVersion()._dict()

static

◆ defaults

adctk.publisher.Publisher.defaults

◆ mode

adctk.publisher.Publisher.mode

◆ paused

adctk.publisher.Publisher.paused

◆ plugin_prefix

adctk.publisher.Publisher.plugin_prefix

◆ state

adctk.publisher.Publisher.state

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

src/adctk/publisher.py

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ _get()

◆ _get_bool()

◆ config()

◆ finalize()

◆ get_option_defaults()

◆ get_port_default()

◆ get_timeout_defaults()

◆ get_url_default()

◆ initialize()

◆ name()

◆ pause()

◆ publish()

◆ publish_obj()

◆ publish_str()

◆ resume()

◆ version()

Member Data Documentation

◆ _name

◆ _version

◆ API_VERSION

◆ defaults

◆ mode

◆ paused

◆ plugin_prefix

◆ state

◆ init()