flash-handler 1.0.1

A simple Excel file handler

Flash-Bomb-Demo 春耕项目教学demo - 使用文档

注意：该工具只可用于python 3环境中。

使用方法

Step: 检查文件夹结构

首先，一个完整的代码包，至少应包含下面的文件：

├── flash_handler                   存放项目代码的文件夹
│   ├── config.py                   存放了一些常量，见后文
│   ├── const.py                    存放了一些常量，见后文
│   ├── excel_processor.py          存放用于操作Excel的基础模块
│   ├── file_keeper.py              存放用于维护文件列表的基础模块
│   ├── handler.py                                              存放中间逻辑，桥接基础模块和上层逻辑          
│   ├── spring.py                   存放上层逻辑
│   ├── static                                                        存放待操作eExcel文件的文件夹                 
│   │   ├── 闪光科技北京库存.xlsx      具体的待操作的Excel文件
│   │   ├── ...                             
│   └── utils.py                    存放工具类函数
└── requirements.txt                存放程序依赖的第三方库的名称和版本

请确保spring.py文件和static文件夹处在同一目录下。

Step: 安装依赖项

在运行工具之前，需要确保工具所依赖的第三方库被正确安装。所需第三方库的名称及版本已经在requirements.txt中，可在终端内执行下面的命令以安装上相应的第三方库：

pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple  -r requirements.txt

注：-i https://pypi.tuna.tsinghua.edu.cn/simple可以让pip3工具是为了加快软件下载

Step: 准备Excel文件

将待操作的Excel文件位于static文件，该文件夹下的其它Excel文件均可删除，以避免干扰。

由于static文件夹下允许存在多个Excel文件，请尽量让static文件夹下的Excel文件有相同的表头，以避免意外情况的发生。

Step: 运行前检查

请确保Microsoft Excel、WPS等软件没有占用static文件夹下的任何一个Excel文件。

Step: 运行

在终端中把当前目录切换到spring.py所在的目录，执行如下命令，即可使用工具：

python spring.py

文件内容描述

文件Config.py

存放程序所需的一些配置项。

class Config(object):
      # 工作目录。程序将从此处获取Excel文件。
    DIR_PATH = os.getenv('FBD_DIR_PATH', 'static')
    
    # 邮箱设置
    SMTP_QQ_HOST = 'smtp.qq.com'
    SMTP_QQ_PORT = 587
    SMTP_MAIL_SUBJECT = 'python发送附件'

文件const.py

存放程序所需的一些常量。

# 分隔符。如，用户输入多个数据时在不同数据间使用的分隔符。
DELIMETERS = ',|，'

# 图表种类的内部表示
CHART_BAR_TYPE = 'bar'
CHART_PIE_TYPE = 'pie'
CHART_LINE_TYPE = 'line'

# 图表种类对外展现的名称
CHART_BAR_REPR = '柱状图'
CHART_PIE_REPR = '饼图'
CHART_LINE_REPR = '折线图'

# 图表种类对外展现的名称和内部表示的映射关系
CHART_REPR2TYPE = {
    CHART_BAR_REPR: CHART_BAR_TYPE,
    CHART_PIE_REPR: CHART_PIE_TYPE,
    CHART_LINE_REPR: CHART_LINE_TYPE,
}

# 图表纵坐标（柱状图或折线图）或统计量（饼图）计算方法的内部表示
METHOD_SUM_TYPE = 'sum'
METHOD_COUNT_TYPE = 'count'

# 图表纵坐标（柱状图或折线图）或统计量（饼图）计算方法对外展现的名称
METHOD_SUM_REPR = '加和'
METHOD_COUNT_REPR = '计数'

# 图表纵坐标（柱状图或折线图）或统计量（饼图）计算方法对外展现的名称和内部表示之间的映射关系
METHOD_REPR2TYPE = {
    METHOD_SUM_REPR: METHOD_SUM_TYPE,
    METHOD_COUNT_REPR: METHOD_COUNT_TYPE,
}

文件excel_processor.py

该文件包括操作Excel文件的基础模块及它所需要的辅助函数。

函数_setup_preferred_font()

设置合适的字体，使中文字符在图表中能正常显示。优先使用沙盒中存在的中文字体。

函数_setup_remedial_font()

设置合适的字体，使中文字符在图表中能正常显示。用于无法找到沙盒中存在的支持中文的字体的情况。

函数_setup_matplotlib()

设置字体（调用上面两个函数）。

类ExcelProcessor

用于操作单个Excel文件的基础模块，不存在与用户交互。

方法search(file_path, primary_key, secondary_key)

根据主键primary_key和secondary_key，搜索位于路径file_path的Excel文件，并将搜索结果返回。

方法append(file_path, values)

向位于路径file_path的Excel文件添加一行新的数据，数据的值由values指定。

方法delete(file_path, row_indexes)

从位于路径file_path的Excel文件中删除一些行，具体哪些行由行的索引row_indexes指定。

