工具集

基础工具一

Functions:

`agg_parser`(agg)	将字典形式的agg聚合参数转换为[原字段名，计算函数，储存字段名]列表形式
`ensure_ext`(ext)	规范文件扩展名，保持扩展名为点(.)开头
`ensure_list`(val)	将标量值和Collection类型都统一转换为LIST类型
`is_empty`(x)	判断变量是否为空值
`log`(msg)	打印带有时间的日志信息
`not_empty`(x)	判断是否非空，对`is_empty`取反
`second_to_desc`(second)	将秒转为时间描述
`second_to_dhms`(second)	将秒转为天、时、分、秒
`to_datetime`(x[, format])	兼容pandas1和2的pd.to_datatime方法
`warn_`(msg[, if_or_not, mode])	打印警告信息，嵌入函数内部，可由if_or_not控制是否打印

ricco.base.agg_parser(agg: dict) → list: 将字典形式的agg聚合参数转换为[原字段名，计算函数，储存字段名]列表形式

ricco.base.ensure_ext(ext: str)

规范文件扩展名，保持扩展名为点(.)开头

示例

>>> ensure_ext('csv')
'.csv'

ricco.base.ensure_list(val): 将标量值和Collection类型都统一转换为LIST类型

ricco.base.is_empty(x) → bool

判断变量是否为空值

以下值认为是空白：

空白列表、字典, 如：[], {}
空白Dataframe、Series, 如：pd.DataFrame()
空白shapely格式的geometry，如：Point(np.nan, np.nan)

ricco.base.log(msg): 打印带有时间的日志信息

ricco.base.not_empty(x) → bool: 判断是否非空，对`is_empty`取反

ricco.base.second_to_desc(second: (<class 'int'>, <class 'float'>)) → str

将秒转为时间描述

示例

>>> second_to_desc(123)
'2m 3s'
>>> second_to_desc(1234)
'20m 40s'
>>> second_to_desc(123456)
'1d 10h 17m 36s'

ricco.base.second_to_dhms(second: int) → tuple: 将秒转为天、时、分、秒

ricco.base.to_datetime(x, format=None, *args, **kwargs): 兼容pandas1和2的pd.to_datatime方法

ricco.base.warn_(msg, if_or_not=True, mode='warning')

打印警告信息，嵌入函数内部，可由if_or_not控制是否打印

参数:

msg – 要输出的警告信息
if_or_not – 是否输出
mode – 警告类型，支持logging和warning

基础工具二

Functions:

`and_`(*conditions)	对多个条件执行and操作
`check_diff`(ls1, ls2)	检查两个列表的差集
`diff`(ls1, ls2)	求两个列表的差集
`drop_repeat`(x)	删除列表中连续重复的元素
`eval_`(x)	将文本型的列表、字典等转为真正的类型
`extract_num`(string[, num_type, method, ...])	提取字符串中的数值，默认返回所有数字组成的列表
`first_notnull_value`(series)	筛选第一个不为空的值
`fix2str`(s)	修复字符串中的换行符和多余的空格：
`fix_str`(x)	将字符串两端的空格及换行符删除，如果为空白字符串则返回空值
`fuzz_match`(string, string_set[, ...])	为某一字符串从某一集合中匹配相似度最高的元素
`fuzz_pair`(ls1, ls2[, score])	模糊配对
`get_city_id_by_name`(city)	获取城市代码
`get_shortest_element`(elements)	获取列表中长度最短的元素
`get_uuid`(s)	针对格式错误的uuid和空白值生成新的uuid
`house_type_format`(x)	通过正则表达式将户型统一修改为1房，2房···5房及以上，目前只支持9室以下户型，其中5室及以上的类别为“5房及以上”
`interchange_dict`(dic)	将字典的key和value互换
`is_digit`(x)	判断一个值是否能通过float方法转为数值型
`is_hex`(string)	判断一个字符串是否是十六进制格式
`is_unique_series`(df[, key_cols, ignore_na])	判断Dataframe中的某一列或某几列的组合是否唯一
`is_valid_uuid`(uuid_to_test[, version])	判断一个字符是否是uuid
`isinstances`(values, types)	检查列表内的元素类型是否全部满足多个类型之一
`list2dict`(x)	列表转为字典，key为元素的顺序
`or_`(*conditions)	对多个条件执行or操作
`per2float`(string)	带有百分号的数值字符串转小数点形式的数值，没有百分号的返回原值
`physical_age`(birthday[, deadline])	计算周岁，默认按照当前时间点计算
`pinyin`(word)	将中文转换为汉语拼音
`re_fast`(pattern, string[, warning])	根据正则表达式快速提取匹配到的第一个
`re_multi`(compiles, string)	根据多个正则表达式提取匹配到的所有值
`relstrip`(string, kwd)	通过正则表达式删除左侧字符串
`remove_null_in_dict`(dic)	将字典中值为空的元素删掉
`rerstrip`(string, kwd)	通过正则表达式删除右侧字符串
`rstrip_d0`(x)	删除末尾的‘.0’,并转为str格式，适用于对手机号等场景，如：'130.0' -> '130'
`segment`(x, gap[, sep, unit, bottom, top])	区间段划分工具
`sort_by_list`(src_list, by_list[, filter_])	根据一个列表对另一个列表进行筛选或排序，参照列表中不存在的元素按照原始顺序排列在后
`to_bool`(x[, na, other, t_list, f_list])	将常见的布尔类型的代替值转为布尔类型
`to_float`(string[, rex_method, ignore_pct, ...])	字符串转换为float
`to_json_string`(string[, errors])	将字符串转为json格式的字符串
`to_str_list`(series)	将列表中的元素保留为字符串、唯一、非空
`union_list_v2`(*lists)	合并列表
`union_str_v2`(*strings[, sep])	连接字符串，空白字符串会被忽略

