pyglet.resource

从已知路径加载应用程序资源。

在Python中，通过指定文件名的相对路径来加载资源通常是有问题的，因为工作目录不一定与应用程序的脚本文件的目录相同。

此模块允许应用程序指定资源的搜索路径。相对路径被认为是相对于应用程序的 __main__ module. Zip文件可以出现在路径上;将在内部搜索它们。当使用Pyterfly、Nuitka、py 2app等冷冻机捆绑应用程序时，资源模块的行为也会符合预期。

除了提供文件引用(使用 file() 函数)，资源模块还包含用于加载图像、纹理、字体、媒体和文档的便利函数。

未绑定到特定应用程序的第三方模块或包应构建自己的模块或包 Loader 实例并重写路径以使用模块目录中的资源。

路径格式

资源路径 path (另见 Loader.__init__() 和 Loader.path() )是搜索资源的位置列表。按照路径中给出的顺序搜索位置。如果位置无效(例如，如果目录不存在)，则跳过该位置。

路径中以“at”符号(‘’@‘’)开头的位置指定了Python包。其他位置指定文件系统上的ZIP存档或目录。不是绝对的位置被假定为相对于脚本Home。以下是一些示例：

# Search just the `res` directory, assumed to be located alongside the
# main script file.
path = ['res']

# Search the directory containing the module `levels.level1`, followed
# by the `res/images` directory.
path = ['@levels.level1', 'res/images']

路径始终是 case-sensitive 和 forward slashes are always used 作为路径分隔符，即使在文件系统或平台不这样做的情况下也是如此。这避免了在平台之间移植应用程序时常见的程序员错误。

默认路径为 ['.'] 。如果修改路径，则必须调用 reindex() 。

exception ResourceNotFoundException

在搜索路径上找不到命名的资源。

__init__(name)

exception UndetectableShaderType

无法识别Shader源的类型。

__init__(name)

class FileLocation

文件系统上的位置。

__init__(filepath: str) → None: 创建一个给定相对或绝对路径的位置。

open(filename: str, mode: str = 'rb') → IO

在此位置打开文件。

参数:

name -- 要打开的文件名。不支持绝对路径。大多数位置不支持相对路径（您应该仅指定文件名，而不指定路径组件）。
mode (str) -- 打开时使用的文件模式。只有在文件系统上打开的文件才使用该参数；其他人则忽略它。

返回类型:

IO

class Loader

从磁盘加载程序资源文件。

加载程序包含一个搜索路径，其中可以包括文件系统目录、Zip存档、URL和Python包。

__init__( pathlist: list[str] | None = None, script_home: str | None = None, ) → None

为给定路径创建加载器。

如果未指定路径，则默认为 ['.'] ;也就是说，只是程序目录。

有关路径格式的详细信息，请参阅模块文档。

参数:

pathlist (list[str] | None) -- 搜索资源的位置列表。
script_home (str | None) -- 相关文件的基本位置。对.的结果表示怀疑 get_script_home() 。

add_font(filename: str) → None

将字体资源添加到应用程序。

必须先将系统上未安装的字体添加到pyglet中，然后才能将其与一起使用 font.load .尽管使用此函数添加字体及其文件名，但始终通过指定字体的族名来加载字体。例如：：

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

返回类型:: None

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, border: int = 1, ) → Animation

加载带有可选变换的动画。

从相同来源加载但具有不同变换的动画将使用相同的纹理。

参数:

name (str) -- 要加载的动画源的文件名。
flip_x (bool) -- 如果 True ，返回的图像将水平翻转。
flip_y (bool) -- 如果 True ，返回的图像将垂直翻转。
rotate (int) -- 返回的图像将顺时针旋转给定度数（必须是90的倍数）。
border (int) -- 在贴图集中的每个图像周围保留指定像素的空白空间，这可能有助于减少纹理渗漏。

返回类型:

Animation

attributed(name: str) → AbstractDocument

加载属性文本文档。

看见 pyglet.text.formats.attributed 有关此格式的详细信息，请参阅。

返回类型:: AbstractDocument

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

加载类似文件的对象。

参数:

name (str) -- 要加载的资源的文件名。
mode (str) -- 组合在一起 r ， w ， a ， b 和 t 具有建筑意义的字符 open 功能。

返回类型:

BytesIO | StringIO | IO

get_cached_animation_names() → list[str]

获取已缓存的动画文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_cached_image_names() → list[str]

获取已缓存的图像文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_cached_texture_names() → list[str]

获取已缓存的纹理文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_texture_bins() → list[TextureBin]

获取正在使用的纹理回收站的列表。

这仅对调试和分析有用。

返回类型:: list[TextureBin]

html(name: str) → AbstractDocument

加载一个HTML文档。

返回类型:: AbstractDocument

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

加载带有可选变换的图像。

这类似于 texture ，除非生成的图像将被打包到 TextureBin （TextureAtlas）如果其尺寸适合包装。这比将图像加载到单独的纹理中更有效。

参数:

name (str) -- 要加载的图像源的文件名。
flip_x (bool) -- 如果 True ，返回的图像将水平翻转。
flip_y (bool) -- 如果 True ，返回的图像将垂直翻转。
rotate (int) -- 返回的图像将顺时针旋转给定的度数(90的倍数)。
atlas (bool) -- 如果 True ，该图像将被加载到由pyglet管理的地图集中。如果阿特拉斯加载因特定纹理原因而不适合（例如需要边界控制），则设置为 False 。
border (int) -- 在贴图集中的每个图像周围保留指定像素的空白空间，这可能有助于减少纹理渗漏。

返回类型:

Texture | TextureRegion

备注

使用时 flip_x/y 或 rotate ，实际图像数据不会被修改。相反，操纵纹理坐标以产生所需的结果。

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

获取资源的位置。

此方法在打开从资源引用的文件时非常有用。例如，作为资源加载的HTML文件可能会引用一些图像。这些图像应该相对于HTML文件定位，而不是在加载器的路径中单独查找。

返回类型:: FileLocation | URLLocation | ZIPLocation

media(name: str, streaming: bool = True) → Source

加载声音或视频资源。

的含义 streaming 是为了 load() .无法流式传输压缩源（即，无法从Zip存档中流式传输视频和压缩音频）。

参数:

name (str) -- 要加载的媒体源的文件名。
streaming (bool) -- 如果源应该从磁盘流传输，则为True；如果应立即将其完全解码到内存中，则为False。

返回类型:

Source

model( name: str, batch: Batch | None = None, ) → Model

加载3D模型。

参数:

name (str) -- 要加载的3D模型的文件名。
batch (Batch | None) -- 要向其中添加此模型的可选批处理实例。

返回类型:

Model

reindex()

刷新文件索引。

如果出现以下情况，则必须调用此方法 resource.path 更改，或者文件系统布局更改。

shader( name: str, shader_type: str | None = None, ) → Shader

加载Shader对象。

参数:

name (str) -- 要加载的着色器源的文件名。
shader_type (str | None) -- 着色器类型的提示，例如“vertex”、“fragment”等。如果着色器具有标准文件扩展名，则不需要此提示，例如 .vert ， .frag 等。

返回类型:

Shader

text(name: str) → AbstractDocument

加载纯文本文档。

返回类型:: AbstractDocument

texture(name: str) → Texture

将图像加载为单个GL纹理。

返回类型:: Texture

class Location

抽象资源位置。

在给定位置的情况下，可以使用 open() 法这提供了一种方便的方法来指定加载文件的路径，即使该路径不驻留在文件系统上也是如此。

open( name: str, mode: str = 'rb', ) → BytesIO | StringIO | IO

在此位置打开文件。

参数:

name (str) -- 要打开的文件名。不支持绝对路径。大多数位置不支持相对路径（您应该仅指定文件名，而不指定路径组件）。
mode (str) -- 打开时使用的文件模式。只有在文件系统上打开的文件才使用该参数；其他人则忽略它。

返回类型:

BytesIO | StringIO | IO

class URLLocation

网络上的位置。

此类使用 urllib 模块打开网络上的文件，给出基本URL。

__init__(base_url: str) → None: 创建一个给定基本URL的位置。

open(filename: str, mode: str = '') → IO

打开远程文件。

参数:

filename (str) -- 要打开的远程资源的名称。
mode (str) -- 未使用，因为模式由远程服务器确定。

返回类型:

IO

class ZIPLocation

ZIP文件中的位置。

__init__(zipfileobj: ZipFile, directory: str | None)

创建一个给定打开的Zip文件和该文件内的路径的位置。

参数:

zipfileobj (ZipFile) -- 来自 zipfile 模块。
directory (str | None) -- 该Zip文件中的路径。可以为空以指定Zip文件顶层的文件。

open(filename: str, mode='rb') → BytesIO | StringIO

从ZipFile内部打开文件。

参数:

filename (str) -- 要打开的文件名。
mode -- 有效模式为“r”和“rb”。

返回类型:

BytesIO | StringIO

add_font(filename: str) → None

将字体资源添加到应用程序。

必须先将系统上未安装的字体添加到pyglet中，然后才能将其与一起使用 font.load .尽管使用此函数添加字体及其文件名，但始终通过指定字体的族名来加载字体。例如：：

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

返回类型:: None

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, border: int = 1, ) → Animation

加载带有可选变换的动画。

从相同来源加载但具有不同变换的动画将使用相同的纹理。

参数:

name (str) -- 要加载的动画源的文件名。
flip_x (bool) -- 如果 True ，返回的图像将水平翻转。
flip_y (bool) -- 如果 True ，返回的图像将垂直翻转。
rotate (int) -- 返回的图像将顺时针旋转给定度数（必须是90的倍数）。
border (int) -- 在贴图集中的每个图像周围保留指定像素的空白空间，这可能有助于减少纹理渗漏。

返回类型:

Animation

attributed(name: str) → AbstractDocument

加载属性文本文档。

看见 pyglet.text.formats.attributed 有关此格式的详细信息，请参阅。

返回类型:: AbstractDocument

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

加载类似文件的对象。

参数:

name (str) -- 要加载的资源的文件名。
mode (str) -- 组合在一起 r ， w ， a ， b 和 t 具有建筑意义的字符 open 功能。

返回类型:

BytesIO | StringIO | IO

get_cached_animation_names() → list[str]

获取已缓存的动画文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_cached_image_names() → list[str]

获取已缓存的图像文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_cached_texture_names() → list[str]

获取已缓存的纹理文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_data_path(name: str) → str

获取用于保存用户数据的目录。

对于基于Posix或Linux的系统，许多发行版都有一个单独的目录来存储特定应用程序的用户数据，并且此函数返回该位置的路径。

在Linux上，一个目录 name 在用户的数据目录中返回(通常在 ~/.local/share )。

在Windows上(包括在Cygwin下) name 用户的目录中 Application Settings 返回目录。

On Mac OS X the name directory under ~/Library/Application Support is returned. :rtype: str

备注

此函数不执行任何目录创建。用户应使用 os.path.exists 和 os.makedirs 如果需要，可以构建目录。

get_script_home() → str

获取包含程序条目模块的目录。

对于普通的Python脚本，这是包含 __main__ module.对于已与Pyterm、Nuitka等捆绑的应用程序，这可能是捆绑包路径或临时目录。

如果上述情况均不适用，且 __main__ 无法确定是否返回了工作目录。

当Python分析器运行脚本时，此函数可能会返回分析器运行的目录，而不是真实脚本的目录。为了解决这种行为，可以在中指定真正脚本的完整路径 pyglet.resource.path 。

返回类型:: str

get_settings_path(name: str) → str

获取目录路径以保存用户首选项。

不同的平台对于保存用户首选项和设置的位置有不同的约定。此函数实现如下所述的这些约定，并返回完全形成的路径。

在Linux上，一个目录 name 在用户的配置目录中返回(通常在 ~/.config )。

在Windows上(包括在Cygwin下) name 用户的目录中 Application Settings 返回目录。

On Mac OS X the name directory under ~/Library/Application Support is returned. :rtype: str

备注

此函数不执行任何目录创建。用户应使用 os.path.exists 和 os.makedirs 如果需要，可以构建目录。

