hio.base.filing

hio.base.filing module

Module Contents

class hio.base.filing.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: 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”

base

another unique path component inserted before name

Type:

str

temp

True means use TempHeadDir in /tmp directory

Type:

bool

headDirPath

head directory path

Type:

str

path

full directory or file path once created else None

Type:

str | None

perm

octal OS permissions for path directory and/or file

Type:

int

filed

True means .path ends in file. False means .path ends in directory

Type:

bool

extensioned

When not filed, True means ensure .path ends with fext.

Type:

bool

mode

file open mode if filed

Type:

str

fext

file extension if filed

Type:

str

file

File instance when filed and created.

Type:

File | None

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.

property name

Property getter for ._name

Returns:

unique identifier of instance used as unique path

component in directory or file path name

Return type:

name (str)

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

Parameters:

• temp (bool) – assign to .temp True means open in temporary directory, clear on close False means open persistent directory, do not clear on close

• headDirPath (str) – optional head directory pathname for main database Default .HeadDirpath

• perm (int) – optional numeric os dir permissions for database directory and database files. Default .Perm

• clear (bool) – True means remove directory upon close False means do not remove directory upon close

• reuse (bool) – True means reuse self.path if already exists False means do not reuse but remake self.path

• clean (bool) – True means path uses clean tail variant False means path uses normal tail variant

• mode (str) – file open mode when .filed

• fext (str) – File extension when .filed

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

Parameters:

• name (str) – unique name alias portion of path

• base (str) – optional base inserted before name in path

• temp (bool) – optional None means ignore, True means open temporary directory, may clear on close False means open persistent directory, may not clear on close

• headDirPath (str) – optional head directory pathname of main database

• perm (int) – 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.

• clean (bool) – 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)

• filed (bool) – True means .path is file path not directory path False means .path is directory path not file path

• 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 when .filed such as “w+”

• fext (str) – File extension when .filed

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.

Parameters:

• name (str) – unique name alias portion of path

• base (str) – optional base inserted before name in path

• headDirPath (str) – optional head directory pathname of main database

• clean (bool) – 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)

• filed (bool) – True means .path is file path not directory path False means .path is directory path not file path

• extensioned (bool) – When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext

• fext (str) – File extension when .filed

Returns:

True means path or alt path exists, false means neither exists

Return type:

bool

flush()

flush self.file if not closed

close(clear=False)

Close .file if any and if clear rm directory or file at .path

Parameters:

clear (bool) – True means remove dir or file at .path

hio.base.filing.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

Parameters:

• instance (cls is Class instance of subclass)

• Filers (name is str name of Filer instance path part so can have multiple) – at different paths that each use different dirs or files

• Boolean (temp is) – Otherwise open in persistent directory, do not clear on close

• directory (True means open in temporary) – Otherwise open in persistent directory, do not clear on close

• close (clear on) – 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 filing.Filer for other keyword parameter passthroughs

Usage:

with openFiler(name="bob") as filer:
    pass

with openFiler(name="eve", cls=FilerSubClass) as filer:
    pass

class hio.base.filing.FilerDoer(filer, **kwa)

Bases: hio.base.doing.Doer

Basic Filer Doer

done

completion state: True means completed Otherwise incomplete. Incompletion maybe due to close or abort.

Type:

bool

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

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.