hio.base.hier.hogging

hio.base.hier.hogging Module

Provides support for hold logging (hogging)

Module Contents

class hio.base.hier.hogging.Hog(iops=None, nabe=Nabes.afdo, base='', filed=True, extensioned=True, mode='a+', fext='hog', reuse=True, rid=None, rule=Rules.every, span=0.0, flushSpan=60.0, flushForce=False, cycleCount=0, cycleSpan=0.0, cycleSize=0, hits=None, **kwa)

Bases: hio.base.hier.acting.ActBase, hio.base.filing.Filer

Hog is Act that supports metrical logging of hold items based on logging rules such as time period, update, or change.

Act comes before Filer in .__mro__ so Act.name property is used not Filer.name

Inherited Class Attributes:

Registry (dict): subclass registry whose items are (name, cls) where:
        name is unique name for subclass
        cls is reference to class object
Instances (dict): instance registry whose items are (name, instance) where:
        name is unique instance name and instance is instance reference
Index (int): default naming index for subclass instances. Each subclass
        overrides with a subclass specific Index value to track
        subclass specific instance default names.

HeadDirPath (str): default abs dir path head such as "/usr/local/var"
TailDirPath (str): default rel dir path tail when using head
CleanTailDirPath (str): default rel dir path tail when creating clean
AltHeadDirPath (str): default alt dir path head such as "~"; fallback when desired head not permitted.
AltTailDirPath (str): default alt rel dir path tail as fallback when using alt head.
AltCleanTailDirPath (str): default alt rel path tail when creating clean
TempHeadDir (str): default temp abs dir path head such as "/tmp"
TempPrefix (str): default rel dir path prefix when using temp head
TempSuffix (str): default rel dir path suffix when using temp head and tail
Perm (int): explicit default octal perms such as 0o1700
Mode (str): open mode such as "r+"
Fext (str): default file extension such as "text" for "fname.text"

Class Attributes:

ReservedTags (dict[str]): reserved tags that prevent collisions with defined parameter names; these may not be used for log tags when using **kwa to provide hold log keys. Uses dict because inclusion test is faster than list.

Inherited Attributes (see Act, File):

hold (Hold): data shared by boxwork

name (str): overridden by .name property from Act (see name property) base (str): another unique path component inserted before name temp (bool): True means use TempHeadDir in /tmp directory headDirPath (str): head directory path path (str | None): full directory or file path once created else None perm (int): octal OS permissions for path directory and/or file filed (bool): True means .path ends in file; False means .path ends in directory extensioned (bool): When not filed, True means ensure .path ends with fext; False means do not ensure .path ends with fext mode (str): file open mode if filed fext (str): file extension if filed file (File | None): File instance when filed and created. opened (bool): True means directory is created and, if filed, file is opened; False otherwise

Inherited Properties (see Act, File):

name (str): unique instance name used for registering Act instance in Act registry and providing a unique path component in file path name iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act

Attributes:

started (bool): True means logging has begun with header
                False means logging has not yet begun needs header
first (float|None): tyme when began logging, None means not yet running
last (float|None): tyme when last logged, None means not yet running
    realtime equiv of last = began + (last - first)
rule (str): condition for log to fire one of Rules
            (once, every, span, update, change)
span (float): tyme span seconds for periodic logging 0.0 means every tyme
onced (bool): True means logged at least one (first) record
              False means not yet logged one (first) record
header (str): header for log file(s)
rid (str):  universally unique run ID for given run of hog
flushSpan (float): tyme span seconds between flushes (flush)
                   0.0 means every tyme
flushForce (bool): True means force flush on every log
    False means only flush at appropriate times
flushLast (float|None): tyme last flushed, None means not yet running
cycleCount (int): number of cycled logs, 0 means do not cycle (count)
cyclePeriod (float): min tyme span for cycling logs (cycle). 0.0 means
    cycle based on cycleHigh not tyme span. One of cycleSpan or
    cycleHigh must be non zero
cycleSize (int): maximum size in bytes allowed for each cycled log
    0 means no maximum. One of cycleSpan or cycleHigh must be non zero
cyclePaths (list[str]): paths for cycled logs
cycleLast (float|None): tyme last cycled. None means not yet running
hits (dict): hold items to log. Item label is log header tag
    Item value is hold key that provides value to log