ricco.util.util.and_(*conditions): 对多个条件执行and操作

ricco.util.util.check_diff(ls1: list, ls2: list): 检查两个列表的差集

ricco.util.util.diff(ls1: list, ls2: list): 求两个列表的差集

ricco.util.util.drop_repeat(x: (<class 'list'>, <class 'tuple'>))

删除列表中连续重复的元素

示例

>>> drop_repeat([1, 2, 2, 3, 4, 4, 4, 3])
[1, 2, 3, 4, 3]

ricco.util.util.eval_(x: str): 将文本型的列表、字典等转为真正的类型

ricco.util.util.extract_num(string: str, num_type: str = 'str', method: str = 'list', join_list: bool = False, ignore_pct: bool = True, multi_warning=False)

提取字符串中的数值，默认返回所有数字组成的列表

参数:

string – 输入的字符串
num_type – 输出的数字类型，int/float/str，默认为str
method – 结果计算方法，对结果列表求最大/最小/平均/和等，numpy方法，默认返回列表本身
join_list – 是否合并列表，默认FALSE
ignore_pct – 是否忽略百分号，默认True
multi_warning – 当有多个值的时候是否输出警告信息

ricco.util.util.first_notnull_value(series: Iterable): 筛选第一个不为空的值

ricco.util.util.fix2str(s: str) → str

修复字符串中的换行符和多余的空格：

连续多个换行符或空格，替换为一个空格
删除字符串两端的换行符或空格
空值：返回空白字符串
非字符串：返回str()后的值

ricco.util.util.fix_str(x: str) -> (<class 'str'>, None): 将字符串两端的空格及换行符删除，如果为空白字符串则返回空值

ricco.util.util.fuzz_match(string: str, string_set: (<class 'list'>, <class 'pandas.core.series.Series'>, <class 'tuple'>), fix_string_set: bool = False, valid_score: int = 0)

为某一字符串从某一集合中匹配相似度最高的元素

参数:

string – 输入的字符串
string_set – 要去匹配的集合
fix_string_set – 是否修复string_set中的异常数据，使用该选项会降低性能
valid_score – 相似度大于该值的才返回

Returns: 字符串及相似度组成的列表

ricco.util.util.fuzz_pair(ls1, ls2, score=50): 模糊配对

ricco.util.util.get_city_id_by_name(city: str): 获取城市代码

ricco.util.util.get_shortest_element(elements: list): 获取列表中长度最短的元素

ricco.util.util.get_uuid(s): 针对格式错误的uuid和空白值生成新的uuid

ricco.util.util.house_type_format(x): 通过正则表达式将户型统一修改为1房，2房···5房及以上，目前只支持9室以下户型，其中5室及以上的类别为“5房及以上”

ricco.util.util.interchange_dict(dic: dict) → dict: 将字典的key和value互换

ricco.util.util.is_digit(x) → bool: 判断一个值是否能通过float方法转为数值型

ricco.util.util.is_hex(string) → bool: 判断一个字符串是否是十六进制格式

ricco.util.util.is_unique_series(df: ~pandas.core.frame.DataFrame, key_cols: (<class 'str'>, <class 'list'>) = None, ignore_na=False): 判断Dataframe中的某一列或某几列的组合是否唯一

ricco.util.util.is_valid_uuid(uuid_to_test, version=4): 判断一个字符是否是uuid

ricco.util.util.isinstances(values: list, types: (<class 'str'>, <class 'list'>)) → bool

检查列表内的元素类型是否全部满足多个类型之一

参数:

values – 要检查的值
types – 类型类别

ricco.util.util.list2dict(x: list): 列表转为字典，key为元素的顺序

ricco.util.util.or_(*conditions): 对多个条件执行or操作

ricco.util.util.per2float(string: str) → float: 带有百分号的数值字符串转小数点形式的数值，没有百分号的返回原值

ricco.util.util.physical_age(birthday: datetime, deadline: datetime | None = None): 计算周岁，默认按照当前时间点计算

ricco.util.util.pinyin(word: str) → str: 将中文转换为汉语拼音

ricco.util.util.re_fast(pattern, string, warning=True): 根据正则表达式快速提取匹配到的第一个

