d8s-utility 0.9.0__py3-none-any.whl

d8s_utility/__init__.py

@@ -0,0 +1,5 @@
+from .utility import *
+
+__version__ = "0.9.0"
+__author__ = """Floyd Hightower"""
+__email__ = "floyd.hightower27@gmail.com"

d8s_utility/utility.py

@@ -0,0 +1,353 @@
+"""This is a collection of functions that really don't belong anywhere else."""
+
+import functools
+from typing import Any, Dict, Iterable, Set, Union
+
+from .utility_temp_utils import listify_first_arg
+
+StrOrNumberType = Union[str, int, float]
+
+
+def copy_first_arg(func):
+    """Decorator to make a copy of the first argument and pass into the func."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        import copy
+
+        first_arg = args[0]
+        other_args = args[1:]
+        try:
+            first_arg_copy = copy.deepcopy(first_arg)
+        # a RecursionError can occur when trying to do a deep copy on objects of certain classes...
+        # (e.g. beautifulsoup objects)...
+        # see: https://github.com/biopython/biopython/issues/787, https://bugs.python.org/issue5508, and...
+        # https://github.com/cloudtools/troposphere/issues/648
+        except RecursionError:
+            message = "Performing a deep copy on the first arg failed; I'll just perform a shallow copy."
+            print(message)
+            first_arg_copy = copy.copy(first_arg)
+        return func(first_arg_copy, *other_args, **kwargs)
+
+    return wrapper
+
+
+def has_more_than_one_item(thing: Any) -> bool:
+    """Return whether or not the given thing has a length of at least one."""
+    return thing and len(thing) > 1
+
+
+def has_one_or_more_items(thing: Any) -> bool:
+    """Return whether or not the given thing has a length of at least one."""
+    return thing and len(thing) >= 1
+
+
+def has_one_item(thing: Any) -> bool:
+    """Return whether or not the given thing has a length of at least one."""
+    return thing and len(thing) == 1
+
+
+def request_or_read(path):
+    """If the given path is a URL, request the URL and return the content; if the path exists read the file.
+
+    Otherwise, just return the string and assume it is the input itself.
+    """
+    from d8s_file_system import file_exists, file_read
+    from d8s_networking import get
+    from d8s_urls import is_url
+
+    # TODO: improve the code below; it is all wrapped in a try-except block primarily due to...
+    # ValueErrors when trying to check if the file exists
+    try:
+        if is_url(path):
+            return get(path, process_response=True)
+        # TODO: do more here to make sure the path looks like a file path
+        elif file_exists(path):
+            return file_read(path)
+        else:
+            return path
+    except ValueError:
+        return path
+
+
+def request_or_read_first_arg(func):
+    """If the first arg is a url - request the URL. If it is a file path, try to read the file.
+
+    If it is neither a URL nor file path, return the content of the first arg.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        first_arg = args[0]
+        other_args = args[1:]
+
+        new_first_arg = request_or_read(first_arg)
+
+        return func(new_first_arg, *other_args, **kwargs)
+
+    return wrapper
+
+
+@listify_first_arg
+def is_sorted(iterable, *, descending: bool = False) -> bool:
+    """Return whether or not the iterable is sorted."""
+    return sorted(iterable, reverse=descending) == iterable
+
+
+@listify_first_arg
+def first_unsorted_value(iterable, *, descending: bool = False) -> Any:
+    """Return the first unsorted value in the iterable."""
+    sorted_items = sorted(iterable, reverse=descending)
+    for original_item, sorted_item in zip(iterable, sorted_items):
+        if original_item != sorted_item:
+            return original_item
+
+
+@listify_first_arg
+@copy_first_arg
+def last_unsorted_value(iterable, *, descending: bool = False) -> Any:
+    """Return the last unsorted value in the iterable."""
+    # we reverse everything so we can iterate through the iterable and return the first item that is not sorted
+    iterable.reverse()
+    descending = not descending
+
+    sorted_items = sorted(iterable, reverse=descending)
+    for original_item, sorted_item in zip(iterable, sorted_items):
+        if original_item != sorted_item:
+            return original_item
+
+
+@listify_first_arg
+def unsorted_values(iterable, *, descending: bool = False) -> Iterable[Any]:
+    """."""
+    sorted_items = sorted(iterable, reverse=descending)
+    for original_item, sorted_item in zip(iterable, sorted_items):
+        if original_item != sorted_item:
+            yield original_item
+
+
+@listify_first_arg
+def sorted_values(iterable, *, descending: bool = False) -> Iterable[Any]:
+    """."""
+    sorted_items = sorted(iterable, reverse=descending)
+    for original_item, sorted_item in zip(iterable, sorted_items):
+        if original_item == sorted_item:
+            yield original_item
+
+
+def ignore_errors(function, *args, **kwargs):
+    """."""
+    result = None
+    try:
+        result = function(*args, **kwargs)
+    except:  # pylint: disable=W0702  # noqa: E722
+        pass
+
+    return result
+
+
+def zip_if_same_length(*iterables, debug_failure: bool = False):
+    """Zip the given iterables if they are the same length.
+
+    If they are not the same length, raise an assertion error.
+    """
+    from d8s_lists import iterables_are_same_length
+
+    if not iterables_are_same_length(*iterables, debug_failure=debug_failure):
+        message = "The given iterables are not the same length."
+        raise ValueError(message)
+
+    for i in zip(*iterables):
+        yield i
+
+
+def unique_items(iterable_a: Any, iterable_b: Any) -> Dict[str, Set[Any]]:
+    """Find the values unique to iterable_a and iterable_b (relative to one another)."""
+    unique_items_list: Dict[str, Set[Any]] = {"a": set(), "b": set()}
+
+    set_a = set(iterable_a)
+    set_b = set(iterable_b)
+    unique_items_list["a"] = set_a.difference(set_b)
+    unique_items_list["b"] = set_b.difference(set_a)
+
+    return unique_items_list
+
+
+def prettify(thing: Any, *args):
+    """."""
+    import pprint
+
+    p = pprint.PrettyPrinter(*args)
+    return p.pformat(thing)
+
+
+def pretty_print(thing: Any, *args):
+    """."""
+    print(prettify(thing, *args))
+
+
+def subprocess_run(command, input_=None):
+    """Run the given command as if it were run in a command line."""
+    import shlex
+    import subprocess
+
+    if isinstance(command, str):
+        command_list = shlex.split(command)
+    else:
+        command_list = command
+
+    process = subprocess.run(command_list, input=input_, universal_newlines=True, capture_output=True)
+    result = (process.stdout, process.stderr)
+    return result
+
+
+def stringify_first_arg(func):
+    """Decorator to convert the first argument to a string."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        first_arg_string = str(args[0])
+        other_args = args[1:]
+        return func(first_arg_string, *other_args, **kwargs)
+
+    return wrapper
+
+
+def retry_if_no_result(wait_seconds=10):
+    """Decorator to call the given function and recall it if it returns nothing."""
+
+    def retry_decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            import time
+
+            return_value = func(*args, **kwargs)
+
+            if return_value:
+                return return_value
+            else:
+                time.sleep(wait_seconds)
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return retry_decorator
+
+
+def map_first_arg(func):
+    """If the first argument is a list or tuple, iterate through each item in the list and send it to the function."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        iterable_arg = args[0]
+        other_args = args[1:]
+
+        # TODO: define these types elsewhere
+        if isinstance(iterable_arg, (list, set, tuple)):
+            results = []
+            # iterate through list argument sending each item to function (along with the other arguments/kwargs)
+            for item in iterable_arg:
+                results.append(func(item, *other_args, **kwargs))
+            return results
+        else:
+            return func(*args, **kwargs)
+
+    return wrapper
+
+
+def repeat_concurrently(n: int = 10):
+    """Repeat the decorated function concurrently n times."""
+
+    def actual_decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            import concurrent.futures
+
+            results = []
+
+            with concurrent.futures.ThreadPoolExecutor() as executor:
+                for __ in range(n):
+                    function_submission = executor.submit(func, *args, **kwargs)
+                    yield function_submission.result()
+
+            return results
+
+        return wrapper
+
+    return actual_decorator
+
+
+def validate_keyword_arg_value(
+    keyword: str, valid_keyword_values: Iterable[Any], fail_if_keyword_not_found: bool = True
+):
+    """Validate that the value for the given keyword is in the list of valid_keyword_values."""
+
+    def actual_decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            keyword_exists = keyword in kwargs
+            if not keyword_exists and fail_if_keyword_not_found:
+                message = f'No keyword "{keyword}".'
+                raise ValueError(message)
+            elif keyword_exists and kwargs[keyword] not in valid_keyword_values:
+                message = (
+                    f'The value of the "{keyword}" keyword argument is not valid '
+                    + f"(valid values are: {valid_keyword_values})."
+                )
+                raise ValueError(message)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return actual_decorator
+
+
+def validate_arg_value(arg_index: StrOrNumberType, valid_values: Iterable[Any]):
+    """Validate that the value of the argument at the given arg_index is in the list of valid_values."""
+
+    def actual_decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            arg_index_int = int(arg_index)
+
+            try:
+                arg_value = args[arg_index_int]
+            except IndexError as e:
+                message = f"No argument at index {arg_index_int}."
+                raise ValueError(message) from e
+
+            if arg_value not in valid_values:
+                message = (
+                    f'The value of the argument at index {arg_index} (whose value is "{arg_value}") '
+                    + "is not valid (valid values are: {valid_values})."
+                )
+                raise ValueError(message)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return actual_decorator
+
+
+def wait_and_retry_on_failure(wait_seconds=10):
+    """Try to call the given function.
+
+    If there is an exception thrown by the function, wait for wait_seconds and try again.
+    """
+
+    def retry_decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            import time
+
+            try:
+                return func(*args, **kwargs)
+            except:  # pylint: disable=W0702  # noqa: E722
+                time.sleep(wait_seconds)
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return retry_decorator

