invesyservertools 0.1.0__py3-none-any.whl

invesyservertools/__init__.py

@@ -0,0 +1,26 @@
+import importlib
+from pathlib import Path
+
+__all__ = []
+
+
+def _load_tools():
+    """Re-export the public names of every ``*_tools.py`` submodule."""
+    package_dir = Path(__file__).parent
+    for file in sorted(package_dir.glob('*_tools.py')):
+        module = importlib.import_module(f'.{file.stem}', __package__)
+        names = getattr(
+            module,
+            '__all__',
+            [name for name in dir(module) if not name.startswith('_')]
+        )
+        for name in names:
+            if name in __all__:
+                raise RuntimeError(
+                    f"duplicate export {name!r} from {file.stem}"
+                )
+            globals()[name] = getattr(module, name)
+            __all__.append(name)
+
+
+_load_tools()

invesyservertools/interactive_tools.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+"""
+=================
+interactive_tools
+=================
+"""
+
+import sys
+import warnings
+from typing import Optional, Union
+
+try:
+    import termios
+except ImportError:  # termios is POSIX-only (absent on Windows)
+    termios = None
+
+from .print_tools import print_
+
+__all__ = ['wait_for_key']
+
+
+def wait_for_key(
+    text: str = 'continue: press any button',
+    list_bullet: Union[bool, str] = False,
+    color: str = None,
+    indent: int = 0
+) -> Optional[str]:
+    ''' Wait for a key press on the console and return it.'''
+
+    if termios is None:
+        raise RuntimeError(
+            'wait_for_key requires a POSIX terminal '
+            '(the termios module is unavailable on this platform)'
+        )
+
+    if text:
+        print_(
+            text,
+            color=color,
+            list_bullet=list_bullet,
+            indent=indent
+        )
+
+    # without a real terminal we cannot switch to raw mode; read a single
+    # character (or return None at EOF) instead of crashing in termios
+    if not sys.stdin.isatty():
+        try:
+            return sys.stdin.read(1) or None
+        except OSError:
+            warnings.warn("wait_for_key: failed to read from stdin")
+            return None
+
+    fd = sys.stdin.fileno()
+    result = None
+
+    try:
+        oldterm = termios.tcgetattr(fd)
+        newattr = termios.tcgetattr(fd)
+        newattr[3] = newattr[3] & ~termios.ICANON & ~termios.ECHO
+        termios.tcsetattr(fd, termios.TCSANOW, newattr)
+    except termios.error:
+        warnings.warn("wait_for_key: failed to configure the terminal")
+        return None
+
+    try:
+        result = sys.stdin.read(1) or None
+    except OSError:
+        warnings.warn("wait_for_key: failed to read from stdin")
+    finally:
+        # only reached when the terminal was reconfigured successfully,
+        # so oldterm is always bound here
+        termios.tcsetattr(fd, termios.TCSAFLUSH, oldterm)
+
+    return result

invesyservertools/print_tools.py

