py3toolset 1.2.18__py3-none-any.whl

py3toolset/LICENSE.md

@@ -0,0 +1,11 @@
+Copyright 2017-2023 Éric Beucler, Hakim Hadj-Djilani
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

py3toolset/__init__.py

@@ -0,0 +1 @@
+""" Utility package """

py3toolset/bash_autocomp.py

@@ -0,0 +1,70 @@
+"""
+Module for installing bash autocompletion scripts.
+"""
+
+import os
+from os.path import exists
+import sys
+
+from py3toolset.cmd_interact import ask_yes_or_no
+from py3toolset.fs import get_prog_parent_dir
+from py3toolset.txt_color import warn, col, Color
+
+
+def propose_bashautocomp(autocomp_script):
+    """
+    Prompts user for a Bash completion script install for the current running
+    program (``sys.argv[0]``).
+
+    User decides not to/to install Bash completion script in his home
+    directory.
+    User is asked whether to prompt her/him again the next time.
+
+    The script install is done as advised in `bash-completion doc
+    <https://github.com/scop/bash-completion/blob/master/README.md>`_.
+    """
+    prog_path = get_prog_parent_dir()
+    # TODO: take care that the script dir might not be writable
+    autocomp_script_src = prog_path + os.sep + autocomp_script
+    dontask_again_file = prog_path + os.sep + ".dontask_autocomp_install"
+    src_command = "source " + autocomp_script_src + " 2>/dev/null\n"
+    # stderr ignored in case of a later script deletion
+    # otherwise user will be bothered with the error every time
+    # (s)he launches a Bash
+    if (not exists(dontask_again_file) and
+        (not exists(INSTALL_PATH) or
+         not _is_cmd_in_install_conf(src_command))):
+        warn("Bash command completion feature for " + sys.argv[0] +
+             " isn't installed on your system.")
+        print("Do you want to install it in ", INSTALL_PATH+"? ")
+        answer = ask_yes_or_no()
+        if answer[0] == "y":
+            f = open(INSTALL_PATH, "a")
+            f.write(src_command)
+            f.close()
+            print(col(Color.GREEN, "Bash completion feature installed! But"
+                      " you need to start a new bash session to have"
+                      " it applied."))
+        else:
+            print("Ask again the next time ?")
+            answer = ask_yes_or_no()
+            if answer[0] == "n":
+                print(dontask_again_file)
+                f = open(dontask_again_file, "w")
+                f.write("This file is a marker for avoiding the program "
+                        + sys.argv[0] +
+                        " to ask again if you want bash completion"
+                        " to be enabled. Delete it to be asked again!\n")
+                f.close()
+
+
+def _is_cmd_in_install_conf(src_command):
+    """
+    Test if a bash completion facility corresponding to src_command is already
+    installed in bash_completion file.
+    """
+    with open(INSTALL_PATH) as f:
+        return [line for line in f.readlines()].count(src_command) > 0
+
+
+INSTALL_PATH = os.getenv("HOME")+os.sep+".bash_completion"

py3toolset/cmd_interact.py

@@ -0,0 +1,153 @@
+"""
+Functions to help writing user interactions with a script (parsing options,
+yes/no question interactions, etc.).
+"""
+
+import re
+
+
+def is_help_switch(string):
+    """
+    Tests if string is a -h/--help switch.
+
+    Args:
+        string: str
+            String to test.
+
+    Return:
+        - True if the string is a help switch: -h or --help.
+        - False otherwise.
+
+    Example:
+        >>> is_help_switch('-h')
+        True
+        >>> is_help_switch('--help')
+        True
+        >>> is_help_switch('-a')
+        False
+        >>> is_help_switch('--anything')
+        False
+        >>> is_help_switch('anything')
+        False
+
+    """
+    return is_switch("h", "help", string)
+
+
+def contains_help_switch(strings):
+    """
+    Tests if strings contain a -h/--help switch.
+
+    strings: list[str]
+        strings to tests.
+
+    Return:
+        - True if strings contain a help switch: -h/--help.
+        - False otherwise.
+
+    Examples:
+        >>> contains_help_switch(["-h", "--anything"])
+        True
+        >>> contains_help_switch(["--help", "anything"])
+        True
+        >>> contains_help_switch(["-a", "--anything"])
+        False
+    """
+    return contains_switch("h", "help", strings)
+
+
+def is_switch(short_sw, long_sw, string):
+    """
+    Tests if string is the switch short_sw or long_sw.
+
+    Args:
+        short_sw: str
+            short switch (e.g. '-s').
+        long_sw:
+            long switch (e.g. '--switch').
+        string: str
+        string to test.
+
+    Return:
+        - True if string is the short or long switch defined in 2 first args.
+        - False otherwise.
+
+    Examples:
+        >>> is_switch("h", "help", "-h")
+        True
+        >>> is_switch("h", "help", "--help")
+        True
+        >>> is_switch("h", "help", "-z")
+        False
+        >>> is_switch("h", "help", "--zip")
+        False
+
+    """
+    return (short_sw and re.match("^(-" + short_sw + ")$", string) is not None
+            or
+            long_sw and re.match("^(--" + long_sw + ")$", string) is not None)
+
+
+def contains_switch(short_sw, long_sw, strings):
+    """
+    Tests if a switch short_sw or long_sw belongs to one of strings.
+
+    Args:
+        short_sw: str
+            short switch (e.g. '-s').
+        long_sw:
+            long switch (e.g. '--switch').
+        strings: list[str]
+            strings to tests.
+
+    Return:
+        - True if any strings[i] verifies:
+            ``is_switch(short_sw, long_sw, strings)``,
+        - False otherwise.
+
+    Examples:
+        >>> contains_switch("h", "help", ["-h","-a"])
+        True
+        >>> contains_switch("h", "help", ["--zip","-a"])
+        False
+
+    """
+    for i in range(0, len(strings)):
+        if is_switch(short_sw, long_sw, strings[i]):
+            return True
+    else:
+        return False
+
+
+def ask_yes_or_no(answer=""):
+    """
+    Asks user 'yes' or 'no' and loops until a valid response is given.
+
+    The response can also be 'y' or 'n'.
+
+    Args:
+        answer: str
+            If set to a valid response, the user is not asked for an answer.
+
+    Return:
+        The answer.
+
+    Examples:
+        >>> ask_yes_or_no('y')
+        'y'
+        >>> ask_yes_or_no('yes')
+        'yes'
+        >>> ask_yes_or_no('no')
+        'no'
+        >>> ask_yes_or_no('n')
+        'n'
+        >>> # with a user input
+        >>> # ask_yes_or_no()
+        # [y/n or yes/no]: y
+        # 'y'
+
+    """
+    while re.match("^(y|yes|n|no)$", answer, re.I) is None:
+        print("[y/n or yes/no]: ", end='')
+        answer = input()
+    return answer

py3toolset/dep.py

