介绍#

对于 Masonite，创建包非常简单。您可以在不到 5 分钟的时间内创建一个包并将其发布到 PyPi 上。使用 Masonite 包，您将搭建和集中一些功能，以便轻松地重用您的所有 Masonite 项目。 Masonite 附带了几个帮助函数，以创建可以添加配置文件、路由、控制器、视图、命令、迁移等的包。

作为开发人员，您将负责制作包和使用包。在本文档中，我们将讨论两者。我们将从讨论如何制作包开始，然后讨论如何使用该包或其他第三方包。

您可以在以下位置浏览 Masonite 包 (官方和社区)：packages.masoniteproject.com(alpha 版)。

Masonite 作为一个 Python 框架，您显然可以使用并非为特定框架设计的所有 Python 包。例如，您显然可以使用像 requests 这样的库，但不能使用特定的 Django Rest Framework。

查找包#

包提供者是您的包和 Masonite 之间的连接。服务提供者负责将事物绑定到 Masonite 容器中，并指定从何处加载包资源，例如视图、配置、路由和资源。

您的 Masonite 项目将通过 providers.py 配置文件中定义的 PROVIDERS 列表发现包。当一个包提供者被添加到这个列表中时，会被允许在你的项目中注册额外的绑定、命令、视图、路由、迁移和资源。

请记住，一些简单的包不需要在您的项目中注册资源。

创建一个包#

包脚手架#

我们提供了两种方法来快速搭建你的包布局：

• GitHub 仓库 starter-package 模板
• cookiecutter template

starter-package#

starter-package 只是一个 GitHub 模板，因此你只需单击 Use this template 即可创建你自己的 GitHub 存储库，并使用默认的包布局和然后克隆你的存储库以开始本地开发。

cookiecutter template#

cookiecutter 模板 正在使用 cookiecutter 包为你的包提供配置选项（名称、作者、url...）。优点是你不需要在生成后编辑所有出现的包名称。

在你的计算机上全局（或本地）安装 cookiecutter：

$ pip install cookiecutterCopy

然后你只需要运行（在你想要创建包存储库的目录中）：

$ cookiecutter https://github.com/girardinsamuel/cookiecutter-masonite-package.gitCopy

你现在可以开始开发你的包了！

开发过程#

创建和激活你的虚拟环境#

有很多方法可以在 Python 中创建虚拟环境，但这里有一个简单的方法：

$ python3 -m venv venvCopy

在 Mac 和 Linux 上激活虚拟环境很简单：

$ source venv/bin/activateCopy

或者如果你在 Windows 上：

$ ./venv/Scripts/activateCopy

初始化你的环境#

默认的包布局包含一个有助于快速入门的 Makefile。你只需要运行：

$ make initCopy

这将安装 Masonite、flake8 和 pytest 等开发工具，它还将在本地安装你的包，以便你可以直接在测试项目中开始使用和测试它。

运行测试#

现在你可以运行测试以确保一切正常：

$ python -m pytestCopy

默认包布局带有一项基本测试。你应该看到这个测试通过了。然后，你可以开始构建你的包并添加更多单元测试。

运行测试项目#

默认包布局带有一个位于 tests/integrations 中的测试项目。这个项目对于直接测试你的包行为非常有用。它作为默认 Masonite 项目搭建，并且你的包已安装（请参阅 安装包 部分）。你可以使用通常的命令运行项目：

$ python craft serveCopy

然后你可以访问 http://localhost:8000 以查看欢迎页面。

提示：当你在本地安装包并在项目中注册时对包进行更改时，你的更改将直接在项目中可用。你只需要刷新页面即可查看更改。

迁移测试项目#

如果你的包有迁移并且你想迁移你的测试项目，你应该首先注册你的迁移，发布它们，然后运行通常的 migrate 命令：

$ masonite-orm migrate -d tests/integrations/databases/migrationsCopy

发布包#

一旦你对你的包感到满意，就可以在 PyPi 上发布它，以便每个人都可以安装它。我们使用 make 命令让这件事变得非常容易。

Registering on PyPi#

如果你之前从未在 PyPi 上上传过包，则需要 注册。确认你的邮件地址。

创建发布令牌#

在将包上传到 PyPI 时，API 令牌提供了一种替代方式（而不是用户名和密码）进行身份验证。强烈建议尽可能使用 API 令牌。

转到你的 PyPi 帐户并找到 API tokens 部分。单击 Add API token，给出一个重要的名称，例如 “发布令牌” 并创建令牌。在某处写下令牌密钥以备后用。

