前言

因为计算方法实验的缘故,需要用python写一些简单的算法,并进行实验、记录实验数据。其中一个实验需要记录一些多项式,而友好得显示公式的一个好办法就是产生Markdown文件。

然而python自带的Markdown库貌似更侧重于解析,不适合这种轻量化的写入性操作,因此决定自己造一个快速生成Markdown文件的库,也就是pyLabOn

python模块的开发

理论上,一个文件就是一个python模块。但是更复杂的Python Package是由一个包含__init__.py的文件夹构成的。

我们在pyCharm中新建一个Python Package, 就是这种形式的。

然后我们添加功能性的源文件,对于pyLabOn而言,就是 LabReport.py

模块和文件信息

文件信息由头部的多行注释完成:

1
2
3
4
5
6
7
8
@File    :   LabReport.py
@Contact : [email protected]
@License : (C)Copyright 2020 Plastic-Metal

@Modify Time @Author @Version @Description
------------ ------- -------- -----------
2020-5-15 Ferdinand Sukhoi 0.1.4 Light-weight tool to generate markdown-formatted lab reports.
"""

模块的信息由以下语句说明:

1
2
3
__all__ = ['Report', 'ReportParagraph', 'ReportPlainContent', 'ReportTable']
__version__ = '0.1.4'
__author__ = 'Ferdinand Sukhoi'

__all__说明模块对外公开的内容,version和author说明版本和作者。

文档注释

像C# xmldoc, javadoc等一样,python也有文档注释。
对于类(以Report为例):

1
2
3
4
5
6
class Report(ReportParagraph):
"""A markdown report file
Attributes:
MarkdownFilePath: full-path of the markdown file
PDFPath: full-path of the PDF file
"""

对于函数,是:

1
2
3
4
5
6
7
8
9
10
11
12
def add_table(self, headers, data, align=0):
"""
Create and add a table to this paragraph
:param headers: Headers of the table
:type headers: list[str]
:param data: Data of the table
:type data list[list[str]]
:param align: Optional. Align of the table, default 0-Central
:type align: list or int
:return: The table added
:type ReportTable
"""

这样,对于一个模块的源文件而言,元素是完全的了。

__init__.py的内容

这个是模块本身对应的文件。

对于pyLabOn而言,它应该包括:

1
2
3
4
5
from .LabReport import *

__all__ = ['Report', 'ReportParagraph', 'ReportPlainContent', 'ReportTable']
__version__ = '0.1.4'
__author__ = 'Ferdinand Sukhoi'

python的打包和发布

打包

在包根目录下新建 setup.py , 其中包含以下内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

from setuptools import setup, find_packages

setup(
name = "pylabon",
version = "0.1.4.3",
keywords = ["markdown", "Plastic-Metal"],
description = "To generate markdown-formatted lab reports.",
long_description = "Light-weight tool to generate markdown-formatted lab reports. For python.",
license = "MIT",

url = "https://github.com/Plastic-Metal/pyLabOn",
author = "Ferdinand Sukhoi",
author_email = "[email protected]",

packages = find_packages(),
include_package_data = True,
platforms = "any",
install_requires = ["pypandoc"]
)

其中字段和对应说明如下:

字段 说明
name 包的名称,必须小写
version 版本号
keywords 关键词
description 说明
long_description 长说明
license 许可协议,比如MIT
url 项目地址,写github就行
author 作者
author_email 作者邮箱
packages 包含的包,直接=find_packages()自动生成就行
include_package_data 是否包含包信息
platforms 适用平台,一般写any即可
install_requires 安装的依赖项,list

本地安装

本地安装只需

script
1
python setup.py install

即可。

打包和发布到PyPI

本部分将利用Github Actions自动化完成。

注册PyPI账号

PyPI官网注册账户,记住用户名和密码。

向Github仓库添加secrets

在仓库的Settings->Secrets里增加:

PYPI_USERNAME:你的PyPI用户名
PYPI_PASSWORD:你的PyPI密码

添加CI

向仓库添加如下CI:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# This workflow will upload a Python Package using Twine when a release is created
# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries

name: deploy

on:
push:
branches:
- master # Default release branch

jobs:
deploy:

runs-on: ubuntu-latest

steps:
- uses: actions/[email protected]
- name: Set up Python
uses: actions/[email protected]
with:
python-version: '3.x'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install setuptools wheel twine
- name: Build and publish
env:
TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
run: |
python ./pyLabOn/setup.py sdist bdist_wheel
twine upload dist/*

注意倒数第二行 setup.py 的位置是相对于仓库根目录的。

完成发布

提交、推送到github,你的软件包会自动发布到PyPI。PyPI的更新和审核(真的有审核吗…)很快。

通过PyPI安装发布的软件包

运行

script
1
pip instal <PackageName>

即可。

总结

以上就是Python模块的开发、打包以及发布,与Nuget体验基本上差不多了,都很方便、友好、快速。

不知道比某些J开头的语言高到哪里去了。