Privex的Python辅助工具

这个小巧的Python 3模块由各种小型函数和类组成，这些函数和类经常在我们的项目之间复制粘贴。

这些“辅助”函数、装饰器或类本身太小，无法独立打包，所以我们把它们合并到了这个PyPi包中，即 privex-helpers。

    +===================================================+
    |                 © 2019 Privex Inc.                |
    |               https://www.privex.io               |
    +===================================================+
    |                                                   |
    |        Originally Developed by Privex Inc.        |
    |                                                   |
    |        Core Developer(s):                         |
    |                                                   |
    |          (+)  Chris (@someguy123) [Privex]        |
    |          (+)  Kale (@kryogenic) [Privex]          |
    |                                                   |
    +===================================================+

长话短说；安装和使用Privex辅助工具

从PyPi安装（详细安装信息见 安装 和 使用包额外功能）

pipenv install privex-helpers    # If you use pipenv (and you should!)
pip3 install privex-helpers      # Otherwise, standard pip installation

# If you're using privex-helpers in a project, then you may want to install with the "full" extras
# which installs all optional requirements (other than Django/tests), so you can use **everything** in privex-helpers
pipenv install 'privex-helpers[full]'    # If you use pipenv (and you should!)
pip3 install 'privex-helpers[full]'      # Otherwise, standard pip installation

非常重要和基本用法（详细示例见 示例用法）

from privex.helpers import is_true, empty
if is_true('yes'):
    print('yes is truthful')

if empty(''):
    print("'' is empty")

目录（Github README）

注意：以下目录是为Github设计的。链接在PyPi的描述中不起作用，如果您在其他地方阅读此README.md，则可能不起作用。

1. 为什么使用Privex辅助工具？

   1.1. 轻量级

   1.2. 保持您的代码DRY（不要重复！）

   1.3. 让您的日子过得更加简单

   1.4. 彻底的单元测试

   1.5. 包含内容的概述

2. 安装

   2.1 通过PyPi（pip）安装

   2.2 通过Git手动安装

3. 文档

4. 许可证

5. 示例用法

6. 最小依赖项/使用包额外功能

   6.1 具有依赖项的模块

   6.2 使用 Setuptools 扩展功能

   6.3 使用克隆库安装扩展功能

7. 单元测试

8. 贡献

为什么使用Privex辅助工具？

Privex 辅助工具的创建目标非常简单：让开发 Python 应用程序变得容易、有趣、简单、无痛苦。

轻量级

无论您是在库中使用它，还是在项目中使用它，您都会很高兴地知道，privex-helpers及其所有必需依赖项的总大小不到200kb。相比之下，仅Django包（不包括其依赖项）就高达26兆字节。

privex-helpers的大部分功能可以在没有其他依赖项的情况下使用。某些模块或模块的部分可能需要某些依赖项，但如果必要的依赖项不可用，则会干净地禁用自己。

请参阅具有依赖项的模块，以查看哪些模块仅在安装了特定软件包时才可用，以及哪些模块在没有依赖项的情况下启用但安装额外软件包时可以启用额外功能。

保持您的代码DRY（不要重复自己！）

厌倦了编写那些相同的冗长if语句来检查用户输入的值是否是某种布尔值？请使用is_true和is_false - 将那些冗长的if语句缩减为一个函数调用。更少地输入，更易阅读。

使您的生活变得简单

编写库并需要缓存？不确定是应该强制用户使用Redis，还是应该将其作为Django插件，或者自己编写某种原始的缓存系统？privex-helpers包括一个模块化缓存抽象层，即开即用，不会强制在用户身上加载数吨依赖项。

也许您只是需要加密一个字符串，或者生成一个RSA密钥对。但是您试图查看流行的cryptography包文档，看起来您可能需要花几个小时编写脚手架代码才能完成这项工作... 说出privex.helpers.crypto - 无论您是处理对称加密还是非对称加密，它都只需要一行导入，几行代码，您就完成了。

详尽的单元测试

在tests/文件夹中包含了一个超过70个单独的单元测试集合，并且随着时间的推移不断添加更多单元测试。

此项目使用Travis进行持续集成（每次提交时自动测试），并使用CodeCov跟踪代码库中有多少部分被单元测试覆盖。有关详细信息，请参阅单元测试。

这确保了privex-helpers的可靠性和健壮性 - 如果库的某个部分在新的更新中损坏，那么我们将在发布更新后不久收到测试失败的警报，以便我们能够立即修复问题。

包括内容的概述

这不是一个详尽的列表，有时可能有些过时。要查看privex-helpers中所有可用的内容，请查看文档。