@@ -0,0 +1,144 @@
+"""
+Dependency checking module.
+"""
+
+import os
+from os.path import exists
+import sys
+
+
+checked_progs = []
+
+
+def check_executable(progname, *extra_paths, info_msg=""):
+    """
+    Checks if the program ``progname`` availability.
+
+    The program is search in PATH environment variable and optionally extra
+    paths.
+    If the program is not found an exception is raised.
+
+    If a program has already been checked before it is stored in module
+    variable ``checked_progs`` and next calls to ``check_executable`` will
+    always succeed.
+
+    Args:
+        progname: ``str``
+            program name to check the availability.
+        extra_paths: ``list[str]``
+            extra paths to find the program in.
+        info_msg: ``str``
+            a message to display if the function failed to find the program.
+
+    Return:
+        None in case of success (program found).
+        Exception raise otherwise.
+
+
+    Example:
+        >>> check_executable('more')
+        >>> info_msg = 'more not found'
+        >>> check_executable('more', None, info_msg)
+        >>> check_executable('more', '/', 'home', info_msg)
+    """
+    if _prog_already_checked(progname):  # work already done
+        return
+    if extra_paths is not None:
+        for p in extra_paths:
+            # don't add a path twice in PATH
+            if p not in os.environ["PATH"].split(os.pathsep):
+                print("Adding: "+repr(p)+" TO PATH ENV.")
+                os.environ["PATH"] = p+os.pathsep+os.environ["PATH"]
+    probed_pathes = [os.path.join(path.strip('"'), progname)
+                     for path in os.environ["PATH"].split(os.pathsep)]
+    existing_pathes = [path for path in probed_pathes if exists(path)]
+    if len(existing_pathes) == 0:
+        raise Exception("Error: " + progname + " not found in PATH environment"
+                        " variable directories.\n"+info_msg)
+    executable_pathes = [path for path in existing_pathes
+                         if os.access(path, os.X_OK)]
+    if len(executable_pathes) == 0:
+        raise Exception("Error: " + progname + " found but not executable "
+                        + repr(existing_pathes))
+    # print("exec pathes: " + repr(executable_pathes))
+    checked_progs.append(progname)
+
+
+def check_prog_deps(prog_list, *extra_paths, info_msgs=None):
+    """
+    Checks the availability of programs in ``prog_list``.
+
+    It is just an helper function that uses :func:`.check_executable`.
+
+    Args:
+        prog_list: ``list[str]``
+            programs to check availability.
+        extra_paths: ``list[str]``
+            paths to search the programs in addition to the paths in PATH
+            environment variable.
+        info_msgs: ``list[str]``
+            Messages to display when the function failed to find a program.
+            One message per program or none at all.
+            The order must match order of ``prog_list``.
+
+
+    Return:
+        None in case of success (program found).
+        Exception raise otherwise.
+
+    Example:
+        >>> check_prog_deps(['more', 'dir'])
+        >>> info_msgs = [['more not found'], ['dir not found']]
+        >>> check_prog_deps(['more', 'dir'], None, info_msgs)
+        >>> check_prog_deps(['more', 'dir'], '/', '/home', info_msgs)
+    """
+    if info_msgs is not None:
+        for progname, info in zip(prog_list, info_msgs):
+            check_executable(progname, *extra_paths, info_msg=info)
+    else:
+        for progname in prog_list:
+            check_executable(progname, *extra_paths)
+
+
+def _prog_already_checked(progname):
+    """
+    Returns ``True`` if a program has already been found ``False`` otherwise.
+
+    """
+    return checked_progs.count(progname) > 0
+
+
+def check_mod_pkg(mod_pkg, message=None, stdout=False):
+    """
+    Checks Python module/package availability.
+
+    Args:
+        mod_pkg: ``str``
+            Python package or module name (including Cython extension module).
+        message: ``str``
+            Error message displayed the module/package has not been found.
+        stdout: ``bool``
+            If ``True`` display ``message`` on ``sys.stdout``,
+            otherwise on ``sys.stderr`` (default).
+
+    Return:
+        ``True`` if Python ``mod_pkg`` (module or package) is found.
+        ``False`` otherwise.
+        ``None`` if ``mod_pkg`` wasn't found but not because of an
+        ``ImportError``.
+
+    Example:
+       >>> check_mod_pkg("notexistingpkg", "pkg not found.", stdout=True)
+       pkg not found.
+       False
+       >>> check_mod_pkg("os.path", "it must be found")
+       True
+
+    """
+    try:
+        exec('import '+mod_pkg)
+        return True
+    except ImportError:
+        if message is not None:
+            print(message, file=sys.stdout if stdout else sys.stderr)
+        return False

py3toolset/file_backup.py