get_texture_bins() → list[TextureBin]

获取正在使用的纹理回收站的列表。

这仅对调试和分析有用。

返回类型:: list[TextureBin]

html(name: str) → AbstractDocument

加载一个HTML文档。

返回类型:: AbstractDocument

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

加载带有可选变换的图像。

这类似于 texture ，除非生成的图像将被打包到 TextureBin （TextureAtlas）如果其尺寸适合包装。这比将图像加载到单独的纹理中更有效。

参数:

name (str) -- 要加载的图像源的文件名。
flip_x (bool) -- 如果 True ，返回的图像将水平翻转。
flip_y (bool) -- 如果 True ，返回的图像将垂直翻转。
rotate (int) -- 返回的图像将顺时针旋转给定的度数(90的倍数)。
atlas (bool) -- 如果 True ，该图像将被加载到由pyglet管理的地图集中。如果阿特拉斯加载因特定纹理原因而不适合（例如需要边界控制），则设置为 False 。
border (int) -- 在贴图集中的每个图像周围保留指定像素的空白空间，这可能有助于减少纹理渗漏。

返回类型:

Texture | TextureRegion

备注

使用时 flip_x/y 或 rotate ，实际图像数据不会被修改。相反，操纵纹理坐标以产生所需的结果。

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

获取资源的位置。

此方法在打开从资源引用的文件时非常有用。例如，作为资源加载的HTML文件可能会引用一些图像。这些图像应该相对于HTML文件定位，而不是在加载器的路径中单独查找。

返回类型:: FileLocation | URLLocation | ZIPLocation

media(name: str, streaming: bool = True) → Source

加载声音或视频资源。

的含义 streaming 是为了 load() .无法流式传输压缩源（即，无法从Zip存档中流式传输视频和压缩音频）。

参数:

name (str) -- 要加载的媒体源的文件名。
streaming (bool) -- 如果源应该从磁盘流传输，则为True；如果应立即将其完全解码到内存中，则为False。

返回类型:

Source

model(name: str, batch: Batch | None = None) → Model

加载3D模型。

参数:

name (str) -- 要加载的3D模型的文件名。
batch (Batch | None) -- 要向其中添加此模型的可选批处理实例。

返回类型:

Model

reindex()

刷新文件索引。

如果出现以下情况，则必须调用此方法 resource.path 更改，或者文件系统布局更改。

shader(name: str, shader_type: str | None = None) → Shader

加载Shader对象。

参数:

name (str) -- 要加载的着色器源的文件名。
shader_type (str | None) -- 着色器类型的提示，例如“vertex”、“fragment”等。如果着色器具有标准文件扩展名，则不需要此提示，例如 .vert ， .frag 等。

返回类型:

Shader

text(name: str) → AbstractDocument

加载纯文本文档。

返回类型:: AbstractDocument

texture(name: str) → Texture

将图像加载为单个GL纹理。

返回类型:: Texture

path = ['.']

默认资源搜索路径。

搜索路径中的位置是按顺序搜索的，并且始终区分大小写。更改路径后，您必须调用 reindex 。

有关路径格式的详细信息，请参阅模块文档。

类型:: 字符串列表

功能

reindex()

刷新文件索引。

如果出现以下情况，则必须调用此方法 resource.path 更改，或者文件系统布局更改。

file(name: str, mode: str = 'rb') → BytesIO | StringIO | IO

加载类似文件的对象。

参数:

name (str) -- 要加载的资源的文件名。
mode (str) -- 组合在一起 r ， w ， a ， b 和 t 具有建筑意义的字符 open 功能。

返回类型:

BytesIO | StringIO | IO

location( filename: str, ) → FileLocation | URLLocation | ZIPLocation

获取资源的位置。

此方法在打开从资源引用的文件时非常有用。例如，作为资源加载的HTML文件可能会引用一些图像。这些图像应该相对于HTML文件定位，而不是在加载器的路径中单独查找。

返回类型:: FileLocation | URLLocation | ZIPLocation

add_font(filename: str) → None

将字体资源添加到应用程序。

