PythonExtensionsCollection 0.2.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

PythonExtensionsCollection/File/CFile.py

@@ -20,7 +20,7 @@
 #
 # XC-CT/ECA3-Queckenstedt
 #
-# 26.01.2022
+# 15.11.2022
 #
 # **************************************************************************************************************
 
@@ -33,6 +33,14 @@ from PythonExtensionsCollection.String.CString import CString
 # **************************************************************************************************************
 
 class enFileStatiType:
+   """
+The class ``enFileStatiType`` defines the sollowing file states:
+
+* ``closed``
+* ``openedforwriting``
+* ``openedforappending``
+* ``openedforreading``
+   """
    closed             = "closed"
    openedforwriting   = "openedforwriting"
    openedforappending = "openedforappending"
@@ -42,8 +50,6 @@ class enFileStatiType:
 
 class CFile(object):
    """
-|
-
 The class ``CFile`` provides a small set of file functions with extended parametrization (like switches
 defining if a file is allowed to be overwritten or not).
 
@@ -61,8 +67,6 @@ It is not possible to create an instance of this class with a file that is alrea
 
 It is also not possible to use ``CopyTo`` or ``MoveTo`` to overwrite files that are already in use by another instance.
 This makes the file handling more save against access violations.
-
-|
    """
    # --------------------------------------------------------------------------------------------------------------
    # TM***
@@ -97,6 +101,9 @@ This makes the file handling more save against access violations.
    # TM***
 
    def __bIsFreeToUse(self, sFile=None):
+      """
+Checks if the file ``sFile`` is free to use, that means: not used by another instance of ``CFile``.
+      """
 
       bIsFreeToUse = False # init
       if sFile is None:
@@ -115,16 +122,12 @@ This makes the file handling more save against access violations.
 
    def __OpenForWriting(self):
       """
-|
-
 Opens a text file for writing.
 
 Returns ``bSuccess`` and ``sResult`` (feedback).
-
-|
       """
 
-      sMethod = "CFile::__OpenForWriting"
+      sMethod = "CFile.__OpenForWriting"
 
       if self.__sFile is None:
          bSuccess = False
@@ -146,8 +149,8 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
          self.Close()
          bSuccess = None
          sResult  = f"Not possible to open file '{self.__sFile}' for writing.\nReason: " + str(reason)
+         sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def __OpenForWriting(self):
@@ -157,16 +160,12 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
    def __OpenForAppending(self):
       """
-|
-
 Opens a text file for appending.
 
 Returns ``bSuccess`` and ``sResult`` (feedback).
-
-|
       """
 
-      sMethod = "CFile::__OpenForAppending"
+      sMethod = "CFile.__OpenForAppending"
 
       if self.__sFile is None:
          bSuccess = False
@@ -188,8 +187,8 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
          self.Close()
          bSuccess = None
          sResult  = f"Not possible to open file '{self.__sFile}' for appending.\nReason: " + str(reason)
+         sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def __OpenForAppending(self):
@@ -199,16 +198,12 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
    def __OpenForReading(self):
       """
-|
-
 Opens a text file for reading.
 
 Returns ``bSuccess`` and ``sResult`` (feedback).
-
-|
       """
 
-      sMethod = "CFile::__OpenForReading"
+      sMethod = "CFile.__OpenForReading"
 
       if self.__sFile is None:
          bSuccess = False
@@ -230,8 +225,8 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
          self.Close()
          bSuccess = None
          sResult  = f"Not possible to open file '{self.__sFile}' for reading.\nReason: " + str(reason)
+         sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def __OpenForReading(self):
@@ -241,15 +236,27 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
    def Close(self):
       """
-|
-
 Closes the opened file.
 
-Returns ``bSuccess`` and ``sResult`` (feedback).
+**Arguments:**
+
+(no args)
+
+**Returns:**
 
-|
+* ``bSuccess``
+
+  / *Type*: bool /
+
+  Indicates if the computation of the method was successful or not.
+
+* ``sResult``
+
+  / *Type*: str /
+
+  The result of the computation of the method.
       """
-      sMethod = "CFile::Close"
+      sMethod = "CFile.Close"
 
       if self.__oFileHandle is not None:
          try:
@@ -260,6 +267,7 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
          except Exception as reason:
             bSuccess = None
             sResult  = f"Exception while closing file '{self.__sFile}'.\nReason: " + str(reason)
+            sResult = CString.FormatResult(sMethod, bSuccess, sResult)
          self.__oFileHandle = None
       else:
          bSuccess = True
@@ -267,7 +275,6 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
       self.__oFileStatus = enFileStatiType.closed
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def Close(self):
@@ -277,24 +284,36 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
    def Delete(self, bConfirmDelete=True):
       """
-|
-
 Deletes the current file.
 
-**bConfirmDelete**
+**Arguments:**
 
-   Defines if it will be handled as error if the file does not exist.
+* ``bConfirmDelete``
 
-   If ``True``: If the file does not exist, the method indicates an error (``bSuccess = False``).
+  / *Condition*: optional / *Type*: bool / *Default*: True /
 
-   If ``False``: It doesn't matter if the file exists or not.
+  Defines if it will be handled as error if the file does not exist.
 
-Returns ``bSuccess`` and ``sResult`` (feedback).
+  If ``True``: If the file does not exist, the method indicates an error (``bSuccess = False``).
+
+  If ``False``: It doesn't matter if the file exists or not.
+
+**Returns:**
 
-|
+* ``bSuccess``
+
+  / *Type*: bool /
+
+  Indicates if the computation of the method was successful or not.
+
+* ``sResult``
+
+  / *Type*: str /
+
+  The result of the computation of the method.
       """
 
-      sMethod = "CFile::Delete"
+      sMethod = "CFile.Delete"
 
       if self.__sFile is None:
          bSuccess = False
@@ -308,7 +327,6 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
          else:
             bSuccess = True
          sResult = f"Nothing to delete. The file '{self.__sFile}' does not exist."
-         sResult = CString.FormatResult(sMethod, bSuccess, sResult)
          return bSuccess, sResult
 
       bSuccess, sResult = self.Close()
@@ -323,8 +341,8 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
       except Exception as reason:
          bSuccess = None
          sResult  = f"Exception while deleting file '{self.__sFile}'.\nReason: " + str(reason)
+         sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def Delete(self, bConfirmDelete=True):
@@ -334,13 +352,9 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
    def __PrepareOutput(self, Content=""):
       """
-|
-
 Helper for ``Write`` and ``Append`` (consideration of composite data types).
 
 Returns a list of strings (that will be written to file).
-
-|
       """
 
       listOut = []
@@ -391,23 +405,50 @@ Returns a list of strings (that will be written to file).
 
    def Write(self, Content="", nVSpaceAfter=0, sPrefix=None, bToScreen=False):
       """
-|
-
 Writes the content of a variable ``Content`` to file.
 
-If ``Content`` is not a string, the ``Write`` method resolves the data structure (therefore ``Content`` can also be of type
-``list``, ``tuple``, ``set``, ``dict``, ``dotdict``).
+**Arguments:**
 
-Adds vertical space ``nVSpaceAfter`` (= number of blank lines) after ``Content``.
+* ``Content``
 
-Prints ``Content`` also to screen in case of ``bToScreen`` is ``True`` (default: ``False``).
+  / *Condition*: required / *Type*: one of: str, list, tuple, set, dict, dotdict /
 
-Returns ``bSuccess`` and ``sResult`` (feedback).
+  If ``Content`` is not a string, the ``Write`` method resolves the data structure before writing the content to file.
+
+* ``nVSpaceAfter``
+
+  / *Condition*: optional / *Type*: int / *Default*: 0 /
+
+  Adds vertical space ``nVSpaceAfter`` (= number of blank lines) after ``Content``.
+
+* ``sPrefix``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  `sPrefix`` is added to every line of output (in case of ``sPrefix`` is not ``None``).
+
+* ``bToScreen``
+
+  / *Condition*: optional / *Type*: bool / *Default*: False /
+
+  Prints ``Content`` also to screen (in case of ``bToScreen`` is ``True``).
 
-|
+**Returns:**
+
+* ``bSuccess``
+
+  / *Type*: bool /
+
+  Indicates if the computation of the method was successful or not.
+
+* ``sResult``
+
+  / *Type*: str /
+
+  The result of the computation of the method.
       """
 
-      sMethod = "CFile::Write"
+      sMethod = "CFile.Write"
 
       if self.__oFileStatus != enFileStatiType.openedforwriting:
          bSuccess, sResult = self.__OpenForWriting()