@@ -0,0 +1,113 @@
+"""
+This module manages the backup and restoration of a list of files.
+"""
+
+import os
+from os.path import dirname, isdir, basename, exists
+import re
+from shutil import copyfile
+
+from py3toolset.cmd_interact import ask_yes_or_no
+from py3toolset.txt_color import print_frame
+
+# default backup folder
+BACKUP_FOLDER = ".backup"
+
+
+def work_on_copies(*files, answer="", backup_folder=BACKUP_FOLDER,
+                   header_msg=None, hdr_frame=True):
+    """
+        Saves/Restores original ``files`` in ``backup_folder``.
+
+        The first call makes a copy, the next one a restoration.
+        All ``files`` must be in the same parent directory.
+        The function quits the program if user refused to restore files.
+
+        Args:
+            answer: ``str``
+                if "yes" then the function auto-restores files from backup
+                (without prompting user for it).
+                Defaultly, the question is asked to user.
+            backup_folder: ``str``
+                The folder into which the files are backed up.
+                It is located in the same parent directory as ``files``.
+            header_msg: ``str``
+                The header message to print before saving/restoring ``files``.
+                Defaultly (``None``) no message.
+
+        Example:
+            >>> from random import randint
+            >>> rand_suffix = str(randint(1, 2**10))
+            >>> # create a folder and dummy files
+            >>> parent_dir = "test_work_on_copies" + rand_suffix
+            >>> os.mkdir(parent_dir)
+            >>> f1 = os.path.join(parent_dir, "f1")
+            >>> f_out = open(f1, 'w')
+            >>> f_out.writelines(["Test test test"])
+            >>> f_out.close()
+            >>> f2 = os.path.join(parent_dir, "f2")
+            >>> f2_out = open(f2, 'w')
+            >>> f2_out.writelines(["Test2 test2 test2"])
+            >>> f2_out.close()
+            >>> # now try work_on_copies
+            >>> work_on_copies(f1, f2, answer="y")
+            Saving original files to .backup
+            >>> # do some modifications
+            >>> f_out = open(f1, 'w')
+            >>> f_out.writelines(["Not the same test"])
+            >>> f_out.close()
+            >>> # file f1 is modified
+            >>> f_out = open(f1, 'r')
+            >>> print(f_out.readlines()[0])
+            Not the same test
+            >>> # restore f1
+            >>> work_on_copies(f1, f2, answer="y") #doctest:+ELLIPSIS
+            Getting back original files from .backup
+            list of files to be restored: test_work_on_copies...
+            The previous file working copy will be overridden...
+            Do you want to proceed?
+            Copying test_work_on_copies...
+            Copying test_work_on_copies...
+            >>> f_out = open(f1, 'r')
+            >>> print(f_out.readlines()[0])
+            Test test test
+            >>> f_out.close()
+            >>> # file f1 has been restored
+
+    """
+    if header_msg:
+        if hdr_frame:
+            print_frame(header_msg)
+        else:
+            print(header_msg)
+    pdir = dirname(files[0])
+    if re.match(pdir, r"\s") is not None:
+        pdir = "."
+    sav_dir_path = pdir + os.sep + backup_folder
+    # print("backup sac copy dir.: "+sav_dir_path)
+    if isdir(sav_dir_path):
+        print("Getting back original files from " + backup_folder)
+        print("list of files to be restored: "+", ".join(files))
+        print("The previous file working copy will be overridden"
+              " (if a corresponding backup file exists)!\n"
+              "Do you want to proceed?")
+        answer = ask_yes_or_no(answer)
+        if answer[0] == 'n':
+            print("Quitting, nothing done.")
+            exit()
+        for _file in files:
+            saved_sac = sav_dir_path + os.sep + basename(_file)
+            if exists(saved_sac):
+                print("Copying " + saved_sac + " to " + _file)
+                copyfile(saved_sac, _file)
+            else:
+                print("Backup doesn't exist in " +
+                      sav_dir_path + "." +
+                      " Keeping file: " + _file)
+                print("Saving the file above in " + sav_dir_path)
+                copyfile(_file, saved_sac)
+    else:
+        print("Saving original files to " + backup_folder)
+        os.mkdir(sav_dir_path)
+        for _file in files:
+            copyfile(_file, sav_dir_path + os.sep + basename(_file))