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