@@ -0,0 +1,260 @@
+# -*- coding: utf-8 -*-
+"""
+===========
+print_tools
+===========
+"""
+
+import logging as _logging
+import os
+import sys
+import textwrap
+from typing import Dict, Optional, Union
+
+from colorama import Fore, Style
+
+LIST_BULLET = '-'
+COLOR_RESET = getattr(Style, 'RESET_ALL')
+
+INDENT_MULT = 4
+
+UNIT_PREFIXES = {
+    'binary': ['', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi'],
+    'decimal': ['', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y']
+}
+
+__all__ = ['and_list', 'indent', 'print_', 'format_filesize']
+
+
+def and_list(
+    elements: list,
+    et: str = 'and'
+) -> str:
+    """Create a human-readable list, joining elements with commas and a final conjunction.
+
+    :param elements: items to join
+    :param et: conjunction before the last element (e.g. ``'and'``, ``'und'``)
+    :return: the formatted string
+    """
+    elements = [str(el) for el in elements]
+    if len(elements) <= 1:
+        return ''.join(elements)
+    return ', '.join(elements[:-1]) + f' {et} ' + elements[-1]
+
+
+def indent(
+    level: int = 1,
+    raw: bool = False,
+    base: int = INDENT_MULT,
+    base_str: str = ' '
+) -> str:
+    """Build an indentation string of *level* steps.
+
+    :param level: number of indentation steps
+    :param raw: if ``True`` return the full width; otherwise trim one
+        character (see below)
+    :param base: width of one indentation step
+    :param base_str: character the indentation is filled with
+    :return: the indentation string
+    """
+    base = base * base_str
+    if raw:
+        return base * level
+    else:
+        # Trim the last character so that appending a single-character marker
+        # — e.g. the bullet from print_(..., list_bullet=True) — places that
+        # marker exactly on the base-column grid (columns base, 2*base, …;
+        # with the defaults: 4, 8, …). Use raw=True when you add no marker.
+        return (base * level)[:-1]
+
+
+def print_(
+    *texts: str,
+    logging: Optional[_logging.Logger] = None,
+    indent: int = 0,
+    list_bullet: Union[bool, str] = '',
+    color: Union[str, Dict[int, str]] = '',
+    style: str = '',
+    sep: str = ' ',
+    end: str = '\n',
+    ignore: bool = False,
+    flush: bool = None,
+    nowrapper: bool = None
+) -> None:
+    """Enhanced print function.
+
+    The text arguments can contain ``'\\n'``, either as a
+    singleton or as part of a string argument.
+
+    :param texts: the texts to print
+    :param logging: provide a logging object to log the output
+    :param indent: set the indentation level
+    :param list_bullet: ``True`` for the default bullet or provide a string
+    :param color: a color name or a dict mapping 1-based text indices to
+        color names, e.g. ``{1: 'red', 4: 'blue'}``.
+        Strings containing only line endings don't count for the index.
+    :param style: a colorama style name
+    :param sep: separator between texts (as in :func:`print`)
+    :param end: end string (as in :func:`print`)
+    :param ignore: don't print (but possibly log)
+    :param flush: flush the output (as in :func:`print`)
+    :param nowrapper: disable textwrap
+    """
+
+    # are we outputting to a tty?
+    output_to_tty = sys.stdout.isatty()
+
+    if nowrapper is None:
+        nowrapper = not output_to_tty
+    if flush is None:
+        flush = not output_to_tty
+
+    # wrapping needs a known terminal width, available only on a tty
+    if not output_to_tty:
+        nowrapper = True
+
+    texts = [str(t) for t in texts]
+
+    # we have line endings
+    if any(
+        ['\n' in t for t in texts]
+    ):
+        for i, t in enumerate(texts):
+            if t.endswith('\n'):
+                try:
+                    texts[i + 1] = '\n' + texts[i + 1]  # update next string by adding line end
+                    texts[i] = t[:-1]  # remove line end from current string
+                except IndexError:
+                    pass
+
+        nowrapper = True
+
+        texts = list(filter(None, texts))  # remove empty strings
+
+    if logging:
+        logging.info(sep.join(texts))
+
+    if ignore:
+        return
+
+    colors = None
+
+    if isinstance(color, dict):
+        colors = color
+        color = None
+
+    # only use colors/styles if stdout is a tty
+    if not output_to_tty:
+        colors = {}
+        color = None
+        style = ''
+
+    if len(texts):
+        try:
+            prefix = ' ' * indent
+        except TypeError:
+            prefix = indent or ''
+
+        # visible width of the prefix, ignoring invisible color escapes
+        visible_prefix_len = len(prefix)
+
+        suffix = ''
+        if color or style:
+            prefix += getattr(
+                Fore,
+                (color or '').upper(), ''
+            ) + getattr(
+                Style, (style or '').upper(),
+                ''
+            )
+            suffix = COLOR_RESET
+
+        if colors:
+            texts_colored = []
+            # line-ending-only arguments don't consume a color index
+            color_index = 0
+            for t in texts:
+                p = s = ''
+                if t.strip('\n'):
+                    color_index += 1
+                    if color_index in colors:
+                        p = getattr(Fore, colors[color_index].upper(), '')
+                        s = COLOR_RESET if p else ''
+
+                texts_colored.append(p + t + s)
+
+            texts = texts_colored
+
+        if isinstance(list_bullet, bool):
+            if list_bullet:
+                list_bullet = LIST_BULLET
+            else:
+                list_bullet = ''
+
+        bullet_sep = ' '
+        if list_bullet:
+            prefix += list_bullet + bullet_sep
+            visible_prefix_len += len(list_bullet) + len(bullet_sep)
+
+        if output_to_tty:
+            try:
+                term_columns = os.get_terminal_size().columns
+                wrapper = textwrap.TextWrapper(
+                    initial_indent=prefix,
+                    width=term_columns,
+                    subsequent_indent=' ' * visible_prefix_len
+                )
+            except OSError:
+                nowrapper = True
+
+        if flush or nowrapper:
+            texts[-1] += suffix
+            print(
+                prefix + texts[0],
+                *texts[1:],
+                sep=sep,
+                end=end,
+                flush=flush
+            )
+        else:
+            print(wrapper.fill(sep.join(texts) + suffix), end=end)
+
+    else:
+        print()
+
+
+def format_filesize(
+    num: Union[int, float],
+    suffix: str = "B",
+    prefix_type: str = 'binary'
+) -> str:
+    """Format a file size as a human-readable string.
+
+    Inspired by `Fred Cirera <https://stackoverflow.com/a/1094933/1690805>`_.
+
+    :param num: size in bytes
+    :param suffix: unit suffix (default ``'B'``)
+    :param prefix_type: ``'binary'`` for IEC prefixes (Ki, Mi, …) or
+        ``'decimal'`` for SI prefixes (K, M, …)
+    :raises ValueError: if *prefix_type* is not ``'binary'`` or ``'decimal'``
+    :return: the formatted size string
+    """
+    if prefix_type not in UNIT_PREFIXES:
+        raise ValueError(
+            f"prefix_type must be one of {sorted(UNIT_PREFIXES)}, "
+            f"got {prefix_type!r}"
+        )
+
+    prefixes = UNIT_PREFIXES[prefix_type]
+    divider = 1024.0 if prefix_type == 'binary' else 1000.0
+
+    # stop before the largest prefix so it can serve as the overflow cap;
+    # dividing past it would underreport values above the largest unit
+    for unit in prefixes[:-1]:
+        if abs(num) < divider:
+            return f"{num:3.1f} {unit}{suffix}"
+
+        num /= divider
+
+    # value reaches or exceeds the largest defined prefix
+    return f"{num:3.1f} {prefixes[-1]}{suffix}"

invesyservertools/system_tools.py

@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+"""
+============
+system_tools
+============
+"""
+
+import os
+import warnings
+from pathlib import Path
+from typing import Optional
+
+try:
+    import pwd
+except ImportError:  # pwd is POSIX-only (absent on Windows)
+    pwd = None
+
+from .print_tools import print_
+
+__all__ = ['get_username', 'get_home_dir', 'find_file_path']
+
+
+def get_username() -> str:
+    """Return the login name of the current user."""
+    if pwd is None:
+        raise RuntimeError(
+            'get_username requires a POSIX platform '
+            '(the pwd module is unavailable on this platform)'
+        )
+    return pwd.getpwuid(os.getuid())[0]
+
+
+def get_home_dir() -> str:
+    """Return the current user's home directory."""
+    return str(Path.home())
+
+
+def find_file_path(
+    filename: str,
+    rootpath: str,
+    path_only: bool = False,
+    verbose=False
+) -> Optional[str]:
+    """Find the complete path for a file.
+
+    Walks the directory tree starting at *rootpath* and returns the
+    full path to the first file matching *filename*.
+
+    Unreadable subdirectories are skipped with a warning rather than
+    aborting the search, so a ``None`` result does not guarantee the file
+    is absent from an inaccessible subtree.
+
+    :param filename: name of the file to search for
+    :param rootpath: root directory to start the search (``~`` is expanded)
+    :param path_only: if ``True``, return only the containing directory
+    :param verbose: if ``True``, print each directory as it is visited
+    :return: the file path, the containing directory, or ``None`` if the
+        file is not found
+    """
+
+    # expand ~ and ~user to the corresponding home directory
+    rootpath = os.path.expanduser(rootpath)
+
+    def _on_error(error):
+        warnings.warn(
+            f"find_file_path: cannot access {error.filename!r}: {error}"
+        )
+
+    for root, dirs, files in os.walk(rootpath, onerror=_on_error):
+        if verbose:
+            print_(root)
+        for name in files:
+            if name == filename:
+                if path_only:
+                    return root
+                return os.path.join(root, filename)
+
+    return None

invesyservertools-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: invesyservertools
+Version: 0.1.0
+Summary: Tools for Python scripts or terminal
+Author-email: Georg Pfolz <georg.pfolz@invesy.at>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/Rastaf/invesyservertools
+Project-URL: Bug Tracker, https://gitlab.com/Rastaf/invesyservertools/-/issues
+Project-URL: Documentation, https://rastaf.gitlab.io/invesyservertools/
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: colorama
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# invesyservertools
+
+A small set of useful tools on a server, especially for terminal scripts.
+
+Why "invesy"? Invesy (from German **In**halts**ve**rwaltungs**sy**stem == content management system) is a closed source cms I created with Thomas Macher. It's only used in-house, that's why we didn't bother making it open source.
+
+## Installation
+
+```sh
+pip install invesyservertools
+```
+
+Requires Python >= 3.9 on a POSIX platform (Linux, *BSD, macOS — uses the Unix-only modules `termios` and `pwd`).
+
+## Quick example
+
+```python
+from invesyservertools import print_, format_filesize, wait_for_key
+
+print_('Hello', 'World', color={1: 'green'}, sep=' ')
+print(format_filesize(234567890))  # '223.7 MiB'
+wait_for_key()
+```
+
+## What's in the box?
+
+### interactive_tools
+- **wait_for_key**: Wait for a pressed key to continue.
+
+### print_tools
+- **and_list**: human-readable list like `a, 1, 2 and something`
+- **indent**: get an indentation string
+- **print_**: Enhanced print function, specially enhanced for printing in the terminal and into log files.
+- **format_filesize**: return a human-readable filesize, like `31.9 GiB`.
+
+### system_tools
+- **get_username**: get the username in the operating system
+- **get_home_dir**: get the home directory
+- **find_file_path**: provide a filename and a start path to begin searching recursively, get the complete path including the filename
+
+## Documentation
+
+Full API docs: https://rastaf.gitlab.io/invesyservertools/
+
+## License
+
+MIT
+
+# History
+## 0.1.0
+- Packaging modernized: built from `pyproject.toml`, tests run under `pytest`
+- **Breaking:** requires Python >= 3.9 (was 3.7)
+- **Breaking:** `find_file_path()` returns `None` when nothing is found (was a message string); the `not_found` argument was removed
+- Targets POSIX (Linux, *BSD, macOS) but now imports cleanly everywhere — the POSIX-only `wait_for_key` and `get_username` raise a clear error on non-POSIX instead of breaking `import invesyservertools`
+- **and_list**: keeps the conjunction for multi-word or punctuated final elements
+- **print_**: several correctness fixes (terminal-size detection, `end`/separator handling, colour indexing and wrapped-line indentation, `style=` off a tty)
+- **format_filesize**: correct SI (decimal) thresholds and large-value handling; clear error on an invalid `prefix_type`
+- **wait_for_key**: robust on non-tty stdin (no crash; returns `None` at EOF)
+
+## 0.0.10 (2023-07-13)
+- bumped version to 0.0.10
+- replaced dynamic package imports using `exec()` and `sys.path` mutation with `importlib`
+
+## 0.0.9 (2023-06-10)
+- fixed IndexError in **print_** (for line ending in last string)
+- **print_** checks for terminal (-> no colors, no wrapper)
+
+## 0.0.5 (2022-12-09)
+- fixed import of submodules
+
+## 0.0.4 (2022-12-09)
+- *wait_for_key* gets a "indent" argument
+- Sphinx documentation
+
+## 0.0.3 (2022-06-16)
+Added support for line breaks in *print_*:
+
+- can be added as singletons or as part of strings
+- line break singletons are not counted in the color argument
+
+## 0.0.2 (2022-06-13)
+* splitted modules (now: *interactive_tools*, *print_tools*, *system_tools*)
+* added new functions:
+	* system_tools
+		* get_username
+		* get\_home\_dir
+		* find\_file\_path
+	* print_tools
+		* and_list
+		* format_filesize
+
+## 0.0.1 (2022-06-10)
+* first version

invesyservertools-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+invesyservertools/__init__.py,sha256=aeEZB3l4AhPmCS1dbDbS27N8_5g7r9bc6iB0zdmYht8,745
+invesyservertools/interactive_tools.py,sha256=w5Vx7wj9lrSQpmWIPGfJ_Ya_Z9rXNZ78QqOqYzwoiXw,1954
+invesyservertools/print_tools.py,sha256=HF8vFZhrT0LH2PAKhdeHFglGQrqsAW9-kosXGROFoYI,7598
+invesyservertools/system_tools.py,sha256=0EiWqlTtotSziXr9SmGETePNnSR8vtp1NMCmNVxeG3g,2150
+invesyservertools-0.1.0.dist-info/licenses/LICENSE.txt,sha256=-vEbVpKDEALxD3QtS7yMJ4T9uRB_AbN9aQey6X941Ws,1050
+invesyservertools-0.1.0.dist-info/METADATA,sha256=3Ga32YQdPNdvJ2K5uFaUm2CEQIzOfya_mtb7Ye8BCB8,4015
+invesyservertools-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+invesyservertools-0.1.0.dist-info/top_level.txt,sha256=goITXYiS_8Th-GRPKmgp9P0erFrNVyKbTFTluN0bL9Y,18
+invesyservertools-0.1.0.dist-info/RECORD,,

invesyservertools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

invesyservertools-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2022 Georg Pfolz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

invesyservertools-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+invesyservertools