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

PythonExtensionsCollection/String/CString.py

@@ -20,7 +20,7 @@
 #
 # XC-CT/ECA3-Queckenstedt
 #
-# 26.01.2022
+# 14.11.2022
 #
 # **************************************************************************************************************
 
@@ -30,57 +30,66 @@ import os, ntpath, re
 # **************************************************************************************************************
 
 class CString(object):
-   """Contains some string computation methods like e.g. normalizing a path."""
+   """
+The class ``CString`` contains some string computation methods like e.g. normalizing a path.
+   """
 
    # --------------------------------------------------------------------------------------------------------------
    #TM***
 
    def NormalizePath(sPath=None, bWin=False, sReferencePathAbs=None, bConsiderBlanks=False, bExpandEnvVars=True, bMask=True):
       """
-|
+Normalizes local paths, paths to local network resources and internet addresses
 
-**Method:**
+**Arguments:**
 
-**NormalizePath**
+* ``sPath``
 
-   Normalizes local paths, paths to local network resources and internet addresses
+  / *Condition*: required / *Type*: str /
 
-**Args:**
+  The path to be normalized
 
-**sPath** (*string*)
+* ``bWin``
 
-   The path to be normalized
+  / *Condition*: optional / *Type*: bool / *Default*: False /
 
-**bWin** (*boolean; optional; default: False*)
+  If ``True`` then returned path contains masked backslashes as separator, otherwise slashes
 
-   If ``True`` then returned path contains masked backslashes as separator, otherwise slashes
+* ``sReferencePathAbs``
 
-**sReferencePathAbs** (*string, optional*)
+  / *Condition*: optional / *Type*: str / *Default*: None /
 
-   In case of ``sPath`` is relative and ``sReferencePathAbs`` (expected to be absolute) is given, then
-   the returned absolute path is a join of both input paths
+  In case of ``sPath`` is relative and ``sReferencePathAbs`` (expected to be absolute) is given, then
+  the returned absolute path is a join of both input paths
 
-**bConsiderBlanks** (*boolean; optional; default: False*)
+* ``bConsiderBlanks``
 
-   If ``True`` then the returned path is encapsulated in quotes - in case of the path contains blanks
+  / *Condition*: optional / *Type*: bool / *Default*: False /
 
-**bExpandEnvVars** (*boolean; optional; default: True*)
+  If ``True`` then the returned path is encapsulated in quotes - in case of the path contains blanks
+
+* ``bExpandEnvVars``
+
+  / *Condition*: optional / *Type*: bool / *Default*: True /
 
    If ``True`` then in the returned path environment variables are resolved, otherwise not.
 
-**bMask** (*boolean; optional; default: True; requires bWin=True*)
+* ``bMask``
+
+  / *Condition*: optional / *Type*: bool / *Default*: True (requires ``bWin=True``)/
 
-   If ``bWin`` is ``True`` and ``bMask`` is ``True`` then the returned path contains masked backslashes as separator.
-   If ``bWin`` is ``True`` and ``bMask`` is ``False`` then the returned path contains single backslashes only - this might be
-   required for applications, that are not able to handle masked backslashes. In case of ``bWin`` is ``False`` ``bMask`` has no effect.
+  * If ``bWin`` is ``True`` and ``bMask`` is ``True`` then the returned path contains masked backslashes as separator.
+  * If ``bWin`` is ``True`` and ``bMask`` is ``False`` then the returned path contains single backslashes only - this might be
+    required for applications, that are not able to handle masked backslashes.
+  * In case of ``bWin`` is ``False`` ``bMask`` has no effect.
 
 **Returns:**
 
-**sPath** (*string*)
+* ``sPath``
 
-   The normalized path (is ``None`` in case of ``sPath`` is ``None``)
+  / *Type*: str /
 
-|
+  The normalized path (is ``None`` in case of ``sPath`` is ``None``)
       """
 
       if sPath is not None:
