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 list
  • ValueError – If all entries in value are not uppercase strings
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:
  • attribute (str) – The attribute name
  • value (str) – The attribute value
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
to_definition()[source]

Returns the definition of the subrecord.

Returns:The definition, a tuple of (definition, struct)
Return type:Tuple[str, Construct]
be(flag)[source]

Set the optional and multiple arguments.

Parameters:flag (str) – The flag to set for the current collection
Returns:The current subrecord
Return type:T_Subrecord
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:
  • attribute (str) – The attribute name
  • value (list) – The attribute value
Raises:
  • ValueError – - When the length of the items is not greater than 0
  • TypeError – - 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:
  • definition (str) – The definition to build from
  • data (list) – The data of the definition
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:
  • names (list) – The previously discovered subrecord names
  • target (str) – The target to discover next
  • strict (bool, optional) – Defaults to True. Enforce that required subrecords should appear before the target
Raises:

exceptions.UnexpectedSubrecord – - When nothing is expected next but target requested - When requested target does not match next expected subrecord

Returns:

The resulting discovered subrecord, or None

Return type:

Subrecord

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 a value that matches the subrecord’s data and a description of Not 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:
  • content (bytes) – The byte content of the archive
  • filepath (str, optional) – Defaults to None. Sets the filepath attribute for user’s reference
Raises:

ValueError – If the given content is not of bytes

Returns:

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 found
Returns:True if file can be handled, otherwise False
Return type:bool
classmethod parse_subrecord(record_id, record_type, subrecord_type, subrecord_data, strict=True)[source]

Parses a subrecord’s data.

Parameters:
  • record_type (str) – The parent record type
  • subrecord_type (str) – The subrecord type
  • subrecord_data (bytes) – The subrecord data to parse
  • strict (bool) – Defaults to True, If True, enforce strict subrecord discovery
Returns:

The resulting parsed container

Return type:

Container

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: