bethesda_structs.plugin¶
This module contains structures that can read and extract Bethesda’s plugin file formats. These are files typically denoted with the following extensions:
.esp
- Elder Scrolls Plugin.esm
- Elder Scrolls Master.esl
- Elder Scrolls Light
These files contain and register logic and resources in order to extend the content and logic of an “Elder Scrolls” (engine) game. Typically the frontline of runtime errors, being able to understand what data the plugin contains is critical to understanding how to fix errors.
-
bethesda_structs.plugin.
get_plugin
(filepath)[source]¶ Get an instance of the first plugin that can handle a given file.
Parameters: filepath (str) – The path of the file to handle Returns: The base plugin Return type: BasePlugin Examples
This method simply returns the first encountered plugin that can handle a given file.
>>> FILEPATH = "" # absolute filepath to some FNV plugin >>> plugin = bethesda_structs.plugin.get_plugin(FILEPATH) >>> plugin FNVPlugin(filepath=PosixPath(...))
Common¶
Below is a listing of common objects, resources, etc. that can are are probably used throughout the other Plugin objects.
An example of this is the BasePlugin
class which provides an abstract class which all valid plugins should extend.
-
class
bethesda_structs.plugin._common.
FormID
(form_id, forms=NOTHING)[source]¶ The standardized form id object.
Raises: ValueError
– If forms is not a list of uppercase strings-
validate
(attribute, value)[source]¶ Validates forms.
Parameters: - attribute (str) – Should always be
forms
- value (Any) – Should be a list of uppercase strings
Raises: ValueError
– If value is not a listValueError
– If all entries in value are not uppercase strings
- attribute (str) – Should always be
-
-
class
bethesda_structs.plugin._common.
Subrecord
(name, struct, optional=False, multiple=False)[source]¶ Defines a subrecord that can be further parsed using the supplied struct.
-
name_validator
(attribute, value)[source]¶ Ensures that the name attribute is valid.
Parameters: Raises: ValueError
– - When the name is not of length 4
-
classmethod
parse_flag
(flag)[source]¶ Parses a given flag into a tuple for optional and multiple.
Parameters: flag (str) – The flag to parse Returns: A tuple containing the new (optional, multiple) booleans Return type: Tuple[bool, bool]
-
classmethod
from_dict
(data)[source]¶ Builds a subrecord from a given dictionary.
Parameters: data (dict) – The dictionary to use Returns: A new instance of a subrecord Return type: T_Subrecord
-
classmethod
from_definition
(definition, struct)[source]¶ Builds a subrecord from a given definition.
Parameters: - definition (str) – The definition to build from
- struct (Construct) – The structure of the subrecord
Returns: A new instance of a subrecord
Return type: T_Subrecord
-
to_dict
()[source]¶ Serializes the current subrecord as a dictionary.
Note
Currently not JSON serializable due to structs requiring the use of lambda functions and self refrences.
Returns: The resulting dictionary. Return type: dict
-
-
class
bethesda_structs.plugin._common.
SubrecordCollection
(name, items=NOTHING, optional=False, multiple=False)[source]¶ Defines a collection of subrecords.
-
items_validator
(attribute, value)[source]¶ Ensures that the items attribute is valid.
Parameters: Raises: ValueError
– - When the length of the items is not greater than 0TypeError
– - When not all of the items within the list are not of instance- Subrecord or SubrecordCollection
-
classmethod
parse_flag
(flag)[source]¶ Parses a given flag into a tuple for optional and multiple.
Parameters: flag (str) – The flag to parse Returns: A tuple containing the new (optional, multiple) booleans Return type: Tuple[bool, bool]
-
classmethod
from_dict
(data)[source]¶ Builds a subrecord collection from a given dictionary.
Parameters: data (dict) – The dictionary to use Returns: A new instance of a collection Return type: T_SubrecordCollection
-
classmethod
from_definition
(definition, data)[source]¶ Builds a subrecord collection from a given definition.
Parameters: Returns: A new instance of a SubrecordCollection
Return type: T_SubrecordCollection
-
to_dict
()[source]¶ Serializes the current collection as a dictionary.
Note
Not JSON serializable due to structs requiring lambda functions and self references.
Returns: The resulting dictionary Return type: Dict[str, Any]
-
to_definition
()[source]¶ Returns the definition of the collection.
Returns: The definition instance Return type: Tuple[str, list]
-
be
(flag)[source]¶ Set the optional and multiple arguments.
Parameters: flag (str) – Teh flag to set for the current collection Returns: The current subrecord collection Return type: T_SubrecordCollection
-
discover
(names, target, strict=True)[source]¶ Discovers the next expected subrecord given a target.
Parameters: Raises: exceptions.UnexpectedSubrecord
– - When nothing is expected next but target requested - When requested target does not match next expected subrecordReturns: The resulting discovered subrecord, or None
Return type:
-
handle_working
(subrecord_name, subrecord_data, working_record, strict=True)[source]¶ - Handles discovering and parsing a given subrecord using a list of already
- handled subrecord names.
Note
Subrecords that cannot be correctly discovered by the collection’s discovery process utilize a default
GreedyBytes * "Not Handled
struct. So any subrecord that cannot be discovered correctly or isn’t handled correctly with simply be a Container with avalue
that matches the subrecord’s data and adescription
ofNot Handled
.Parameters: - subrecord_name (str) – The name of the subrecord to discover and parse
- subrecord_data (bytes) – The data of the subrecord to discover and parse
- working_record (list) – The list of names that have already been handled in the working record
- strict (bool) – Defaults to True, If True, enforce strict discovery
Returns: - A tuple of
(parsed container, new handled names to extend the working record with)
Return type: Tuple[Container, List[str]]
-
-
class
bethesda_structs.plugin._common.
BasePlugin
(content, filepath=None, record_registry=<CIMultiDict()>)[source]¶ The base class all Plugins should subclass.
-
plugin_struct
¶ The base plugin structure to use for parsing a plugin.
Returns: The plugin structure Return type: Construct
-
classmethod
parse
(content, filepath=None)[source]¶ Create a BasePlugin from a byte array.
Parameters: Raises: ValueError
– If the given content is not of bytesReturns: A created BasePlugin
Return type: T_BasePlugin
-
iter_records
(record_type=None, include_header=False)[source]¶ Iterates over the container’s records.
- record_type (str, optional): Defaults to None. Filters the record types to
- yield
- include_header (bool, optional): Defaults to False. Includes the header
- record (regardless of
record_type
)
Yields: Container – A record’s container Return type: Generator
[Container
,None
,None
]
-
iter_subrecords
(subrecord_type=None, record_type=None, include_header=False)[source]¶ Iterates over the container’s subrecords.
- subrecord_type (str, optional): Defaults to None. Filters the subrecord
- types to yield
- record_type (str, optional): Defaults to None. Filters the record types to
- look for subrecords in
- include_header (bool, optional): Defaults to False. Includes the header
- record in the filter (regardless of
record_type
)
Yields: Container – A subrecord’s container Return type: Generator
[Container
,None
,None
]
-
Fallout: New Vegas¶
This module contains all the required structures to parse FNV plugins.
-
class
bethesda_structs.plugin.fnv.
FNVPlugin
(content, filepath=None, record_registry=<CIMultiDict()>)[source]¶ Bases:
bethesda_structs.plugin._common.BasePlugin
The plugin for Fallout: New Vegas.
- This plugin structure should handle plugins for the games:
- Fallout 3
- Fallout: New Vegas
Note
This structure currently reads all data on initialization. This may appear as slower initialization times for larger plugins. Should be fixed by lazy constructs when they become more stable.
- Credit:
-
subrecord_struct
= <Struct>¶ The structure for FO3/FNV subrecords.
Returns: The structure of FO3/FNV subrecords Return type: Struct
-
record_struct
= <Struct>¶ The structure for FO3/FNV records.
Returns: The structure of FO3/FNV records Return type: Struct
-
group_struct
= <Struct>¶ The structure for FO3/FNV groups.
Returns: The structure of FO3/FNV groups Return type: Struct
-
plugin_struct
= <Struct>¶ The structure for FO3/FNV plugins.
Returns: The structure of FO3/FNV plugins Return type: Struct
-
classmethod
can_handle
(filepath)[source]¶ Determines if a given file can be handled by the plugin.
Parameters: filepath (str) – The filepath to evaluate Raises: FileNotFoundError
– When the given filepath cannot be foundReturns: True if file can be handled, otherwise False Return type: bool
Fallout 3¶
This module contains all the required structures to parse FO3 plugins.
-
class
bethesda_structs.plugin.fo3.
FO3FormID
(forms, *args, **kwargs)[source]¶ Bases:
bethesda_structs.plugin.fnv._common.FNVFormID
A formid wrapper for Fallout 3.
Note
Because the logic for parsing Fallout 3 form ids is the same as Fallout: New Vegas form ids, this class is simply a subclass of
FNVFormID
.- Credit:
-
class
bethesda_structs.plugin.fo3.
FO3Plugin
(content, filepath=None, record_registry=<CIMultiDict()>)[source]¶ Bases:
bethesda_structs.plugin.fnv.FNVPlugin
The plugin for Fallout 3.
Note
Because the logic for parsing Fallout 3 plugins is the same as Fallout: New Vegas plugins, this class is simply a subclass of
FNVPlugin
.- Credit: