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