pybear 0.2.0__py3-none-any.whl

pybear/__init__.py

@@ -0,0 +1,24 @@
+# Author:
+#         Bill Sousa
+#
+# License: BSD 3 clause
+#
+
+
+
+from ._version import __version__
+from ._version import __version_tuple__
+
+__all__ = [
+    "base",
+    "feature_extraction",
+    "model_selection",
+    "new_numpy",
+    "preprocessing",
+    "utilities",
+    "__version__"
+]
+
+
+
+

pybear/_version.py

@@ -0,0 +1,38 @@
+# Author:
+#         Bill Sousa
+#
+# License: BSD 3 clause
+#
+
+
+from typing import Tuple
+from typing_extensions import Union
+import numpy as np
+
+
+try:
+    from importlib.metadata import version as get_version
+except ImportError:
+    # For older Python versions, use importlib-metadata package
+    from importlib_metadata import version as get_version
+
+
+version: str
+__version__: str
+VERSION_TUPLE = Tuple[Union[int, str], ...]
+version_tuple: VERSION_TUPLE
+__version_tuple__: VERSION_TUPLE
+
+__version__ = version = get_version('pybear')
+dot_idxs = np.arange(len(__version__))[np.array(list(__version__)) == '.']
+dot_idxs = list(map(int, dot_idxs))
+__version_tuple__ = version_tuple = (
+    int(__version__[:dot_idxs[0]]),
+    int(__version__[dot_idxs[0]+1:dot_idxs[1]]),
+    int(__version__[dot_idxs[1]+1:])
+)
+
+
+
+
+

pybear/base/_DictMenuPrint.py