• common - 一个函数和类的熔炉，通常会让开发Python代码变得100倍容易，并使其10倍易于阅读。其中一些最有用的包括

  • empty - 检查值是否为“空”，例如 None，''，0，'0'，[] 等。
  • is_true - 模糊的“true”测试，检查常见的true形式，例如 True，"true"，"yes"，1。
  • is_false - 模糊的“false”测试，检查常见的false形式，例如 False，"false"，"no"，0。
  • env_csv - 加载环境变量，类似于CSV，允许在环境变量中表达列表形式。
  • env_keyval - 以键值对的形式加载环境变量，允许环境变量中存在元组对/字典表示
  • dec_round - 使用内置的Quantize方法对Python Decimal进行四舍五入，无需麻烦。
  • Dictable - 可以轻松地将Python 3.7 dataclass从字典创建出来，并且可以通过dict(mydataclass)将它们转换为普通字典
  • 还有更多，请查看文档！

• cache - 无依赖项、框架无关的缓存层，支持

  • 自动超时
  • 可以扩展缓存项的超时时间（即使在某些缓存适配器上缓存项已经“过期”）
  • 支持带回调函数/方法的get_or_set
  • 可选使用Redis（需要可选依赖项）

• crypto - 类，使对称加密和非对称加密都非常容易使用

  • EncryptHelper - 用于具有共享密钥的对称AES-128加密/解密，可以生成安全的随机共享密钥，也可以从密码+盐生成共享密钥
  • KeyManager - 用于非对称签名/验证，以及如果使用RSA则进行加密/解密。支持生成/加载RSA、ECDSA和Ed25519密钥，以及以各种格式和编码输出它们。

• setuppy - 一个模块，包含各种帮助创建Python包或处理requirements.txt文件的函数

  • common.extras_require - 一个辅助函数，允许您通过传递一个额外的名称列表来在setup.py中简单生成extras_require设置，例如extras_require=extras_require(['cache', 'net']),
  • bump.bump_version - 升级包的semver版本号的一部分，并更新包含版本号的文件
  • commands.BumpCommand - 一个setup.py命令类，允许您在包中使用bump.bump_version，只需键入一个命令，例如./setup.py bump --minor（升级您的包的0.x.0小版本，并更新包含版本的文件）
  • commands.ExtrasCommand - 提供管理包中的extras_require的各种功能，包括轻松生成/保存额外的requirements.txt文件，安装需求，以及输出额外的列表。

• decorators - 不同的装饰器，可以简化代码

  • retry_on_err - 在抛出异常时自动重新运行函数/方法，具有各种可定制的选项
  • r_cache - 自动缓存函数/属性，支持基于参数或lambda的缓存

• net - 各种网络函数，包括

  • 处理IP地址
  • 生成反向DNS记录
  • 根据其数字查找ASN名称
  • 检查IP是否在线（通过ping）- 支持IPv4和IPv6

• asyncx - 各种异步辅助函数，帮助同步代码与异步代码和谐共存

• django - 各种Django辅助函数，其中大部分您可能会质疑“为什么这个不是内置在Django中的？”

• exceptions - 各种异常类，其中大多数由privex-helpers函数/类使用，但也可以在任何Python项目中使用，以节省重新发明异常名称

安装

从PyPi下载和安装

使用Pipenv（推荐）

pipenv install privex-helpers

使用标准Python pip

pip3 install privex-helpers

（替代）从Git手动安装

选项1 - 使用pip直接从Github安装

pip3 install git+https://github.com/Privex/python-helpers

选项2 - 克隆并手动安装

# Clone the repository from Github
git clone https://github.com/Privex/python-helpers
cd python-helpers

# RECOMMENDED MANUAL INSTALL METHOD
# Use pip to install the source code
pip3 install .

# ALTERNATIVE MANUAL INSTALL METHOD
# If you don't have pip, or have issues with installing using it, then you can use setuptools instead.
python3 setup.py install

文档

本项目的完整文档如下（点击Read The Docs图片），包括

• 如何安装应用程序及其依赖项
• 如何使用各种函数和类
• 模块和类的通用文档，供贡献者参考

构建文档

git clone https://github.com/Privex/python-helpers
cd python-helpers/docs
pip3 install -r requirements.txt

# It's recommended to run make clean to ensure old HTML files are removed
# `make html` generates the .html and static files in docs/build for production
make clean && make html

# After the files are built, you can live develop the docs using `make live`
# then browse to http://127.0.0.1:8100/
# If you have issues with content not showing up correctly, try make clean && make html
# then run make live again.
make live

许可证

此Python模块由伯利兹城Privex Inc.创建，并许可在X11/MIT许可证下。请参阅文件LICENSE以获取许可文本。

TL;DR; 许可证

我们不提供任何保证。您可以复制它、修改它、在不同许可的项目中使用它，甚至在使用商业（付费）软件中。

最重要的规则是 - 您必须在任何副本中保留原始许可证文本可见（参见LICENSE）。

示例用途