ricco.util.util.re_multi(compiles: list, string)

根据多个正则表达式提取匹配到的所有值

参数:

compiles – 经过re.compile 处理过后的正则表达式组成的列表
string – 要提取的字符串

ricco.util.util.relstrip(string, kwd): 通过正则表达式删除左侧字符串

ricco.util.util.remove_null_in_dict(dic: dict) → dict: 将字典中值为空的元素删掉

ricco.util.util.rerstrip(string, kwd): 通过正则表达式删除右侧字符串

ricco.util.util.rstrip_d0(x): 删除末尾的‘.0’,并转为str格式，适用于对手机号等场景，如：’130.0’ -> ‘130’

ricco.util.util.segment(x: (<class 'int'>, <class 'float'>), gap: (<class 'list'>, <class 'tuple'>, <class 'set'>, <class 'float'>, <class 'int'>), sep: str = '-', unit: str = '', bottom: str = '以下', top: str = '以上') → str

区间段划分工具

参数:

x – 数值
gap – 间隔，固定间隔或列表
unit – 单位，末尾
sep – 分隔符，中间
bottom – 默认为“以下”：80米以下
top – 默认为“以上”：100米以上

返回:

区间段 ‘num1分隔符num2单位’：‘80-100米’

ricco.util.util.sort_by_list(src_list, by_list, filter_=False) → list

根据一个列表对另一个列表进行筛选或排序，参照列表中不存在的元素按照原始顺序排列在后

参数:

src_list – 要进行排序的列表
by_list – 参照的列表
filter – 是否根据参照列表筛选

示例

>>> a = [1, 2, 3, 4, 5]
>>> b = [2, 5, 4, 1]
>>> sort_by_list(a, b)
[2, 5, 4, 1, 3]
>>> sort_by_list(a, b, filter_=True)
[2, 5, 4, 1]
>>> sort_by_list(b, a)
[1, 2, 4, 5]

ricco.util.util.to_bool(x, na=False, other=False, t_list: list | None = None, f_list: list | None = None)

将常见的布尔类型的代替值转为布尔类型

参数:

x – 输入值
na – 空值返回真还是假
other – 无法判断的值如何处理 - ‘raise’：抛出异常 - ‘coerce’：返回传入的值 - 除 ‘raise’ 和 ‘coerce’ 之外的其他值：直接返回该值
t_list – 指定为True的类别
f_list – 指定为False的类别

ricco.util.util.to_float(string, rex_method: str = 'mean', ignore_pct: bool = False, multi_warning=True): 字符串转换为float

ricco.util.util.to_json_string(string, errors='raise'): 将字符串转为json格式的字符串

ricco.util.util.to_str_list(series: (<class 'list'>, <class 'pandas.core.series.Series'>, <class 'tuple'>)) → list: 将列表中的元素保留为字符串、唯一、非空

ricco.util.util.union_list_v2(*lists) → list

合并列表

示例

>>> a = [1]
>>> b = [2, 3]
>>> union_list_v2(a, b)
[1, 2, 3]

ricco.util.util.union_str_v2(*strings, sep='') → str

连接字符串，空白字符串会被忽略

参数:

*strings – 要连接字符串，依次传入
sep – 连接符，默认为空白字符串

示例

>>> union_str_v2('a', 'b', sep='-')
'a-b'
>>> union_str_v2('a', 'b', 'c')
'abc'

时间和日期

Classes:

`DT`(date[, format, dst_format])	DT日期类
`DT2`(date[, date_format])

Functions:

`auto2date`(string[, errors])	自动检查格式并输出日期
`excel2date`(dates[, date_type])	excel的数字样式时间格式转日期格式
`infer_format`(string)	自动判断日期格式
`is_valid_date`(string[, na])	判断是否是一个有效的日期字符串
`to_str`(func)	将日期转为字符串的装饰器

class ricco.util.dt.DT(date: (<class 'str'>, <class 'datetime.date'>, <class 'datetime.datetime'>) = None, format='%Y-%m-%d', dst_format=None)

基类：object

DT日期类

参数:

date – 初始化支持字符串、datetime.date和datetime.datetime格式作为基准日期。不指定时，默认基准日期今天。
format – 当初始化为字符串时，需要输入format指定日期字符串格式。
dst_format – 可选。未指定时，类方法输出结果为datetime.date日期格式。指定dst_format时，输出结果为符合dst_format的字符串格式。

Methods:

date_move([years, months, days])

基于当前日期移动日期

Attributes:

`day_half_year_ago`	半年前
`first_day_of_this_month`	本月第一天
`last_day_of_this_month`	本月最后一天
`monday_of_this_week`	本周一
`one_year_ago`	一年前
`the_day_after_tomorrow`	后天
`the_day_before_yesterday`	前天
`today`	今天
`tomorrow`	明天
`yesterday`	昨天

date_move(years=0, months=0, days=0): 基于当前日期移动日期

property day_half_year_ago: 半年前

property first_day_of_this_month: 本月第一天