@@ -436,8 +477,8 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
       except Exception as reason:
          bSuccess = None
          sResult  = f"Not possible to write to file '{self.__sFile}'.\nReason: " + str(reason)
+         sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def Write(self, Content="", nVSpaceAfter=0, sPrefix=None, bToScreen=False):
@@ -447,23 +488,49 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
    def Append(self, Content="", nVSpaceAfter=0, sPrefix=None, bToScreen=False):
       """
-|
-
 Appends the content of a variable ``Content`` to file.
 
-If ``Content`` is not a string, the ``Write`` method resolves the data structure (therefore ``Content`` can also be of type
-``list``, ``tuple``, ``set``, ``dict``, ``dotdict``).
+**Arguments:**
 
-Adds vertical space ``nVSpaceAfter`` (= number of blank lines) after ``Content``.
+* ``Content``
 
-Prints ``Content`` also to screen in case of ``bToScreen`` is ``True`` (default: ``False``).
+  / *Condition*: required / *Type*: one of: str, list, tuple, set, dict, dotdict /
 
-Returns ``bSuccess`` and ``sResult`` (feedback).
+  If ``Content`` is not a string, the ``Write`` method resolves the data structure before writing the content to file.
 
-|
-      """
+* ``nVSpaceAfter``
 
-      sMethod = "CFile::Append"
+  / *Condition*: optional / *Type*: int / *Default*: 0 /
+
+  Adds vertical space ``nVSpaceAfter`` (= number of blank lines) after ``Content``.
+
+* ``sPrefix``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  `sPrefix`` is added to every line of output (in case of ``sPrefix`` is not ``None``).
+
+* ``bToScreen``
+
+  / *Condition*: optional / *Type*: bool / *Default*: False /
+
+  Prints ``Content`` also to screen (in case of ``bToScreen`` is ``True``).
+
+**Returns:**
+
+* ``bSuccess``
+
+  / *Type*: bool /
+
+  Indicates if the computation of the method was successful or not.
+
+* ``sResult``
+
+  / *Type*: str /
+
+  The result of the computation of the method.
+      """
+      sMethod = "CFile.Append"
 
       if self.__oFileStatus != enFileStatiType.openedforappending:
          bSuccess, sResult = self.__OpenForAppending()
@@ -492,8 +559,8 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
       except Exception as reason:
          bSuccess = None
          sResult  = f"Not possible to append to file '{self.__sFile}'.\nReason: " + str(reason)
+         sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def Append(self, Content="", nVSpaceAfter=0, sPrefix=None, bToScreen=False):
@@ -517,19 +584,119 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
                  bRStrip         = True,
                  bToScreen       = False):
       """
-|
-
 Reads content from current file. Returns an array of lines together with ``bSuccess`` and ``sResult`` (feedback).
 
 The method takes care of opening and closing the file. The complete file content is read by ``ReadLines`` in one step,
 but with the help of further parameters it is possible to reduce the content by including and excluding lines.
 
-T.B.C.
+Internally ``ReadLines`` uses the string filter method ``StringFilter``. All filter related input parameter of
+``ReadLines`` and ``StringFilter`` are the same.
+
+The logical join of all filter is: ``AND``.
+
+**Arguments:**
+
+* ``bCaseSensitive``
 
-|
+  / *Condition*: optional / *Type*: bool / *Default*: True /
+
+  * If ``True``, the standard filters work case sensitive, otherwise not.
+  * This has no effect to the regular expression based filters ``sInclRegEx`` and ``sExclRegEx``.
+
+* ``bSkipBlankLines``
+
+  / *Condition*: optional / *Type*: bool / *Default*: False /
+
+  If ``True``, blank lines will be skipped, otherwise not.
+
+* ``sComment``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  In case of a line starts with the string ``sComment``, this line is skipped.
+
+* ``sStartsWith``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * The criterion of this filter is fulfilled in case of the input string starts with the string ``sStartsWith``
+  * More than one string can be provided (semicolon separated; logical join: ``OR``)
+
+* ``sEndsWith``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * The criterion of this filter is fulfilled in case of the input string ends with the string ``sEndsWith``
+  * More than one string can be provided (semicolon separated; logical join: ``OR``)
+
+* ``sStartsNotWith``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * The criterion of this filter is fulfilled in case of the input string starts not with the string ``sStartsNotWith``
+  * More than one string can be provided (semicolon separated; logical join: ``AND``)
+
+* ``sEndsNotWith``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * The criterion of this filter is fulfilled in case of the input string ends not with the string ``sEndsNotWith``
+  * More than one string can be provided (semicolon separated; logical join: ``AND``)
+
+* ``sContains``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * The criterion of this filter is fulfilled in case of the input string contains the string ``sContains`` at any position
+  * More than one string can be provided (semicolon separated; logical join: ``OR``)
+
+* ``sContainsNot``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * The criterion of this filter is fulfilled in case of the input string does **not** contain the string ``sContainsNot`` at any position
+  * More than one string can be provided (semicolon separated; logical join: ``AND``)
+
+* ``sInclRegEx``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * *Include* filter based on regular expressions (consider the syntax of regular expressions!)
+  * The criterion of this filter is fulfilled in case of the regular expression ``sInclRegEx`` matches the input string
+  * Leading and trailing blanks within the input string are considered
+  * ``bCaseSensitive`` has no effect
+  * A semicolon separated list of several regular expressions is **not** supported
+
+* ``sExclRegEx``
+
+  / *Condition*: optional / *Type*: str / *Default*: None /
+
+  * *Exclude* filter based on regular expressions (consider the syntax of regular expressions!)
+  * The criterion of this filter is fulfilled in case of the regular expression ``sExclRegEx`` does **not** match the input string
+  * Leading and trailing blanks within the input string are considered
+  * ``bCaseSensitive`` has no effect
+  * A semicolon separated list of several regular expressions is **not** supported
+
+* ``bLStrip``
+
+  / *Condition*: optional / *Type*: bool / *Default*: False /
+
+  If ``True``, leading spaces are removed from line before the filters are used, otherwise not.
+
+* ``bRStrip``
+
+  / *Condition*: optional / *Type*: bool / *Default*: True /
+
+  If ``True``, trailing spaces are removed from line before the filters are used, otherwise not.
+
+* ``bToScreen``
+
+  / *Condition*: optional / *Type*: bool / *Default*: False /
+
+  If ``True``, the content read from file is also printed to screen, otherwise not.
       """
 
-      sMethod = "[CFile::ReadLines]"
+      sMethod = "CFile.ReadLines"
 
       listLines = []
 
@@ -593,7 +760,6 @@ T.B.C.
 
       bSuccess = True
       sResult  = f"Read {nNrOfLines} lines from '{self.__sFile}'."
-      sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
       return listLines, bSuccess, sResult
 
    # eof def ReadLines(...)
@@ -603,42 +769,55 @@ T.B.C.
 
    def GetFileInfo(self):
       """
-|
+Returns the following informations about the file (encapsulated within a dictionary ``dFileInfo``):
 
-Returns the following informations about the file (encapsulated within a dictionary):
+**Returns:**
 
-Key **sFile**
+* Key ``sFile``
 
-   Path and name of current file
+  / *Type*: str /
 
-Key **bFileIsExisting**
+  Path and name of current file
 
-   ``True`` if file is existing, otherwise not
 
-Key **sFileName**
+* Key ``bFileIsExisting``
 
-   The name of the current file (incl. extension)
+  / *Type*: bool /
 
-Key **sFileExtension**
+  ``True`` if file is existing, otherwise ``False``
 
-   The extension of the current file
+* Key ``sFileName``
 
-Key **sFileNameOnly**
+  / *Type*: str /
 
-   The pure name of the current file (without extension)
+  The name of the current file (incl. extension)
 
-Key **sFilePath**
+* Key ``sFileExtension``
 
-   The the path to current file
+  / *Type*: str /
 
-Key **bFilePathIsExisting**
+  The extension of the current file
 
-   ``True`` if file path is existing, otherwise not
+* Key ``sFileNameOnly``
 
-|
+  / *Type*: str /
+
+  The pure name of the current file (without extension)
+
+* Key ``sFilePath``
+
+  / *Type*: str /
+
+  The the path to current file
+
+* Key ``bFilePathIsExisting``
+
+  / *Type*: bool /
+
+  ``True`` if file path is existing, otherwise ``False``
       """
 
-      sMethod = "CFile::GetFileInfo"
+      sMethod = "CFile.GetFileInfo"
 
       dFileInfo = {}
       dFileInfo['sFile']               = None
@@ -682,8 +861,6 @@ Key **bFilePathIsExisting**
 
    def CopyTo(self, sDestination=None, bOverwrite=False):
       """
-|
-
 Copies the current file to ``sDestination``, that can either be a path without file name or a path together with a file name.
 
 In case of the destination file already exists and ``bOverwrite`` is ``True``, than the destination file will be overwritten.
@@ -691,12 +868,37 @@ In case of the destination file already exists and ``bOverwrite`` is ``True``, t
 In case of the destination file already exists and ``bOverwrite`` is ``False`` (default), than the destination file will not be overwritten
 and ``CopyTo`` returns ``bSuccess = False``.
 
-Returns ``bSuccess`` and ``sResult`` (feedback).
+**Arguments:**
 
-|
-      """
+* ``sDestination``
+
+  / *Condition*: required / *Type*: string /
+
+  The path to destination file (either incl. file name or without file name)
+
+* ``bOverwrite``
+
+  / *Condition*: optional / *Type*: bool / *Default*: False /
+
+  * In case of the destination file already exists and ``bOverwrite`` is ``True``, than the destination file will be overwritten.
+  * In case of the destination file already exists and ``bOverwrite`` is ``False`` (default), than the destination file will not be overwritten
+    and ``CopyTo`` returns ``bSuccess = False``.
+
+**Returns:**
+
+* ``bSuccess``
+
+  / *Type*: bool /
+
+  Indicates if the computation of the method was successful or not.
+
+* ``sResult``
 
-      sMethod = "CFile::CopyTo"
+  / *Type*: str /
+
+  The result of the computation of the method.
+      """
+      sMethod = "CFile.CopyTo"
 
       if self.__sFile is None:
          bSuccess = False
@@ -786,6 +988,7 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
                sResult  = f"Exception while deleting destination file '{sDestFile}'.\nReason: " + str(reason)
                sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
                return bSuccess, sResult
+      # eof if bDeleteDestFile is True:
 
       try:
          shutil.copyfile(self.__sFile, sDestFile)
@@ -794,8 +997,8 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
       except Exception as reason:
          bSuccess = None
          sResult  = f"Exception while copying file '{self.__sFile}' to '{sDestFile}'.\nReason: " + str(reason)
+         sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
 
-      sResult = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def CopyTo(self, sDestination=None, bOverwrite=False):
@@ -805,21 +1008,39 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
    def MoveTo(self, sDestination=None, bOverwrite=False):
       """
-|
-
 Moves the current file to ``sDestination``, that can either be a path without file name or a path together with a file name.
 
-In case of the destination file already exists and ``bOverwrite`` is ``True``, than the destination file will be overwritten.
+**Arguments:**
 
-In case of the destination file already exists and ``bOverwrite`` is ``False`` (default), than the destination file will not be overwritten
-and ``CopyTo`` returns ``bSuccess = False``.
+* ``sDestination``
 
-Returns ``bSuccess`` and ``sResult`` (feedback).
+  / *Condition*: required / *Type*: string /
 
-|
-      """
+  The path to destination file (either incl. file name or without file name)
+
+* ``bOverwrite``
 
-      sMethod = "CFile::MoveTo"
+  / *Condition*: optional / *Type*: bool / *Default*: False /
+
+  * In case of the destination file already exists and ``bOverwrite`` is ``True``, than the destination file will be overwritten.
+  * In case of the destination file already exists and ``bOverwrite`` is ``False`` (default), than the destination file will not be overwritten
+    and ``MoveTo`` returns ``bSuccess = False``.
+
+**Returns:**
+
+* ``bSuccess``
+
+  / *Type*: bool /
+
+  Indicates if the computation was successful or not
+
+* ``sResult``
+
+  / *Type*: str /
+
+  Contains details about what happens during computation
+      """
+      sMethod = "CFile.MoveTo"
 
       bSuccess, sResult = self.CopyTo(sDestination, bOverwrite)
       if bSuccess is not True:
@@ -840,7 +1061,6 @@ Returns ``bSuccess`` and ``sResult`` (feedback).
 
       bSuccess = True
       sResult  = f"File moved from '{self.__sFile}' to '{self.__sLastDestination}'"
-      sResult  = CString.FormatResult(sMethod, bSuccess, sResult)
       return bSuccess, sResult
 
    # eof def MoveTo(self, sDestination=None, bOverwrite=False):