@@ -0,0 +1,342 @@
+# Author:
+#         Bill Sousa
+#
+# License: BSD 3 clause
+#
+
+
+
+from typing import Optional
+from typing_extensions import Union
+
+import numbers
+
+from ._validate_user_input import validate_user_str_cs
+
+
+
+class DictMenuPrint:
+    """Manage the display and operation of an interactive user menu.
+
+    Display the allowed sub-menu options from a full menu to the screen.
+
+    The :meth:`choose` method displays the allowed menu options and
+    offers a validated prompt to select one of the options.
+
+    Parameters
+    ----------
+    MENU_DICT : dict[str, str]
+        Required. A Dictionary of unit-length alpha characters as keys
+        and the descriptions of their associated actions as values. Keys
+        are case-sensitive.
+    disp_width : Optional[numbers.Integral], default=80
+        The maximum number of characters to display per line.
+    fixed_col_width : Optional[Union[numbers.Integral, None]], default=None
+        Set a fixed width for each column of menu items in the display.
+        DMP will determine a number of columns that causes the overall
+        width of the display to be less than or equal to `disp_width`.
+    allowed : Optional[Union[str, None]], default=None
+        Can only enter this if `disallowed` is not entered, cannot enter
+        both. The action keys that are allowed to be selected from the
+        full selection available in `MENU_DICT`. case-sensitive. Enter
+        as a contiguous sequence of characters.
+    disallowed : Optional[Union[str, None]], default=None
+        Can only enter this if `allowed` is not entered, cannot enter
+        both. The action keys that are not allowed to be selected from
+        `MENU_DICT`. `allowed` becomes the space of action keys that are
+        not disallowed. Case-sensitive. Enter as a contiguous sequence
+        of characters.
+
+    Attributes
+    ----------
+    allowed : str
+        The positive space out of `MENU_DICT` that the user is allowed
+        to select from. This attribute is always the set of allowed
+        options determined at instantiation. The instance attribute IS
+        NOT overwritten by any `allowed` or `disallowed` passed to the
+        methods. The `allowed` passed to or determined by the methods
+        is used only temporarily in place of the permanent `allowed`
+        attribute. The menu associated with the stored `allowed`
+        attribute is always available as the default menu.
+    all_allowed_str : str
+        The full set of possible options taken from the keys of
+        `MENU_DICT`.
+    disp_width : numbers.Integral
+        The maximum character display width passed at instantiation or
+        the default if not passed.
+    fixed_col_width : numbers.Integral
+        The fixed column width within the full display width passed at
+        instantiation or the default if not passed.
+    MENU_DICT : dict[str, str]
+        The `MENU_DICT` passed at instantiation.
+
+    Examples
+    --------
+    >>> MENU_DICT = {
+    ...    'a': 'Apply Option 1', 'b': 'Apply Option 2',
+    ...    'c': 'Apply Option 3', 'd': 'Apply Option 4'
+    ... }
+    >>> DMP = DictMenuPrint(
+    ...    MENU_DICT,
+    ...    disp_width = 80,
+    ...    fixed_col_width = None,
+    ...    allowed = 'abcd',
+    ...    disallowed = None
+    ... )
+    >>> DMP.choose(allowed='ab', prompt='pick one')   # doctest:+SKIP
+    a) Apply Option 1     b) Apply Option 2
+    pick one >
+
+    """
+
+
+    def __init__(
+        self,
+        MENU_DICT:dict[str, str],
+        *,
+        disp_width:Optional[numbers.Integral] = 80,
+        fixed_col_width:Optional[Union[numbers.Integral, None]] = None,
+        allowed:Optional[Union[str, None]] = None,
+        disallowed:Optional[Union[str, None]] = None
+    ) -> None:
+        """Initialize the DictMenuPrint instance."""
+
+        # validation v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v
+
+        # MENU_DICT -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+        if not isinstance(MENU_DICT, dict):
+            raise TypeError(f"'MENU_DICT' must be a dictionary")
+
+        if len(MENU_DICT) == 0:
+            raise ValueError(f"'MENU_DICT' cannot be empty")
+
+        if not all(map(isinstance, MENU_DICT, (str for _ in MENU_DICT))):
+            raise TypeError(f"MENU_DICT keys must be str.")
+
+        if not all(map(
+            isinstance, MENU_DICT.values(), (str for _ in MENU_DICT)
+        )):
+            raise TypeError(f"MENU_DICT values must be str.")
+
+        if max(map(len, MENU_DICT.keys())) != 1:
+            raise ValueError(f"Illegal key in MENU_DICT, len must be 1.")
+
+        self.MENU_DICT = MENU_DICT
+        # END MENU_DICT -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+
+        # MENU_DICT cant have duplicate keys, its a dictionary
+        self.all_allowed_str = ''.join(MENU_DICT.keys())
+
+        # disp_width -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+        if not isinstance(disp_width, numbers.Integral):
+            raise TypeError(f"'disp_width' must be a non-boolean integer")
+        if isinstance(disp_width, bool):
+            raise TypeError(f"'disp_width' must be a non-boolean integer")
+        if disp_width < 10:
+            raise ValueError(f"'disp_width' must be >=10")
+
+        self.disp_width = disp_width
+        # END disp_width -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+
+        # fixed_column_width -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+        if not isinstance(fixed_col_width, (numbers.Integral, type(None))):
+            raise TypeError(f"'fixed_col_width' must be an integer or None")
+        if isinstance(fixed_col_width, bool):
+            raise TypeError(f"'fixed_col_width' must be a non-boolean integer")
+        if fixed_col_width is not None and fixed_col_width < 10:
+            raise ValueError(f"'disp_width' must be >=10")
+        if fixed_col_width and fixed_col_width > disp_width:
+            raise ValueError(f"'fixed_col_width' must be <= 'disp_width'")
+
+        self.fixed_col_width = fixed_col_width
+        # END fixed_column_width -- -- -- -- -- -- -- -- -- -- -- -- -- --
+
+        self.allowed = self._val_allowed_disallowed_and_get_allowed(
+            allowed,
+            disallowed
+        )
+
+        # END allowed / disallowed -- -- -- -- -- -- -- -- -- -- -- --
+
+        # END validation v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v^v
+
+
+    def _val_allowed_disallowed_and_get_allowed(
+        self,
+        _allowed:Optional[Union[str, None]] = None,
+        _disallowed:Optional[Union[str, None]] = None
+    ) -> str:
+        """Validate `allowed` & `disallowed`, determine allowed, and
+        return it.
+
+        Parameters
+        ----------
+        _allowed : Optional[Union[str, None]], default = None
+            Options in the full menu that the user is allowed to choose.
+        _disallowed : Optional[Union[str, None]], default = None
+            Options in the full menu that the user is not allowed to
+            choose.
+
+        Returns
+        -------
+        __ : str
+            The allowed subset from `all_allowed_str`, arrived at by
+            applying the characters in `allowed` and `disallowed` against
+            the characters in `all_allowed_str`.
+
+        """
+
+        # allowed / disallowed -- -- -- -- -- -- -- -- -- -- -- -- -- --
+
+        if not isinstance(_allowed, (str, type(None))):
+            raise TypeError(f"'allowed' must be a str or None")
+
+        if not isinstance(_disallowed, (str, type(None))):
+            raise TypeError(f"'disallowed' must be a str or None")
+
+        _allowed = None if _allowed == '' else _allowed
+        _disallowed = None if _disallowed == '' else _disallowed
+
+        if _allowed is not None and _disallowed is not None:
+            raise ValueError(
+                f"cannot enter both 'allowed' and 'disallowed', must be "
+                f"one or the other or neither."
+            )
+        elif _allowed is None and _disallowed is None:
+            _allowed = self.all_allowed_str
+
+        elif _allowed is not None:   #  _disallowed is None
+
+            # CLEAR OUT ANY DUPLICATES THAT MAY BE IN ALLOWED
+            _allowed = ''.join(list(set(_allowed)))
+
+            if not all(map(lambda x: x in self.all_allowed_str, _allowed)):
+                raise ValueError(
+                    f"Invalid key in 'allowed' ({_allowed}), must be in "
+                    f"{self.all_allowed_str}."
+                )
+
+        elif _disallowed is not None:   # _allowed is None
+
+            # CLEAR OUT ANY DUPLICATES THAT MAY BE IN disallowed
+            _disallowed = ''.join(list(set(_disallowed)))
+
+            if not all(map(lambda x: x in self.all_allowed_str, _disallowed)):
+                raise ValueError(
+                    f"Invalid key in 'disallowed' ({_disallowed}), must "
+                    f"be in {self.all_allowed_str}."
+                )
+
+            _allowed = ''.join(set(self.all_allowed_str) - set(_disallowed))
+
+        if len(_allowed) == 0:
+            raise ValueError(
+                f"the given values for 'allowed' or 'disallowed' have left "
+                f"no allowed menu choices."
+            )
+
+        return _allowed
+
+
+    def _generate_subdict_and_print(self, _allowed: str):
+        """Print the allowed menu options to screen.
+
+        Parameters
+        ----------
+        allowed : str
+            The subset of the fullset of menu options that are to be
+            printed to screen.
+
+        Returns
+        -------
+        None
+
+        """
+
+        SUB_DICT = {
+            k: v for k, v in self.MENU_DICT.items() if k in _allowed
+        }
+
+        if self.fixed_col_width is not None:
+            num_cols = self.disp_width // int(self.fixed_col_width)
+            ljust = int(self.fixed_col_width)
+        else:  # fixed_col_width is None
+            # +3 FOR '(' + <the menu option> + ')' +2 FOR BUFFER
+            _max_desc_len = max(map(len, SUB_DICT.values())) + 3 + 2
+            num_cols = max(1, self.disp_width // _max_desc_len)
+            ljust = self.disp_width // num_cols
+            del _max_desc_len
+
+        # attrs are MENU_DICT, SUB_DICT, all_allowed_str, fixed_column_width,
+        # allowed, num_cols, ljust
+
+        for itr, (k, v) in enumerate(SUB_DICT.items()):
+            print_line = f'{v[:ljust-5]}({k})'.ljust(ljust)
+            if itr % num_cols < num_cols - 1:
+                print(print_line, end='')
+            else:
+                print(print_line)
+
+        del print_line
+
+
+    def choose(
+        self,
+        prompt:str,
+        *,
+        allowed:Optional[Union[str, None]] = None,
+        disallowed:Optional[Union[str, None]] = None
+    ) -> str:
+        """Displays the allowed menu options to the screen.
+
+        Prompts the user for a case-sensitive selection. Returns the
+        single-character action command selected by the user. The default
+        menu associated with the `allowed` action keys that were passed
+        at instantiation is available by passing no kwargs, or pass
+        custom `allowed` or `disallowed` to generate a different menu
+        for the one time. The custom `allowed` or `disallowed` that are
+        passed here DO NOT overwrite the `allowed` attribute of the
+        instance, that will always be available as the default menu.
+
+        Parameters
+        ----------
+        allowed : Optional[Union[str, None]], default=None
+            Can only enter this if `disallowed` is not entered,
+            cannot enter both. The action keys that are allowed to be
+            selected from the full section available in `MENU_DICT`.
+            Case-sensitive. Enter as a contiguous sequence of characters.
+        disallowed : Optional[Union[str, None]], default=None
+            Can only enter this if `allowed` is not entered, cannot
+            enter both. The action keys that are not allowed to be
+            selected from `MENU_DICT`. `allowed` becomes the space of
+            action keys that are not disallowed. Case-sensitive. Enter
+            as a contiguous sequence of characters.
+
+        Returns
+        -------
+        char : str
+            The value of the menu item selected by the user.
+
+        """
+
+        if not isinstance(prompt, str):
+            raise TypeError(f"'prompt' must be a string")
+
+        if allowed is None and disallowed is None:
+            _allowed = self.allowed
+        else:
+            _allowed = \
+                self._val_allowed_disallowed_and_get_allowed(
+                    allowed,
+                    disallowed
+                )
+
+        self._generate_subdict_and_print(_allowed)
+
+
+        return validate_user_str_cs(f'\n{prompt} > ', _allowed)
+
+
+
+
+

pybear/base/__init__.py

@@ -0,0 +1,99 @@
+# Author:
+#         Bill Sousa
+#
+# License: BSD 3 clause
+#
+
+
+
+from ._cast_to_ndarray import cast_to_ndarray
+from ._check_1D_num_sequence import check_1D_num_sequence
+from ._check_1D_str_sequence import check_1D_str_sequence
+from ._check_2D_num_array import check_2D_num_array
+from ._check_2D_str_array import check_2D_str_array
+from ._check_dtype import check_dtype
+from ._check_feature_names import check_feature_names
+from ._check_n_features import check_n_features
+from ._check_is_finite import check_is_finite
+from ._check_is_fitted import check_is_fitted
+from ._check_scipy_sparse import check_scipy_sparse
+from ._check_shape import check_shape
+from ._copy_X import copy_X
+from ._DictMenuPrint import DictMenuPrint
+from ._ensure_2D import ensure_2D
+from ._get_feature_names import get_feature_names
+from ._get_feature_names_out import get_feature_names_out
+from ._is_fitted import is_fitted
+from ._num_features import num_features
+from ._num_samples import num_samples
+from ._set_order import set_order
+from ._validate_data import validate_data
+from ._validate_user_input import (
+    validate_user_str,
+    validate_user_str_cs,
+    validate_user_mstr,
+    validate_user_int,
+    validate_user_float,
+    user_entry,
+    ValidateUserDate
+)
+
+
+from .mixins._FeatureMixin import FeatureMixin
+from .mixins._FileDumpMixin import FileDumpMixin
+from .mixins._FitTransformMixin import FitTransformMixin
+from .mixins._GetParamsMixin import GetParamsMixin
+from .mixins._ReprMixin import ReprMixin
+from .mixins._SetOutputMixin import SetOutputMixin
+from .mixins._SetParamsMixin import SetParamsMixin
+
+from .exceptions._exceptions import NotFittedError
+
+
+
+__all__ = [
+    'cast_to_ndarray',
+    'check_1D_num_sequence',
+    'check_1D_str_sequence',
+    'check_2D_num_array',
+    'check_2D_str_array',
+    'check_dtype',
+    'check_feature_names',
+    'check_n_features',
+    'check_is_finite',
+    'check_is_fitted',
+    'check_scipy_sparse',
+    'check_shape',
+    'copy_X',
+    'DictMenuPrint',
+    'ensure_2D',
+    'get_feature_names',
+    'get_feature_names_out',
+    'is_fitted',
+    'num_features',
+    'num_samples',
+    'set_order',
+    'user_entry',
+    'validate_data',
+    'validate_user_float',
+    'validate_user_int',
+    'validate_user_mstr',
+    'validate_user_str',
+    'validate_user_str_cs',
+    'ValidateUserDate',
+    'FeatureMixin',
+    'FileDumpMixin',
+    'FitTransformMixin',
+    'GetParamsMixin',
+    'ReprMixin',
+    'SetOutputMixin',
+    'SetParamsMixin',
+    'NotFittedError'
+]
+
+
+
+
+
+
+

pybear/base/__type_aliases.py

@@ -0,0 +1,45 @@
+# Author:
+#         Bill Sousa
+#
+# License: BSD 3 clause
+#
+
+
+
+from typing_extensions import (
+    TypeAlias,
+    Union
+)
+import numpy.typing as npt
+
+import pandas as pd
+import polars as pl
+import scipy.sparse as ss
+
+
+
+Python1DTypes: TypeAlias = Union[list, tuple, set]
+Python2DTypes: TypeAlias = Union[list[list], tuple[tuple]]
+PythonTypes: TypeAlias = Union[list, tuple, set, list[list], tuple[tuple]]
+
+Numpy1DTypes: TypeAlias = npt.NDArray
+Numpy2DTypes: TypeAlias = npt.NDArray
+NumpyTypes: TypeAlias = npt.NDArray
+
+Pandas1DTypes: TypeAlias = pd.core.series.Series
+Pandas2DTypes: TypeAlias = pd.core.frame.DataFrame
+PandasTypes: TypeAlias = Union[pd.core.series.Series, pd.core.frame.DataFrame]
+
+Polars1DTypes: TypeAlias = pl.series.Series
+Polars2DTypes: TypeAlias = pl.dataframe.DataFrame
+PolarsTypes: TypeAlias = Union[pl.series.Series, pl.dataframe.DataFrame]
+
+ScipySparseTypes: TypeAlias = Union[
+    ss.csc_matrix, ss.csc_array, ss.csr_matrix, ss.csr_array,
+    ss.coo_matrix, ss.coo_array, ss.dia_matrix, ss.dia_array,
+    ss.lil_matrix, ss.lil_array, ss.dok_matrix, ss.dok_array,
+    ss.bsr_matrix, ss.bsr_array
+]
+
+
+