方法update(file_path, row_indexes, column_index, new_value)

修改位于路径file_path的Excel文件中的一些行，将这些行的指定列的取值更改为new_value。具体哪些行由行的索引row_indexes指定，具体哪一列由列的索引column_index指定。

方法read_all(file_path)

读取位于路径file_path的Excel文件的所有数据并返回。

方法read_headers(file_path)

读取位于路径file_path的Excel文件的表头并返回。

方法draw_chart(cls, file_path, chart_type, horizontal_axis, vertical_axis, method, title, output_path

绘制图表。

file_path：提供数据的Excel文件的路径

chart_type：图表类型：柱状图、饼图、折线图

horizontal_axis：Excel文件中用作横坐标的列名

vertical_axis：Excel文件中用来计算图表纵坐标值（柱状图或折线图）或统计值（饼图）的列的名字

method：计算纵坐标值（柱状图或折线图）或统计值（饼图）的方法：计数或加和

title：图表标题

output_path：图表保存的路径

方法post_draw_line_chart(df, axis)

折线图特殊处理，用于调整折线图的刻度显示，使其与柱状图在样式上风格一致。

df：数据源。

axis：图表对象。

文件file_keeper.py

该文件包含了类FileKeeper及其实例。

类FileKeeper

文件“管家”。管理工作目录下的Excel文件列表和全部文件的列表。每个文件都有自己的索引。可用该索引获取文件名和文件路径，并进行相关操作。这是一个基础功能模块，不存在与用户交互。

构造器_init__(self, dir_path)

构造该类的实例。

方法refresh(self)

更新文件列表。

属性all_files(self)

全部文件的列表。字典类型：键为索引，值为文件名。

属性excel_files(self)

全部Excel文件的列表。字典类型：键为索引，值为文件名。

方法get_file_path(self, index)

根据文件索引，获取文件的路径。

方法print_excel_files(self, indexes=None)

打印所有Excel文件。可选参数indexes是文件索引，可以用于选择要打印的文件。

方法print_all_files(self)

打印所有文件。

文件handler.py

函数_split(str_)

把用户输入的数据按分隔符分割。

函数_to_index_list(file_indexes)

把用户输入的文件索引转化成索引列表。

函数print_headers(file_path, prompt='')

打印位于file_path的Excel文件的表头。其中的prompt是打印在表头前的提示信息，默认为空。

函数print_match_detail(matches, primary_key, secondary_key)

打印以primary_key为主键、以secondary_key为次键的Excel查询结果的详细信息：查询命中的文件名和具体数据行。

函数print_match_summary(matches)

打印以primary_key为主键、以secondary_key为次键的Excel查询结果的概要信息：查询命中的文件名。

函数excel_search(primary_key, secondary_key='')

以主键primary_key和次键secondary_key对Excel文件进行搜索。所需要的其它信息会要求用户进行输入。其中的secondary_key为可选参数，默认为空字符串。

函数excel_files(path)

打印工作目录下的Excel文件名。参数path并无作用，只是为了满足spring.py的需要。

函数excel_add(file_indexes)

向索引file_indexes指定的Excel文件添加新的一行数据。所需要的其它信息会要求用户进行输入。

函数excel_delete(matches, file_indexes)

根据查询结果，对索引file_indexes指定的Excel文件进行删除操作。所需要的其它信息会要求用户进行输入。

函数excel_headers(file_indexes, prompt='表格的表头是: ')

打印file_indexes指定的Excel文件中第1个文件的表头。其中的prompt是打印在表头前的提示信息。

函数excel_update(matches, file_indexes, column)

根据查询结果matches，对文件索引file_indexes指定的Excel文件的列进行更新。具体是哪个列由参数column决定。所需要的其它信息会要求用户进行输入。

函数auto_picture()

绘制图表。所需要的信息会要求用户进行输入。

函数auto_email()

发送邮件。所需要的信息会要求用户进行输入。

文件spring.py

函数auto_add()

向工作目录下的部分或全部Excel文件添加新的一行数据，然后打印新增的行等信息。所需要的全部信息会要求用户进行输入。

函数auto_search()

对工作目录下的部分或全部Excel文件中的数据进行搜索，打印搜索结果。所需要的全部信息会要求用户进行输入。

函数auto_delete()

删除工作目录下的部分或全部Excel文件中符合特定条件的行，随后打印删除操作是否成功等结果信息。所需要的全部信息会要求用户进行输入。

函数auto_update()

对工作目录下的部分或全部Excel文件中符合特定条件的行，随后打印更新操作产生的效果等结果信息。所需要的全部信息会要求用户进行输入。

函数pro_controller()

入口函数。在终端上提供菜单，让用户选择欲进行的Excel操作，并调用相应函数（上面所列函数）。

文件Utils.py

包含工具类Utils。

类Utils

方法to_chart_type(type_repr)

把图表种类对外展现的名称转化为内部表示。转化失败时返回None。

方法to_method_type(type_repr)

把图表纵坐标（柱状图或折线图）或统计量（饼图）计算方法对外展现的名称转化为内部表示。转化失败时返回None。

方法get_all_methods(delimeter='/')

把程序所支持的、图表纵坐标（柱状图或折线图）或统计量（饼图）的所有计算方法（计数或加和）对外展现的名称用分隔符连接起来，得到字符串供调用者进行打印。分隔符的默认值为'/'。

方法send_mail(to_mail, from_mail, auth_code, body, file_paths=None)

以to_mail为目标邮箱、from_mail为发送人邮箱、auth_code为发送邮件所需要的授权码、body为邮件正文、file_paths为邮件附件，发送邮件。file_paths默认为None，表示邮件不带附件。

文件requirements.txt

存放程序依赖的第三方库的名称和版本。

通常只在安装依赖项时有用（见前面步骤），一般无需理会。

cycler==0.10.0
et-xmlfile==1.0.1
jdcal==1.4.1
kiwisolver==1.1.0
matplotlib==3.1.2
numpy==1.18.1
openpyxl==3.0.2
pandas==0.25.3
pyparsing==2.4.6
python-dateutil==2.8.1
pytz==2019.3
six==1.13.0

高级设置

如果不希望把Excel文件放在static文件夹中，可在终端中设置环境变量，将当前目录切换至spring.py文件所在文件夹。Linux/Mac下的具体命令是：

export FBD_DIR_PATH=Excel文件所在的路径

Windows下的具体命令是：

set FBD_DIR_PATH=Excel文件所在的路径

开发规范

安装

欲安装依赖项，可参考命令：

pip install -r requirements.txt  -i https://pypi.tuna.tsinghua.edu.cn/simple 

代码规范

flake8

检查代码规范符合程度：

flake8 .

如果使用了虚拟环境，可能需要使用：

flake8 . --exclude=env名称

autopep8

尝试自动修复规范错误：

autopep8 -i --exclude spring.py -r .

单元测试

建议优先使用coverage方式，并通过它报告的覆盖率是否在90%左右，来判断程序功能是否异常。这是因为，目前的单测重点落在跑通功能，而没有对运行结果做过多的检测。也就是说，即使过程当中有一些错误，单测可能也不会报告出来。这时，如果覆盖率比较大，则过程当中很可能就没有出错。当然，以后应该把对结构的检测补上。

准备

环境变量准备：

项目使用dotenv从.env配置文件中读取环境变量。这些环境变量目前主要由开发自已用来单元测试，并没有面向用户。

当前可配置的环境变量如下：

FROM_MAIL=源邮箱地址
AUTH_CODE=认证码
TO_MAILS=目标邮箱地址
CC_MAILS=抄送邮箱地址

如果想通过环境变量更改“excel所在文件夹”，可参考前面“高级设置”。也可以写在.env中。

unittest

执行整个测试文件中的测试

PYTHONPATH=. pytest

执行单个测试用例类

PYTHONPATH=. pytest flash_handler/tests/test_basic.py::TestSpring

执行单个测试用例类的方法

PYTHONPATH=. pytest flash_handler/tests/test_basic.py::TestSpring::test_auto_add

如果使用pipenv，可以在项目根目录执行如下命令：

pipenv run pytest

coverage

用coverage跑单元测试：

coverage run --source . -m pytest

生成代码覆盖率概要信息：

coverage report -m

生成代码覆盖率html文件：

coverage html

随后，可在htmlcov文件夹中打开index.html，观看覆盖率数据。

上传至pypi？

主要参考

• How to Publish an Open-Source Python Package to PyPI

主要步骤

• 准备
  • 安装twine pip install twine
  • 在TestPyPI上注册账号。这里可用公司个人邮箱。其实自个儿邮箱也没问题，因为这个网站本身就是供发包人进行测试用的。
  • 在PyPI上注册账号。这里可用公司个人邮箱。
• 修改setup.py
  • 作者、邮箱、版本、license等
• 打包 python setup.py sdist
• 测试打出的包
  • 检查包中文件：tar tzf XXX-X.X.X.tar.gz
  • 检查包的描述是否会在pypi上被正确地展示：twine check dist/*
  • 上传至TestPyPI进行测试
    • 上传命令：twine upload --repository-url https://test.pypi.org/legacy/ dist/*
    • 上传后，即可在TestPyPI上查看该包。
    • 在新的环境上测试包的安装和使用：
      • 可从TestPyPI上把包手动下载下来，方便用国内源。
      • 然后在终端中切换到包所在的文件夹，使用下面命令去安装: pip install 下载下来的包名 -i https://pypi.tuna.tsinghua.edu.cn/simple
      • 在终端或脚本中，用from flash_handler import handler来导入handler，对其进行测试。

注意

**千万别发⼀个不可⽤的包。**别的不说，pypi不允许名字重⽤。如果发了⼀个不可⽤包，下次发包时，版本号肯定得变（通常是变 ⼤）。