hio.base.filing =============== .. py:module:: hio.base.filing .. autoapi-nested-parse:: hio.base.filing module Module Contents --------------- .. py:class:: Filer(*, name='main', base='', temp=False, headDirPath=None, perm=None, reopen=True, clear=False, reuse=False, clean=False, filed=False, extensioned=False, mode=None, fext=None, **kwa) Bases: :py:obj:`hio.hioing.Mixin` Filer instances manage file directories and files to hold keri installation specific resources like databases and configuration files. Class Attributes: 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). AltTailDirPath (str): default alt rel dir path tail (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" .. attribute:: base another unique path component inserted before name :type: str .. attribute:: temp True means use TempHeadDir in /tmp directory :type: bool .. attribute:: headDirPath head directory path :type: str .. attribute:: path full directory or file path once created else None :type: str | None .. attribute:: perm octal OS permissions for path directory and/or file :type: int .. attribute:: filed True means .path ends in file. False means .path ends in directory :type: bool .. attribute:: extensioned When not filed, True means ensure .path ends with fext. :type: bool .. attribute:: mode file open mode if filed :type: str .. attribute:: fext file extension if filed :type: str .. attribute:: file File instance when filed and created. :type: File | None .. attribute:: opened True means directory created and if filed then file is opened. False otherwise :type: bool Properties: name (str): unique path component used in directory or file path name Hidden: _name (str): unique name for .name property File/Directory Creation Mode Notes:: .Perm provides default restricted access permissions to directory and/or files stat.S_ISVTX | stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR 0o1700==960 stat.S_ISVTX is Sticky bit. When this bit is set on a directory it means that a file in that directory can be renamed or deleted only by the owner of the file, by the owner of the directory, or by a privileged process. When this bit is set on a file it means nothing stat.S_IRUSR Owner has read permission. stat.S_IWUSR Owner has write permission. stat.S_IXUSR Owner has execute permission. .. py:property:: name Property getter for ._name :returns: unique identifier of instance used as unique path component in directory or file path name :rtype: name (str) .. py:method:: reopen(temp=None, headDirPath=None, perm=None, clear=False, reuse=False, clean=False, mode=None, fext=None, **kwa) Open if closed or close and reopen if opened or create and open if not :param temp: assign to .temp True means open in temporary directory, clear on close False means open persistent directory, do not clear on close :type temp: bool :param headDirPath: optional head directory pathname for main database Default .HeadDirpath :type headDirPath: str :param perm: optional numeric os dir permissions for database directory and database files. Default .Perm :type perm: int :param clear: True means remove directory upon close False means do not remove directory upon close :type clear: bool :param reuse: True means reuse self.path if already exists False means do not reuse but remake self.path :type reuse: bool :param clean: True means path uses clean tail variant False means path uses normal tail variant :type clean: bool :param mode: file open mode when .filed :type mode: str :param fext: File extension when .filed :type fext: str .. py:method:: remake(*, name='', base='', temp=None, headDirPath=None, perm=None, clean=False, filed=False, extensioned=False, mode=None, fext=None, **kwa) Make and return (path. file) by opening or creating and opening if not preexistent, directory or file at path :param name: unique name alias portion of path :type name: str :param base: optional base inserted before name in path :type base: str :param temp: optional None means ignore, True means open temporary directory, may clear on close False means open persistent directory, may not clear on close :type temp: bool :param headDirPath: optional head directory pathname of main database :type headDirPath: str :param perm: directory or file permissions such as stat.S_IRUSR Owner has read permission. stat.S_IWUSR Owner has write permission. stat.S_IXUSR Owner has execute permission. :type perm: int :param clean: True means make path for cleaned version and remove old directory or file at clean path if any. False means make path normally (not clean) :type clean: bool :param filed: True means .path is file path not directory path False means .path is directory path not file path :type filed: bool :param extensioned: When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext :type extensioned: bool :param mode: file open mode when .filed such as "w+" :type mode: str :param fext: File extension when .filed :type fext: str .. py:method:: exists(name='', base='', headDirPath=None, clean=False, filed=False, extensioned=False, fext=None) Check if (path. file) exists for a given set of parameters for remake. Temp is not allowed. :param name: unique name alias portion of path :type name: str :param base: optional base inserted before name in path :type base: str :param headDirPath: optional head directory pathname of main database :type headDirPath: str :param clean: True means make path for cleaned version and remove old directory or file at clean path if any. False means make path normally (not clean) :type clean: bool :param filed: True means .path is file path not directory path False means .path is directory path not file path :type filed: bool :param extensioned: When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext :type extensioned: bool :param fext: File extension when .filed :type fext: str :returns: True means path or alt path exists, false means neither exists :rtype: bool .. py:method:: flush() flush self.file if not closed .. py:method:: close(clear=False) Close .file if any and if clear rm directory or file at .path :param clear: True means remove dir or file at .path :type clear: bool .. py:function:: openFiler(cls=None, name='test', temp=True, reopen=True, clear=False, **kwa) Context manager wrapper Filer 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 :param cls is Class instance of subclass instance: :param name is str name of Filer instance path part so can have multiple Filers: at different paths that each use different dirs or files :param temp is Boolean: Otherwise open in persistent directory, do not clear on close :param True means open in temporary directory: Otherwise open in persistent directory, do not clear on close :param clear on close: Otherwise open in persistent directory, do not clear on close :param reopen: True (re)open with this init False not (re)open with this init but later (default) :type reopen: bool :param clear: True means remove directory upon close when reopening False means do not remove directory upon close when reopening :type clear: bool See filing.Filer for other keyword parameter passthroughs Usage:: with openFiler(name="bob") as filer: pass with openFiler(name="eve", cls=FilerSubClass) as filer: pass .. py:class:: FilerDoer(filer, **kwa) Bases: :py:obj:`hio.base.doing.Doer` Basic Filer Doer .. attribute:: done completion state: True means completed Otherwise incomplete. Incompletion maybe due to close or abort. :type: bool .. attribute:: filer instance :type: Filer 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. :param temp: True means use temporary file resources if any None means ignore parameter value. Use self.temp :type temp: bool | None 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.