写作项目¶

截至 PySpigot 0.9.0 版本，PySpigot 已经支持多文件项目。

本页面仅涵盖撰写多文件项目时需要了解的关键信息和区别，与编写单文件脚本有所不同。关于 PySpigot 脚本/项目的全部信息，请查看通用信息页面。

基本项目信息¶

撰写 PySpigot 项目几乎与撰写多模块 Python 项目相同。项目中的模块与常规 Python 中的模块行为完全相同。例如，使用模块需要首先导入它，而变量、函数和作用域对每个模块都是独立的。此外，导入机制也完全相同（即在项目子文件夹中需要一个__init__.py文件，以使其成为 Python 包）。

与单文件脚本类似，PySpigot 项目设计为自包含。这意味着每个项目被视为单个“捆绑包”，项目文件夹内的所有 Python 模块与其他文件隔离。然而，与单文件脚本类似，项目可以以各种方式相互交互。

PySpigot 项目被放置在projects文件夹中，这个文件夹位于 PySpigot 的主插件文件夹中。每个项目必须是一个文件夹，不允许单文件项目（因为这将是一个单文件脚本，应该放在scripts文件夹中）。projects文件夹中的所有文件夹都被视为项目，并将在服务器启动/插件加载时自动加载。

警告

项目名称必须在其他项目名称和单文件脚本名称中是唯一的，因为它们的名称用于在运行时识别它们。例如，PySpigot 无法同时加载和运行名为 test_project 的项目和名为 test_project.py 的脚本。

项目选项¶

有各种选项可以为每个项目进行设置，包括其主模块，是否启用，加载优先级以及日志选项。

项目选项在项目的 project.yml 文件中指定，该文件放置在项目的主目录中。例如，如果有一个名为 test_project 的项目，我会将其 project.yml 文件放在 /plugins/PySpigot/projects/test_project/project.yml。

要特别注意的项目选项是 main，它指定项目的主模块。PySpigot 使用此选项确定在加载项目时要执行哪个模块。如果在项目的 project.yml 文件中未指定此值，或者项目根本没有 project.yml 文件，则将使用主 config.yml 的 script-options-default 部分下的默认值（默认为 main.py）。

所有其他项目选项与用于单文件脚本的常规脚本选项相同。有关项目选项的更多信息，请参阅项目选项页面。

注意

为项目定义项目选项是可选的；如果项目的主模块与此项目选项的默认值相匹配，则项目将正常运作，而无需这些选项。

项目权限¶

PySpigot允许项目定义它们使用的权限列表。如果一个项目想要限制对某些功能的访问，这会很有用。权限在解析和执行项目的主模块之前初始化和加载，并在项目停止后立即移除。

项目权限在项目的project.yml文件中定义。有关如何定义权限的更多信息，请参阅项目选项文档。

项目加载¶

PySpigot会在插件加载或服务器启动时自动加载和运行项目文件夹中的所有项目。项目加载顺序由加载优先级决定，如项目的project.yml文件中所定义。未指定加载优先级的项目将继承config.yml中script-option-defaults部分中指定的默认加载优先级。具有相同加载优先级的项目按字母顺序加载。

项目也可以使用/pyspigot load <projectname>手动加载，如果你想在服务器启动/插件加载后加载/启用项目。如果您在运行时更改项目文件，必须重新加载项目以使更改生效。使用/pyspigot reload <projectname>重新加载项目。

与加载项目相关的配置选项有一个：

script-load-delay：这是PySpigot在服务器加载完成后等待加载脚本和项目的延迟时间（以tick为单位）。一个真实世界秒内有20个服务器ticks。例如，如果值是20，那么PySpigot将在服务器加载完成后等待20 ticks（或1秒）才加载脚本和项目。

脚本和项目在加载时交织在一起。换句话说，它们被一起加载。这意味着脚本和项目的加载优先级会同时进行比较，具有更高加载优先级的项目会比具有较低加载优先级的脚本先加载，反之亦然。

项目卸载¶

可以使用 /pyspigot unload <projectname> 手动卸载项目。运行 /pyspigot reload 也会在重新加载前先卸载项目（如果之前正在运行）。

从项目内部卸载一个项目¶

从项目内部卸载一个项目的方式与在常规Python中相同，通过使用 sys.exit 函数：

import sys

sys.exit(0)

sys.exit 函数可以安全地从项目内的任何模块中调用。在内部，调用 sys.exit 会引发 SystemExit 异常。PySpigot会捕获此异常并执行其标准卸载任务，以卸载引发异常的项目。

如果要使用信号卸载项目并指示发生错误，则将 1 传递给 sys.exit。这样做将阻止在卸载时调用项目主模块中的 stop 函数。

警告

不要使用脚本管理器从项目内部卸载项目！这将导致意外的错误/问题。

开始和停止函数¶

项目的 start 和 stop 函数的工作方式与单文件脚本的工作方式完全相同，但有一个重要的警告：它们必须放置在脚本的主模块中。

有关更详细信息，请参阅关于单文件脚本的开始和停止函数部分。

`pyspigot.py` 辅助模块¶

PySpigot 软件附带一个名为 pyspigot.py 的辅助模块，其中包含各种有用的函数，用于访问 PySpigot 的管理类。这个辅助模块可以通过简单导入的方式在项目中的任何模块中访问：

import pyspigot as ps

...

有关更多信息，请参阅PySpigot 辅助模块页面。

全局变量¶

全局变量系统对于项目和单文件脚本的功能方式完全相同。

请参阅全局变量页面，详细了解如何使用全局变量系统。

项目错误和异常¶

项目中的错误和异常的功能方式与单文件脚本完全相同，唯一的区别是在除项目的主模块之外的模块中发生异常时，回溯将包括完整的调用堆栈（最后一行是引发异常的模块）。

有关详细信息，请参阅单文件脚本中有关脚本错误和异常的部分。

项目日志记录¶

项目中的脚本日志记录与单文件脚本的方式完全相同。有关详细信息，请参阅单文件脚本中有关脚本日志记录的部分。

项目文件中的非 ASCII 字符¶

有关如何在项目文件中包含非 ASCII 字符的信息，请访问此页面。