hio.base.hier.hogging ===================== .. py:module:: hio.base.hier.hogging .. autoapi-nested-parse:: hio.base.hier.hogging Module Provides support for hold logging (hogging) Module Contents --------------- .. py:class:: 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: :py:obj:`hio.base.hier.acting.ActBase`, :py:obj:`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. .. py:method:: act(**iops) Act called by ActBase. :param iops: input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str :type iops: dict When made by boxer.do then have "_boxer" and "_box" keys in self.iops iops = ``dict(_boxer=self.name, _box=m.box.name, **iops)`` .. py:method:: 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 .. py:method:: 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 .. py:method:: cycle(tyme) Cycle log files Parameters:: tyme (float): current tyme of cycle .. py:function:: 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: .. py:class:: HogDoer(hog, **kwa) Bases: :py:obj:`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 .. py:method:: 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 .. py:method:: 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.