feilian 1.3.4__py3-none-any.whl

feilian/__init__.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+from .io import ensure_parent_dir_exist
+from .dataframe import read_dataframe, save_dataframe, extract_dataframe_sample, merge_dataframe_rows, iter_dataframe
+from .dataframe import is_empty_text, is_nonempty_text, is_blank_text, is_non_blank_text
+from .datetime import format_time, format_date
+from .arg import ArgValueParser
+from .json import read_json, save_json, write_json, read_big_json
+from .txt import (
+    detect_stream_encoding, detect_file_encoding, get_file_encoding,
+    read_txt, save_txt, write_txt,
+)
+from .process import DataframeProcessor
+from .excel import save_excel, write_excel
+from .utils import flatten_dict, flatten_list
+from .version import __version__
+
+__all__ = [
+    'ensure_parent_dir_exist',
+    'read_dataframe', 'save_dataframe', 'extract_dataframe_sample', 'merge_dataframe_rows', 'iter_dataframe',
+    'is_empty_text', 'is_nonempty_text', 'is_blank_text', 'is_non_blank_text',
+    'format_time', 'format_date',
+    'ArgValueParser',
+    'read_json', 'save_json', 'write_json', 'read_big_json',
+    'detect_stream_encoding', 'detect_file_encoding', 'get_file_encoding',
+    'read_txt', 'save_txt', 'write_txt',
+    'save_excel', 'write_excel',
+    'DataframeProcessor',
+    'flatten_dict', 'flatten_list',
+    '__version__',
+]

feilian/_dist_ver.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+# file generated by setuptools_scm
+# don't change, don't track in version control
+VERSION = (1, 3, 4)
+__version__ = '1.3.4'

feilian/_typing.py

@@ -0,0 +1,5 @@
+from typing import *
+try:
+    from typing import Literal
+except ImportError:
+    from typing_extensions import Literal