在你的计算机上配置 PyPi#

如果你之前从未在 PyPi 上上传过包，则需要在计算机上配置 PyPi。为此，你需要在主目录中添加一个 .pypirc 文件。如果你没有，那么你可以使用以下方法轻松创建一个：

$ make pypircCopy

这会将文件移动到你的主目录。如果你使用的是 Windows，你可能需要手动移动此文件。

然后使用你稍后创建的以 pypi- 为前缀的令牌填写 password 键。使用以 AgEIcHlwaS5vcmcCJGNjYjA4M... 开头的标记，.pypirc 文件如下所示：

[distutils]
index-servers =
  pypi
  pypitest

[pypi]
username=__token__
password=pypi-AgEIcHlwaS5vcmcCJGNjYjA4M...Copy

将包发布到 PyPI#

现在你已准备好将你的包上传到 PyPI。确保 setup.py 文件的所有参数都是最新的。这是描述你的包裹的文件。填写你要发布的正确版本号。准备好后，你可以运行：

$ make publishCopy

如果你还没安装，这将安装 twine，构建包，将其上传到 PyPi 并删除构建工件。然后，你应该会看到一条成功消息，并能够在 PyPi 上浏览你的包。

注意：你应该经常检查包名在 PyPi 上是否可用，并且要发布的版本号之前没有发布过。否则你将无法发布你的包。

让包在 masonite 包列表中可用#

要使你的包在 packages.masoniteproject.com（alpha 版本）上可用，你需要在 setup.py 中添加 Framework :: Masonite 分类器：

# setup.py
    classifiers=[
        #...
        "Framework :: Masonite",
    ]Copy

你可以在 网站常见问题解答 上找到更多信息。

注册资源#

在开发包时，你可能需要使用配置文件来添加迁移、路由和控制器或视图。所有这些资源都可以位于你的包中，但有时用户可能想要覆盖它，并且需要在其项目中本地发布这些资源。

以下部分将说明如何在包中注册这些资源以在 Masonite 项目中使用，以及如何使这些资源可发布。

Masonite 通过创建一个特定的包提供程序来注册你的包资源，从而使执行此操作变得非常容易。默认包布局带有这样的提供程序，它继承自 PackageProvider 类：

# providers/SuperAwesomeProvider.py
from masonite.packages import PackageProvider

class SuperAwesomeProvider(PackageProvider):

    def configure(self):
        (
            self.root("super_awesome_package")
            .name("super_awesome")
        )

    def boot(self):
        passCopy

configure() 方法在通常的 register() 方法中调用，用于注册包中使用的所有资源。

root(import_path) 方法应该首先被调用，用于指定你的包的导入路径。如果你的包需要这样使用：

from super_awesome_package.providers import SuperAwesomeProviderCopy

那么 super_awesome_package 就是你的包的导入路径。如果你的包是这样导入的：

from masonite.inertia.providers import InertiaProviderCopy

然后 masonite.inertia 是你的包的导入路径。

name(string) 方法应该在第二个被调用并用于指定你的包的名称（不是 PyPi 包名也不是 Python 模块名），而是用于在发布命令中引用你的包的名称或在资源路径中（它应该是没有特殊字符和空格的名称，即 Python 有效名称）。这也将是你的包配置文件的名称。

配置#

你的包很可能有一个配置文件。你将希望通过方便的 config() Masonite 助手使你的包配置可用。为此，你需要在 configure() 方法中调用 config(path, publish=False)：

def configure(self):
    (
        self.root("super_awesome_package")
        .name("super_awesome")
        .config("config/super_awesome.py")
    )Copy

这会将位于 super_awesome_package/config/super_awesome.py 的包配置文件加载到 Masonite 配置中。然后配置将可通过 config("super_awesome.key") 获得。

如果你想允许用户将配置文件发布到他们自己的项目中，你应该添加 publish=True 参数。

def configure(self):
    (
        self.root("super_awesome_package")
        .name("super_awesome")
        .config("config/super_awesome.py", publish=True)
    )Copy

package publish 命令会将配置发布到定义的项目配置文件夹中。使用默认项目设置，它将位于 config/super_awesome.py 中。

提示：位于包和本地项目中的配置值将被合并。项目中本地定义的值优先于包的默认值。

迁移#

如果你的扩展包包含迁移内容，你可以注册要在项目中发布的迁移文件：

