Skip to content

自动完成和代码建议

注意

目前，这是一个实验性项目。如果您选择设置和使用PySpigot的这部分，请预计会有错误和频繁更改。我会在Discord上通知任何更新和变更，所以如果您还没有加入，请务必加入以保持最新动态。

如果您正在寻找如何为自己设置此功能的指导，请直接跳转到设置部分。

在编写PySpigot脚本时，您可能会遇到一个困难，即在您编写脚本时，IDE中缺乏代码建议和自动完成功能。之所以在编写脚本时这些功能不可用的原因相对直接 - 因为PySpigot脚本是在运行时执行的，IDE/文本编辑器完全不知道您在编写脚本时引用的函数、类等是什么。

编写更复杂的脚本可能很快变得繁琐，因为API中没有任何内容可用，所以您需要手动查找一切，包括包、类名、函数和API文档。这个项目旨在在编写脚本时消除这些困难。

概述

该项目的核心是docs-translator，这是一个Java程序，简单来说，它接受有文档记录的Java源代码，将其翻译为带文档记录的Python代码，然后将翻译后的源代码捆绑到一个可安装的Python包中。然后可以将这些Python包安装到一个虚拟环境中，供IDE使用。

docs-translator的工作原理

docs-translator 严重依赖于JavaParser库，简单来说，该库可以读取Java源文件（.java），然后将其转换为抽象语法树，这样就可以通过程序进行读取并相对容易地将其转换为Python源文件。

该应用程序通过以下步骤运行：

  1. 应用程序初始化所有工作目录。
  2. 从远程存储库/URL下载Java源文件JAR（即格式为*-sources.jar的文件）。
  3. 应用程序循环遍历下载的源文件JAR中包含的所有文件。当遇到Java源文件（以.java结尾）时，使用JavaParser解析文件，并尽力将源文件翻译为Python代码。
    • 忽略任何不以.java结尾的文件。
  4. 翻译后的.py文件被放置在用户定义的输出文件夹（默认为generated）中，放置在适当的包中。
  5. 在适当的包中的__init__.py文件中添加条目，以允许按照在Jython中导入Java类的方式导入Python模块。
  6. 之前转换的Java源文件中使用的Java标准库的任何源文件也会按照上述相同的过程进行翻译。
  7. 所有__init__.py文件都将生成并放置在适当的位置。
  8. 基于settings.yml文件中指定的选项生成Python包相关的文件（setup.py、pyproject.toml、MANIFEST.in、LICENSE），并将其放置在用户定义的输出文件夹中（默认为generated）。

我接着使用 python -m build 命令构建生成的 Python 包，并使用 twine 将其上传到 PyPI。目前，这个步骤是手动的，但我正在考虑扩展 docs-translator 的功能，以便自动化完成这一步骤。

设置

设置相对简单，包括创建一个新的 Python 虚拟环境，在其中使用 pip 安装来自 PyPI 的必要包，然后将虚拟环境指定为您选择的 IDE 中的 Python 安装位置。

虽然这应该适用于任何 IDE，但此示例使用Visual Studio Code (VS Code)，因为这个 IDE 非常受欢迎、免费、功能丰富，并且是我在编写 Python 代码时使用的IDE。我也没有测试这在其他IDE中的兼容性。

先决条件

  • 确保您的系统上已安装 Python 3，并且正在运行 Python 3.6 或更高版本。尽管 PySpigot 只支持 Python 2，但此项目需要 Python 3。您可以通过运行以下命令来检查： 
    1
    python --version
  • 您选择的 IDE。本指南偏爱使用 VS Code。
  • 一个用于放置脚本和项目的项目目录。这可以是 PySpigot 插件文件夹，或者如果您希望将开发环境与服务器分开（或者服务器位于另一台计算机上），则可以是一个单独的目录。
    • 这也是放置 Python 虚拟环境的首选位置。

创建 Python 虚拟环境

Note

虽然在设置这个过程中不是严格要求的，但强烈建议创建一个虚拟环境，因为包含翻译后的 Java 源代码的 Python 包可能以不可预测的方式干扰其他本地 Python 包。使用虚拟环境可以确保翻译后的源代码与全局安装的本地 Python 包保持隔离。

  1. 打开 命令提示符（cmd） 或者 PowerShell。
  2. 切换到您的项目目录： 
    1
    cd 项目目录的路径
  3. 使用 Python 创建一个虚拟环境： 
    1
    python -m venv venv
    • 注意，在上述命令中，最后一个参数是虚拟环境的名称。在这种情况下，我们将其命名为 venv。
  4. 激活虚拟环境：
    • 命令提示符： 
      1
      venv\Scripts\activate
    • PowerShell： 
      1
      venv\Scripts\activate.ps1
      (注意：如果使用 PowerShell，您可能需要使用 Set-ExecutionPolicy Unrestricted -Scope Process 命令来启用脚本执行权限)
  5. 虚拟环境现在已激活，您应该在命令行提示符中看到 (venv)。
  6. 要停用虚拟环境： 
    1
    deactivate
  1. 打开一个终端。
  2. 导航到您的项目目录： 
    1
    cd path/to/your/project/directory
  3. 使用Python创建一个虚拟环境： 
    1
    python -m venv venv
    • 请注意，在上述命令中，最后一个参数是虚拟环境的名称。在这种情况下，我们将其命名为venv。
  4. 激活虚拟环境： 
    1
    source venv/bin/activate
  5. 现在虚拟环境已被激活，您应该在命令行提示中看到(venv)。
  6. 要停用虚拟环境： 
    1
    deactivate

安装翻译后的源代码

正如之前所述，翻译后的源代码已被打包到Python包中，并发布到PyPI供方便安装。至少应该安装两个包到虚拟环境中：

  • 您正在开发的服务器软件的翻译源代码：

    如果您的服务器运行... 那么您应该安装的包是...
    Spigot pyspigot-spigot-sources
    Paper pyspigot-paper-sources
    Purpur pyspigot-purpur-sources
    Mohist pyspigot-spigot-sources
    BungeeCord pyspigot-bungee-sources

    要安装的版本是您服务器的Minecraft版本。

    一些示例：

  • 如果您的服务器正在运行Minecraft 1.18.2上的Spigot，请安装pyspigot-spigot-sources==1.18.2。

  • 如果您的服务器正在运行Minecraft 1.21.4上的Paper，请安装pyspigot-paper-sources==1.21.4。
  • 如果您的服务器正在运行Minecraft 1.20.6上的Purpur，请安装pyspigot-purpur-sources==1.20.6。

  • 如果您的服务器正在运行Minecraft 1.19.4上的BungeeCord，请安装pyspigot-bungeecord-sources==1.19.4。

  • PySpigot本身的翻译源码：

确定要安装PySpigot翻译源码的PyPI软件包更加简单：

如果您的服务器正在运行... 那么您应该安装的软件包是...
Bukkit (Spigot, Paper, Purpur等) pyspigot-sources-bukkit
BungeeCord pyspigot-sources-bungee

要安装的版本是您服务器上的PySpigot版本。

一些示例：

  • 如果您的服务器正在运行Bukkit和PySpigot版本0.8.0，请安装pyspigot-sources-bukkit==0.8.0。
  • 如果您的服务器正在运行BungeeCord和PySpigot版本0.8.0，请安装pyspigot-sources-bungee==0.8.0。

确定您需要安装哪些软件包后，请按照以下步骤操作：

  1. 确保之前创建的虚拟环境已被激活：
    • 确认命令行提示符中出现(venv)。
    • 运行以下命令： 
      1
2
      where python (Windows)
which python (macOS/Linux)
      确认输出包含您刚刚安装虚拟环境的位置。
  2. 安装每个包： 
    1
2
    pip install mc-paper-sources==1.21.4
pip install ps-bukkit-sources==0.8.0
    注意：这些根据您的服务器软件、Minecraft版本和PySpigot版本而有所不同！如果不确定要安装什么，请查看上面的部分。
  3. 确认所有包均已正确安装： 
    1
    pip freeze
    应列出您安装的每个包。

配置 VS Code 使用虚拟环境

  1. 打开 VS Code 并导航到/打开您的项目目录。
    • Windows：如果您已经在之前步骤的项目目录中，可以在命令提示符/PowerShell中键入以下内容来打开VS Code： 
      1
      code .
  2. 打开 命令面板：
    • Windows/Linux：Ctrl + Shift + P
    • macOS： + Shift + P
  3. 搜索并选择Python: Select Interpreter。
  4. 在出现的列表中，选择位于您之前创建的虚拟环境内部的解释器：
    • Windows：./venv/Scripts/python.exe
    • macOS/Linux：./venv/bin/python
  5. 确保所选解释器出现在VS Code 右下角。
  6. VS Code 现在将自动激活虚拟环境。

如果您为多个服务器软件和/或Minecraft版本编写脚本，必须为每个服务器软件和Minecraft版本创建不同的虚拟环境。将翻译后的源代码安装到同一虚拟环境中的多个不同服务器软件/Minecraft版本中会导致冲突和覆盖。

搞定了！现在，当您编写脚本时，VS Code应该会给出代码建议、自动补全建议，并显示API文档，因为它现在可以从已安装到虚拟环境中的翻译源中提取这些信息。

编写脚本时使用类型提示

类型提示对您的集成开发环境很有用，它可以在类型不明确的情况下提供代码建议和自动补全。这种情况出现在为事件监听器、命令、任务和PySpigot从Java调用您脚本中的函数等情况下。例如，请考虑以下注册事件监听器的脚本：

1
2
3
4
5
6
7
import pyspigot as ps
from org.bukkit.event.player import AsyncPlayerChatEvent

def player_chat(event): # (1)!
    print('Player sent a chat! Their message was: ' + event.getMessage())

listener = ps.listener.registerListener(player_chat, AsyncPlayerChatEvent)
  1. 您的集成开发环境不知道event的类型，因此无法为这个变量提供任何代码建议或自动补全。

当在player_chat函数内部调用event.<something>时，您的集成开发环境将无法提供代码建议，因为它不知道event的类型。为event参数添加类型提示可以纠正此不明确性：

1
2
3
4
5
6
7
import pyspigot as ps
from org.bukkit.event.player import AsyncPlayerChatEvent

def player_chat(event: "AsyncPlayerChatEvent"): # (1)!
    print('玩家发送了一条聊天！他们的消息是：' + event.getMessage())

listener = ps.listener.registerListener(player_chat, AsyncPlayerChatEvent)
  1. 现在，IDE 知道 event 的类型将是 AsyncPlayerChatEvent，因此它现在可以根据AsyncPlayerChatEvent类中的函数提供代码建议。
Note

自从 Python 3.5 引入了类型提示，Jython 将无法解析它们。在运行脚本之前，您必须手动删除它们。我计划在 PySpigot 中添加一个功能，可以在加载脚本文件时自动删除类型提示，以简化用户端的操作。

安装额外的库

这个系统的美妙之处在于任何 Java 库的源代码都可以被翻译并安装到您的虚拟环境中，以便在编写脚本时使用。如果您使用了某个外部库，并希望我将其翻译并发布到 PyPI，欢迎在 Discord 上与我联系。

问题

由于这是一个新项目，我预计会有问题。如果您遇到任何问题，请在 Discord 或 docs-translator Github 页面 上报告。 ```