property last_day_of_this_month: 本月最后一天

property monday_of_this_week: 本周一

property one_year_ago: 一年前

property the_day_after_tomorrow: 后天

property the_day_before_yesterday: 前天

property today: 今天

property tomorrow: 明天

property yesterday: 昨天

class ricco.util.dt.DT2(date: (<class 'str'>, <class 'datetime.date'>, <class 'datetime.datetime'>) = None, date_format='%Y-%m-%d')

基类：object

Methods:

`date_move`([years, months, days])	移动任意年/月/日后的日期，移动数量为正数表示向后移动，负数表示向前移动
`get`([format])	指定format，输出符合format格式的字符串，否则输出datetime.date类实例

Attributes:

`day_half_year_ago`	半年前的今天
`first_day_of_this_month`	本月第一天
`last_day_of_this_month`	本月最后一天
`monday_of_this_week`	本周的星期一
`one_year_ago`	一年前的今天
`the_day_after_tomorrow`	后天
`the_day_before_yesterday`	前天
`today`	今天
`tomorrow`	明天
`yesterday`	昨天

date_move(years=0, months=0, days=0): 移动任意年/月/日后的日期，移动数量为正数表示向后移动，负数表示向前移动

property day_half_year_ago: 半年前的今天

property first_day_of_this_month: 本月第一天

get(format=None): 指定format，输出符合format格式的字符串，否则输出datetime.date类实例

property last_day_of_this_month: 本月最后一天

property monday_of_this_week: 本周的星期一

property one_year_ago: 一年前的今天

property the_day_after_tomorrow: 后天

property the_day_before_yesterday: 前天

property today: 今天

property tomorrow: 明天

property yesterday: 昨天

ricco.util.dt.auto2date(string, errors='ignore'): 自动检查格式并输出日期

ricco.util.dt.excel2date(dates, date_type='str')

excel的数字样式时间格式转日期格式

参数:

dates – 传入excel的日期格式，或ymd的日期格式
date_type – 返回日期类型，str or date

ricco.util.dt.infer_format(string) → str: 自动判断日期格式

ricco.util.dt.is_valid_date(string, na=False): 判断是否是一个有效的日期字符串

ricco.util.dt.to_str(func): 将日期转为字符串的装饰器

文件路径

Functions:

`count_files`(dir_path)	统计文件夹中文件的数量
`dir2zip`(dir_path[, overwrite, delete_origin])	压缩文件夹
`dir_iter`(dir_path[, exts, abspath, ...])	文件夹中的文件路径生成器，用于遍历文件夹中的文件
`dir_iter_list`(dir_path[, exts, abspath, ...])	文件夹中的文件路径列表
`ensure_dir`(dirpath)	确保路径为文件夹格式（以斜杠“/”结尾）
`ensure_dirpath_exist`(filepath)	确保目录存在，不存在则创建
`ext`(filepath)	获取文件扩展名
`extension`(filepath)	获取文件扩展名
`file2zip`(filepath[, overwrite, delete_origin])	将一个文件压缩为zip格式
`fn`(filepath)	路径及文件名（不含扩展名）
`getsize`(filepath)	获取文件大小
`is_using_in`(filepath, hours)	判断文件是否在某个时间段内修改过
`move_file_with_metadata`(src, dst)	移动文件并保留元数据
`path_name`(filepath)	路径及文件名（不含扩展名）
`protect_dir`(path)	检查路径是否为系统目录
`remove_ds_store`(dir_path)	删除文件夹中的.DS_Store文件
`remove_path`(path[, log])	删除文件或文件夹
`rm_scratch_file`(dir_path, days[, recursive, ...])	删除指定天数前修改过的文件
`single_ext`(path_list)	获取文件列表中所有文件的扩展名，如果只有一个则返回该扩展名
`split_path`(filepath[, abspath])	将文件路径拆分为文件夹路径、文件名、扩展名三部分

ricco.util.os.count_files(dir_path): 统计文件夹中文件的数量

ricco.util.os.dir2zip(dir_path, overwrite=False, delete_origin=False)

压缩文件夹

参数:

dir_path – 文件夹路径
overwrite – 是否覆盖已有文件
delete_origin – 是否删除原文件

ricco.util.os.dir_iter(dir_path, exts: (<class 'list'>, <class 'str'>) = None, abspath=False, recursive=False, ignore_hidden_files=True)

文件夹中的文件路径生成器，用于遍历文件夹中的文件

参数:

dir_path – 文件目录
exts – 文件扩展名，不指定则返回所有文件
abspath – 是否返回绝对路径
recursive – 是否循环遍历更深层级的文件，默认只返回当前目录下的文件
ignore_hidden_files – 是否忽略隐藏文件

ricco.util.os.dir_iter_list(dir_path, exts: (<class 'list'>, <class 'str'>) = None, abspath=False, recursive=False, reverse=False)

文件夹中的文件路径列表

参数:

dir_path – 文件目录
exts – 文件扩展名，不指定则返回所有文件
abspath – 是否返回绝对路径
recursive – 是否循环遍历更深层级的文件，默认只返回当前目录下的文件
reverse – 路径列表是否倒序

ricco.util.os.ensure_dir(dirpath: str): 确保路径为文件夹格式（以斜杠“/”结尾）

ricco.util.os.ensure_dirpath_exist(filepath): 确保目录存在，不存在则创建

ricco.util.os.ext(filepath): 获取文件扩展名

ricco.util.os.extension(filepath): 获取文件扩展名

ricco.util.os.file2zip(filepath, overwrite=False, delete_origin=False): 将一个文件压缩为zip格式

ricco.util.os.fn(filepath): 路径及文件名（不含扩展名）

ricco.util.os.getsize(filepath): 获取文件大小

ricco.util.os.is_using_in(filepath, hours): 判断文件是否在某个时间段内修改过

ricco.util.os.move_file_with_metadata(src, dst): 移动文件并保留元数据

ricco.util.os.path_name(filepath): 路径及文件名（不含扩展名）

ricco.util.os.protect_dir(path): 检查路径是否为系统目录

ricco.util.os.remove_ds_store(dir_path): 删除文件夹中的.DS_Store文件

ricco.util.os.remove_path(path, log=True): 删除文件或文件夹

ricco.util.os.rm_scratch_file(dir_path, days, recursive=False, rm_hidden_file=False, exts=None): 删除指定天数前修改过的文件

ricco.util.os.single_ext(path_list): 获取文件列表中所有文件的扩展名，如果只有一个则返回该扩展名

ricco.util.os.split_path(filepath, abspath=False): 将文件路径拆分为文件夹路径、文件名、扩展名三部分

字符串处理

Functions:

`cyclic_slice`(s[, n])	迭代生成长度为n的字符串
`drop_repeat_string`(string[, min_length, ...])	删除连续重复的字符串，按照step从大到小删除重复字符，返回去重后最短的字符串
`drop_repeat_string_by_step`(string, step)	根据指定的小块长度，获取去重后的字符串
`easy_split`(string[, seps, extra_seps])	使用常见的分隔符将字符串拆分为列表
`extract_city`(string[, na])	从字符串中提取城市（可能包含县级市）
`format_industry_addr`(addr)	产业地址清洗代码，该部分地址主要用于Geocoding，清洗到“xx路xx号即可”，过于详细的地址会导致Geocoding的准确率下降，过长的地址也会导致准确率下降
`get_breaks`(length, step)	通过长度和步长获所有可能的取端点列表的列表 .
`get_list_by_position`(string, breaks)	按照位置信息将字符串拆解为多个字符串的列表 :param string: 需要拆分的字符串 :param breaks: 位置集合列表的列表（左闭右开），[[1, 5], [5, 10], [10, 15]]
`get_single_list`(start, length, step)	获取单个起点的位置端点列表，如果起始位置不是零，则会返回0到起始位置的列表 :param start: 起始位置 :param length: 总长度 :param step: 步长
`has_chinese`(text)	检查字符串是否包含至少一个中文字符
`is_repeated`(string[, min_length])	检查输入是重复字符串组成的字符串
`is_seq`(num_str, n)	判断一个全部为数字的字符串是否含有连续n个递增或递减1的数字
`join_unique`(strs)	删除列表中连续重复的元素，并拼接成字符串
`punctuation_en2cn`(text)	将英文标点符号替换为中文标点符号
`remove_control_chars`(text)	删除特殊字符

ricco.util.strings.cyclic_slice(s, n=5): 迭代生成长度为n的字符串

ricco.util.strings.drop_repeat_string(string, min_length=3, max_length=None)

删除连续重复的字符串，按照step从大到小删除重复字符，返回去重后最短的字符串

参数:

string – 要处理的字符串
min_length – 识别的最短长度，默认为3
max_length – 识别的最长长度，默认不限制

示例

>>> drop_repeat_string('上海市上海市杨浦区')
'上海市杨浦区'

ricco.util.strings.drop_repeat_string_by_step(string, step): 根据指定的小块长度，获取去重后的字符串

ricco.util.strings.easy_split(string: str, seps: list = None, extra_seps: list = None)

使用常见的分隔符将字符串拆分为列表

参数:

string –
seps – 自定义分隔符
extra_seps – 额外的分隔符

ricco.util.strings.extract_city(string: str, na=None): 从字符串中提取城市（可能包含县级市）

ricco.util.strings.format_industry_addr(addr: str): 产业地址清洗代码，该部分地址主要用于Geocoding，清洗到“xx路xx号即可”，过于详细的地址会导致Geocoding的准确率下降，过长的地址也会导致准确率下降

ricco.util.strings.get_breaks(length, step)

通过长度和步长获所有可能的取端点列表的列表 .. rubric:: 示例

>>> get_breaks(10, 3) == [
>>>   [[0, 3], [3, 6], [6, 9], [9, 10]],
>>>   [[0, 1], [1, 4], [4, 7], [7, 10]],
>>>   [[0, 2], [2, 5], [5, 8], [8, 10]]
>>> ]