@@ -212,60 +221,69 @@ class CString(object):
 
    def DetectParentPath(sStartPath=None, sFolderName=None, sFileName=None):
       """
-|
+Computes the path to any parent folder inside a given path. Optionally DetectParentPath is able
+to search for files inside the identified parent folder.
 
-**Method:**
+**Arguments:**
 
-**DetectParentPath**
+* ``sStartPath``
 
-   Computes the path to any parent folder inside a given path. Optionally DetectParentPath is able
-   to search for files inside the parent folder.
+  / *Condition*: required / *Type*: str /
 
-**Args:**
+  The path in which to search for a parent folder
 
-**sStartPath** (*string*)
+* ``sFolderName``
 
-   The path in which to search for a parent folder
+  / *Condition*: required / *Type*: str /
 
-**sFolderName** (*string*)
+  The name of the folder to search for within ``sStartPath``. It is possible to provide more than one folder name separated by semicolon
 
-   The name of the folder to search for within ``sStartPath``. It is possible to provide more than one folder name separated by semicolon
+* ``sFileName``
 
-**sFileName** (*string, optional*)
+  / *Condition*: optional / *Type*: str / *Default*: None /
 
-   The name of a file to search within the detected parent folder
+  The name of a file to search within the detected parent folder
 
 **Returns:**
 
-**sDestPath** (*string*)
+* ``sDestPath``
+
+  / *Type*: str /
+
+  Path and name of parent folder found inside ``sStartPath``, ``None`` in case of ``sFolderName`` is not found inside ``sStartPath``.
+  In case of more than one parent folder is found ``sDestPath`` contains the first result and ``listDestPaths`` contains all results.
+
+* ``listDestPaths``
 
-   Path and name of parent folder found inside ``sStartPath``, ``None`` in case of ``sFolderName`` is not found inside ``sStartPath``.
-   In case of more than one parent folder is found ``sDestPath`` contains the first result and ``listDestPaths`` contains all results.
+  / *Type*: list /
 
-**listDestPaths** (*list*)
+  If ``sFolderName`` contains a single folder name this list contains only one element that is ``sDestPath``.
+  In case of ``FolderName`` contains a semicolon separated list of several folder names this list contains all found paths of the given folder names.
+  ``listDestPaths`` is ``None`` (and not an empty list!) in case of ``sFolderName`` is not found inside ``sStartPath``.
 
-   If ``sFolderName`` contains a single folder name this list contains only one element that is ``sDestPath``.
-   In case of ``FolderName`` contains a semicolon separated list of several folder names this list contains all found paths of the given folder names.
-   ``listDestPaths`` is ``None`` (and not an empty list!) in case of ``sFolderName`` is not found inside ``sStartPath``.
+* ``sDestFile``
 
-**sDestFile** (*string*)
+  / *Type*: str /
 
-   Path and name of ``sFileName``, in case of ``sFileName`` is given and found inside ``listDestPaths``.
-   In case of more than one file is found ``sDestFile`` contains the first result and ``listDestFiles`` contains all results.
-   ``sDestFile`` is ``None`` in case of ``sFileName`` is ``None`` and also in case of ``sFileName`` is not found inside ``listDestPaths``
-   (and therefore also in case of ``sFolderName`` is not found inside ``sStartPath``).
+  Path and name of ``sFileName``, in case of ``sFileName`` is given and found inside ``listDestPaths``.
+  In case of more than one file is found ``sDestFile`` contains the first result and ``listDestFiles`` contains all results.
+  ``sDestFile`` is ``None`` in case of ``sFileName`` is ``None`` and also in case of ``sFileName`` is not found inside ``listDestPaths``
+  (and therefore also in case of ``sFolderName`` is not found inside ``sStartPath``).
 
-**listDestFiles** (*list*)
+* ``listDestFiles``
 
-   Contains all positions of ``sFileName`` found inside ``listDestPaths``.
-   ``listDestFiles`` is ``None`` (and not an empty list!) in case of ``sFileName`` is ``None`` and also in case of ``sFileName``
-   is not found inside ``listDestPaths`` (and therefore also in case of ``sFolderName`` is not found inside ``sStartPath``).
+  / *Type*: list /
 
-**sDestPathParent** (*string*)
+  Contains all positions of ``sFileName`` found inside ``listDestPaths``.
 
-   The parent folder of ``sDestPath``, ``None`` in case of ``sFolderName`` is not found inside ``sStartPath`` (``sDestPath`` is ``None``).
+  ``listDestFiles`` is ``None`` (and not an empty list!) in case of ``sFileName`` is ``None`` and also in case of ``sFileName``
+  is not found inside ``listDestPaths`` (and therefore also in case of ``sFolderName`` is not found inside ``sStartPath``).
 
-|
+* ``sDestPathParent``
+
+  / *Type*: str /
+
+  The parent folder of ``sDestPath``, ``None`` in case of ``sFolderName`` is not found inside ``sStartPath`` (``sDestPath`` is ``None``).
       """
 
       sDestPath       = None
@@ -324,7 +342,7 @@ class CString(object):
       if len(listDestPaths) > 0:
          # -- returning sDestPath and sDestPathParent related to first entry in list; just to return anything else than None
          sDestPath = listDestPaths[0]
-         sDestPathParent = CString.NormalizePath(os.path.dirname(sDestPath))
+         sDestPathParent = os.path.dirname(sDestPath)
 
       # -- optionally searching also for a single file
       # Input: file name
@@ -338,7 +356,8 @@ class CString(object):
                for sFileNameTmp in listFileNames:
                   if sFileNameTmp == sFileName:
                      sFile = CString.NormalizePath(os.path.join(sLocalRootPath, sFileName))
-                     listDestFiles.append(sFile)
+                     if sFile not in listDestFiles:
+                        listDestFiles.append(sFile)
             # eof for sLocalRootPath, listFolderNames, listFileNames in os.walk(sDestPathToWalk):
          # eof for sDestPathToWalk in listDestPaths:
       # eof if ( (sFileName is not None) and (len(listDestPaths) > 0) ):
@@ -376,65 +395,16 @@ class CString(object):
                     sExclRegEx        = None,
                     bDebug            = False):
       """
-|
-
-During the computation of strings there might occur the need to get to know if this string fulfils certain criteria or not.
-Such a criterion can e.g. be that the string contains a certain substring. Also an inverse logic might be required:
-In this case the criterion is that the string does **not** contain this substring.
-
-It might also be required to combine several criteria to a final conclusion if in total the criterion for a string is fulfilled or not.
-For example: The string must start with the string *prefix* and must also contain either the string *substring1* or the string *substring2*
-but must also **not** end with the string *suffix*.
-
 This method provides a bunch of predefined filters that can be used singly or combined to come to a final conclusion if the string fulfils all criteria or not.
 
-The filters are divided into three different types:
-
-1. Filters that are interpreted as raw strings (called 'standard filters'; no wild cards supported)
-2. Filters that are interpreted as regular expressions (called 'regular expression based filters'; the syntax of regular expressions has to be considered)
-3. Boolean switches (e.g. indicating if also an empty string is accepted or not)
-
-The input string might contain leading and trailing blanks and tabs. This kind of horizontal space is removed from the input string
-before the standard filters start their work (except the regular expression based filters).
-
-The regular expression based filters consider the original input string (including the leading and trailing space). 
-
-The outcome is that in case of the leading and trailing space shall be part of the criterion, the regular expression based filters can be used only.
-
-It is possible to decide if the standard filters shall work case sensitive or not. This decision has no effect on the regular expression based filters.
-
-The regular expression based filters always work with the original input string that is not modified in any way.
-
-Except the regular expression based filters it is possible to provide more than one string for every standard filter (must be a semikolon separated list in this case).
-A semicolon that shall be part of the search string, has to be masked in this way: ``\;``.
-
-This method returns a boolean value that is ``True`` in case of all criteria are fulfilled, and ``False`` in case of some or all of them are not fulfilled.
-
-The default value for all filters is ``None`` (except ``bSkipBlankStrings``). In case of a filter value is ``None`` this filter has no influence on the result.
-
-In case of all filters are ``None`` (default) the return value is ``True`` (except the string itself is ``None``
-or the string is empty and ``bSkipBlankStrings`` is ``True``).
-
-In case of the string is ``None``, the return value is ``False``, because nothing concrete can be done with ``None`` strings.
-
-Internally every filter has his own individual acknowledge that indicates if the criterion of this filter is fulfilled or not.
+These filters can be e.g. used to select or exclude lines while reading from a text file. Or they can be used to select or exclude files or folders
+while walking through the file system.
 
-The meaning of *criterion fulfilled* of a filter is that the filter supports the final return value ``bAck`` of this method with ``True``.
-
-The final return value ``bAck`` of this method is a logical join (``AND``) of all individual acknowledges (except ``bSkipBlankStrings`` and ``sComment``;
-in case of their criteria are **not** fulfilled, immediately ``False`` is returned).
-
-Summarized:
-
-* Filters are used to define *criteria*
-* The return value of this method provides the *conclusion* - indicating if all criteria are fulfilled or not
-
-
-*The following filters are available:*
+**The following filters are available:**
 
 **bSkipBlankStrings**
 
-   * Like already mentioned above leading and trailing spaces are removed from the input string at the beginning
+   * Leading and trailing spaces are removed from the input string at the beginning
    * In case of the result is an empty string and ``bSkipBlankStrings`` is ``True``, the method immediately returns ``False``
      and all other filters are ignored
 
@@ -504,238 +474,35 @@ Summarized:
    * ``bCaseSensitive`` has no effect
    * A semicolon separated list of several regular expressions is **not** supported
 
-*Further parameter:*
+**Further arguments:**
+
+* ``sString``
 
-**sString**
+  / *Condition*: required / *Type*: str /
 
   The input string that has to be investigated. 
 
-**bCaseSensitive** (*boolean, optional, default*: ``True``)
+* ``bCaseSensitive``
+
+  / *Condition*: optional / *Type*: bool / *Default*: True /
 
   If ``True``, the standard filters work case sensitive, otherwise not.
 
-**bDebug** (*boolean, optional, default*: ``False``)
+* ``bDebug``
+
+  / *Condition*: optional / *Type*: bool / *Default*: False /
 
   If ``True``, additional output is printed to console (e.g. the decision of every single filter), otherwise not.
 
-*Examples:*
-
-Returns ``True``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Speed is 25 beats per minute",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = "Sp",
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = "beats",
-                               sContainsNot      = None,
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-Returns ``False``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Speed is 25 beats per minute",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = "Sp",
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = "minute",
-                               sContains         = "beats",
-                               sContainsNot      = None,
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-Returns ``True``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Speed is 25 beats per minute",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = None,
-                               sContainsNot      = "Beats",
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-Returns ``True``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Speed is 25 beats per minute",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = None,
-                               sContainsNot      = None,
-                               sInclRegEx        = r"\d{2}",
-                               sExclRegEx        = None)
-
-Returns ``False``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Speed is 25 beats per minute",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = "Speed",
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = None,
-                               sContainsNot      = None,
-                               sInclRegEx        = r"\d{3}",
-                               sExclRegEx        = None)
-
-Returns ``False``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Speed is 25 beats per minute",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = "Speed",
-                               sEndsWith         = "minute",
-                               sStartsNotWith    = "speed",
-                               sEndsNotWith      = None,
-                               sContains         = "beats",
-                               sContainsNot      = None,
-                               sInclRegEx        = r"\d{2}",
-                               sExclRegEx        = r"\d{2}")
-
-Returns ``False``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "     ",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = None,
-                               sContainsNot      = None,
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-Returns ``False``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "# Speed is 25 beats per minute",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = "#",
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = "beats",
-                               sContainsNot      = None,
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-
-Returns ``False``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "   Alpha is not beta; and beta is not gamma  ",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = "   Alpha ",
-                               sContainsNot      = None,
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-Because blanks around search strings (here ``"   Alpha "``) are considered, whereas the blanks around the input string are removed before computation.
-Therefore ``"   Alpha "`` cannot be found within the (shortened) input string.
-
-
-This alternative solution returns ``True``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "   Alpha is not beta; and beta is not gamma  ",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = None,
-                               sContainsNot      = None,
-                               sInclRegEx        = r"\s{3}Alpha",
-                               sExclRegEx        = None)
-
-
-Returns ``True``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Alpha is not beta; and beta is not gamma",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = "beta; and",
-                               sContainsNot      = None,
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-The meaning of ``"beta; and"`` is: The criterion is fulfilled in case of either ``"beta"`` or ``" and"`` can be found. That's ``True`` in this example - but this
-has nothing to do with the fact, that also this string ``"beta; and"`` can be found. A semicolon that shall be part of the search, has to be masked!
-
-The meaning of ``"beta\; not"`` in the following example is: The criterion is fulfilled in case of ``"beta; not"`` can be found.
-
-That's **not** ``True``. Therefore the method returns ``False``:
-
-.. code::
-
-   bAck = CString.StringFilter(sString           = "Alpha is not beta; and beta is not gamma",
-                               bCaseSensitive    = True,
-                               bSkipBlankStrings = True,
-                               sComment          = None,
-                               sStartsWith       = None,
-                               sEndsWith         = None,
-                               sStartsNotWith    = None,
-                               sEndsNotWith      = None,
-                               sContains         = r"beta\; not",
-                               sContainsNot      = None,
-                               sInclRegEx        = None,
-                               sExclRegEx        = None)
-
-|
+**Returns:**
+
+* ``bAck``
+
+  / *Type*: bool /
+
+  Final statement about the input string ``sString`` after filter computation
+
+Further details together with codde examples can be found within chapter **Description**, subsubsection **StringFilter**.
       """
 
       if sString is None:
@@ -909,7 +676,6 @@ That's **not** ``True``. Therefore the method returns ``False``:
                listParts = sContainsModified.split(";")
                for sPart in listParts:
                   sPart = sPart.replace(sSeparatorSubstitute , ";") # recover the original version
-                  print(f"- Part: '{sPart}'")
                   listContains.append(sPart)
             else:
                sContainsModified = sContains.replace(r"\;", ";") # convert to unmasked version
@@ -1055,24 +821,42 @@ That's **not** ``True``. Therefore the method returns ``False``:
 
    def FormatResult(sMethod="", bSuccess=True, sResult=""):
       """
-|
+Formats the result string ``sResult`` depending on ``bSuccess``:
+
+* ``bSuccess`` is ``True`` indicates *success*
+* ``bSuccess`` is ``False`` indicates an *error*
+* ``bSuccess`` is ``None`` indicates an *exception*
+
+Additionally the name of the method that causes the result, can be provided (*optional*).
+This is useful for debugging.
+
+**Arguments:**
+
+* ``sMethod``
+
+  / *Condition*: optional / *Type*: str / *Default*: (empty string) /
 
-**Method:**
+  Name of the method that causes the result.
 
-**FormatResult**
+* ``bSuccess``
 
-   Formats the result string ``sResult`` depending on ``bSuccess``:
+  / *Condition*: optional / *Type*: bool / *Default*: True /
 
-   * ``bSuccess`` is ``True`` indicates *success*
-   * ``bSuccess`` is ``False`` indicates an *error*
-   * ``bSuccess`` is ``None`` indicates an *exception*
+  Indicates if the computation of the method ``sMethod`` was successful or not.
+
+* ``sResult``
+
+  / *Condition*: optional / *Type*: str / *Default*: (empty string) /
+
+  The result of the computation of the method ``sMethod``.
+
+**Returns:**
 
-   Additionally the name of the method that causes the result, can be provided (*optional*).
-   This is useful for debugging.
+* ``sResult``
 
-   Returns the formatted result string.
+  / *Type*: str /
 
-|
+  The formatted result string.
       """
 
       if sMethod is None:

PythonExtensionsCollection/String/__init__.py

@@ -1,4 +1,4 @@
-#  Copyright 2020-2022 Robert Bosch Car Multimedia GmbH
+#  Copyright 2020-2022 Robert Bosch GmbH
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.