feilian 1.1.2__py3-none-any.whl → 1.1.4__py3-none-any.whl

feilian/__init__.py

@@ -6,7 +6,7 @@ from .dataframe import is_empty_text, is_nonempty_text, is_blank_text, is_non_bl
 from .datetime import format_time, format_date
 from .arg import ArgValueParser
 from .json import read_json, save_json
-from .about import __version__
+from .version import __version__
 
 __all__ = [
     'ensure_parent_dir_exist',

feilian/arg.py

@@ -1,6 +1,30 @@
 # -*- coding: utf-8 -*-
 
-from typing import Union, List, Any, Iterable, Callable, Set, Optional, Tuple
+from typing import Union, List, Any, Iterable, Callable, Set, Optional, Tuple, Dict, Hashable
+try:
+    from typing import Literal
+except ImportError:
+    from typing_extensions import 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
@@ -92,49 +116,63 @@ class ArgValueParser(object):
                                                  elem_type=elem_type, allowed_type=allowed_type)
 
     @staticmethod
-    def ensure_list(value: Any, allow_none=True) -> Optional[List[Any]]:
+    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.
-        If value is `None`, return `None` if `allow_none` is `True`, else return `[None]`.
+        See more arg docs in `ensure_collection()`.
         """
-        if value is None and allow_none:
-            if allow_none:
-                return value
-            return [value]
-        if isinstance(value, list):
-            return value
-        if isinstance(value, (set, tuple)):
-            return list(value)
-        return [value]
+        return cls.ensure_collection(value, expected_type=list, collection_type=(tuple, set),
+                                     na_checker=na_checker, na_converter=na_converter)
 
-    @staticmethod
-    def ensure_tuple(value: Any, allow_none=True) -> Optional[Tuple[Any]]:
+    @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.
-        If value is `None`, return `None` if `allow_none` is `True`, else return `(None, )`.
+        See more arg docs in `ensure_collection()`.
         """
-        if value is None and allow_none:
-            if allow_none:
-                return value
-            return (value,)
-        if isinstance(value, tuple):
-            return value
-        if isinstance(value, (set, list)):
-            return tuple(value)
-        return (value,)
+        return cls.ensure_collection(value, expected_type=tuple, collection_type=(list, set),
+                                     na_checker=na_checker, na_converter=na_converter)
 
-    @staticmethod
-    def ensure_set(value: Any, allow_none=True) -> Optional[Set[Any]]:
+    @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.
-        If value is `None`, return `None` if `allow_none` is `True`, else return `{None}`.
+        See more arg docs in `ensure_collection()`.
         """
-        if value is None and allow_none:
-            if allow_none:
-                return value
-            return {value}
-        if isinstance(value, set):
-            return value
-        if isinstance(value, (tuple, list)):
-            return set(value)
-        return {value}
+        return cls.ensure_collection(value, expected_type=set, collection_type=(list, tuple),
+                                     na_checker=na_checker, na_converter=na_converter)
+

feilian/dataframe.py

@@ -4,7 +4,12 @@
 Encapsulate methods for pandas `DataFrame`.
 """
 
-from typing import Union, Iterable, Dict, Literal, List, Any, Sequence, Callable, Tuple, Hashable
+from typing import Union, Iterable, Dict, List, Any, Sequence, Callable, Tuple, Hashable
+try:
+    from typing import Literal
+except ImportError:
+    from typing_extensions import Literal
+
 import os
 import pandas as pd
 import random