def configure(self):
    (
        self.root("super_awesome_package")
        .name("super_awesome")
        .migrations("migrations/create_some_table.py", "migrations/create_other_table.py")
    )Copy

package publish 命令会将迁移文件发布到定义的项目迁移文件夹中。使用默认项目设置，它将位于 databases/migrations/ 中。迁移文件发布时带有时间戳，因此这里会生成这两个文件：{timestamp}_create_some_table.py 和 {timestamp}_create_other_table.py。

路由 / 控制器#

如果你的包包含路由，你可以通过提供路由文件和从中加载控制器（由你的路由使用）的位置来注册它们。为此，你需要调用 controllers(*locations)，然后在 configure() 方法中调用 routes(*routes)。

如果你的路由在 super_awesome_package/routes/api.py 和 super_awesome_package/routes/web.py 中定义，并且控制器文件在 super_awesome_package/controllers 中可用，你可以执行以下操作：

def configure(self):
    (
        self.root("super_awesome_package")
        .name("super_awesome")
        .controllers("controllers") # before routes !
        .routes("routes/api.py", "routes/web.py")
    )Copy

现在 Masonite 应该能够从你的包中解析新路由。

视图#

如果你的包包含视图，你可以通过提供包含视图的文件夹来注册它们。为此，你需要在 configure() 方法中调用 views(*folders, publish=False)。视图将在你的包名称之后命名：

例如，如果你的包包含位于 super_awesome_package/admin/ 的 admin 文件夹，其中包含 index.html 视图，你可以执行以下操作：

def configure(self):
    (
        self.root("super_awesome_package")
        .name("super_awesome")
        .views("admin")
    )Copy

视图将在控制器中可用：

class ProjectController(Controller):

    def index(self, view: View):
        return view.render("super_awesome.admin.index")Copy

如果你想允许用户将视图文件发布到他们自己的项目中以便他们可以调整它们，你应该添加 publish=True 参数。 package publish 命令会将视图文件发布到定义的项目视图文件夹中。使用默认项目设置，它将位于 templates/vendor/super_awesome/admin/index.html。

静态资源#

如果你的项目包含资产（例如 JS、CSS 或图像文件），你可以通过在 configure() 方法中调用 assets(*paths) 来注册它们以在项目中发布。

例如，如果你的包包含位于 super_awesome_package/assets/ 的 assets 文件夹，其中包含一些资产文件和文件夹，你可以执行以下操作：

def configure(self):
    (
        self.root("super_awesome_package")
        .name("super_awesome")
        .views("assets")
    )Copy

package publish 命令将资产发布到定义的项目资源文件夹中。使用默认项目设置，它将位于 resources/vendor/super_awesome/。

命令#

如果你的项目包含命令，当你的包安装到项目中时，你需要注册它，以便我们可以运行 python craft my_package_command。为此，你需要在 configure() 方法中调用 commands(*command_class)。

from ..commands import MyPackageCommand, AnOtherCommand

def configure(self):
    (
        self.root("super_awesome_package")
        .name("super_awesome")
        .commands(MyPackageCommand, AnOtherCommand)
    )Copy

现在，当你运行 python craft 时，你应该会看到两个已注册的命令。

发布资源#

当使用 PackageProvider 类创建你的包服务提供者时，你将能够在一个项目中发布下面定义的所有包资源。你只需要使用包的名称（在 configure() 方法中声明）运行命令 package:publish。在我们的示例中，它将是：

$ python craft package:publish super_awesomeCopy

如果你只想发布某些特定资源，可以使用 --resources 标志：

$ python craft package:publish super_awesome --resources config,viewsCopy

在这里，这只会将配置和视图发布到你的项目中。

最后，如果你想检查一个包可以发布哪些资源，你只需要运行：

$ python craft package:publish super_awesome --dryCopy

这将输出包将要发布到你的项目中的资源列表。

消费一个包#

如果包已在 PyPi 上发布，你需要将其安装为任何 Python 包：

$ pip install super-awesome-packageCopy

那么你应该遵循软件包安装指南，但通常它包括：

• 在你的项目中注册包 Service Provider：

from super_awesome_package.providers import SuperAwesomeProvider

PROVIDERS = [
  # ...
  SuperAwesomeProvider,
]Copy

• 如果你需要调整包资源或配置，请发布一些文件：

$ python craft package:publish super-awesome-packageCopy

你应该准备好在你的项目中使用这个包了！

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/masonite/4.0/fe...

译文地址：https://learnku.com/docs/masonite/4.0/fe...