d8s_utility/utility_temp_utils.py

@@ -0,0 +1,16 @@
+import functools
+
+
+def listify_first_arg(func):
+    """Make sure the first argument is a list... if it is not, listify it."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        first_arg = args[0]
+        other_args = args[1:]
+        if not isinstance(first_arg, list):
+            first_arg = list(first_arg)
+
+        return func(first_arg, *other_args, **kwargs)
+
+    return wrapper

d8s_utility-0.9.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: d8s_utility
+Version: 0.9.0
+Summary: Democritus functions for working with utility functions.
+Project-URL: Source, https://github.com/democritus-project/d8s-utility
+Project-URL: Issues, https://github.com/democritus-project/d8s-utility/issues
+Author: Floyd Hightower
+License: GNU Lesser General Public License v3
+License-File: COPYING
+License-File: COPYING.LESSER
+Keywords: democritus,python,utilities,utility,utility-functions,utility-functions-utility,utils
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: d8s-file-system<1.0,>=0.10.0
+Requires-Dist: d8s-lists<1.0,>=0.8.0
+Requires-Dist: d8s-networking<1.0,>=0.4.2
+Requires-Dist: d8s-urls<1.0,>=0.6.0
+Description-Content-Type: text/markdown
+
+# Democritus Utility
+
+[![PyPI](https://img.shields.io/pypi/v/d8s-utility.svg)](https://pypi.python.org/pypi/d8s-utility)
+[![CI](https://github.com/democritus-project/d8s-utility/workflows/CI/badge.svg)](https://github.com/democritus-project/d8s-utility/actions)
+[![Lint](https://github.com/democritus-project/d8s-utility/workflows/Lint/badge.svg)](https://github.com/democritus-project/d8s-utility/actions)
+[![codecov](https://codecov.io/gh/democritus-project/d8s-utility/branch/main/graph/badge.svg?token=V0WOIXRGMM)](https://codecov.io/gh/democritus-project/d8s-utility)
+[![The Democritus Project uses semver version 2.0.0](https://img.shields.io/badge/-semver%20v2.0.0-22bfda)](https://semver.org/spec/v2.0.0.html)
+[![The Democritus Project uses ruff to format and lint code](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://choosealicense.com/licenses/lgpl-3.0/)
+
+Democritus functions<sup>[1]</sup> for working with utility functions.
+
+[1] Democritus functions are <i>simple, effective, modular, well-tested, and well-documented</i> Python functions.
+
+We use `d8s` (pronounced "dee-eights") as an abbreviation for `democritus` (you can read more about this [here](https://github.com/democritus-project/roadmap#what-is-d8s)).
+
+## Installation
+
+```
+pip install d8s-utility
+```
+
+## Usage
+
+You import the library like:
+
+```python
+from d8s_utility import *
+```
+
+Once imported, you can use any of the functions listed below.
+
+## Functions
+
+  - ```python
+    def copy_first_arg(func):
+        """Decorator to make a copy of the first argument and pass into the func."""
+    ```
+  - ```python
+    def has_more_than_one_item(thing: Any) -> bool:
+        """Return whether or not the given thing has a length of at least one."""
+    ```
+  - ```python
+    def has_one_or_more_items(thing: Any) -> bool:
+        """Return whether or not the given thing has a length of at least one."""
+    ```
+  - ```python
+    def has_one_item(thing: Any) -> bool:
+        """Return whether or not the given thing has a length of at least one."""
+    ```
+  - ```python
+    def request_or_read(path):
+        """If the given path is a URL, request the URL and return the content; if the path exists read the file.
+    
+    Otherwise, just return the string and assume it is the input itself."""
+    ```
+  - ```python
+    def request_or_read_first_arg(func):
+        """If the first arg is a url - request the URL. If it is a file path, try to read the file.
+    
+    If it is neither a URL nor file path, return the content of the first arg."""
+    ```
+  - ```python
+    def is_sorted(iterable, *, descending: bool = False) -> bool:
+        """Return whether or not the iterable is sorted."""
+    ```
+  - ```python
+    def first_unsorted_value(iterable, *, descending: bool = False) -> Any:
+        """Return the first unsorted value in the iterable."""
+    ```
+  - ```python
+    def last_unsorted_value(iterable, *, descending: bool = False) -> Any:
+        """Return the last unsorted value in the iterable."""
+    ```
+  - ```python
+    def unsorted_values(iterable, *, descending: bool = False) -> Iterable[Any]:
+        """."""
+    ```
+  - ```python
+    def sorted_values(iterable, *, descending: bool = False) -> Iterable[Any]:
+        """."""
+    ```
+  - ```python
+    def ignore_errors(function, *args, **kwargs):
+        """."""
+    ```
+  - ```python
+    def zip_if_same_length(*iterables, debug_failure: bool = False):
+        """Zip the given iterables if they are the same length.
+    
+    If they are not the same length, raise an assertion error."""
+    ```
+  - ```python
+    def unique_items(iterable_a: Any, iterable_b: Any) -> Dict[str, Set[Any]]:
+        """Find the values unique to iterable_a and iterable_b (relative to one another)."""
+    ```
+  - ```python
+    def prettify(thing: Any, *args):
+        """."""
+    ```
+  - ```python
+    def pretty_print(thing: Any, *args):
+        """."""
+    ```
+  - ```python
+    def subprocess_run(command, input_=None):
+        """Run the given command as if it were run in a command line."""
+    ```
+  - ```python
+    def stringify_first_arg(func):
+        """Decorator to convert the first argument to a string."""
+    ```
+  - ```python
+    def retry_if_no_result(wait_seconds=10):
+        """Decorator to call the given function and recall it if it returns nothing."""
+    ```
+  - ```python
+    def map_first_arg(func):
+        """If the first argument is a list or tuple, iterate through each item in the list and send it to the function."""
+    ```
+  - ```python
+    def repeat_concurrently(n: int = 10):
+        """Repeat the decorated function concurrently n times."""
+    ```
+  - ```python
+    def validate_keyword_arg_value(
+        keyword: str, valid_keyword_values: Iterable[Any], fail_if_keyword_not_found: bool = True
+    ):
+        """Validate that the value for the given keyword is in the list of valid_keyword_values."""
+    ```
+  - ```python
+    def validate_arg_value(arg_index: StrOrNumberType, valid_values: Iterable[Any]):
+        """Validate that the value of the argument at the given arg_index is in the list of valid_values."""
+    ```
+  - ```python
+    def wait_and_retry_on_failure(wait_seconds=10):
+        """Try to call the given function.
+    
+    If there is an exception thrown by the function, wait for wait_seconds and try again."""
+    ```
+
+## Development
+
+👋 &nbsp;If you want to get involved in this project, we have some short, helpful guides below:
+
+- [contribute to this project 🥇][contributing]
+- [test it 🧪][local-dev]
+- [lint it 🧹][local-dev]
+- [explore it 🔭][local-dev]
+
+If you have any questions or there is anything we did not cover, please raise an issue and we'll be happy to help.
+
+## Credits
+
+This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and Floyd Hightower's [Python project template](https://github.com/fhightower-templates/python-project-template).
+
+[contributing]: https://github.com/democritus-project/.github/blob/main/CONTRIBUTING.md#contributing-a-pr-
+[local-dev]: https://github.com/democritus-project/.github/blob/main/CONTRIBUTING.md#local-development-

d8s_utility-0.9.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+d8s_utility/__init__.py,sha256=8fIpSWRC8iZikD1Qn7qaUQq-jMf1CjSwdLEUy0vfnyY,123
+d8s_utility/utility.py,sha256=FSjrP3ZUsceci09Pa9Wkikq3UNJqoQYw5-BjqiGjtIw,11012
+d8s_utility/utility_temp_utils.py,sha256=s63AwfDKD9bU8kBUKEM5QXQH_dtHwvFEyr7bDWwKLq8,405
+d8s_utility-0.9.0.dist-info/METADATA,sha256=D2HH4eWPsN1-ImuVbVb-HxmA3Af1WUqfCMufPgyQ8WU,7534
+d8s_utility-0.9.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+d8s_utility-0.9.0.dist-info/licenses/COPYING,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
+d8s_utility-0.9.0.dist-info/licenses/COPYING.LESSER,sha256=z72U6pv-bQgJ_Svr4uCXnMjemsp38aSerhHEdEAOMJ4,7632
+d8s_utility-0.9.0.dist-info/RECORD,,

d8s_utility-0.9.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any