feilian/arg.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+
+from ._typing import (
+    Union, List, Any, Iterable,
+    Callable, Set, Optional, Tuple,
+    Dict, Hashable, Sequence,
+    Literal,
+)
+
+_build_in_na_checkers = {
+    'always_na': lambda x: True,
+    'never_na': lambda x: False,
+    'is_none': lambda x: x is None,
+}
+_NA_CHECKER_TYPES = Union[Callable[[Any], bool], Literal['always_na', 'never_na', 'is_none']]
+
+_build_in_na_converters = {
+    'none': lambda x: None,
+    'self': lambda x: x,
+    'empty': lambda x: [],
+    'single': lambda x: [x],
+}
+_NA_CONVERTER_TYPES = Union[Callable[[Any], Any], Literal['none', 'self', 'empty', 'single']]
+
+def _get_or_default(value: Any, mapping: Dict[Hashable, Any], default_key: Any) -> Any:
+    if value is None:
+        return mapping[default_key]
+    return mapping.get(value, value)
+
+class ArgValueParser(object):
+    @classmethod
+    def split_and_parse_strs(cls, strings: Union[Sequence[str], str, None],
+                             func: Callable[[str], Any] = None,
+                             sep=',', do_trim=True, ignore_blank=True) -> Iterable[Any]:
+        """
+        split and parse multi string values
+        :param strings:  sequence of strings
+        :param func:     function to parse single string value
+        :param sep:      seperator to split single string
+        :param do_trim:  trim every word or not
+        :param ignore_blank:    ignore blank or not; in some case, this must be `True`
+        """
+        if isinstance(strings, str):
+            strings = [strings]
+        if strings:
+            for value in strings:
+                for x in value.split(sep):
+                    if do_trim:
+                        x = x.strip()
+                    if not x and ignore_blank:
+                        continue
+                    yield func(x) if func else x
+
+    @classmethod
+    def split_strs_to_set(cls, values: Union[Sequence[str], str, None],
+                          func: Callable[[str], Any] = None,
+                          sep=',', do_trim=True, ignore_blank=True) -> Optional[Set[Any]]:
+        """
+        split multi string values as words to a set
+        """
+        return set(cls.split_and_parse_strs(values, func, sep, do_trim, ignore_blank))
+
+    @classmethod
+    def split_strs_to_list(cls, values: Union[Sequence[str], str, None],
+                           func: Callable[[str], Any] = None,
+                           sep=',', do_trim=True, ignore_blank=True) -> Optional[List[Any]]:
+        """
+        split multi string values as words to a list
+        """
+        return list(cls.split_and_parse_strs(values, func, sep, do_trim, ignore_blank))
+
+    @staticmethod
+    def bound_collection_if_singleton(value: Any, collection_type: type,
+                                      elem_type: Union[type, Tuple[type]] = (),
+                                      allowed_type=(list, tuple, set)) -> Any:
+        """
+        if `value` is a singleton element, bound it with a collection type.
+        :param value:       the input value may be bounded
+        :param collection_type:     may be `list`, `tuple` or `set`
+        :param elem_type:       if `value` is instance of `elem_type` but not instance of `allowed_type`, bound  it.
+        :param allowed_type:    if `value` is instance of `allowed_type`, return the `value` unchanged.
+        """
+        if isinstance(value, allowed_type):
+            return value
+        if isinstance(value, elem_type):
+            return collection_type([value])
+        return value
+
+    @classmethod
+    def bound_list_if_singleton(cls, value: Any, elem_type: Union[type, Tuple[type]] = (),
+                                allowed_type=(list, tuple, set)) -> Any:
+        """
+        If `value` is a singleton element, bound it to be a `list`.
+        See more arg docs in `bound_collection_if_singleton()`.
+        """
+        return cls.bound_collection_if_singleton(value, collection_type=list,
+                                                 elem_type=elem_type, allowed_type=allowed_type)
+
+    @classmethod
+    def bound_tuple_if_singleton(cls, value: Any, elem_type: Union[type, Tuple[type]] = (),
+                                 allowed_type=(list, tuple, set)) -> Any:
+        """
+        If `value` is a singleton element, bound it to be a `tuple`.
+        See more arg docs in `bound_collection_if_singleton()`.
+        """
+        return cls.bound_collection_if_singleton(value, collection_type=tuple,
+                                                 elem_type=elem_type, allowed_type=allowed_type)
+
+    @classmethod
+    def bound_set_if_singleton(cls, value: Any, elem_type: Union[type, Tuple[type]] = (),
+                               allowed_type=(list, tuple, set)) -> Any:
+        """
+        If `value` is a singleton element, bound it to be a `set`.
+        See more arg docs in `bound_collection_if_singleton()`.
+        """
+        return cls.bound_collection_if_singleton(value, collection_type=set,
+                                                 elem_type=elem_type, allowed_type=allowed_type)
+
+    @staticmethod
+    def ensure_collection(value: Any, expected_type: type, collection_type: Union[type, Tuple[type, ...]],
+                          na_checker: _NA_CHECKER_TYPES = None, na_converter: _NA_CONVERTER_TYPES = None) -> Any:
+        """
+        Ensure the value to be a list, tuple or set.
+        :param value:   any type value
+        :param expected_type:       expected return type, can be list, tuple or set
+        :param collection_type:     other collection type to be convert
+        :param na_checker:      check if `value` is na, default is 'is_none'
+                                str value means some built-in functions:
+                                    always_na:  always treat the value as na
+                                    never_na:   never treat the value as na
+                                    is_none:    test if the value is `None`
+        :param na_converter:    if `value` is na, return output of this function, default is 'self'
+                                str value means some built-in functions:
+                                    none:   `None`
+                                    self:   the value no changed
+                                    empty:  an empty list
+                                    single: a single value list: `[value]`
+        :return:    expected to be an instance of `expected_type`, or be `None` for some condition
+        """
+        na_checker = _get_or_default(na_checker, _build_in_na_checkers, 'is_none')
+        if na_checker(value):
+            na_converter = _get_or_default(na_converter, _build_in_na_converters, 'self')
+            return na_converter(value)
+        if isinstance(value, expected_type):
+            return value
+        if isinstance(value, collection_type):
+            return expected_type(value)
+        return expected_type([value])
+
+    @classmethod
+    def ensure_list(cls, value: Any, na_checker: _NA_CHECKER_TYPES = None,
+                    na_converter: _NA_CONVERTER_TYPES = None) -> Optional[List[Any]]:
+        """
+        Ensure the value to be a list.
+        See more arg docs in `ensure_collection()`.
+        """
+        return cls.ensure_collection(value, expected_type=list, collection_type=(tuple, set),
+                                     na_checker=na_checker, na_converter=na_converter)
+
+    @classmethod
+    def ensure_tuple(cls, value: Any, na_checker: _NA_CHECKER_TYPES = None,
+                     na_converter: _NA_CONVERTER_TYPES = None) -> Optional[Tuple[Any]]:
+        """
+        Ensure the value to be a tuple.
+        See more arg docs in `ensure_collection()`.
+        """
+        return cls.ensure_collection(value, expected_type=tuple, collection_type=(list, set),
+                                     na_checker=na_checker, na_converter=na_converter)
+
+    @classmethod
+    def ensure_set(cls, value: Any, na_checker: _NA_CHECKER_TYPES = None,
+                   na_converter: _NA_CONVERTER_TYPES = None) -> Optional[Set[Any]]:
+        """
+        Ensure the value to be a set.
+        See more arg docs in `ensure_collection()`.
+        """
+        return cls.ensure_collection(value, expected_type=set, collection_type=(list, tuple),
+                                     na_checker=na_checker, na_converter=na_converter)
+

