Resources¶
pme.resources reads the registered resource folders and icon folders, the
script and icon files in them, and the resolution of a script reference. It
reads the resource configuration PME currently uses and
changes nothing. From an external script, pme is the
short alias or the explicit package import.
Added in version 2.2.0: Read-only queries for registered folders, script and icon files, and script reference resolution. The API is Experimental.
Function |
Purpose |
|---|---|
Returns the registered resource folders with their current status. |
|
Returns the registered icon folders with their current status. |
|
Lists the script and icon files in those folders. |
|
Resolves a script reference as script execution does. |
Results are immutable dataclasses. dataclasses.asdict() converts one to a
dictionary, including the nested folder.
Folders¶
- pme.resources.list_folders()¶
Return the registered resource folders in their saved order, with their current status.
- Returns:
One entry per registered folder. Missing locations are included.
- Return type:
tuple[ResourceFolderInfo, …]
- Raises:
RuntimeError – The resource settings could not be read and no previous valid configuration is available. The message is
"Resource settings are unavailable".
Notes
When no resource folder is registered, the result is empty. No default folder is created.
- pme.resources.list_icon_folders()¶
Return the registered icon folders in their saved order, with their current status.
Icon folders are registered separately from resource folders.
- Returns:
One entry per registered icon folder.
nameis"".- Return type:
tuple[ResourceFolderInfo, …]
- Raises:
RuntimeError – The resource settings could not be read and no previous valid configuration is available. The message is
"Resource settings are unavailable".
Notes
An empty result means that only the bundled icons are used. No default folder is created.
- class pme.resources.ResourceFolderInfo¶
A registered folder as observed at the time of the call. Used for resource folders and icon folders.
Attribute
Type
Value
indexint
Position in registration order, from 0. Not a stable identity.
namestr
Display name of a resource folder.
""for an icon folder. Not a namespace or a stable identity.raw_pathstr
The path as saved.
resolved_pathstr
Absolute path. A relative
raw_pathis resolved from the directory that contains the running Blender executable;~and environment variables are expanded.""whenstatusisinvalid.statusstr
See Folder status.
Folder status
statusMeaning
availableThe directory can be opened for listing. Its children are not checked; some can still be unreadable.
missingThe registered location does not exist.
not_directoryThe location is not a directory.
unreadableThe location cannot be inspected or scanned.
invalidThe saved path cannot be resolved.
resolved_pathis"".
Files¶
- pme.resources.list_files(kind=None)¶
List the existing script and icon files in the registered folders, including files that no slot uses.
Each call reads the active resource configuration and the file system again.
- Parameters:
kind (str or None) –
Nonefor both kinds,"script"or"icon".- Returns:
The files found and the locations that could not be read.
- Return type:
- Raises:
ValueError –
kindis another value. The message is"kind must be None, 'script', or 'icon'".RuntimeError – The resource settings could not be read and no previous valid configuration is available. The message is
"Resource settings are unavailable".
Scan scope
Kind
Files listed
Scripts
Files ending in lowercase
.pyanywhere in each resource folder, also outsidescripts/, because relative script references are resolved from the folder itself. Folders whose name starts with.and__pycache__are skipped. Directory symbolic links are followed; each real directory is visited once per registered folder.Icons
Files ending in lowercase
.pngdirectly in each icon folder, except names with the reserved_intr_prefix. Files with conflicting names and names starting with_(hidden in the Custom picker) are included. This is not a list of icons confirmed to be selectable or drawable.Example
Collect the registered folders and files as JSON for another tool:
from dataclasses import asdict import json import pme folders = pme.resources.list_folders() listing = pme.resources.list_files() payload = { "folders": [asdict(folder) for folder in folders], "files": [asdict(item) for item in listing.files], "issues": [asdict(issue) for issue in listing.issues], } print(json.dumps(payload, ensure_ascii=False, indent=2))
Notes
filesis a complete inventory only whenissuesis empty. A folder that is notavailablecontributes an issue and no files. A path that fails during the scan contributes an issue; the rest of its folder is still listed.A registered resource folder or icon folder that is missing is an issue.
With
kind=None, scripts come first, then icons. Folders follow registration order; names are sorted within each directory.Files with the same name in different folders are separate entries.
Contents are not executed or decoded.
Changes that an external editor makes to the resource settings file are loaded on the next startup or when the add-on is enabled again.
- class pme.resources.ResourceFileListing¶
Result of
list_files().Attribute
Type
Value
filestuple[ResourceFileInfo, …]
The files found.
issuestuple[ResourcePathIssue, …]
Folders and paths that could not be read.
- class pme.resources.ResourceFileInfo¶
An existing script or icon file.
Attribute
Type
Value
folderResourceFolderInfo
The registered folder that contains the file, with its status at the time of the scan.
kindstr
"script"or"icon".relative_pathstr
Path relative to
folder, with/separators: such asscripts/modeling/align.pyfor a script, the file name such asname.pngfor an icon. For a script it is a lookup reference: other registered folders can hold a file under the same reference, whichresolve_script()reports.absolute_pathstr
Absolute path of the file.
- class pme.resources.ResourcePathIssue¶
A folder or path that could not be read.
Attribute
Type
Value
folderResourceFolderInfo
The registered folder concerned.
pathstr
The folder’s
resolved_path(raw_pathwhen it is empty) for a folder that is not available, or the path that failed during the scan. Exception text is not included.codestr
missing,not_directory,unreadableorinvalid, with the meanings of Folder status.
Script references¶
- pme.resources.resolve_script(reference)¶
Resolve a script reference with the resolver that script execution uses, without running the script.
A slot stores the path of a file inside a registered folder relative to that folder, such as
scripts/modeling/align.py. The resolved absolute path identifies the file found now.- Parameters:
reference (str) – An absolute path or a relative reference.
- Returns:
The resolution status and the matching files.
- Return type:
Search order
referenceLocations checked
Absolute path
That path only.
assets/examples/scripts/...The bundled examples in the add-on package only.
Any other relative reference
Every registered resource folder, with
\read as/. The add-on package is checked only when no registered folder has a candidate and every registered location could be inspected. In the package, ascripts/...reference also finds the bundled examples at their earlier locations.Status
statusMeaning
resolvedOne file was found. Read permission and Python syntax are not checked.
missingNo matching file was found.
ambiguousTwo or more distinct files match.
unavailableA location could not be resolved or inspected, so resolution could not be completed.
Example
Build a command string for a slot. This neither runs the script nor edits a slot:
import pme reference = "scripts/modeling/align.py" result = pme.resources.resolve_script(reference) if result.status == "resolved": command = f"execute_script({reference!r})" print(command) # execute_script('scripts/modeling/align.py') else: print(result.status, result.candidates)
Notes
Distinct files are separate candidates even when their contents are the same. Paths that lead to the same real file count as one candidate.
ambiguoustakes precedence overunavailable.Files can change after the call. Script execution resolves the reference again.
- class pme.resources.ScriptResolution¶
Result of
resolve_script().Attribute
Type
Value
referencestr
The
referenceargument.statusstr
resolved,missing,ambiguousorunavailable.resolved_pathstr or None
Absolute path of the file when
statusisresolved;Noneotherwise.candidatestuple[str, …]
Paths of the matching files found: one for
resolved, two or more forambiguous, none formissing, those that could be inspected forunavailable.
Scope¶
The functions do not execute scripts, decode images, create directories or migrate settings.
Which slots use a file is not reported. Slot references are not updated when a file is moved or renamed.