ricco.util.strings.get_list_by_position(string: str, breaks: list): 按照位置信息将字符串拆解为多个字符串的列表 :param string: 需要拆分的字符串 :param breaks: 位置集合列表的列表（左闭右开），[[1, 5], [5, 10], [10, 15]]

ricco.util.strings.get_single_list(start, length, step)

获取单个起点的位置端点列表，如果起始位置不是零，则会返回0到起始位置的列表 :param start: 起始位置 :param length: 总长度 :param step: 步长

示例

>>> get_single_list(0, 7, 3) == [[0, 3], [3, 6], [6, 7]]
>>> get_single_list(1, 7, 3) == [[0, 1], [1, 4], [4, 7]]

ricco.util.strings.has_chinese(text): 检查字符串是否包含至少一个中文字符

ricco.util.strings.is_repeated(string, min_length: int = 1): 检查输入是重复字符串组成的字符串

ricco.util.strings.is_seq(num_str: str, n: int): 判断一个全部为数字的字符串是否含有连续n个递增或递减1的数字

ricco.util.strings.join_unique(strs: list): 删除列表中连续重复的元素，并拼接成字符串

ricco.util.strings.punctuation_en2cn(text: str): 将英文标点符号替换为中文标点符号

ricco.util.strings.remove_control_chars(text): 删除特殊字符

数据校验

Functions:

`assert_columns_exists`(df, columns)	检查列是否存在
`assert_not_empty_str`(df, col[, ...])	校验是否存在空白字符串
`assert_not_null`(df, col[, skip_if_not_exists])	检查是否非空（空白字符串认为是空值）
`assert_series_digit`(df, col)	检查一列是否可以转为数值型
`assert_series_not_like`(df, col, pattern)	检查并输出符合正则表达式pattern的值
`assert_series_unique`(df[, columns, text, ...])	检查并输出重复项
`assert_subset`(values, superset)	检查values是否是superset的子集
`assert_values_in`(df, col, enums[, ...])	检查Dataframe中某一列的值是否在指定的值的范围内
`skip_column`(df, col[, skip_if_not_exists])

ricco.util.assertion.assert_columns_exists(df: DataFrame, columns: list): 检查列是否存在

ricco.util.assertion.assert_not_empty_str(df: DataFrame, col: str, skip_if_not_exists: bool = True): 校验是否存在空白字符串

ricco.util.assertion.assert_not_null(df: DataFrame, col: str, skip_if_not_exists: bool = True): 检查是否非空（空白字符串认为是空值）

ricco.util.assertion.assert_series_digit(df: DataFrame, col: str): 检查一列是否可以转为数值型

ricco.util.assertion.assert_series_not_like(df: DataFrame, col: str, pattern): 检查并输出符合正则表达式pattern的值

ricco.util.assertion.assert_series_unique(df: ~pandas.core.frame.DataFrame, columns: (<class 'str'>, <class 'list'>) = '名称', text: str = '', ignore_na=False)

检查并输出重复项

参数:

df – 要检查的Dataframe
columns – 唯一的列
text – 输出的文案
ignore_na – 是否忽略空值，默认False，为True时，有空值的行不参与校验

ricco.util.assertion.assert_subset(values: (<class 'list'>, <class 'set'>, <class 'tuple'>), superset: (<class 'list'>, <class 'set'>, <class 'tuple'>)): 检查values是否是superset的子集

ricco.util.assertion.assert_values_in(df: ~pandas.core.frame.DataFrame, col: str, enums: (<class 'dict'>, <class 'list'>), skip_if_not_exists: bool = True)

检查Dataframe中某一列的值是否在指定的值的范围内

参数:

df – 要检查的dataframe
col – 列名
enums – 指定的enum值，当传入dict时，包含在key和value中的值都通过
skip_if_not_exists – 当列不存在时是否跳过

ricco.util.assertion.skip_column(df: DataFrame, col: str, skip_if_not_exists: bool = True)

行政区划工具

Classes:

District()

Functions:

`build_automaton`(ls)	构建前缀树
`build_city`()
`build_region`()
`city_full_short_mapping`()	全称和简称的映射关系
`city_id_shortname_mapping`()	城市id和城市名称的映射关系
`city_short_full_mapping`()	简称和全称的映射关系
`city_shortname_id_mapping`()	城市名称和城市id的映射关系
`ensure_city_name`(name[, full, warning])	输入城市或区县，返回城市
`extract_city`(string[, na])	从字符串中提取城市（可能包含县级市）
`find_cities`(text)	从字符串中获取全部的城市名称的简称列表
`find_regions`(text)	从字符串中获取全部的区县名称的简称列表
`get_city_and_region`(string)	从字符串中提取城市、区县
`get_city_id_by_name`(name[, warning])	根据城市名称获取城市id
`get_city_name_by_id`(city_id[, full, warning])	根据城市id获取城市名称
`get_upload_region`(df, city)	从bd_region表中提取某个城市的区县数据，并处理成可以上传的格式
`get_upload_street`(df, city)	从bd_region表中提取某个城市的街道数据，并处理成可以上传的格式
`if_many_value`(ls[, action, warning])	处理多个值的情况 :param ls: 列表 :param action: 处理方式，可选值：'raise', 'first', 'last', 'coerce', 'all' :param warning: 是否打印警告
`is_city`(name)	是否是城市
`is_region`(name)	是否是区县
`norm_city_name`(name[, full, warning])	标准化城市名称为简称或全称
`region_full_city_mapping`()	区县名称和城市简称的映射关系，仅保留一对一的关系
`region_short_city_mapping`()	区县简称和城市简称的映射关系，仅保留一对一的关系