feilian/dataframe.py

@@ -0,0 +1,311 @@
+# -*- coding: utf-8 -*-
+
+"""
+Encapsulate methods for pandas `DataFrame`.
+"""
+
+import io
+import os
+import pathlib
+import pandas as pd
+import random
+import collections
+from ._typing import Union, Iterable, Dict, List, Any, Sequence, Callable, Tuple, Hashable, Literal
+from .io import ensure_parent_dir_exist
+from .txt import detect_stream_encoding, detect_file_encoding
+
+# Compatible with different pandas versions
+PD_PARAM_NEWLINE = 'lineterminator'
+pd_version = [int(x) for x in pd.__version__.split('.')]
+if pd_version[0] < 1 or (pd_version[0] == 1 and pd_version[1] < 5):
+    PD_PARAM_NEWLINE = 'line_terminator'
+
+FILE_FORMAT = Literal['csv', 'tsv', 'json', 'xlsx', 'parquet']
+COMPRESSION_FORMAT = Literal[None, 'infer', 'snappy', 'gzip', 'brotli', 'bz2', 'zip', 'xz']
+
+def _drop_na_values(data: Union[pd.DataFrame, Dict[str, pd.DataFrame]], axis: Literal['columns', 'rows']):
+    if isinstance(data, pd.DataFrame):
+        data.dropna(axis=axis, how='all', inplace=True)
+    else:
+        assert isinstance(data, dict)
+        for df in data.values():
+            df.dropna(axis=axis, how='all', inplace=True)
+
+def _infer_file_format(file) -> str:
+    if isinstance(file, pd.ExcelWriter):
+        return 'xlsx'
+    elif isinstance(file, str):
+        return os.path.splitext(file)[1].lower()[1:]
+    elif isinstance(file, pathlib.PurePath):
+        suf = file.suffix
+        return suf[1:] if suf.startswith('.') else suf
+    elif isinstance(file, os.PathLike):
+        return os.path.splitext(os.fspath(file))[1].lower().lstrip('.')
+    else:
+        raise ValueError(f"Cannot infer format for type: {type(file)}")
+
+def read_dataframe(file: Union[str, os.PathLike, io.IOBase], *args, sheet_name=0,
+                   file_format: FILE_FORMAT = None, encoding='auto',
+                   jsonl=False, dtype: type = None,
+                   drop_na_columns=False, drop_na_rows=False,
+                   **kwargs) -> Union[pd.DataFrame, Dict[str, pd.DataFrame]]:
+    """
+    read file as pandas `DataFrame`
+    :param file:        the file to be read
+    :param args:        extra args for `pd.read_xx()`
+    :param sheet_name:      `sheet_name` for `pd.read_excel()`
+    :param file_format:     csv, tsv, json ,xlsx, parquet
+    :param encoding:    text file encoding
+    :param jsonl:       jsonl format or not, only used in json format
+    :param dtype:       `dtype` for `pd.read_xx()`
+    :param drop_na_columns:     drop column if all values of the column is na
+    :param drop_na_rows:        drop row if all values of the row is na
+    :param kwargs:      extra kwargs for `pd.read_xx()`
+    """
+    # decide the file format
+    if not file_format:
+        file_format = _infer_file_format(file)
+
+    for key in ['lines', 'line_delimited_json_format']:
+        if key in kwargs and kwargs.pop(key):
+            jsonl = True
+
+    # handle special formats
+    if file_format == 'tsv':
+        # if the file format is tsv, actually same as csv
+        file_format = 'csv'
+        if 'sep' in kwargs:
+            kwargs.pop('sep')
+        kwargs['delimiter'] = '\t'
+    elif file_format == 'jsonl':
+        file_format = 'json'
+        jsonl = True
+
+    # detect encoding
+    if encoding == 'auto' and file_format in ['csv', 'json']:
+        if isinstance(file, (str, os.PathLike)):
+            encoding = detect_file_encoding(file)
+        elif isinstance(file, io.IOBase) and file.seekable():
+            tell = file.tell()
+            encoding = detect_stream_encoding(file)
+            file.seek(tell)
+        else:
+            # read file may cause content change, so we cannot detect the encoding
+            encoding = None
+
+    if file_format == 'csv':
+        df = pd.read_csv(file, *args, encoding=encoding, dtype=dtype, **kwargs)
+    elif file_format == 'xlsx':
+        df = pd.read_excel(file, *args, sheet_name=sheet_name, dtype=dtype, **kwargs)
+    elif file_format == 'json':
+        try:
+            df = pd.read_json(file, *args, encoding=encoding, lines=jsonl, dtype=dtype, **kwargs)
+        except Exception as e:
+            # if failed, try again with different arg `lines`
+            try:
+                df = pd.read_json(file, *args, lines=not jsonl, dtype=dtype, **kwargs)
+            except Exception:
+                raise e
+    elif file_format == 'parquet':
+        df = pd.read_parquet(file, *args, **kwargs)
+    else:
+        raise IOError(f"Unknown file format: {file}")
+
+    if drop_na_columns:
+        _drop_na_values(df, axis='columns')
+    if drop_na_rows:
+        _drop_na_values(df, axis='rows')
+
+    return df
+
+def save_dataframe(file: Union[str, os.PathLike, 'pd.WriteBuffer[bytes]',  'pd.WriteBuffer[str]'],
+                   df: Union[pd.DataFrame, Iterable[Union[pd.Series, Dict[str, Any]]]],
+                   *args, sheet_name='Sheet1',
+                   file_format: FILE_FORMAT = None,
+                   compression: COMPRESSION_FORMAT = None,
+                   index=False, index_label=None,
+                   encoding='utf-8', newline='\n',
+                   force_ascii=False,
+                   orient='records', jsonl=True, indent=None,
+                   column_mapper: Union[Dict[str, str], Sequence[str]] = None,
+                   include_columns: Sequence[str] = None,
+                   exclude_columns: Sequence[str] = None,
+                   **kwargs):
+    """
+    save data into file
+    :param file:                where to save the data to
+    :param df:                  the data
+    :param args:                extra args for df.to_xx()
+    :param sheet_name:          `sheet_name` for excel format
+    :param file_format:         csv, tsv, json, xlsx, parquet
+    :param compression:         name of the compression to use.
+                                use `None` for no compression.
+    :param index:               save index or not, see docs in df.to_csv();
+                                if set as str and `index_label` not set, `index_label` will be set as this
+    :param index_label:         header for the index when `index` is `True`
+    :param encoding:            text file encoding
+    :param newline:             text file newline
+    :param force_ascii:         `force_ascii` for json format
+    :param orient:              `orient` for json format
+    :param jsonl:               jsonl format or not
+    :param indent:              indent for json format
+    :param column_mapper:       rename columns; if set, columns not list here will be ignored
+    :param include_columns:     if set, columns not list here will be ignored
+    :param exclude_columns:     if set, columns list here will be ignored
+    :param kwargs:              extra kwargs for df.to_xx()
+    """
+    # decide file format
+    if not file_format:
+        file_format = _infer_file_format(file)
+
+    # convert data to be a dataframe
+    if not isinstance(df, pd.DataFrame):
+        df = pd.DataFrame(df)
+
+    for key in ['lines', 'line_delimited_json_format']:
+        if key in kwargs and kwargs.pop(key):
+            jsonl = True
+
+    # deal with columns
+    if column_mapper:
+        df = df.rename(columns=column_mapper)
+    if exclude_columns:
+        df = df.drop(exclude_columns, axis=1)
+    if include_columns:
+        df = df.reindex(include_columns, axis=1)
+
+    # ensure parent dir exists
+    if isinstance(file, (str, os.PathLike)):
+        ensure_parent_dir_exist(file)
+
+    # compatible for set index just use arg `index`
+    if index_label is None and isinstance(index, str):
+        index, index_label = True, index
+
+    # handle special formats
+    if file_format == 'tsv':
+        # tsv is actually a csv
+        file_format = 'csv'
+        kwargs['sep'] = '\t'
+    elif file_format == 'jsonl':
+        file_format = 'json'
+        jsonl = True
+
+    # save to file for different format
+    if file_format == 'csv':
+        kwargs[PD_PARAM_NEWLINE] = newline
+        df.to_csv(file, *args, compression=compression, index=index, index_label=index_label,
+                  encoding=encoding, **kwargs)
+    elif file_format == 'xlsx':
+        df.to_excel(file, *args, index=index, index_label=index_label, sheet_name=sheet_name, **kwargs)
+    elif file_format == 'json':
+        if jsonl:
+            orient = 'records'
+            indent = None
+        if orient not in ['split', 'table']:
+            index = True
+        df.to_json(file, *args, compression=compression, index=index,
+                   force_ascii=force_ascii, orient=orient, lines=jsonl,
+                   indent=indent, **kwargs)
+    elif file_format == 'parquet':
+        df.to_parquet(file, *args, compression=compression, index=index, **kwargs)
+    else:
+        raise IOError(f"Unknown file format: {file}")
+
+def iter_dataframe(data: pd.DataFrame,
+                   progress_bar: Union[bool, str, 'tqdm', Callable[[Iterable[Any]], 'tqdm']] = False
+                   ) -> Iterable[Tuple[Hashable, pd.Series]]:
+    """
+    iter dataframe rows, may show a progress bar
+    :param data:            dataframe
+    :param progress_bar:    show a progress bar or not
+                            if set a non-empty string, the string will be set as the progress bar description
+    """
+    rows = data.iterrows()
+    if progress_bar:
+        from tqdm import tqdm
+        if isinstance(progress_bar, tqdm):
+            progress_bar.iterable = rows
+            rows = progress_bar
+        elif isinstance(progress_bar, str):
+            rows = tqdm(rows, total=len(data), desc=progress_bar)
+        elif callable(progress_bar):
+            rows = progress_bar(rows)
+        else:
+            rows = tqdm(rows, total=len(data))
+    return rows
+
+def extract_dataframe_sample(data: pd.DataFrame,
+                             filter_func: Callable[[pd.Series], bool],
+                             size=0, shuffle=False,
+                             return_format: Literal['df', 'dataframe', 'list'] = 'dataframe',
+                             progress_bar=False) -> Union[pd.DataFrame, List[pd.Series]]:
+    """
+    extract sample from a dataframe
+    :param data:            original data
+    :param filter_func:     bool function, `True` means to reserve the row
+    :param size:            max size for the result
+    :param shuffle:         shuffle result or not
+    :param progress_bar:    passed to `iter_dataframe()`
+    :param return_format:   one of {'dataframe', 'list'}
+    """
+    result = [row for _, row in iter_dataframe(data, progress_bar=progress_bar) if filter_func(row)]
+    if shuffle:
+        random.shuffle(result)
+    if 0 < size < len(result):
+        result = result[:size]
+    if return_format == 'df' or return_format == 'dataframe':
+        try:
+            return pd.DataFrame(result)
+        except pd.errors.InvalidIndexError:
+            return pd.DataFrame([{k: v for k, v in x.items()} for x in result])
+    elif return_format == 'list':
+        return result
+    raise ValueError("Param 'return_format' should be one of {'dataframe', 'list'}.")
+
+def is_empty_text(s: str) -> bool:
+    return pd.isna(s) or not s
+
+def is_nonempty_text(s: str) -> bool:
+    return pd.notna(s) and isinstance(s, str) and s
+
+def is_blank_text(s: str) -> bool:
+    return pd.isna(s) or isinstance(s, str) and not s.strip()
+
+def is_non_blank_text(s: str) -> bool:
+    return pd.notna(s) and isinstance(s, str) and s.strip()
+
+def join_values(values: Sequence[Any], sep=None) -> str:
+    if not values:
+        return ''
+    if len(values) == 1:
+        return str(values[0])
+    return sep.join(map(str, values)) if sep else values
+
+def merge_dataframe_rows(data: pd.DataFrame, col_id='ID', na=None, join_sep=None, progress_bar=False) -> pd.DataFrame:
+    """
+    merge rows of same id to one row, similar to group by in sql
+    :param data:            original data
+    :param col_id:          column name for the id col
+    :param na:              values to be treated as na
+    :param join_sep:        seperator to join multi values
+    :param progress_bar:    passed to `iter_dataframe()`
+    """
+    if na is None:
+        na = set()
+    elif isinstance(na, str):
+        na = {na}
+    else:
+        na = set(na)
+    counts = collections.defaultdict(lambda: collections.defaultdict(collections.Counter))
+    rows = iter_dataframe(data, progress_bar=progress_bar)
+    for i, row in rows:
+        eid = row[col_id]
+        for k, v in row.items():
+            if pd.notna(v) and v not in na:
+                counts[eid][k][v] += 1
+    result = []
+    for x in counts.values():
+        item = {col: join_values(list(values.keys()), sep=join_sep) for col, values in x.items()}
+        result.append(item)
+    return pd.DataFrame(result)