@@ -19,14 +24,16 @@ if pd_version[0] < 1 or (pd_version[0] == 1 and pd_version[1] < 5):
 
 def read_dataframe(file: str, *args, sheet_name=0,
                    file_format: Literal['csv', 'tsv', 'json', 'xlsx'] = None,
-                   jsonl=False, **kwargs) -> Union[pd.DataFrame, Dict[str, pd.DataFrame]]:
+                   jsonl=False, dtype: pd._typing.DtypeArg = None,
+                   **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
-    :param jsonl:           jsonl format or not, only used in json format
+    :param jsonl:       jsonl format or not, only used in json format
+    :param dtype:       `dtype` for `pd.read_xx()`
     :param kwargs:      extra kwargs for `pd.read_xx()`
     """
     # decide the file format
@@ -47,17 +54,17 @@ def read_dataframe(file: str, *args, sheet_name=0,
         kwargs['delimiter'] = '\t'
 
     if file_format == 'csv':
-        return pd.read_csv(file, *args, **kwargs)
+        return pd.read_csv(file, *args, dtype=dtype, **kwargs)
     elif file_format == 'xlsx':
-        return pd.read_excel(file, *args, sheet_name=sheet_name, **kwargs)
+        return pd.read_excel(file, *args, sheet_name=sheet_name, dtype=dtype, **kwargs)
     elif file_format == 'json':
-        return pd.read_json(file, *args, lines=jsonl, **kwargs)
+        return pd.read_json(file, *args, lines=jsonl, dtype=dtype, **kwargs)
     else:
         raise IOError(f"Unknown file format: {file}")
 
 def save_dataframe(file: Union[str, 'pd.WriteBuffer[bytes]',  'pd.WriteBuffer[str]'],
                    df: Union[pd.DataFrame, Iterable[Union[pd.Series, Dict[str, Any]]]],
-                   *args,
+                   *args, sheet_name='Sheet1',
                    file_format: Literal['csv', 'tsv', 'json', 'xlsx'] = None,
                    index=False, index_label=None,
                    encoding='utf-8', newline='\n',
@@ -72,8 +79,10 @@ def save_dataframe(file: Union[str, 'pd.WriteBuffer[bytes]',  'pd.WriteBuffer[st
     :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
-    :param index:               save index or not, see docs in df.to_csv()
+    :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
@@ -114,6 +123,10 @@ def save_dataframe(file: Union[str, 'pd.WriteBuffer[bytes]',  'pd.WriteBuffer[st
     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
+
     # tsv is actually a csv
     if file_format == 'tsv':
         file_format = 'csv'
@@ -124,7 +137,7 @@ def save_dataframe(file: Union[str, 'pd.WriteBuffer[bytes]',  'pd.WriteBuffer[st
         kwargs[PD_PARAM_NEWLINE] = newline
         df.to_csv(file, *args, index=index, index_label=index_label, encoding=encoding, **kwargs)
     elif file_format == 'xlsx':
-        df.to_excel(file, *args, index=index, index_label=index_label, **kwargs)
+        df.to_excel(file, *args, index=index, index_label=index_label, sheet_name=sheet_name, **kwargs)
     elif file_format == 'json':
         if jsonl:
             orient = 'records'

feilian/datetime.py

@@ -16,5 +16,6 @@ def format_time(time: Union[str, int, float, datetime.datetime] = None, fmt='%Y-
             raise ValueError(f"Unexpected type: {type(time)}")
     return time.strftime(fmt)
 
-def format_date(date: Union[str, int, float, datetime.datetime] = None, sep='-') -> str:
+# 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/json.py

@@ -2,6 +2,7 @@
 
 from typing import Dict, List, Union, Any
 import json
+from .io import ensure_parent_dir_exist
 
 def read_json(filepath: str, encoding='utf-8', **kwargs):
     """
