Skip to content

Latest commit

 

History

History
250 lines (195 loc) · 17.9 KB

Third_Party_Packages.md

File metadata and controls

250 lines (195 loc) · 17.9 KB
Raw

第三方包 (Third Party Packages)

软件生态系统 […] 建立一个社区，进一步加速知识、内容、问题、专业知识和技能的共享。—— Jan Bosch

关于第三方包 (About Third Party Packages)

第三方软件包允许开发人员共享扩展 Django REST framework 功能的代码，以支持其他用例。

我们支持、鼓励并强烈支持创建第三方包来封装新的行为，而不是直接向 Django REST framework 添加额外的功能。

我们的目标是尽可能简单地创建第三方软件包，同时保持简单且维护良好的核心 API。通过推广第三方软件包，我们确保软件包的责任仍由其作者承担。如果一个包被证明是受欢迎的，那么它总是可以被考虑包含到核心 REST framework 中。

如果您对新功能有所了解，请考虑如何将其打包为第三方包。我们总是很乐意在邮件列表上讨论想法。

如何创建第三方包 (How to create a Third Party Package)

创建您的包 (Creating your package)

您可以使用此 cookiecutter 模板快速创建可重用的 Django REST Framework 包。Cookiecutter 从项目模板创建项目。虽然是可选的，但是这个 cookiecutter 模板包括 Django REST framework 和其他包中的最佳实践，以及 Travis CI 配置、Tox 配置和合理的 setup.py，以便于 PyPI 注册/分发。

注意：如果您有备用 cookiecuter 包，请告诉我们，以便我们也可以链接到它。

运行初始 cookiecutter 命令 (Running the initial cookiecutter command)

要运行初始 cookiecutter 命令，首先需要安装 Python cookiecutter 包。

$ pip install cookiecutter

安装 cookiecutter 后，只需运行以下命令即可创建新项目。

$ cookiecutter gh:jpadilla/cookiecutter-django-rest-framework

系统会提示您一些问题，然后回答它们，然后它会根据这些值在当前工作目录中创建您的 Python 包。

full_name (default is "Your full name here")? Johnny Appleseed
email (default is "you@example.com")? jappleseed@example.com
github_username (default is "yourname")? jappleseed
pypi_project_name (default is "dj-package")? djangorestframework-custom-auth
repo_name (default is "dj-package")? django-rest-framework-custom-auth
app_name (default is "djpackage")? custom_auth
project_short_description (default is "Your project description goes here")?
year (default is "2014")?
version (default is "0.1.0")?

把它带到 Github 上 (Getting it onto GitHub)

要将项目放在 GitHub 上，您需要一个存储库才能使用它。您可以在此处创建新存储库。如果您需要帮助，请查看 GitHub 上的 Create A Repo 文章。

添加到 Travis CI (Adding to Travis CI)

我们建议使用 Travis CI，这是一种托管的持续集成服务，可以与 GitHub 完美集成，并且可以免费用于公共存储库。

要开始使用 Travis CI，请使用您的 GitHub 帐户登录。登录后，转到您的配置文件页面并为所需的存储库启用服务挂钩。

如果您使用 cookiecutter 模板，您的项目将包含一个 .travis.yml 文件，Travis CI 将使用该文件来构建项目并运行测试。默认情况下，每次推送到存储库或创建 Pull Request 时都会触发构建。

上传到 PyPI (Uploading to PyPI)

一旦您至少有了一个原型工作和测试运行，您就应该在 PyPI 上发布它，以允许其他人通过 pip 安装它。

在发布到 PyPI 之前，您必须注册一个帐户。

要在 PyPI 上注册您的包，请运行以下命令。

$ python setup.py register

如果这是第一次发布到 PyPI，系统将提示您登录。

注意：在发布之前，您需要确保您有最新的支持 wheel 的 pip，以及安装 wheel 包。

$ pip install --upgrade pip
$ pip install wheel

在此之后，每次要在 PyPI 上发布新版本时，只需运行以下命令即可。

$ python setup.py publish
You probably want to also tag the version now:
    git tag -a {0} -m 'version 0.1.0'
    git push --tags

在向 PyPI 发布新版本后，标记版本并将其作为 GitHub 发行版提供始终是一个好主意。

我们建议对您的包版本遵循语义版本控制。

发展 (Development)

版本要求 (Version requirements)

cookiecutter 模板假定将为 Python 和 Django 提供一组受支持的版本。确保您正确更新您的要求，文档，tox.ini，.travis.yml 和 setup.py 以匹配您希望支持的版本集。

测试 (Tests)

cookiecutter 模板包含 runtests.py，它使用 pytest 包作为测试运行器。

在运行之前，您需要安装几个测试要求 (依赖)。

$ pip install -r requirements.txt

安装依赖后，您可以运行 runtests.py。

$ ./runtests.py

使用更简洁的输出样式运行。

$ ./runtests.py --fast

不要运行 flake8 代码检查。

$ ./runtests.py --nolint

只运行 flake8 代码检查，不要运行测试。

$ ./runtests.py --lintonly

为给定的测试用例运行测试。

$ ./runtests.py MyTestCase

为给定的测试方法运行测试。

$ ./runtests.py MyTestCase.test_this_method

为给定的测试方法以较短形式运行测试。

$ ./runtests.py test_this_method

要针对不同版本的需求 (例如 Django) 对多个版本的 Python 运行测试，我们建议使用 tox。Tox 是一种通用的 virtualenv 管理和测试命令行工具。

首先，全局安装 tox。

$ pip install tox

要运行 tox，只需运行：

$ tox

要运行特定的 tox 环境：

$ tox -e envlist

envlist 是一个以逗号分隔的值，用于指定要对其运行测试的环境。要查看所有可能的测试环境的列表，请运行：

$ tox -l

版本兼容性 (Version compatibility)

有时，为了确保您的代码适用于各种不同版本的 Django、Python 或第三方库，您需要根据环境运行稍微不同的代码。以这种方式分支的任何代码都应该被隔离到 compat.py 模块中，并且应该提供代码库其余部分可以使用的单个公共接口。

查看 Django REST framework 的 compat.py 作为示例。

一旦您的包可用 (Once your package is available)

一旦您的包在 PyPI 上被正确记录并可用，您可能希望与发现它有用的其他人共享它。

添加到 Django REST framework 网格 (Adding to the Django REST framework grid)

我们建议将您的包添加到 Django Packages 上的 REST Framework 网格中。

添加到 Django REST framework 文档 (Adding to the Django REST framework docs)

在 GitHub 上创建一个 Pull Request 或 Issue，我们将从主 REST framework 文档中添加一个链接。您可以在最适用的 API 指南部分的第三方软件包下添加您的软件包，例如身份验证或权限。您还可以在第三方包小节下链接您的包。

在讨论组上宣布 (Announce on the discussion group.)

您还可以通过讨论组让其他人了解您的包。

现有第三方包 (Existing Third Party Packages)

Django REST Framework 拥有越来越多的开发人员，软件包和资源社区。

查看详细介绍 Django Packages 中 Django REST Framework 周围所有包和生态系统的网格。

要提交新内容，请打开问题或创建拉取请求。

认证 (Authentication)

权限 (Permissions)

序列化器 (Serializers)

序列化器字段 (Serializer fields)

视图 (Views)

  • djangorestframework-bulk - 实现通用视图混合以及一些常见的具体通用视图，以允许通过 API 请求应用批量操作。
  • django-rest-multiple-models - 提供通用视图 (和 mixin)，用于通过单个 API 请求发送多个序列化模型和/或查询集。

路由器 (Routers)

  • drf-nested-routers - 提供用于处理嵌套资源的路由器和关系字段。
  • wq.db.rest - 提供具有合理默认 URL 和视图集的管理员样式模型注册 API。

解析器 (Parsers)

渲染器 (Renderers)

过滤 (Filtering)

  • djangorestframework-chain - 允许任意链接的关系和查找过滤器。
  • django-url-filter - 允许以安全的方式通过人性化的 URL 过滤数据。它是一个不依赖于 DRF 的通用库，但它提供了与 DRF 的简单集成。
  • drf-url-filter 是一个简单的 Django 应用程序，它以简洁、可配置的方式在 drf ModelViewSet 的 Queryset 上应用过滤器。它还支持对传入查询参数及其值的验证。

杂项 (Misc)