我们在privex/helpers/__init__.py中导出所有子模块的内容，因此您可以直接从privex.helper导入任何函数/类/属性，而无需多个导入行。

以下是一些最有用的示例（部分来自我们的.common模块，无依赖项）

from privex.helpers import empty, is_true, random_str, ip_is_v4, ip_is_v6

####
# Our empty() helper is very convenient and easy to remember. It allows you to quick check if a variable is "empty" 
# (a blank string, None, zero, or an empty list/dict/tuple).
#
#   empty(v, zero: bool = False, itr: bool = False) -> bool
#
# For safety, it only returns True for empty iterables / integer zero (0) if you enable `zero` and/or `itr` respectively.
####

x = ''
if empty(x):
    print('Var x is empty: either None or empty string')

y = []
if empty(y, itr=True):
    print('Var y is empty: either None, empty string, or empty iterable')

####
# Our is_true() / is_false() helpers are designed to ease checking boolean values from plain text config files
# such as .env files, or values passed in an API call
####

# The strings 'true' / 'y' / 'yes' / '1' are all considered truthy, plus int 1 / bool True
enable_x = 'YES'    # String values are automatically cast to lowercase, so even 'YeS' and 'TrUe' are fine.
if is_true(enable_x):
    print('Enabling feature X')

####
# Need to generate a random alphanumeric string for a password / API key? Try random_str(), which uses SystemRandom()
# for cryptographically secure randomness, and by default uses our SAFE_CHARS character set, removing look-alike 
# characters such as 1 and l, or o and 0
####

# Default random string - 50 character alphanum without easily mistaken chars
random_str()   # outputs: 'MrCWLYMYtT9A7bHc5ZNE4hn7PxHPmsWaT9GpfCkmZASK7ApN8r'

# Customised random string - 12 characters using only the characters `abcdef12345` 
random_str(12, chars='abcdef12345') # outputs: 'aba4cc14a43d'

####
# As a server hosting provider, we deal with IP addresses a lot :)
# The helper functions ip_is_v4 and ip_is_v6 do exactly as their name says, they return a boolean
# if an IP is IPv4 or IPv6 respectively.
####

ip_is_v4('192.168.1.1') # True
ip_is_v4('2a07:e00::1') # False

ip_is_v6('192.168.1.1') # False
ip_is_v6('2a07:e00::1') # True

最小依赖项

我们的大部分辅助代码是独立的，不会导致安装任何额外的依赖项。

我们的一些辅助代码依赖于外部库或框架，例如Django或Flask。为了避免无谓地安装大型Python包，如Django，我们根据您是否已安装所需的依赖项来编程地启用/禁用一些辅助代码。

此包只需要（并在需要时自动安装）单个依赖项 - 我们的privex-loghelper包，它本身轻量级且无依赖项。

使用Setuptools额外功能

自版本2.0.0起 - Privex Helper现在支持Setuptools额外功能，允许您在requirements.txt中指定与privex-helpers相关的额外依赖项，或在运行pip3 install时。

每个额外功能是什么？

为在项目/包中使用privex-helpers包而设计的额外功能

• full - 一个元额外功能，包括大多数其他需要完整库功能的其他额外功能。
  • 它不包括django额外功能，因为Django包及其子依赖项会导致安装约30-50MB的包，而可能使用django模块的人可能已经安装了Django...
  • 它不包括docs或tests额外功能，因为这两个功能仅用于构建文档或运行单元测试。
• crypto - 安装使用crypto模块所需的依赖项
• cache - 安装可选依赖项以启用cache中的所有缓存后端
• django - 安装与django模块相关的依赖项（包括Django本身）
• net - 安装可选依赖项以启用net模块的完整功能
• setuppy - 安装可选依赖项以启用setuppy模块的完整功能

为开发、测试、编写文档或构建privex-helpers而设计的额外功能

• dev - 包括与privex-helpers相关的开发和相关活动所需的一切。通常包括所有额外功能，与full不同，它包括django、docs和tests
• docs - 此额外功能不是privex-helpers模块所必需的。它包含构建文档的要求。
• tests - 不是privex-helpers模块使用的必需功能。它包含运行单元测试的要求。

使用pip install使用额外功能

# Example: Install privex-helpers AND all optional dependencies (excluding django), for full functionality
pip3 install 'privex-helpers[full]'

# Example: Install privex-helpers with only the crypto and cache module dependencies
pip3 install 'privex-helpers[cache,crypto]'

# Example: Install just privex-helpers and REQUIRED dependencies (i.e. critical to basic functionality)
pip3 install privex-helpers

或者，只需使用pip3 install根据所需的辅助程序安装额外包

# For all Django-specific helpers in privex.helpers.django
Django
# For certain DNS dependant helpers in privex.helpers.net
dnspython>=1.16.0
# For using Redis with the privex.helpers.cache module
redis>=3.3.8
# For using the privex.helpers.crypto module
cryptography>=2.8

在克隆存储库时安装额外功能

首先，建议安装extras/setuppy.txt中的要求，以确保setup.py功能完全。

pip3 install -r extras/setuppy.txt

从privex-helpers 2.1.0版本开始，您可以使用方便的setup.py extras命令轻松安装单个额外需求或所有额外需求

# Install ALL extras requirements (including Django and unit testing related)
./setup.py extras -i

# Install an individual extras requirements, for example 'cache' or 'net'
./setup.py extras -i -e cache

如果您只想从源代码安装privex-helpers包，则可以使用pip安装当前文件夹，并指定您想要的额外功能

# Standard "full" install, excluding Django and development packages for docs/testing
pip3 install '.[full]'
# Full development installation, includes everything in 'full', with the addition of the django, docs, and tests extras
pip3 install '.[dev]'

有依赖关系的模块

如果您在正常项目（非包）中使用 privex-helpers，建议直接安装包含所有主要依赖的 privex-helpers[full]。

如果您在包中使用它，则应仅包含对包功能至关重要的额外模块。非必要的内容应放在 setup.py 的 extras_require 中，以避免在用户端安装不必要的包。

需要依赖才能使用的模块

• crypto - 此模块在没有 cryptography 库（或 privex-helpers[crypto]）的情况下无法工作。
• django - 显然，与 Django 相关的帮助程序在没有安装 Django 的情况下无法工作。但由于它们旨在在 Django 项目中使用，如果您需要它们，您已经安装了 Django。

动态模块，仅当您安装了某些包时才启用额外功能

• setuppy - 通常，common 子模块无需任何依赖项即可工作，但为了能够使用此模块的所有功能，例如 bump 和 commands 子模块，您需要安装带有 setuppy 额外的 privex-helpers[setuppy]。
• net - 一些功能依赖于 dnspython（或 privex-helpers[net]），但该模块的大部分内容无需依赖。
• cache - 缓存层无需任何依赖项即可正常工作。如果您在项目中使用 privex-helper，则可能希望安装 redis（或 privex-helpers[cache]），以使 Redis 缓存适配器可用。
• plugin - 虽然此模块在其他项目/包中使用不常见，但它确实公开了一些 Redis 单例管理功能（以及撰写本文时可能的其他功能）。如果您计划使用此模块，我们建议使用 privex-helpers[full] 以获得最佳体验。

单元测试

截至 2019 年 10 月底，我们在 tests/ 文件夹中已有超过 70 个单元测试，这些测试分为几个 test_xxxx 文件，每个文件包含特定模块或较小代码区域的测试。此库始终保持平均 70-80% 的测试覆盖率，有助于证明此包经过高度测试以确保可靠和健壮的代码。

我们使用 Travis CI 进行持续集成，每次将新提交、标签或分支推送到此 GitHub 仓库时都会运行测试套件。

我们还使用 CodeCov，它集成到我们的 Travis CI 设置中，并提供测试覆盖率统计信息，使我们和贡献者可以直观地看到代码中有多少部分被单元测试所覆盖。

TL;Dr; 运行测试

pip3 install -r docs/requirements.txt
pytest -v

有关使用单元测试的更多信息，请参阅文档中的 如何使用单元测试 部分。

贡献

我们很高兴接受任何大小的拉取请求。

请确保您所做的任何更改都符合以下基本要求

• 没有额外的依赖项。我们希望我们的帮助程序包轻量且易于安装。
• 从其他项目获取的任何代码应兼容 MIT 许可证。
• 这是一个新项目，因此支持 3.4 版本之前的 Python 的优先级非常低。
• 然而，我们愿意接受改进与旧版 Python 兼容性的 PR，只要它不会
  • 大大增加代码的复杂性
  • 或对使用较新版本 Python 的人造成问题。

贡献的法律免责声明

没有人愿意阅读一个充满法律文本的长文档，所以我们在这里总结了重要的部分。

如果您向Privex创建/拥有的项目中贡献您创建/拥有的内容，例如代码或文档，那么您可能自动授予我们无限使用您内容的使用权，无论我们的项目适用的开源许可协议如何。

如果您不想授予我们无限使用您内容的使用权，请确保将您的内容放在单独的文件中，确保在文件开头（例如代码注释）或其包含文件夹内（例如名为LICENSE的文件）清楚地显示您内容的使用许可。

您应在您的pull request或issue中告知我们，您已包括受单独许可的文件，以便我们可以确保不存在可能导致我们无法接受您的贡献的许可冲突。

如果您想阅读整个法律文本，它应包含在privex_contribution_agreement.txt中。

感谢阅读！

如果这个项目帮助了您，请考虑从Privex购买VPS或专用服务器。

价格从低至每月8美元起（我们接受加密货币！）