@@ -15,5 +16,6 @@ def save_json(filepath: str, data: Union[Dict[str, Any], List[Any]],
     """
     An agent for `json.dump()` with some default value.
     """
+    ensure_parent_dir_exist(filepath)
     with open(filepath, 'w', encoding=encoding, newline=newline) as f:
         json.dump(data, f, indent=indent, ensure_ascii=ensure_ascii, **kwargs)

feilian/string.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+
+from typing import Any, Callable
+
+def join_values(*values: Any, sep='', func: Callable[[Any], str] = str, do_trim=False, ignore_empty=False):
+    def f():
+        for x in values:
+            s = func(x)
+            if do_trim:
+                s = s.strip()
+            if s or not ignore_empty:
+                yield s
+    return sep.join(f())

feilian/version.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("feilian")
+except PackageNotFoundError:
+    # package is not installed
+    __version__ = "UNKNOWN"

{feilian-1.1.2.dist-info → feilian-1.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: feilian
-Version: 1.1.2
+Version: 1.1.4
 Summary: General data processing tool.
 Home-page: https://github.com/darkpeath/feilian
 Author: darkpeath

feilian-1.1.4.dist-info/RECORD

@@ -0,0 +1,12 @@
+feilian/__init__.py,sha256=D_OYSAfDALQnRsbaAXMnHyC0LtykaIXLTHq7XNcsYjU,763
+feilian/arg.py,sha256=lGZ99RkU9uhE_ziaFK2SClS3vrygteNNxTm3i_68SWw,8359
+feilian/dataframe.py,sha256=121EcLvAkbBWv_antTABTJUaq3MIl1IHh1bPjaPCC0c,9853
+feilian/datetime.py,sha256=IONvWhLeGEy9IVe6GWKEW3FhrfRrShyhGP8-RTf9r3c,763
+feilian/io.py,sha256=aYN3QwWcLoRKzhGMNutqdkmxArVcXfeWXzxCB07LcFc,155
+feilian/json.py,sha256=1GsnL-CASi4xBaycMN-Tw1ytxty7GeL2wmt7nfLfnB4,754
+feilian/string.py,sha256=G_X3dnR0Oxmi4hXF-6E5jm5M7GPjGoMYrSMyI1dj6Z4,370
+feilian/version.py,sha256=qI88ygIU5YG1b7BXxWD6l2jeVvcb78eQ__3BmRl3KCU,217
+feilian-1.1.4.dist-info/METADATA,sha256=pc2HUo4iTEzUOakzR-Js_SiNrdqHyUSg68h_HRw0dh4,911
+feilian-1.1.4.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
+feilian-1.1.4.dist-info/top_level.txt,sha256=1Q2-B6KJrcTr7drW_kik35PTVEUJLPP4wVrn0kYKwGw,8
+feilian-1.1.4.dist-info/RECORD,,

{feilian-1.1.2.dist-info → feilian-1.1.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.1)
+Generator: bdist_wheel (0.41.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

feilian/about.py

@@ -1,5 +0,0 @@
-# -*- coding: utf-8 -*-
-
-VERSION = (1, 1, 2)
-
-__version__ = ".".join(map(str, VERSION))

feilian-1.1.2.dist-info/RECORD

@@ -1,11 +0,0 @@
-feilian/__init__.py,sha256=oDG4bUXVJpqC2Q1Yhwt2AY-8-NFX1ZKcv5YyXYKuCC4,761
-feilian/about.py,sha256=_-XUlhoKoRnnHfLXI02xXzYtCUI83o2ww0MU8hlm0Mg,88
-feilian/arg.py,sha256=NwaBcKpHv7m00D5_LFuR8clQBSGX5brVXnh7ubGssas,5918
-feilian/dataframe.py,sha256=ZqGLNQLKFTGaJiK2dw41ch0IIRJhLWTHpdLBHzgafJk,9260
-feilian/datetime.py,sha256=FEZOf3pYDkjE1A1mPJU6eXmj6Mi6jyJgQxCK-04WzuI,722
-feilian/io.py,sha256=aYN3QwWcLoRKzhGMNutqdkmxArVcXfeWXzxCB07LcFc,155
-feilian/json.py,sha256=fcGHxwUEpCVaMkE9HoILC693e1_H-P6J4a8Y_6Locig,676
-feilian-1.1.2.dist-info/METADATA,sha256=sXlS7cKZR0vLodpiVzrxPd2UUpbc-DT9L1DlQ-tYyn4,911
-feilian-1.1.2.dist-info/WHEEL,sha256=5sUXSg9e4bi7lTLOHcm6QEYwO5TIF1TNbTSVFVjcJcc,92
-feilian-1.1.2.dist-info/top_level.txt,sha256=1Q2-B6KJrcTr7drW_kik35PTVEUJLPP4wVrn0kYKwGw,8
-feilian-1.1.2.dist-info/RECORD,,