meerschaum.utils.misc

   1#! /usr/bin/env python
   2# -*- coding: utf-8 -*-
   3# vim:fenc=utf-8
   4"""
   5Miscellaneous functions go here
   6"""
   7
   8from __future__ import annotations
   9import sys
  10from datetime import timedelta, datetime, timezone
  11from meerschaum.utils.typing import (
  12    Union,
  13    Any,
  14    Callable,
  15    Optional,
  16    List,
  17    Dict,
  18    SuccessTuple,
  19    Iterable,
  20    PipesDict,
  21    Tuple,
  22    InstanceConnector,
  23    Hashable,
  24    Generator,
  25    Iterator,
  26    TYPE_CHECKING,
  27)
  28import meerschaum as mrsm
  29if TYPE_CHECKING:
  30    import collections
  31
  32__pdoc__: Dict[str, bool] = {
  33    'to_pandas_dtype': False,
  34    'filter_unseen_df': False,
  35    'add_missing_cols_to_df': False,
  36    'parse_df_datetimes': False,
  37    'df_from_literal': False,
  38    'get_json_cols': False,
  39    'get_unhashable_cols': False,
  40    'enforce_dtypes': False,
  41    'get_datetime_bound_from_df': False,
  42    'df_is_chunk_generator': False,
  43    'choices_docstring': False,
  44    '_get_subaction_names': False,
  45}
  46
  47
  48def add_method_to_class(
  49        func: Callable[[Any], Any],
  50        class_def: 'Class',
  51        method_name: Optional[str] = None,
  52        keep_self: Optional[bool] = None,
  53    ) -> Callable[[Any], Any]:
  54    """
  55    Add function `func` to class `class_def`.
  56
  57    Parameters
  58    ----------
  59    func: Callable[[Any], Any]
  60        Function to be added as a method of the class
  61
  62    class_def: Class
  63        Class to be modified.
  64
  65    method_name: Optional[str], default None
  66        New name of the method. None will use func.__name__ (default).
  67
  68    Returns
  69    -------
  70    The modified function object.
  71
  72    """
  73    from functools import wraps
  74
  75    is_class = isinstance(class_def, type)
  76    
  77    @wraps(func)
  78    def wrapper(self, *args, **kw):
  79        return func(*args, **kw)
  80
  81    if method_name is None:
  82        method_name = func.__name__
  83
  84    setattr(class_def, method_name, (
  85            wrapper if ((is_class and keep_self is None) or keep_self is False) else func
  86        )
  87    )
  88
  89    return func
  90
  91
  92def generate_password(length: int = 12) -> str:
  93    """Generate a secure password of given length.
  94
  95    Parameters
  96    ----------
  97    length : int, default 12
  98        The length of the password.
  99
 100    Returns
 101    -------
 102    A random password string.
 103
 104    """
 105    import secrets, string
 106    return ''.join((secrets.choice(string.ascii_letters) for i in range(length)))
 107
 108def is_int(s : str) -> bool:
 109    """
 110    Check if string is an int.
 111
 112    Parameters
 113    ----------
 114    s: str
 115        The string to be checked.
 116        
 117    Returns
 118    -------
 119    A bool indicating whether the string was able to be cast to an integer.
 120
 121    """
 122    try:
 123        float(s)
 124    except Exception as e:
 125        return False
 126    
 127    return float(s).is_integer()
 128
 129
 130def string_to_dict(
 131        params_string: str
 132    ) -> Dict[str, Any]:
 133    """
 134    Parse a string into a dictionary.
 135    
 136    If the string begins with '{', parse as JSON. Otherwise use simple parsing.
 137
 138    Parameters
 139    ----------
 140    params_string: str
 141        The string to be parsed.
 142        
 143    Returns
 144    -------
 145    The parsed dictionary.
 146
 147    Examples
 148    --------
 149    >>> string_to_dict("a:1,b:2") 
 150    {'a': 1, 'b': 2}
 151    >>> string_to_dict('{"a": 1, "b": 2}')
 152    {'a': 1, 'b': 2}
 153
 154    """
 155    if params_string == "":
 156        return {}
 157
 158    import json
 159
 160    ### Kind of a weird edge case.
 161    ### In the generated compose file, there is some weird escaping happening,
 162    ### so the string to be parsed starts and ends with a single quote.
 163    if (
 164        isinstance(params_string, str)
 165        and len(params_string) > 4
 166        and params_string[1] == "{"
 167        and params_string[-2] == "}"
 168    ):
 169        return json.loads(params_string[1:-1])
 170    if str(params_string).startswith('{'):
 171        return json.loads(params_string)
 172
 173    import ast
 174    params_dict = {}
 175    for param in params_string.split(","):
 176        _keys = param.split(":")
 177        keys = _keys[:-1]
 178        try:
 179            val = ast.literal_eval(_keys[-1])
 180        except Exception as e:
 181            val = str(_keys[-1])
 182
 183        c = params_dict
 184        for _k in keys[:-1]:
 185            try:
 186                k = ast.literal_eval(_k)
 187            except Exception as e:
 188                k = str(_k)
 189            if k not in c:
 190                c[k] = {}
 191            c = c[k]
 192
 193        c[keys[-1]] = val
 194
 195    return params_dict
 196
 197
 198def parse_config_substitution(
 199        value: str,
 200        leading_key: str = 'MRSM',
 201        begin_key: str = '{',
 202        end_key: str = '}',
 203        delimeter: str = ':'
 204    ) -> List[Any]:
 205    """
 206    Parse Meerschaum substitution syntax
 207    E.g. MRSM{value1:value2} => ['value1', 'value2']
 208    NOTE: Not currently used. See `search_and_substitute_config` in `meerschaum.config._read_yaml`.
 209    """
 210    if not value.beginswith(leading_key):
 211        return value
 212
 213    return leading_key[len(leading_key):][len():-1].split(delimeter)
 214
 215
 216def edit_file(
 217        path: Union[pathlib.Path, str],
 218        default_editor: str = 'pyvim',
 219        debug: bool = False
 220    ) -> bool:
 221    """
 222    Open a file for editing.
 223    
 224    Attempt to launch the user's defined `$EDITOR`, otherwise use `pyvim`.
 225
 226    Parameters
 227    ----------
 228    path: Union[pathlib.Path, str]
 229        The path to the file to be edited.
 230        
 231    default_editor: str, default 'pyvim'
 232        If `$EDITOR` is not set, use this instead.
 233        If `pyvim` is not installed, it will install it from PyPI.
 234
 235    debug: bool, default False
 236        Verbosity toggle.
 237
 238    Returns
 239    -------
 240    A bool indicating the file was successfully edited.
 241    """
 242    import os
 243    from subprocess import call
 244    from meerschaum.utils.debug import dprint
 245    from meerschaum.utils.packages import run_python_package, attempt_import, package_venv
 246    try:
 247        EDITOR = os.environ.get('EDITOR', default_editor)
 248        if debug:
 249            dprint(f"Opening file '{path}' with editor '{EDITOR}'...")
 250        rc = call([EDITOR, path])
 251    except Exception as e: ### can't open with default editors
 252        if debug:
 253            dprint(e)
 254            dprint('Failed to open file with system editor. Falling back to pyvim...')
 255        pyvim = attempt_import('pyvim', lazy=False)
 256        rc = run_python_package('pyvim', [path], venv=package_venv(pyvim), debug=debug)
 257    return rc == 0
 258
 259
 260def is_pipe_registered(
 261        pipe: mrsm.Pipe,
 262        pipes: PipesDict,
 263        debug: bool = False
 264    ) -> bool:
 265    """
 266    Check if a Pipe is inside the pipes dictionary.
 267
 268    Parameters
 269    ----------
 270    pipe: meerschaum.Pipe
 271        The pipe to see if it's in the dictionary.
 272        
 273    pipes: PipesDict
 274        The dictionary to search inside.
 275        
 276    debug: bool, default False
 277        Verbosity toggle.
 278
 279    Returns
 280    -------
 281    A bool indicating whether the pipe is inside the dictionary.
 282    """
 283    from meerschaum.utils.debug import dprint
 284    ck, mk, lk = pipe.connector_keys, pipe.metric_key, pipe.location_key
 285    if debug:
 286        dprint(f'{ck}, {mk}, {lk}')
 287        dprint(f'{pipe}, {pipes}')
 288    return ck in pipes and mk in pipes[ck] and lk in pipes[ck][mk]
 289
 290
 291def get_cols_lines(default_cols: int = 100, default_lines: int = 120) -> Tuple[int, int]:
 292    """
 293    Determine the columns and lines in the terminal.
 294    If they cannot be determined, return the default values (100 columns and 120 lines).
 295
 296    Parameters
 297    ----------
 298    default_cols: int, default 100
 299        If the columns cannot be determined, return this value.
 300
 301    default_lines: int, default 120
 302        If the lines cannot be determined, return this value.
 303
 304    Returns
 305    -------
 306    A tuple if integers for the columns and lines.
 307    """
 308    import os
 309    try:
 310        size = os.get_terminal_size()
 311        _cols, _lines = size.columns, size.lines
 312    except Exception as e:
 313        _cols, _lines = (
 314            int(os.environ.get('COLUMNS', str(default_cols))),
 315            int(os.environ.get('LINES', str(default_lines))),
 316        )
 317    return _cols, _lines
 318
 319
 320def iterate_chunks(iterable, chunksize: int, fillvalue: Optional[Any] = None):
 321    """
 322    Iterate over a list in chunks.
 323    https://stackoverflow.com/questions/434287/what-is-the-most-pythonic-way-to-iterate-over-a-list-in-chunks
 324
 325    Parameters
 326    ----------
 327    iterable: Iterable[Any]
 328        The iterable to iterate over in chunks.
 329        
 330    chunksize: int
 331        The size of chunks to iterate with.
 332        
 333    fillvalue: Optional[Any], default None
 334        If the chunks do not evenly divide into the iterable, pad the end with this value.
 335
 336    Returns
 337    -------
 338    A generator of tuples of size `chunksize`.
 339
 340    """
 341    from itertools import zip_longest
 342    args = [iter(iterable)] * chunksize
 343    return zip_longest(*args, fillvalue=fillvalue)
 344
 345def sorted_dict(d: Dict[Any, Any]) -> Dict[Any, Any]:
 346    """
 347    Sort a dictionary's values and return a new dictionary.
 348
 349    Parameters
 350    ----------
 351    d: Dict[Any, Any]
 352        The dictionary to be sorted.
 353
 354    Returns
 355    -------
 356    A sorted dictionary.
 357
 358    Examples
 359    --------
 360    >>> sorted_dict({'b': 1, 'a': 2})
 361    {'b': 1, 'a': 2}
 362    >>> sorted_dict({'b': 2, 'a': 1})
 363    {'a': 1, 'b': 2}
 364
 365    """
 366    try:
 367        return {key: value for key, value in sorted(d.items(), key=lambda item: item[1])}
 368    except Exception as e:
 369        return d
 370
 371def flatten_pipes_dict(pipes_dict: PipesDict) -> List[Pipe]:
 372    """
 373    Convert the standard pipes dictionary into a list.
 374
 375    Parameters
 376    ----------
 377    pipes_dict: PipesDict
 378        The pipes dictionary to be flattened.
 379
 380    Returns
 381    -------
 382    A list of `Pipe` objects.
 383
 384    """
 385    pipes_list = []
 386    for ck in pipes_dict.values():
 387        for mk in ck.values():
 388            pipes_list += list(mk.values())
 389    return pipes_list
 390
 391
 392def round_time(
 393        dt: Optional[datetime] = None,
 394        date_delta: Optional[timedelta] = None,
 395        to: 'str' = 'down'
 396    ) -> datetime:
 397    """
 398    Round a datetime object to a multiple of a timedelta.
 399    http://stackoverflow.com/questions/3463930/how-to-round-the-minute-of-a-datetime-object-python
 400
 401    NOTE: This function strips timezone information!
 402
 403    Parameters
 404    ----------
 405    dt: Optional[datetime], default None
 406        If `None`, grab the current UTC datetime.
 407
 408    date_delta: Optional[timedelta], default None
 409        If `None`, use a delta of 1 minute.
 410
 411    to: 'str', default 'down'
 412        Available options are `'up'`, `'down'`, and `'closest'`.
 413
 414    Returns
 415    -------
 416    A rounded `datetime` object.
 417
 418    Examples
 419    --------
 420    >>> round_time(datetime(2022, 1, 1, 12, 15, 57, 200))
 421    datetime.datetime(2022, 1, 1, 12, 15)
 422    >>> round_time(datetime(2022, 1, 1, 12, 15, 57, 200), to='up')
 423    datetime.datetime(2022, 1, 1, 12, 16)
 424    >>> round_time(datetime(2022, 1, 1, 12, 15, 57, 200), timedelta(hours=1))
 425    datetime.datetime(2022, 1, 1, 12, 0)
 426    >>> round_time(
 427    ...   datetime(2022, 1, 1, 12, 15, 57, 200),
 428    ...   timedelta(hours=1),
 429    ...   to = 'closest'
 430    ... )
 431    datetime.datetime(2022, 1, 1, 12, 0)
 432    >>> round_time(
 433    ...   datetime(2022, 1, 1, 12, 45, 57, 200),
 434    ...   datetime.timedelta(hours=1),
 435    ...   to = 'closest'
 436    ... )
 437    datetime.datetime(2022, 1, 1, 13, 0)
 438
 439    """
 440    if date_delta is None:
 441        date_delta = timedelta(minutes=1)
 442    round_to = date_delta.total_seconds()
 443    if dt is None:
 444        dt = datetime.now(timezone.utc).replace(tzinfo=None)
 445    seconds = (dt.replace(tzinfo=None) - dt.min.replace(tzinfo=None)).seconds
 446
 447    if seconds % round_to == 0 and dt.microsecond == 0:
 448        rounding = (seconds + round_to / 2) // round_to * round_to
 449    else:
 450        if to == 'up':
 451            rounding = (seconds + dt.microsecond/1000000 + round_to) // round_to * round_to
 452        elif to == 'down':
 453            rounding = seconds // round_to * round_to
 454        else:
 455            rounding = (seconds + round_to / 2) // round_to * round_to
 456
 457    return dt + timedelta(0, rounding - seconds, - dt.microsecond)
 458
 459
 460def timed_input(
 461        seconds: int = 10,
 462        timeout_message: str = "",
 463        prompt: str = "",
 464        icon: bool = False,
 465        **kw
 466    ) -> Union[str, None]:
 467    """
 468    Accept user input only for a brief period of time.
 469
 470    Parameters
 471    ----------
 472    seconds: int, default 10
 473        The number of seconds to wait.
 474
 475    timeout_message: str, default ''
 476        The message to print after the window has elapsed.
 477
 478    prompt: str, default ''
 479        The prompt to print during the window.
 480
 481    icon: bool, default False
 482        If `True`, print the configured input icon.
 483
 484
 485    Returns
 486    -------
 487    The input string entered by the user.
 488
 489    """
 490    import signal, time
 491
 492    class TimeoutExpired(Exception):
 493        """Raise this exception when the timeout is reached."""
 494
 495    def alarm_handler(signum, frame):
 496        raise TimeoutExpired
 497
 498    # set signal handler
 499    signal.signal(signal.SIGALRM, alarm_handler)
 500    signal.alarm(seconds) # produce SIGALRM in `timeout` seconds
 501
 502    try:
 503        return input(prompt)
 504    except TimeoutExpired:
 505        return None
 506    except (EOFError, RuntimeError):
 507        try:
 508            print(prompt)
 509            time.sleep(seconds)
 510        except TimeoutExpired:
 511            return None
 512    finally:
 513        signal.alarm(0) # cancel alarm
 514
 515
 516
 517
 518
 519def replace_pipes_in_dict(
 520        pipes : Optional[PipesDict] = None,
 521        func: 'function' = str,
 522        debug: bool = False,
 523        **kw
 524    ) -> PipesDict:
 525    """
 526    Replace the Pipes in a Pipes dict with the result of another function.
 527
 528    Parameters
 529    ----------
 530    pipes: Optional[PipesDict], default None
 531        The pipes dict to be processed.
 532
 533    func: Callable[[Any], Any], default str
 534        The function to be applied to every pipe.
 535        Defaults to the string constructor.
 536
 537    debug: bool, default False
 538        Verbosity toggle.
 539    
 540
 541    Returns
 542    -------
 543    A dictionary where every pipe is replaced with the output of a function.
 544
 545    """
 546    import copy
 547    def change_dict(d : Dict[Any, Any], func : 'function') -> None:
 548        for k, v in d.items():
 549            if isinstance(v, dict):
 550                change_dict(v, func)
 551            else:
 552                d[k] = func(v)
 553
 554    if pipes is None:
 555        from meerschaum import get_pipes
 556        pipes = get_pipes(debug=debug, **kw)
 557
 558    result = copy.deepcopy(pipes)
 559    change_dict(result, func)
 560    return result
 561
 562def enforce_gevent_monkey_patch():
 563    """
 564    Check if gevent monkey patching is enabled, and if not, then apply patching.
 565    """
 566    from meerschaum.utils.packages import attempt_import
 567    import socket
 568    gevent, gevent_socket, gevent_monkey = attempt_import(
 569        'gevent', 'gevent.socket', 'gevent.monkey'
 570    )
 571    if not socket.socket is gevent_socket.socket:
 572        gevent_monkey.patch_all()
 573
 574def is_valid_email(email: str) -> Union['re.Match', None]:
 575    """
 576    Check whether a string is a valid email.
 577
 578    Parameters
 579    ----------
 580    email: str
 581        The string to be examined.
 582        
 583    Returns
 584    -------
 585    None if a string is not in email format, otherwise a `re.Match` object, which is truthy.
 586
 587    Examples
 588    --------
 589    >>> is_valid_email('foo')
 590    >>> is_valid_email('foo@foo.com')
 591    <re.Match object; span=(0, 11), match='foo@foo.com'>
 592
 593    """
 594    import re
 595    regex = r'^[a-z0-9]+[\._]?[a-z0-9]+[@]\w+[.]\w{2,3}$'
 596    return re.search(regex, email)
 597
 598
 599def string_width(string: str, widest: bool = True) -> int:
 600    """
 601    Calculate the width of a string, either by its widest or last line.
 602
 603    Parameters
 604    ----------
 605    string: str:
 606        The string to be examined.
 607        
 608    widest: bool, default True
 609        No longer used because `widest` is always assumed to be true.
 610
 611    Returns
 612    -------
 613    An integer for the text's visual width.
 614
 615    Examples
 616    --------
 617    >>> string_width('a')
 618    1
 619    >>> string_width('a\\nbc\\nd')
 620    2
 621
 622    """
 623    def _widest():
 624        words = string.split('\n')
 625        max_length = 0
 626        for w in words:
 627            length = len(w)
 628            if length > max_length:
 629                max_length = length
 630        return max_length
 631
 632    return _widest()
 633
 634def _pyinstaller_traverse_dir(
 635        directory: str,
 636        ignore_patterns: Iterable[str] = ('.pyc', 'dist', 'build', '.git', '.log'),
 637        include_dotfiles: bool = False
 638    ) -> list:
 639    """
 640    Recursively traverse a directory and return a list of its contents.
 641    """
 642    import os, pathlib
 643    paths = []
 644    _directory = pathlib.Path(directory)
 645
 646    def _found_pattern(name: str):
 647        for pattern in ignore_patterns:
 648            if pattern.replace('/', os.path.sep) in str(name):
 649                return True
 650        return False
 651
 652    for root, dirs, files in os.walk(_directory):
 653        _root = str(root)[len(str(_directory.parent)):]
 654        if _root.startswith(os.path.sep):
 655            _root = _root[len(os.path.sep):]
 656        if _root.startswith('.') and not include_dotfiles:
 657            continue
 658        ### ignore certain patterns
 659        if _found_pattern(_root):
 660            continue
 661
 662        for filename in files:
 663            if filename.startswith('.') and not include_dotfiles:
 664                continue
 665            path = os.path.join(root, filename)
 666            if _found_pattern(path):
 667                continue
 668
 669            _path = str(path)[len(str(_directory.parent)):]
 670            if _path.startswith(os.path.sep):
 671                _path = _path[len(os.path.sep):]
 672            _path = os.path.sep.join(_path.split(os.path.sep)[:-1])
 673
 674            paths.append((path, _path))
 675    return paths
 676
 677
 678def replace_password(d: Dict[str, Any], replace_with: str = '*') -> Dict[str, Any]:
 679    """
 680    Recursively replace passwords in a dictionary.
 681
 682    Parameters
 683    ----------
 684    d: Dict[str, Any]
 685        The dictionary to search through.
 686
 687    replace_with: str, default '*'
 688        The string to replace each character of the password with.
 689
 690    Returns
 691    -------
 692    Another dictionary where values to the keys `'password'`
 693    are replaced with `replace_with` (`'*'`).
 694
 695    Examples
 696    --------
 697    >>> replace_password({'a': 1})
 698    {'a': 1}
 699    >>> replace_password({'password': '123'})
 700    {'password': '***'}
 701    >>> replace_password({'nested': {'password': '123'}})
 702    {'nested': {'password': '***'}}
 703    >>> replace_password({'password': '123'}, replace_with='!')
 704    {'password': '!!!'}
 705
 706    """
 707    import copy
 708    _d = copy.deepcopy(d)
 709    for k, v in d.items():
 710        if isinstance(v, dict):
 711            _d[k] = replace_password(v)
 712        elif 'password' in str(k).lower():
 713            _d[k] = ''.join([replace_with for char in str(v)])
 714        elif str(k).lower() == 'uri':
 715            from meerschaum.connectors.sql import SQLConnector
 716            try:
 717                uri_params = SQLConnector.parse_uri(v)
 718            except Exception as e:
 719                uri_params = None
 720            if not uri_params:
 721                continue
 722            if not 'username' in uri_params or not 'password' in uri_params:
 723                continue
 724            _d[k] = v.replace(
 725                uri_params['username'] + ':' + uri_params['password'],
 726                uri_params['username'] + ':' + ''.join(
 727                    [replace_with for char in str(uri_params['password'])]
 728                )
 729            )
 730    return _d
 731
 732
 733def filter_arguments(
 734    func: Callable[[Any], Any],
 735    *args: Any,
 736    **kwargs: Any
 737) -> Tuple[Tuple[Any], Dict[str, Any]]:
 738    """
 739    Filter out unsupported positional and keyword arguments.
 740
 741    Parameters
 742    ----------
 743    func: Callable[[Any], Any]
 744        The function to inspect.
 745
 746    *args: Any
 747        Positional arguments to filter and pass to `func`.
 748
 749    **kwargs
 750        Keyword arguments to filter and pass to `func`.
 751
 752    Returns
 753    -------
 754    The `args` and `kwargs` accepted by `func`.
 755    """
 756    args = filter_positionals(func, *args)
 757    kwargs = filter_keywords(func, **kwargs)
 758    return args, kwargs
 759
 760
 761def filter_keywords(
 762    func: Callable[[Any], Any],
 763    **kw: Any
 764) -> Dict[str, Any]:
 765    """
 766    Filter out unsupported keyword arguments.
 767
 768    Parameters
 769    ----------
 770    func: Callable[[Any], Any]
 771        The function to inspect.
 772
 773    **kw: Any
 774        The arguments to be filtered and passed into `func`.
 775
 776    Returns
 777    -------
 778    A dictionary of keyword arguments accepted by `func`.
 779
 780    Examples
 781    --------
 782    ```python
 783    >>> def foo(a=1, b=2):
 784    ...     return a * b
 785    >>> filter_keywords(foo, a=2, b=4, c=6)
 786    {'a': 2, 'b': 4}
 787    >>> foo(**filter_keywords(foo, **{'a': 2, 'b': 4, 'c': 6}))
 788    8
 789    ```
 790
 791    """
 792    import inspect
 793    func_params = inspect.signature(func).parameters
 794    ### If the function has a **kw method, skip filtering.
 795    for param, _type in func_params.items():
 796        if '**' in str(_type):
 797            return kw
 798    return {k: v for k, v in kw.items() if k in func_params}
 799
 800
 801def filter_positionals(
 802    func: Callable[[Any], Any],
 803    *args: Any
 804) -> Tuple[Any]:
 805    """
 806    Filter out unsupported positional arguments.
 807
 808    Parameters
 809    ----------
 810    func: Callable[[Any], Any]
 811        The function to inspect.
 812
 813    *args: Any
 814        The arguments to be filtered and passed into `func`.
 815        NOTE: If the function signature expects more arguments than provided,
 816        the missing slots will be filled with `None`.
 817
 818    Returns
 819    -------
 820    A tuple of positional arguments accepted by `func`.
 821
 822    Examples
 823    --------
 824    ```python
 825    >>> def foo(a, b):
 826    ...     return a * b
 827    >>> filter_positionals(foo, 2, 4, 6)
 828    (2, 4)
 829    >>> foo(*filter_positionals(foo, 2, 4, 6))
 830    8
 831    ```
 832
 833    """
 834    import inspect
 835    from meerschaum.utils.warnings import warn
 836    func_params = inspect.signature(func).parameters
 837    acceptable_args: List[Any] = []
 838
 839    def _warn_invalids(_num_invalid):
 840        if _num_invalid > 0:
 841            warn(
 842                "Too few arguments were provided. "
 843                + f"{_num_invalid} argument"
 844                + ('s have ' if _num_invalid != 1 else " has ")
 845                + " been filled with `None`.",
 846            )
 847
 848    num_invalid: int = 0
 849    for i, (param, val) in enumerate(func_params.items()):
 850        if '=' in str(val) or '*' in str(val):
 851            _warn_invalids(num_invalid)
 852            return tuple(acceptable_args)
 853
 854        try:
 855            acceptable_args.append(args[i])
 856        except IndexError:
 857            acceptable_args.append(None)
 858            num_invalid += 1
 859
 860    _warn_invalids(num_invalid)
 861    return tuple(acceptable_args)
 862
 863
 864def dict_from_od(od: collections.OrderedDict) -> Dict[Any, Any]:
 865    """
 866    Convert an ordered dict to a dict.
 867    Does not mutate the original OrderedDict.
 868    """
 869    from collections import OrderedDict
 870    _d = dict(od)
 871    for k, v in od.items():
 872        if isinstance(v, OrderedDict) or (
 873            issubclass(type(v), OrderedDict)
 874        ):
 875            _d[k] = dict_from_od(v)
 876    return _d
 877
 878def remove_ansi(s : str) -> str:
 879    """
 880    Remove ANSI escape characters from a string.
 881
 882    Parameters
 883    ----------
 884    s: str:
 885        The string to be cleaned.
 886
 887    Returns
 888    -------
 889    A string with the ANSI characters removed.
 890
 891    Examples
 892    --------
 893    >>> remove_ansi("\x1b[1;31mHello, World!\x1b[0m")
 894    'Hello, World!'
 895
 896    """
 897    import re
 898    return re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])').sub('', s)
 899
 900
 901def get_connector_labels(
 902        *types: str,
 903        search_term: str = '',
 904        ignore_exact_match = True,
 905    ) -> List[str]:
 906    """
 907    Read connector labels from the configuration dictionary.
 908
 909    Parameters
 910    ----------
 911    *types: str
 912        The connector types.
 913        If none are provided, use the defined types (`'sql'` and `'api'`) and `'plugin'`.
 914
 915    search_term: str, default ''
 916        A filter on the connectors' labels.
 917
 918    ignore_exact_match: bool, default True
 919        If `True`, skip a connector if the search_term is an exact match.
 920
 921    Returns
 922    -------
 923    A list of the keys of defined connectors.
 924
 925    """
 926    from meerschaum.config import get_config
 927    connectors = get_config('meerschaum', 'connectors')
 928
 929    _types = list(types)
 930    if len(_types) == 0:
 931        _types = list(connectors.keys()) + ['plugin']
 932
 933    conns = []
 934    for t in _types:
 935        if t == 'plugin':
 936            from meerschaum.plugins import get_data_plugins
 937            conns += [
 938                f'{t}:' + plugin.module.__name__.split('.')[-1]
 939                for plugin in get_data_plugins()
 940            ]
 941            continue
 942        conns += [ f'{t}:{label}' for label in connectors.get(t, {}) if label != 'default' ]
 943
 944    possibilities = [
 945        c for c in conns
 946            if c.startswith(search_term)
 947                and c != (
 948                    search_term if ignore_exact_match else ''
 949                )
 950    ]
 951    return sorted(possibilities)
 952
 953
 954def json_serialize_datetime(dt: datetime) -> Union[str, None]:
 955    """
 956    Serialize a datetime object into JSON (ISO format string).
 957    
 958    Examples
 959    --------
 960    >>> import json
 961    >>> from datetime import datetime
 962    >>> json.dumps({'a': datetime(2022, 1, 1)}, default=json_serialize_datetime)
 963    '{"a": "2022-01-01T00:00:00Z"}'
 964
 965    """
 966    if not isinstance(dt, datetime):
 967        return None
 968    tz_suffix = 'Z' if dt.tzinfo is None else ''
 969    return dt.isoformat() + tz_suffix
 970
 971
 972def wget(
 973        url: str,
 974        dest: Optional[Union[str, 'pathlib.Path']] = None,
 975        headers: Optional[Dict[str, Any]] = None,
 976        color: bool = True,
 977        debug: bool = False,
 978        **kw: Any
 979    ) -> 'pathlib.Path':
 980    """
 981    Mimic `wget` with `requests`.
 982
 983    Parameters
 984    ----------
 985    url: str
 986        The URL to the resource to be downloaded.
 987        
 988    dest: Optional[Union[str, pathlib.Path]], default None
 989        The destination path of the downloaded file.
 990        If `None`, save to the current directory.
 991
 992    color: bool, default True
 993        If `debug` is `True`, print color output.
 994
 995    debug: bool, default False
 996        Verbosity toggle.
 997
 998    Returns
 999    -------
1000    The path to the downloaded file.
1001
1002    """
1003    from meerschaum.utils.warnings import warn, error
1004    from meerschaum.utils.debug import dprint
1005    import os, pathlib, re, urllib.request
1006    if headers is None:
1007        headers = {}
1008    request = urllib.request.Request(url, headers=headers)
1009    if not color:
1010        dprint = print
1011    if debug:
1012        dprint(f"Downloading from '{url}'...")
1013    try:
1014        response = urllib.request.urlopen(request)
1015    except Exception as e:
1016        import ssl
1017        ssl._create_default_https_context = ssl._create_unverified_context
1018        try:
1019            response = urllib.request.urlopen(request)
1020        except Exception as _e:
1021            print(_e)
1022            response = None
1023    if response is None or response.code != 200:
1024        error_msg = f"Failed to download from '{url}'."
1025        if color:
1026            error(error_msg)
1027        else:
1028            print(error_msg)
1029            import sys
1030            sys.exit(1)
1031
1032    d = response.headers.get('content-disposition', None)
1033    fname = (
1034        re.findall("filename=(.+)", d)[0].strip('"') if d is not None
1035        else url.split('/')[-1]
1036    )
1037
1038    if dest is None:
1039        dest = pathlib.Path(os.path.join(os.getcwd(), fname))
1040    elif isinstance(dest, str):
1041        dest = pathlib.Path(dest)
1042
1043    with open(dest, 'wb') as f:
1044        f.write(response.fp.read())
1045
1046    if debug:
1047        dprint(f"Downloaded file '{dest}'.")
1048
1049    return dest
1050
1051
1052def async_wrap(func):
1053    """
1054    Run a synchronous function as async.
1055    https://dev.to/0xbf/turn-sync-function-to-async-python-tips-58nn
1056    """
1057    import asyncio
1058    from functools import wraps, partial
1059
1060    @wraps(func)
1061    async def run(*args, loop=None, executor=None, **kwargs):
1062        if loop is None:
1063            loop = asyncio.get_event_loop()
1064        pfunc = partial(func, *args, **kwargs)
1065        return await loop.run_in_executor(executor, pfunc)
1066    return run 
1067
1068
1069def debug_trace(browser: bool = True):
1070    """
1071    Open a web-based debugger to trace the execution of the program.
1072
1073    This is an alias import for `meerschaum.utils.debug.debug_trace`.
1074    """
1075    from meerschaum.utils.debug import trace
1076    trace(browser=browser)
1077
1078
1079def items_str(
1080        items: List[Any],
1081        quotes: bool = True,
1082        quote_str: str = "'",
1083        commas: bool = True,
1084        comma_str: str = ',',
1085        and_: bool = True,
1086        and_str: str = 'and',
1087        oxford_comma: bool = True,
1088        spaces: bool = True,
1089        space_str = ' ',
1090    ) -> str:
1091    """
1092    Return a formatted string if list items separated by commas.
1093
1094    Parameters
1095    ----------
1096    items: [List[Any]]
1097        The items to be printed as an English list.
1098
1099    quotes: bool, default True
1100        If `True`, wrap items in quotes.
1101
1102    quote_str: str, default "'"
1103        If `quotes` is `True`, prepend and append each item with this string.
1104
1105    and_: bool, default True
1106        If `True`, include the word 'and' before the final item in the list.
1107
1108    and_str: str, default 'and'
1109        If `and_` is True, insert this string where 'and' normally would in and English list.
1110
1111    oxford_comma: bool, default True
1112        If `True`, include the Oxford Comma (comma before the final 'and').
1113        Only applies when `and_` is `True`.
1114
1115    spaces: bool, default True
1116        If `True`, separate items with `space_str`
1117
1118    space_str: str, default ' '
1119        If `spaces` is `True`, separate items with this string.
1120
1121    Returns
1122    -------
1123    A string of the items as an English list.
1124
1125    Examples
1126    --------
1127    >>> items_str([1,2,3])
1128    "'1', '2', and '3'"
1129    >>> items_str([1,2,3], quotes=False)
1130    '1, 2, and 3'
1131    >>> items_str([1,2,3], and_=False)
1132    "'1', '2', '3'"
1133    >>> items_str([1,2,3], spaces=False, and_=False)
1134    "'1','2','3'"
1135    >>> items_str([1,2,3], oxford_comma=False)
1136    "'1', '2' and '3'"
1137    >>> items_str([1,2,3], quote_str=":")
1138    ':1:, :2:, and :3:'
1139    >>> items_str([1,2,3], and_str="or")
1140    "'1', '2', or '3'"
1141    >>> items_str([1,2,3], space_str="_")
1142    "'1',_'2',_and_'3'"
1143
1144    """
1145    if not items:
1146        return ''
1147    
1148    q = quote_str if quotes else ''
1149    s = space_str if spaces else ''
1150    a = and_str if and_ else ''
1151    c = comma_str if commas else ''
1152
1153    if len(items) == 1:
1154        return q + str(list(items)[0]) + q
1155
1156    if len(items) == 2:
1157        return q + str(list(items)[0]) + q + s + a + s + q + str(list(items)[1]) + q
1158
1159    sep = q + c + s + q
1160    output = q + sep.join(str(i) for i in items[:-1]) + q
1161    if oxford_comma:
1162        output += c
1163    output += s + a + (s if and_ else '') + q + str(items[-1]) + q
1164    return output
1165
1166
1167def interval_str(delta: Union[timedelta, int]) -> str:
1168    """
1169    Return a human-readable string for a `timedelta` (or `int` minutes).
1170
1171    Parameters
1172    ----------
1173    delta: Union[timedelta, int]
1174        The interval to print. If `delta` is an integer, assume it corresponds to minutes.
1175
1176    Returns
1177    -------
1178    A formatted string, fit for human eyes.
1179    """
1180    from meerschaum.utils.packages import attempt_import
1181    humanfriendly = attempt_import('humanfriendly')
1182    delta_seconds = (
1183        delta.total_seconds()
1184        if isinstance(delta, timedelta)
1185        else (delta * 60)
1186    )
1187    return humanfriendly.format_timespan(delta_seconds)
1188
1189
1190def is_docker_available() -> bool:
1191    """Check if we can connect to the Docker engine."""
1192    import subprocess
1193    try:
1194        has_docker = subprocess.call(
1195            ['docker', 'ps'], stdout=subprocess.DEVNULL, stderr=subprocess.STDOUT
1196        ) == 0
1197    except Exception as e:
1198        has_docker = False
1199    return has_docker
1200
1201
1202def is_android() -> bool:
1203    """Return `True` if the current platform is Android."""
1204    import sys
1205    return hasattr(sys, 'getandroidapilevel')
1206
1207
1208def is_bcp_available() -> bool:
1209    """Check if the MSSQL `bcp` utility is installed."""
1210    import subprocess
1211
1212    try:
1213        has_bcp = subprocess.call(
1214            ['bcp', '-v'], stdout=subprocess.DEVNULL, stderr=subprocess.STDOUT
1215        ) == 0
1216    except Exception as e:
1217        has_bcp = False
1218    return has_bcp
1219
1220
1221def get_last_n_lines(file_name: str, N: int):
1222    """
1223    https://thispointer.com/python-get-last-n-lines-of-a-text-file-like-tail-command/
1224    """
1225    import os
1226    # Create an empty list to keep the track of last N lines
1227    list_of_lines = []
1228    # Open file for reading in binary mode
1229    with open(file_name, 'rb') as read_obj:
1230        # Move the cursor to the end of the file
1231        read_obj.seek(0, os.SEEK_END)
1232        # Create a buffer to keep the last read line
1233        buffer = bytearray()
1234        # Get the current position of pointer i.e eof
1235        pointer_location = read_obj.tell()
1236        # Loop till pointer reaches the top of the file
1237        while pointer_location >= 0:
1238            # Move the file pointer to the location pointed by pointer_location
1239            read_obj.seek(pointer_location)
1240            # Shift pointer location by -1
1241            pointer_location = pointer_location -1
1242            # read that byte / character
1243            new_byte = read_obj.read(1)
1244            # If the read byte is new line character then it means one line is read
1245            if new_byte == b'\n':
1246                # Save the line in list of lines
1247                list_of_lines.append(buffer.decode()[::-1])
1248                # If the size of list reaches N, then return the reversed list
1249                if len(list_of_lines) == N:
1250                    return list(reversed(list_of_lines))
1251                # Reinitialize the byte array to save next line
1252                buffer = bytearray()
1253            else:
1254                # If last read character is not eol then add it in buffer
1255                buffer.extend(new_byte)
1256        # As file is read completely, if there is still data in buffer, then its first line.
1257        if len(buffer) > 0:
1258            list_of_lines.append(buffer.decode()[::-1])
1259    # return the reversed list
1260    return list(reversed(list_of_lines))
1261
1262
1263def tail(f, n, offset=None):
1264    """
1265    https://stackoverflow.com/a/692616/9699829
1266    
1267    Reads n lines from f with an offset of offset lines.  The return
1268    value is a tuple in the form ``(lines, has_more)`` where `has_more` is
1269    an indicator that is `True` if there are more lines in the file.
1270    """
1271    avg_line_length = 74
1272    to_read = n + (offset or 0)
1273
1274    while True:
1275        try:
1276            f.seek(-(avg_line_length * to_read), 2)
1277        except IOError:
1278            # woops.  apparently file is smaller than what we want
1279            # to step back, go to the beginning instead
1280            f.seek(0)
1281        pos = f.tell()
1282        lines = f.read().splitlines()
1283        if len(lines) >= to_read or pos == 0:
1284            return lines[-to_read:offset and -offset or None], \
1285                   len(lines) > to_read or pos > 0
1286        avg_line_length *= 1.3
1287
1288
1289def truncate_string_sections(item: str, delimeter: str = '_', max_len: int = 128) -> str:
1290    """
1291    Remove characters from each section of a string until the length is within the limit.
1292
1293    Parameters
1294    ----------
1295    item: str
1296        The item name to be truncated.
1297
1298    delimeter: str, default '_'
1299        Split `item` by this string into several sections.
1300
1301    max_len: int, default 128
1302        The max acceptable length of the truncated version of `item`.
1303
1304    Returns
1305    -------
1306    The truncated string.
1307
1308    Examples
1309    --------
1310    >>> truncate_string_sections('abc_def_ghi', max_len=10)
1311    'ab_de_gh'
1312
1313    """
1314    if len(item) < max_len:
1315        return item
1316
1317    def _shorten(s: str) -> str:
1318        return s[:-1] if len(s) > 1 else s
1319
1320    sections = list(enumerate(item.split('_')))
1321    sorted_sections = sorted(sections, key=lambda x: (-1 * len(x[1])))
1322    available_chars = max_len - len(sections)
1323
1324    _sections = [(i, s) for i, s in sorted_sections]
1325    _sections_len = sum([len(s) for i, s in _sections])
1326    _old_sections_len = _sections_len
1327    while _sections_len > available_chars:
1328        _sections = [(i, _shorten(s)) for i, s in _sections]
1329        _old_sections_len = _sections_len
1330        _sections_len = sum([len(s) for i, s in _sections])
1331        if _old_sections_len == _sections_len:
1332            raise Exception(f"String could not be truncated: '{item}'")
1333
1334    new_sections = sorted(_sections, key=lambda x: x[0])
1335    return delimeter.join([s for i, s in new_sections])
1336
1337
1338def separate_negation_values(
1339        vals: Union[List[str], Tuple[str]],
1340        negation_prefix: Optional[str] = None,
1341    ) -> Tuple[List[str], List[str]]:
1342    """
1343    Separate the negated values from the positive ones.
1344    Return two lists: positive and negative values.
1345
1346    Parameters
1347    ----------
1348    vals: Union[List[str], Tuple[str]]
1349        A list of strings to parse.
1350
1351    negation_prefix: Optional[str], default None
1352        Include values that start with this string in the second list.
1353        If `None`, use the system default (`_`).
1354    """
1355    if negation_prefix is None:
1356        from meerschaum.config.static import STATIC_CONFIG
1357        negation_prefix = STATIC_CONFIG['system']['fetch_pipes_keys']['negation_prefix']
1358    _in_vals, _ex_vals = [], []
1359    for v in vals:
1360        if str(v).startswith(negation_prefix):
1361            _ex_vals.append(str(v)[len(negation_prefix):])
1362        else:
1363            _in_vals.append(v)
1364
1365    return _in_vals, _ex_vals
1366
1367
1368def get_in_ex_params(params: Optional[Dict[str, Any]]) -> Dict[str, Tuple[List[Any], List[Any]]]:
1369    """
1370    Translate a params dictionary into lists of include- and exclude-values.
1371
1372    Parameters
1373    ----------
1374    params: Optional[Dict[str, Any]]
1375        A params query dictionary.
1376
1377    Returns
1378    -------
1379    A dictionary mapping keys to a tuple of lists for include and exclude values.
1380
1381    Examples
1382    --------
1383    >>> get_in_ex_params({'a': ['b', 'c', '_d', 'e', '_f']})
1384    {'a': (['b', 'c', 'e'], ['d', 'f'])}
1385    """
1386    if not params:
1387        return {}
1388    return {
1389        col: separate_negation_values(
1390            (
1391                val
1392                if isinstance(val, (list, tuple))
1393                else [val]
1394            )
1395        )
1396        for col, val in params.items()
1397    }
1398
1399
1400def flatten_list(list_: List[Any]) -> List[Any]:
1401    """
1402    Recursively flatten a list.
1403    """
1404    for item in list_:
1405        if isinstance(item, list):
1406            yield from flatten_list(item)
1407        else:
1408            yield item
1409
1410
1411def make_symlink(src_path: pathlib.Path, dest_path: pathlib.Path) -> SuccessTuple:
1412    """
1413    Wrap around `pathlib.Path.symlink_to`, but add support for Windows.
1414
1415    Parameters
1416    ----------
1417    src_path: pathlib.Path
1418        The source path.
1419
1420    dest_path: pathlib.Path
1421        The destination path.
1422
1423    Returns
1424    -------
1425    A SuccessTuple indicating success.
1426    """
1427    if dest_path.exists() and dest_path.resolve() == src_path.resolve():
1428        return True, "Symlink already exists."
1429    try:
1430        dest_path.symlink_to(src_path)
1431        success = True
1432    except Exception as e:
1433        success = False
1434        msg = str(e)
1435    if success:
1436        return success, "Success"
1437    
1438    ### Failed to create a symlink.
1439    ### If we're not on Windows, return an error.
1440    import platform
1441    if platform.system() != 'Windows':
1442        return success, msg
1443
1444    try:
1445        import _winapi
1446    except ImportError:
1447        return False, "Unable to import _winapi."
1448
1449    if src_path.is_dir():
1450        try:
1451            _winapi.CreateJunction(str(src_path), str(dest_path))
1452        except Exception as e:
1453            return False, str(e)
1454        return True, "Success"
1455
1456    ### Last resort: copy the file on Windows.
1457    import shutil
1458    try:
1459        shutil.copy(src_path, dest_path)
1460    except Exception as e:
1461        return False, str(e)
1462    
1463    return True, "Success"
1464
1465
1466def is_symlink(path: pathlib.Path) -> bool:
1467    """
1468    Wrap `path.is_symlink()` but add support for Windows junctions.
1469    """
1470    if path.is_symlink():
1471        return True
1472    import platform, os
1473    if platform.system() != 'Windows':
1474        return False
1475    try:
1476        return bool(os.readlink(path))
1477    except OSError:
1478        return False
1479
1480
1481def parametrized(dec):
1482    """
1483    A meta-decorator for allowing other decorator functions to have parameters.
1484
1485    https://stackoverflow.com/a/26151604/9699829
1486    """
1487    def layer(*args, **kwargs):
1488        def repl(f):
1489            return dec(f, *args, **kwargs)
1490        return repl
1491    return layer
1492
1493
1494def safely_extract_tar(tarf: 'file', output_dir: Union[str, 'pathlib.Path']) -> None:
1495    """
1496    Safely extract a TAR file to a give directory.
1497    This defends against CVE-2007-4559.
1498
1499    Parameters
1500    ----------
1501    tarf: file
1502        The TAR file opened with `tarfile.open(path, 'r:gz')`.
1503
1504    output_dir: Union[str, pathlib.Path]
1505        The output directory.
1506    """
1507    import os
1508
1509    def is_within_directory(directory, target):
1510        abs_directory = os.path.abspath(directory)
1511        abs_target = os.path.abspath(target)
1512        prefix = os.path.commonprefix([abs_directory, abs_target])
1513        return prefix == abs_directory 
1514
1515    def safe_extract(tar, path=".", members=None, *, numeric_owner=False):
1516        for member in tar.getmembers():
1517            member_path = os.path.join(path, member.name)
1518            if not is_within_directory(path, member_path):
1519                raise Exception("Attempted Path Traversal in Tar File")
1520
1521        tar.extractall(path=path, members=members, numeric_owner=numeric_owner)
1522
1523    return safe_extract(tarf, output_dir)
1524
1525##################
1526# Legacy imports #
1527##################
1528
1529def choose_subaction(*args, **kwargs) -> Any:
1530    """
1531    Placeholder function to prevent breaking legacy behavior.
1532    See `meerschaum.actions.choose_subaction`.
1533    """
1534    from meerschaum.actions import choose_subaction as _choose_subactions
1535    return _choose_subactions(*args, **kwargs)
1536
1537
1538def print_options(*args, **kwargs) -> None:
1539    """
1540    Placeholder function to prevent breaking legacy behavior.
1541    See `meerschaum.utils.formatting.print_options`.
1542    """
1543    from meerschaum.utils.formatting import print_options as _print_options
1544    return _print_options(*args, **kwargs)
1545
1546
1547def to_pandas_dtype(*args, **kwargs) -> Any:
1548    """
1549    Placeholder function to prevent breaking legacy behavior.
1550    See `meerschaum.utils.dtypes.to_pandas_dtype`.
1551    """
1552    from meerschaum.utils.dtypes import to_pandas_dtype as _to_pandas_dtype
1553    return _to_pandas_dtype(*args, **kwargs)
1554
1555
1556def filter_unseen_df(*args, **kwargs) -> Any:
1557    """
1558    Placeholder function to prevent breaking legacy behavior.
1559    See `meerschaum.utils.dataframe.filter_unseen_df`.
1560    """
1561    from meerschaum.utils.dataframe import filter_unseen_df as real_function
1562    return real_function(*args, **kwargs)
1563
1564
1565def add_missing_cols_to_df(*args, **kwargs) -> Any:
1566    """
1567    Placeholder function to prevent breaking legacy behavior.
1568    See `meerschaum.utils.dataframe.add_missing_cols_to_df`.
1569    """
1570    from meerschaum.utils.dataframe import add_missing_cols_to_df as real_function
1571    return real_function(*args, **kwargs)
1572
1573
1574def parse_df_datetimes(*args, **kwargs) -> Any:
1575    """
1576    Placeholder function to prevent breaking legacy behavior.
1577    See `meerschaum.utils.dataframe.parse_df_datetimes`.
1578    """
1579    from meerschaum.utils.dataframe import parse_df_datetimes as real_function
1580    return real_function(*args, **kwargs)
1581
1582
1583def df_from_literal(*args, **kwargs) -> Any:
1584    """
1585    Placeholder function to prevent breaking legacy behavior.
1586    See `meerschaum.utils.dataframe.df_from_literal`.
1587    """
1588    from meerschaum.utils.dataframe import df_from_literal as real_function
1589    return real_function(*args, **kwargs)
1590
1591
1592def get_json_cols(*args, **kwargs) -> Any:
1593    """
1594    Placeholder function to prevent breaking legacy behavior.
1595    See `meerschaum.utils.dataframe.get_json_cols`.
1596    """
1597    from meerschaum.utils.dataframe import get_json_cols as real_function
1598    return real_function(*args, **kwargs)
1599
1600
1601def get_unhashable_cols(*args, **kwargs) -> Any:
1602    """
1603    Placeholder function to prevent breaking legacy behavior.
1604    See `meerschaum.utils.dataframe.get_unhashable_cols`.
1605    """
1606    from meerschaum.utils.dataframe import get_unhashable_cols as real_function
1607    return real_function(*args, **kwargs)
1608
1609
1610def enforce_dtypes(*args, **kwargs) -> Any:
1611    """
1612    Placeholder function to prevent breaking legacy behavior.
1613    See `meerschaum.utils.dataframe.enforce_dtypes`.
1614    """
1615    from meerschaum.utils.dataframe import enforce_dtypes as real_function
1616    return real_function(*args, **kwargs)
1617
1618
1619def get_datetime_bound_from_df(*args, **kwargs) -> Any:
1620    """
1621    Placeholder function to prevent breaking legacy behavior.
1622    See `meerschaum.utils.dataframe.get_datetime_bound_from_df`.
1623    """
1624    from meerschaum.utils.dataframe import get_datetime_bound_from_df as real_function
1625    return real_function(*args, **kwargs)
1626
1627
1628def df_is_chunk_generator(*args, **kwargs) -> Any:
1629    """
1630    Placeholder function to prevent breaking legacy behavior.
1631    See `meerschaum.utils.dataframe.df_is_chunk_generator`.
1632    """
1633    from meerschaum.utils.dataframe import df_is_chunk_generator as real_function
1634    return real_function(*args, **kwargs)
1635
1636
1637def choices_docstring(*args, **kwargs) -> Any:
1638    """
1639    Placeholder function to prevent breaking legacy behavior.
1640    See `meerschaum.actions.choices_docstring`.
1641    """
1642    from meerschaum.actions import choices_docstring as real_function
1643    return real_function(*args, **kwargs)
1644
1645
1646def _get_subaction_names(*args, **kwargs) -> Any:
1647    """
1648    Placeholder function to prevent breaking legacy behavior.
1649    See `meerschaum.actions._get_subaction_names`.
1650    """
1651    from meerschaum.actions import _get_subaction_names as real_function
1652    return real_function(*args, **kwargs)
1653
1654
1655_current_module = sys.modules[__name__]
1656__all__ = tuple(
1657    name
1658    for name, obj in globals().items()
1659    if callable(obj)
1660        and name not in __pdoc__
1661        and getattr(obj, '__module__', None) == _current_module.__name__
1662)