marks (dict): tyme or value tuples marks of hold items logged with
    updated or changed rule. Label is hold key.
activeKey (str|None): hold key to active box name of boxer given by iops
    None otherwise
tockKey (str|None): hold key to tock value of boxer given by iops
    None otherwise
tymeKey (str|None): hold key to tyme value of boxer given by iops
    None otherwise

Hidden:

_name (str): unique name of instance for .name property
_iopts (dict): input-output-parameters for .act for .iops property
_nabe (str): action nabe (context) for .act for .nabe property

As ActBase subclass that is managed inside boxwork, the Hog is created and inited by Boxer.make which is run in the enter context of the BoxerDoer. So opening file during init is compatible as its in the enter context of the its Doer even though its not in the endo context of its box. It still needs to be closed. Unlike the hold subery the Boxer doesn’t know about any Hogs running as acts inside its boxes so can’t close in its BoxerDoer exit context. So must be closed inside with a close do act

Since filed it should reopen without truncating so does not overwrite existing log file of same name so uses mode = ‘a+’. Need to test reopen logic Always rewrites header on first log after restart which may have changed log behavior so header demarcation enables recognition of log parameters. Log header includes rid (unique run id) and datetime stamp so can always uniquely match a given run data to header even when reusing same log file. This is most important when rotating logs. Because each individual log record after header always starts with tyme as floating point decimal, processor can find header demarcations interior to log file not merely at start.

act(**iops)

Act called by ActBase.

Parameters:

iops (dict) – input/output parameters, same as self.iops. Puts **iops in local scope in case act compiles exec/eval str

When made by boxer.do then have “_boxer” and “_box” keys in self.iops

iops = dict(_boxer=self.name, _box=m.box.name, **iops)

log(record, tyme, force=False)

Write one record to file and flush when indicated

Parameters:

record (str):  one line of tab delimited newline ended values
tyme (float):  tyme of log record
force (bool): True means force flush even when not flushSpan elapsed
              False means do not force flush only if flushSpan elapsed

record()

Generate one record line from .hits values from .hold

Returns:

record (str): one newline delimited line of tab delimited values
           from .hits. Each hit time value is key into hold
           vector holds each get entry in record per field

cycle(tyme)

Cycle log files

Parameters:

tyme (float): current tyme of cycle

hio.base.hier.hogging.openHog(cls=None, name=None, temp=True, reopen=True, clear=False, **kwa)

Context manager wrapper Hog instances for managing a filesystem directory and or files in a directory.

Defaults to using temporary directory path. Context ‘with’ statements call .close on exit of ‘with’ block

Parameters:

cls is Class instance of subclass instance
name is str name of Filer instance path part so can have multiple Filers
     at different paths that each use different dirs or files
temp is Boolean, True means open in temporary directory, clear on close
        Otherwise open in persistent directory, do not clear on close
reopen (bool): True (re)open with this init
                   False not (re)open with this init but later (default)
clear (bool): True means remove directory upon close when reopening
                  False means do not remove directory upon close when reopening

See hogging.Hog for other keyword parameter passthroughs

Usage:

with openHog(name="bob") as hog:

with openHog(name="eve", cls=HogSubClass) as hog:

class hio.base.hier.hogging.HogDoer(hog, **kwa)

Bases: hio.base.doing.Doer

Basic Hog Doer

Attributes:

done (bool): completion state:
    True means completed
    Otherwise incomplete. Incompletion maybe due to close or abort.
hog (Hog): instance

Properties:

tyme (float): relative cycle time of associated Tymist .tyme obtained
    via injected .tymth function wrapper closure.
tymth (func): closure returned by Tymist .tymeth() method.
    When .tymth is called it returns associated Tymist .tyme.
    .tymth provides injected dependency on Tymist tyme base.
tock (float)): desired time in seconds between runs or until next run,
         non negative, zero means run asap

enter(*, temp=None)

Do ‘enter’ context actions. Override in subclass. Not a generator method. Set up resources. Comparable to context manager enter.

Parameters:

temp (bool | None): True means use temporary file resources if any
                    None means ignore parameter value. Use self.temp

Inject temp or self.temp into file resources here if any

exit()

Do ‘exit’ context actions. Override in subclass. Not a generator method. Clean up resources. Comparable to context manager exit. Called by finally after normal return, close, or abort. After .exit() do returns resulting in StopIteration.