必须先将系统上未安装的字体添加到pyglet中，然后才能将其与一起使用 font.load .尽管使用此函数添加字体及其文件名，但始终通过指定字体的族名来加载字体。例如：：

resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

返回类型:: None

image( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, atlas: bool = True, border: int = 1, ) → Texture | TextureRegion

加载带有可选变换的图像。

这类似于 texture ，除非生成的图像将被打包到 TextureBin （TextureAtlas）如果其尺寸适合包装。这比将图像加载到单独的纹理中更有效。

参数:

name (str) -- 要加载的图像源的文件名。
flip_x (bool) -- 如果 True ，返回的图像将水平翻转。
flip_y (bool) -- 如果 True ，返回的图像将垂直翻转。
rotate (int) -- 返回的图像将顺时针旋转给定的度数(90的倍数)。
atlas (bool) -- 如果 True ，该图像将被加载到由pyglet管理的地图集中。如果阿特拉斯加载因特定纹理原因而不适合（例如需要边界控制），则设置为 False 。
border (int) -- 在贴图集中的每个图像周围保留指定像素的空白空间，这可能有助于减少纹理渗漏。

返回类型:

Texture | TextureRegion

备注

使用时 flip_x/y 或 rotate ，实际图像数据不会被修改。相反，操纵纹理坐标以产生所需的结果。

animation( name: str, flip_x: bool = False, flip_y: bool = False, rotate: int = 0, border: int = 1, ) → Animation

加载带有可选变换的动画。

从相同来源加载但具有不同变换的动画将使用相同的纹理。

参数:

name (str) -- 要加载的动画源的文件名。
flip_x (bool) -- 如果 True ，返回的图像将水平翻转。
flip_y (bool) -- 如果 True ，返回的图像将垂直翻转。
rotate (int) -- 返回的图像将顺时针旋转给定度数（必须是90的倍数）。
border (int) -- 在贴图集中的每个图像周围保留指定像素的空白空间，这可能有助于减少纹理渗漏。

返回类型:

Animation

texture(name: str) → Texture

将图像加载为单个GL纹理。

返回类型:: Texture

media(name: str, streaming: bool = True) → Source

加载声音或视频资源。

的含义 streaming 是为了 load() .无法流式传输压缩源（即，无法从Zip存档中流式传输视频和压缩音频）。

参数:

name (str) -- 要加载的媒体源的文件名。
streaming (bool) -- 如果源应该从磁盘流传输，则为True；如果应立即将其完全解码到内存中，则为False。

返回类型:

Source

model(name: str, batch: Batch | None = None) → Model

加载3D模型。

参数:

name (str) -- 要加载的3D模型的文件名。
batch (Batch | None) -- 要向其中添加此模型的可选批处理实例。

返回类型:

Model

shader(name: str, shader_type: str | None = None) → Shader

加载Shader对象。

参数:

name (str) -- 要加载的着色器源的文件名。
shader_type (str | None) -- 着色器类型的提示，例如“vertex”、“fragment”等。如果着色器具有标准文件扩展名，则不需要此提示，例如 .vert ， .frag 等。

返回类型:

Shader

html(name: str) → AbstractDocument

加载一个HTML文档。

返回类型:: AbstractDocument

attributed(name: str) → AbstractDocument

加载属性文本文档。

看见 pyglet.text.formats.attributed 有关此格式的详细信息，请参阅。

返回类型:: AbstractDocument

text(name: str) → AbstractDocument

加载纯文本文档。

返回类型:: AbstractDocument

get_cached_image_names() → list[str]

获取已缓存的图像文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_cached_animation_names() → list[str]

获取已缓存的动画文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

get_texture_bins() → list[TextureBin]

获取正在使用的纹理回收站的列表。

这仅对调试和分析有用。

返回类型:: list[TextureBin]

get_cached_texture_names() → list[str]

获取已缓存的纹理文件名列表。

这仅对调试和分析有用。

返回类型:: list[str]

例外情况

class ResourceNotFoundException

在搜索路径上找不到命名的资源。

__init__(name)

class UndetectableShaderType

无法识别Shader源的类型。

__init__(name)