class ricco.util.district.District

基类：object

Methods:

`city`(name[, if_not_unique, warning])	通过地名（城市、区县）获取所在的城市名称
`city_names`(name)	返回匹配到的全部城市名称列表
`get_city_id_by_name`(name[, warning])	通过城市名称获取城市id
`get_city_name_by_id`(city_id[, full, warning])	通过城市id获取城市名称
`is_city`(name)	判断是否是地级市
`is_region`(name)	判断是否是县市区
`province`(name[, if_not_unique, warning])	通过地名（省份、城市、区县）获取所在的省份名称
`province_names`(name)	返回匹配到的全部省份名称列表

Attributes:

`city_list`	全部城市（全程+简称）列表
`region_list`	全部区县（全程+简称）列表

city(name: str, if_not_unique: str = 'coerce', warning: bool = True)

通过地名（城市、区县）获取所在的城市名称

参数:

name – 城市名称
if_not_unique – 当查询到多个结果如何处理， - None，默认，返回空值 - ‘first’，返回第一个 - ‘last’，返回最后一个 - ‘all’，返回所有城市的列表
warning – 是否打印警告

property city_list: 全部城市（全程+简称）列表

city_names(name: str): 返回匹配到的全部城市名称列表

static get_city_id_by_name(name: str, warning=True): 通过城市名称获取城市id

static get_city_name_by_id(city_id: int, full=False, warning=False): 通过城市id获取城市名称

static is_city(name: str) → bool: 判断是否是地级市

static is_region(name: str) → bool: 判断是否是县市区

province(name, if_not_unique='coerce', warning=True)

通过地名（省份、城市、区县）获取所在的省份名称

参数:

name – 地名
if_not_unique – 当查询到多个结果如何处理， - None，默认，返回空值 - first，返回第一个 - last，返回最后一个 - ‘all’，返回所有省份的列表
warning – 是否打印警告

province_names(name: str): 返回匹配到的全部省份名称列表

property region_list: 全部区县（全程+简称）列表

ricco.util.district.build_automaton(ls): 构建前缀树

ricco.util.district.build_city()

ricco.util.district.build_region()

ricco.util.district.city_full_short_mapping(): 全称和简称的映射关系

ricco.util.district.city_id_shortname_mapping(): 城市id和城市名称的映射关系

ricco.util.district.city_short_full_mapping(): 简称和全称的映射关系

ricco.util.district.city_shortname_id_mapping(): 城市名称和城市id的映射关系

ricco.util.district.ensure_city_name(name, full=False, warning=False): 输入城市或区县，返回城市

ricco.util.district.extract_city(string: str, na=None): 从字符串中提取城市（可能包含县级市）

ricco.util.district.find_cities(text): 从字符串中获取全部的城市名称的简称列表

ricco.util.district.find_regions(text): 从字符串中获取全部的区县名称的简称列表

ricco.util.district.get_city_and_region(string) → tuple: 从字符串中提取城市、区县

ricco.util.district.get_city_id_by_name(name: str, warning=True): 根据城市名称获取城市id

ricco.util.district.get_city_name_by_id(city_id: (<class 'str'>, <class 'int'>), full=False, warning=False): 根据城市id获取城市名称

ricco.util.district.get_upload_region(df, city): 从bd_region表中提取某个城市的区县数据，并处理成可以上传的格式

ricco.util.district.get_upload_street(df, city): 从bd_region表中提取某个城市的街道数据，并处理成可以上传的格式

ricco.util.district.if_many_value(ls, action='raise', warning=False): 处理多个值的情况 :param ls: 列表 :param action: 处理方式，可选值：’raise’, ‘first’, ‘last’, ‘coerce’, ‘all’ :param warning: 是否打印警告

ricco.util.district.is_city(name): 是否是城市

ricco.util.district.is_region(name): 是否是区县

ricco.util.district.norm_city_name(name, full=False, warning=False): 标准化城市名称为简称或全称

ricco.util.district.region_full_city_mapping(): 区县名称和城市简称的映射关系，仅保留一对一的关系

ricco.util.district.region_short_city_mapping(): 区县简称和城市简称的映射关系，仅保留一对一的关系

Functions:

`get_city_from_postcode`(postcode[, full, warning])	根据邮编获取城市名称
`postcode_city_mapping`()	获取邮编与城市名称的映射关系

