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(":", maxsplit=1)
 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 truncate_text_for_display(
1359    text: str,
1360    max_length: int = 50,
1361    suffix: str = '…',
1362) -> str:
1363    """
1364    Truncate a potentially long string for display purposes.
1365
1366    Parameters
1367    ----------
1368    text: str
1369        The string to be truncated.
1370
1371    max_length: int, default 60
1372        The maximum length of `text` before truncation.
1373
1374    suffix: str, default '…'
1375        The string to append to the length of `text` to indicate truncation.
1376
1377    Returns
1378    -------
1379    A string of length `max_length` or less.
1380    """
1381    text_length = len(text)
1382    if text_length <= max_length:
1383        return text
1384
1385    suffix_length = len(suffix)
1386
1387    truncated_text = text[:max_length - suffix_length]
1388    return truncated_text + suffix
1389
1390
1391def separate_negation_values(
1392    vals: Union[List[str], Tuple[str]],
1393    negation_prefix: Optional[str] = None,
1394) -> Tuple[List[str], List[str]]:
1395    """
1396    Separate the negated values from the positive ones.
1397    Return two lists: positive and negative values.
1398
1399    Parameters
1400    ----------
1401    vals: Union[List[str], Tuple[str]]
1402        A list of strings to parse.
1403
1404    negation_prefix: Optional[str], default None
1405        Include values that start with this string in the second list.
1406        If `None`, use the system default (`_`).
1407    """
1408    if negation_prefix is None:
1409        from meerschaum.config.static import STATIC_CONFIG
1410        negation_prefix = STATIC_CONFIG['system']['fetch_pipes_keys']['negation_prefix']
1411    _in_vals, _ex_vals = [], []
1412    for v in vals:
1413        if str(v).startswith(negation_prefix):
1414            _ex_vals.append(str(v)[len(negation_prefix):])
1415        else:
1416            _in_vals.append(v)
1417
1418    return _in_vals, _ex_vals
1419
1420
1421def get_in_ex_params(params: Optional[Dict[str, Any]]) -> Dict[str, Tuple[List[Any], List[Any]]]:
1422    """
1423    Translate a params dictionary into lists of include- and exclude-values.
1424
1425    Parameters
1426    ----------
1427    params: Optional[Dict[str, Any]]
1428        A params query dictionary.
1429
1430    Returns
1431    -------
1432    A dictionary mapping keys to a tuple of lists for include and exclude values.
1433
1434    Examples
1435    --------
1436    >>> get_in_ex_params({'a': ['b', 'c', '_d', 'e', '_f']})
1437    {'a': (['b', 'c', 'e'], ['d', 'f'])}
1438    """
1439    if not params:
1440        return {}
1441    return {
1442        col: separate_negation_values(
1443            (
1444                val
1445                if isinstance(val, (list, tuple))
1446                else [val]
1447            )
1448        )
1449        for col, val in params.items()
1450    }
1451
1452
1453def flatten_list(list_: List[Any]) -> List[Any]:
1454    """
1455    Recursively flatten a list.
1456    """
1457    for item in list_:
1458        if isinstance(item, list):
1459            yield from flatten_list(item)
1460        else:
1461            yield item
1462
1463
1464def parse_arguments_str(args_str: str) -> Tuple[Tuple[Any], Dict[str, Any]]:
1465    """
1466    Parse a string containing the text to be passed into a function
1467    and return a tuple of args, kwargs.
1468
1469    Parameters
1470    ----------
1471    args_str: str
1472        The contents of the function parameter (as a string).
1473
1474    Returns
1475    -------
1476    A tuple of args (tuple) and kwargs (dict[str, Any]).
1477
1478    Examples
1479    --------
1480    >>> parse_arguments_str('123, 456, foo=789, bar="baz"')
1481    (123, 456), {'foo': 789, 'bar': 'baz'}
1482    """
1483    import ast
1484    args = []
1485    kwargs = {}
1486
1487    for part in args_str.split(','):
1488        if '=' in part:
1489            key, val = part.split('=', 1)
1490            kwargs[key.strip()] = ast.literal_eval(val)
1491        else:
1492            args.append(ast.literal_eval(part.strip()))
1493
1494    return tuple(args), kwargs
1495
1496
1497def make_symlink(src_path: 'pathlib.Path', dest_path: 'pathlib.Path') -> SuccessTuple:
1498    """
1499    Wrap around `pathlib.Path.symlink_to`, but add support for Windows.
1500
1501    Parameters
1502    ----------
1503    src_path: pathlib.Path
1504        The source path.
1505
1506    dest_path: pathlib.Path
1507        The destination path.
1508
1509    Returns
1510    -------
1511    A SuccessTuple indicating success.
1512    """
1513    if dest_path.exists() and dest_path.resolve() == src_path.resolve():
1514        return True, "Symlink already exists."
1515    try:
1516        dest_path.symlink_to(src_path)
1517        success = True
1518    except Exception as e:
1519        success = False
1520        msg = str(e)
1521    if success:
1522        return success, "Success"
1523
1524    ### Failed to create a symlink.
1525    ### If we're not on Windows, return an error.
1526    import platform
1527    if platform.system() != 'Windows':
1528        return success, msg
1529
1530    try:
1531        import _winapi
1532    except ImportError:
1533        return False, "Unable to import _winapi."
1534
1535    if src_path.is_dir():
1536        try:
1537            _winapi.CreateJunction(str(src_path), str(dest_path))
1538        except Exception as e:
1539            return False, str(e)
1540        return True, "Success"
1541
1542    ### Last resort: copy the file on Windows.
1543    import shutil
1544    try:
1545        shutil.copy(src_path, dest_path)
1546    except Exception as e:
1547        return False, str(e)
1548
1549    return True, "Success"
1550
1551
1552def is_symlink(path: pathlib.Path) -> bool:
1553    """
1554    Wrap `path.is_symlink()` but add support for Windows junctions.
1555    """
1556    if path.is_symlink():
1557        return True
1558    import platform
1559    import os
1560    if platform.system() != 'Windows':
1561        return False
1562    try:
1563        return bool(os.readlink(path))
1564    except OSError:
1565        return False
1566
1567
1568def parametrized(dec):
1569    """
1570    A meta-decorator for allowing other decorator functions to have parameters.
1571
1572    https://stackoverflow.com/a/26151604/9699829
1573    """
1574    def layer(*args, **kwargs):
1575        def repl(f):
1576            return dec(f, *args, **kwargs)
1577        return repl
1578    return layer
1579
1580
1581def safely_extract_tar(tarf: 'file', output_dir: Union[str, 'pathlib.Path']) -> None:
1582    """
1583    Safely extract a TAR file to a give directory.
1584    This defends against CVE-2007-4559.
1585
1586    Parameters
1587    ----------
1588    tarf: file
1589        The TAR file opened with `tarfile.open(path, 'r:gz')`.
1590
1591    output_dir: Union[str, pathlib.Path]
1592        The output directory.
1593    """
1594    import os
1595
1596    def is_within_directory(directory, target):
1597        abs_directory = os.path.abspath(directory)
1598        abs_target = os.path.abspath(target)
1599        prefix = os.path.commonprefix([abs_directory, abs_target])
1600        return prefix == abs_directory 
1601
1602    def safe_extract(tar, path=".", members=None, *, numeric_owner=False):
1603        for member in tar.getmembers():
1604            member_path = os.path.join(path, member.name)
1605            if not is_within_directory(path, member_path):
1606                raise Exception("Attempted Path Traversal in Tar File")
1607
1608        tar.extractall(path=path, members=members, numeric_owner=numeric_owner)
1609
1610    return safe_extract(tarf, output_dir)
1611
1612
1613##################
1614# Legacy imports #
1615##################
1616
1617def choose_subaction(*args, **kwargs) -> Any:
1618    """
1619    Placeholder function to prevent breaking legacy behavior.
1620    See `meerschaum.actions.choose_subaction`.
1621    """
1622    from meerschaum.actions import choose_subaction as _choose_subactions
1623    return _choose_subactions(*args, **kwargs)
1624
1625
1626def print_options(*args, **kwargs) -> None:
1627    """
1628    Placeholder function to prevent breaking legacy behavior.
1629    See `meerschaum.utils.formatting.print_options`.
1630    """
1631    from meerschaum.utils.formatting import print_options as _print_options
1632    return _print_options(*args, **kwargs)
1633
1634
1635def to_pandas_dtype(*args, **kwargs) -> Any:
1636    """
1637    Placeholder function to prevent breaking legacy behavior.
1638    See `meerschaum.utils.dtypes.to_pandas_dtype`.
1639    """
1640    from meerschaum.utils.dtypes import to_pandas_dtype as _to_pandas_dtype
1641    return _to_pandas_dtype(*args, **kwargs)
1642
1643
1644def filter_unseen_df(*args, **kwargs) -> Any:
1645    """
1646    Placeholder function to prevent breaking legacy behavior.
1647    See `meerschaum.utils.dataframe.filter_unseen_df`.
1648    """
1649    from meerschaum.utils.dataframe import filter_unseen_df as real_function
1650    return real_function(*args, **kwargs)
1651
1652
1653def add_missing_cols_to_df(*args, **kwargs) -> Any:
1654    """
1655    Placeholder function to prevent breaking legacy behavior.
1656    See `meerschaum.utils.dataframe.add_missing_cols_to_df`.
1657    """
1658    from meerschaum.utils.dataframe import add_missing_cols_to_df as real_function
1659    return real_function(*args, **kwargs)
1660
1661
1662def parse_df_datetimes(*args, **kwargs) -> Any:
1663    """
1664    Placeholder function to prevent breaking legacy behavior.
1665    See `meerschaum.utils.dataframe.parse_df_datetimes`.
1666    """
1667    from meerschaum.utils.dataframe import parse_df_datetimes as real_function
1668    return real_function(*args, **kwargs)
1669
1670
1671def df_from_literal(*args, **kwargs) -> Any:
1672    """
1673    Placeholder function to prevent breaking legacy behavior.
1674    See `meerschaum.utils.dataframe.df_from_literal`.
1675    """
1676    from meerschaum.utils.dataframe import df_from_literal as real_function
1677    return real_function(*args, **kwargs)
1678
1679
1680def get_json_cols(*args, **kwargs) -> Any:
1681    """
1682    Placeholder function to prevent breaking legacy behavior.
1683    See `meerschaum.utils.dataframe.get_json_cols`.
1684    """
1685    from meerschaum.utils.dataframe import get_json_cols as real_function
1686    return real_function(*args, **kwargs)
1687
1688
1689def get_unhashable_cols(*args, **kwargs) -> Any:
1690    """
1691    Placeholder function to prevent breaking legacy behavior.
1692    See `meerschaum.utils.dataframe.get_unhashable_cols`.
1693    """
1694    from meerschaum.utils.dataframe import get_unhashable_cols as real_function
1695    return real_function(*args, **kwargs)
1696
1697
1698def enforce_dtypes(*args, **kwargs) -> Any:
1699    """
1700    Placeholder function to prevent breaking legacy behavior.
1701    See `meerschaum.utils.dataframe.enforce_dtypes`.
1702    """
1703    from meerschaum.utils.dataframe import enforce_dtypes as real_function
1704    return real_function(*args, **kwargs)
1705
1706
1707def get_datetime_bound_from_df(*args, **kwargs) -> Any:
1708    """
1709    Placeholder function to prevent breaking legacy behavior.
1710    See `meerschaum.utils.dataframe.get_datetime_bound_from_df`.
1711    """
1712    from meerschaum.utils.dataframe import get_datetime_bound_from_df as real_function
1713    return real_function(*args, **kwargs)
1714
1715
1716def df_is_chunk_generator(*args, **kwargs) -> Any:
1717    """
1718    Placeholder function to prevent breaking legacy behavior.
1719    See `meerschaum.utils.dataframe.df_is_chunk_generator`.
1720    """
1721    from meerschaum.utils.dataframe import df_is_chunk_generator as real_function
1722    return real_function(*args, **kwargs)
1723
1724
1725def choices_docstring(*args, **kwargs) -> Any:
1726    """
1727    Placeholder function to prevent breaking legacy behavior.
1728    See `meerschaum.actions.choices_docstring`.
1729    """
1730    from meerschaum.actions import choices_docstring as real_function
1731    return real_function(*args, **kwargs)
1732
1733
1734def _get_subaction_names(*args, **kwargs) -> Any:
1735    """
1736    Placeholder function to prevent breaking legacy behavior.
1737    See `meerschaum.actions._get_subaction_names`.
1738    """
1739    from meerschaum.actions import _get_subaction_names as real_function
1740    return real_function(*args, **kwargs)
1741
1742
1743def json_serialize_datetime(dt: datetime) -> Union[str, None]:
1744    """
1745    Serialize a datetime object into JSON (ISO format string).
1746
1747    Examples
1748    --------
1749    >>> import json
1750    >>> from datetime import datetime
1751    >>> json.dumps({'a': datetime(2022, 1, 1)}, default=json_serialize_datetime)
1752    '{"a": "2022-01-01T00:00:00Z"}'
1753
1754    """
1755    from meerschaum.utils.dtypes import serialize_datetime
1756    return serialize_datetime(dt)
1757
1758
1759_current_module = sys.modules[__name__]
1760__all__ = tuple(
1761    name
1762    for name, obj in globals().items()
1763    if callable(obj)
1764        and name not in __pdoc__
1765        and getattr(obj, '__module__', None) == _current_module.__name__
1766)