feilian/datetime.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+from ._typing import Union
+import pandas as pd
+import datetime
+
+def format_time(time: Union[str, int, float, datetime.datetime] = None, fmt='%Y-%m-%d %H:%M:%S') -> str:
+    if time is None:
+        time = datetime.datetime.now()
+    elif isinstance(time, (int, float)):
+        time = datetime.datetime.fromtimestamp(time)
+    elif isinstance(time, str):
+        time = pd.to_datetime(time)
+    else:
+        if not isinstance(time, datetime.datetime):
+            raise ValueError(f"Unexpected type: {type(time)}")
+    return time.strftime(fmt)
+
+# when format a date, no sep is used more
+def format_date(date: Union[str, int, float, datetime.datetime] = None, sep='') -> str:
+    return format_time(date, fmt=sep.join(['%Y', '%m', '%d']))

feilian/excel.py

@@ -0,0 +1,83 @@
+import pandas as pd
+from ._typing import Union, Iterable, Dict, Sequence, Any, List, Tuple
+from .dataframe import save_dataframe
+
+def _save_excel(file, df, *args, **kwargs):
+    # if df is a list of dataframe, then save each dataframe into a sheet
+    if isinstance(df, (list, tuple)) and df and all(isinstance(x, pd.DataFrame) for x in df):
+        if 'sheet_name' in kwargs:
+            kwargs.pop('sheet_name')
+        with pd.ExcelWriter(file) as writer:
+            for i, x in enumerate(df, 1):
+                save_dataframe(writer, x, *args, sheet_name=f"Sheet{i}", **kwargs)
+    elif isinstance(df, dict) and df and all(isinstance(x, pd.DataFrame) for x in df.values()):
+        if 'sheet_name' in kwargs:
+            kwargs.pop('sheet_name')
+        with pd.ExcelWriter(file) as writer:
+            for name, x in df.items():
+                save_dataframe(writer, x, *args, sheet_name=name, **kwargs)
+    else:
+        return save_dataframe(file, df, *args, **kwargs)
+
+_FILE_TYPES = Union[str, 'pd.WriteBuffer[bytes]', 'pd.WriteBuffer[str]']
+_DATA_TYPES = Union[
+    pd.DataFrame, Iterable[Union[pd.Series, Dict[str, Any]]],
+    List[pd.DataFrame], Tuple[pd.DataFrame], Dict[str, pd.DataFrame]
+]
+
+def save_excel(file: _FILE_TYPES, df: _DATA_TYPES,
+               *args, sheet_name='Sheet1',
+               header: Union[Sequence[str], bool] = True,
+               index=False, index_label=None,
+               column_mapper: Union[Dict[str, str], Sequence[str]] = None,
+               include_columns: Sequence[str] = None,
+               exclude_columns: Sequence[str] = None,
+               **kwargs):
+    """
+    save data into file
+    :param file:                where to save the data to
+    :param df:                  the data
+    :param args:                extra args for df.to_xx()
+    :param sheet_name:          `sheet_name` for excel format
+    :param header:              `header` for excel format
+    :param index:               save index or not, see docs in df.to_csv();
+                                if set as str and `index_label` not set, `index_label` will be set as this
+    :param index_label:         header for the index when `index` is `True`
+    :param column_mapper:       rename columns; if set, columns not list here will be ignored
+    :param include_columns:     if set, columns not list here will be ignored
+    :param exclude_columns:     if set, columns list here will be ignored
+    :param kwargs:              extra kwargs for df.to_xx()
+    """
+    _save_excel(
+        file, df, *args,
+        sheet_name=sheet_name,
+        header=header,
+        index=index,
+        index_label=index_label,
+        column_mapper=column_mapper,
+        include_columns=include_columns,
+        exclude_columns=exclude_columns,
+        **kwargs
+    )
+
+def write_excel(
+    file: _FILE_TYPES, df: _DATA_TYPES,
+    *args, sheet_name='Sheet1',
+    header: Union[Sequence[str], bool] = True,
+    index=False, index_label=None,
+    column_mapper: Union[Dict[str, str], Sequence[str]] = None,
+    include_columns: Sequence[str] = None,
+    exclude_columns: Sequence[str] = None,
+    **kwargs
+):
+    save_excel(
+        file, df, *args,
+        sheet_name=sheet_name,
+        header=header,
+        index=index,
+        index_label=index_label,
+        column_mapper=column_mapper,
+        include_columns=include_columns,
+        exclude_columns=exclude_columns,
+        **kwargs
+    )

feilian/io.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+import os
+
+def ensure_parent_dir_exist(filepath: str):
+    os.makedirs(os.path.abspath(os.path.dirname(filepath)), exist_ok=True)