ricco.util.postcode.get_city_from_postcode(postcode: str, full=False, warning=False)

根据邮编获取城市名称

参数:

postcode – 邮编
full – 是否返回全称
warning – 是否打印警告

ricco.util.postcode.postcode_city_mapping(): 获取邮编与城市名称的映射关系

随机工具

Functions:

`ramdom_lnglat`(df[, lng_range, lat_range])	随机生成经纬度
`random_by_prob`(mapping)	根据概率生成随机值
`random_date`()	获取随机日期
`random_name`()	随机生成中文名字，仅生成2或3字名字
`random_room_number`([unit])	生成随机的房间号

ricco.util.random.ramdom_lnglat(df: ~pandas.core.frame.DataFrame, lng_range: (<class 'tuple'>, <class 'list'>) = (72, 138), lat_range: (<class 'tuple'>, <class 'list'>) = (0, 56))

随机生成经纬度

参数:

df – 输入的dataframe
lng_range – 城市的经度范围
lat_range – 城市的纬度范围

ricco.util.random.random_by_prob(mapping: dict): 根据概率生成随机值

ricco.util.random.random_date(): 获取随机日期

ricco.util.random.random_name(): 随机生成中文名字，仅生成2或3字名字

ricco.util.random.random_room_number(unit=False): 生成随机的房间号

Kdtree

Functions:

`filter_by_dist`(ind, dist, r)	通过距离列表筛选出距离小于r的点的位置
`filter_by_limit`(ls, n)	筛选列表中的列表的前limit个元素
`kdtree_nearest`(xy_tree, xy_query[, limit, ...])	使用kdtree查询最近点
`kdtree_query`(xy_tree, xy_query[, limit, r, ...])	使用kdtree查询最近的一个或多个点
`kdtree_query_radius`(xy_tree, xy_query, r[, ...])	使用kdtree查询半径为r的点

ricco.util.kdtree.filter_by_dist(ind, dist, r): 通过距离列表筛选出距离小于r的点的位置

ricco.util.kdtree.filter_by_limit(ls, n: int): 筛选列表中的列表的前limit个元素

ricco.util.kdtree.kdtree_nearest(xy_tree, xy_query, limit: int | None = None, r: float | None = None, leaf_size=2): 使用kdtree查询最近点

ricco.util.kdtree.kdtree_query(xy_tree, xy_query, limit: int = None, r=None, leaf_size=2)

使用kdtree查询最近的一个或多个点

参数:

xy_tree – 要构造数的点集
xy_query – 查询的点集
limit – 数量限制
r – 半径限制
leaf_size – kdtree叶子节点的大小

ricco.util.kdtree.kdtree_query_radius(xy_tree, xy_query, r, limit: int = None, leaf_size=2)

使用kdtree查询半径为r的点

参数:

xy_tree – 要构造数的点集
xy_query – 查询的点集
r – 查询半径
limit – 数量限制
leaf_size – kdtree叶子节点的大小

Word文档处理

Classes:

Docx()

class ricco.util.docx.Docx

基类：object

Methods:

`add_bullet_list`(text)	添加无序列表
`add_hist_from_data`(data[, newline])	通过数据生成并添加直方图
`add_intense_quote`(text)	添加高亮段落
`add_normal_p`(text)	添加普通段落
`add_order_list`(text)	添加有序列表
`add_paragraph_color`(text, rgb)	添加自定义颜色的段落
`add_paragraph_red`(text)	添加红色字体的段落
`add_table_from_df`(df[, newline])	将dataframe作为表格写入
`add_title`(text, n)	添加标题
`add_title_0`(text)	添加大标题
`add_title_1`(text)	添加一级标题
`add_title_2`(text)	添加二级标题
`add_title_3`(text)	添加三级标题
`add_title_4`(text)	添加四级标题
`save`(file_path)	保存文件至word文档
`set_default_style`()	格式初始化

add_bullet_list(text: str): 添加无序列表

add_hist_from_data(data: list, newline=False): 通过数据生成并添加直方图

add_intense_quote(text: str): 添加高亮段落

add_normal_p(text: str): 添加普通段落

add_order_list(text: str): 添加有序列表

add_paragraph_color(text: str, rgb: (<class 'list'>, <class 'tuple'>)): 添加自定义颜色的段落

add_paragraph_red(text: str): 添加红色字体的段落

add_table_from_df(df: DataFrame, newline=False): 将dataframe作为表格写入

add_title(text: str, n: int): 添加标题

add_title_0(text: str): 添加大标题

add_title_1(text: str): 添加一级标题

add_title_2(text: str): 添加二级标题

add_title_3(text: str): 添加三级标题

add_title_4(text: str): 添加四级标题

save(file_path: str): 保存文件至word文档

set_default_style(): 格式初始化

多媒体文件处理

Functions:

get_mp3_metadata(file_path)

获取MP3文件中的元数据信息

ricco.util.media.get_mp3_metadata(file_path): 获取MP3文件中的元数据信息