upgrade_planner¶

check_valid_upgrade_pair(

from_obj: UpgradeMapperSource | None,

to_obj: UpgradeMapperDestination | None,

) → list[Warning] | None¶

Checks a mapping from a “source” object to a “destination” objects, and returns a list of warnings if the transformation is malformed in some way.

Parameters:

from_obj: UpgradeMapperSource | None¶

The source entity/item specification.

to_obj: UpgradeMapperDestination | None¶

The destination entity/item specification.

Returns:

A list of one or more Warning objects containing the reason why the mapping would be invalid, or None if the transformation is considered valid.

class Mapper(index: ~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7436dd5c5ba0>], from_=None, to=None, *, extra_keys: dict[str, ~typing.Any] | None = None)¶

Bases: Exportable

An object which represents a upgrade “path” from an existing entity/item to an upgraded entity/item.

extra_keys : dict[str, Any] | None¶

Serialized

This attribute is imported/exported from blueprint strings.

Any additional keys that are not recognized by Draftsman when loading from a raw JSON dictionary end up as keys in this attribute. Under normal circumstances, this field should always remain None, indicating that all fields provided were properly translated into the internal Python format.

If there are any values in extra_keys after being imported from a raw JSON dictionary, then (left alone) these values will also be exported back into an output JSON dictionary in order to keep import-export cycles stable. A side effect of this is that users can use this attribute to add additional fields that will end up in the output string, primarily for custom metadata that can be read by other tools:

>>> input_dict = {
...    "name": "wooden-chest",
...    "position": {"x": 0.5, "y": 0.5},
...    "unknown_key": "blah"
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"unknown_key": "blah"}
>>> container.extra_keys["custom"] = "data"
>>> container.to_dict()
{
    "name": "wooden-chest",
    "position": {"x": 0.5, "y": 0.5},
    "unknown_key": "blah",
    "custom": "data"
}

The structure of input keys are preserved, meaning you may have to recurse through keys to find the unknown data:

>>> input_dict = {
...     "name": "wooden-chest",
...     "position": {"x": 0.5, "y": 0.5},
...     "nested": {
...         "dictionary": "value"
...     }
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"nested": {"dictionary": "value"}}

Note

While Draftsman makes an effort to preserve keys that it doesn’t recognize, Factorio itself makes no such effort - so if you create a blueprint string with custom metadata and then import it into the game, that additional data will be stripped and cannot be retrieved when exporting a new string from the game.

from_ : UpgradeMapperSource | None¶

Which item/entity to upgrade from.

index : _AndValidator object at 0x7436dd5c5ba0>]¶

Index of this mapper in the upgrade planner’s GUI.

to : UpgradeMapperDestination | None¶

Which item/entity to upgrade to.

classmethod from_dict(

d: dict,

version: tuple[int, ...] | None = None,

) → Self¶

Attempts to construct a new instance of this class from a Python dictionary in JSON format.

Parameters:

d: dict¶

The dictionary to interpret.

version: tuple[int, ...] | None = None¶

The Factorio version that the input data is compliant with.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

to_dict(

version: tuple[int, ...] | None = None,

exclude_none: bool = True,

exclude_defaults: bool = True,

) → dict¶

Export this object to a JSON dictionary, usually directly prior to encoding into the compressed blueprint string format.

Parameters:

version: tuple[int, ...] | None = None¶

Which Factorio version format this entity should be exported with. The same Draftsman object can be converted to many version-specific output dictionaries, each of which may have different structures.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

exclude_none: bool = True¶

Whether or not None properties should be omitted from the output string. For certain properties this option has no effect, as they either must always be present or never be present if None.

exclude_defaults: bool = True¶

Whether or not to exclude properties that are equivalent to their default values. Including these values in the generated output is redundant as Factorio will populate them automatically, but it is useful to disable for debug/illustation purposes.

validate(

mode: ValidationMode = ValidationMode.STRICT,

) → ValidationResult¶

Validates the called object against it’s known format.

Example:

>>> import draftsman
>>> from draftsman.constants import ValidationMode
>>> from draftsman.entity import Container
>>> from draftsman.error import DataFormatError
>>> c = Container("wooden-chest")
>>> with draftsman.validators.set_mode(ValidationMode.DISABLED):
...     c.bar = "incorrect"
>>> try:
...     c.validate().reissue_all()
... except DataFormatError as e:
...     print("wrong!")
wrong!

Parameters:

mode: ValidationMode = ValidationMode.STRICT¶

How strict to be when valiating the object, corresponding to the number and type of errors and warnings returned.

Returns:

A ValidationResult object, which contains all errors and warnings from the validation pass.

class UpgradeMapperDestination(type: ~typing.Literal['entity', 'item'], name: str | None = None, quality: ~typing.Literal[None, 'normal', 'uncommon', 'rare', 'epic', 'legendary', 'quality-unknown'] | None = None, module_limit: ~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7436dd5c5660>] | None = None, module_slots: list[~draftsman.signatures.ItemID] | None = [], *, extra_keys: dict[str, ~typing.Any] | None = None)¶

Bases: Exportable

An object representing a target entity or item to upgrade to.

extra_keys : dict[str, Any] | None¶

Serialized

This attribute is imported/exported from blueprint strings.

Any additional keys that are not recognized by Draftsman when loading from a raw JSON dictionary end up as keys in this attribute. Under normal circumstances, this field should always remain None, indicating that all fields provided were properly translated into the internal Python format.

If there are any values in extra_keys after being imported from a raw JSON dictionary, then (left alone) these values will also be exported back into an output JSON dictionary in order to keep import-export cycles stable. A side effect of this is that users can use this attribute to add additional fields that will end up in the output string, primarily for custom metadata that can be read by other tools:

>>> input_dict = {
...    "name": "wooden-chest",
...    "position": {"x": 0.5, "y": 0.5},
...    "unknown_key": "blah"
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"unknown_key": "blah"}
>>> container.extra_keys["custom"] = "data"
>>> container.to_dict()
{
    "name": "wooden-chest",
    "position": {"x": 0.5, "y": 0.5},
    "unknown_key": "blah",
    "custom": "data"
}

The structure of input keys are preserved, meaning you may have to recurse through keys to find the unknown data:

>>> input_dict = {
...     "name": "wooden-chest",
...     "position": {"x": 0.5, "y": 0.5},
...     "nested": {
...         "dictionary": "value"
...     }
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"nested": {"dictionary": "value"}}

Note

While Draftsman makes an effort to preserve keys that it doesn’t recognize, Factorio itself makes no such effort - so if you create a blueprint string with custom metadata and then import it into the game, that additional data will be stripped and cannot be retrieved when exporting a new string from the game.

module_limit : _AndValidator object at 0x7436dd5c5660>] | None¶

When upgrading modules, this defines the maximum number of this module to be installed in the destination entity. 0 or None means no limit.

Added in version 3.0.0: (Factorio 2.0)

module_slots : list[ItemID] | None¶

When upgrading entities, this defines which modules to be installed in the destination entity.

Added in version 3.0.0: (Factorio 2.0)

name : str | None¶

Name of the item or entity being upgraded to.

quality : Literal[None, 'normal', 'uncommon', 'rare', 'epic', 'legendary', 'quality-unknown']¶

The entity quality to upgrade to.

Added in version 3.0.0: (Factorio 2.0)

type : Literal['entity', 'item']¶

The type of this particular mapping, either "entity" or "item".

classmethod from_dict(

d: dict,

version: tuple[int, ...] | None = None,

) → Self¶

Attempts to construct a new instance of this class from a Python dictionary in JSON format.

Parameters:

d: dict¶

The dictionary to interpret.

version: tuple[int, ...] | None = None¶

The Factorio version that the input data is compliant with.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

to_dict(

version: tuple[int, ...] | None = None,

exclude_none: bool = True,

exclude_defaults: bool = True,

) → dict¶

Export this object to a JSON dictionary, usually directly prior to encoding into the compressed blueprint string format.

Parameters:

version: tuple[int, ...] | None = None¶

Which Factorio version format this entity should be exported with. The same Draftsman object can be converted to many version-specific output dictionaries, each of which may have different structures.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

exclude_none: bool = True¶

Whether or not None properties should be omitted from the output string. For certain properties this option has no effect, as they either must always be present or never be present if None.

exclude_defaults: bool = True¶

Whether or not to exclude properties that are equivalent to their default values. Including these values in the generated output is redundant as Factorio will populate them automatically, but it is useful to disable for debug/illustation purposes.

validate(

mode: ValidationMode = ValidationMode.STRICT,

) → ValidationResult¶

Validates the called object against it’s known format.

Example:

>>> import draftsman
>>> from draftsman.constants import ValidationMode
>>> from draftsman.entity import Container
>>> from draftsman.error import DataFormatError
>>> c = Container("wooden-chest")
>>> with draftsman.validators.set_mode(ValidationMode.DISABLED):
...     c.bar = "incorrect"
>>> try:
...     c.validate().reissue_all()
... except DataFormatError as e:
...     print("wrong!")
wrong!

Parameters:

mode: ValidationMode = ValidationMode.STRICT¶

How strict to be when valiating the object, corresponding to the number and type of errors and warnings returned.

Returns:

A ValidationResult object, which contains all errors and warnings from the validation pass.

class UpgradeMapperSource(

type: 'entity' | 'item',

name: str | None,

quality: None | 'normal' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'quality-unknown' | None = None,

comparator='=',

module_filter: Any | None = None,

*,

extra_keys: dict[str, Any] | None = None,

)¶

Bases: Exportable

An object representing an existing entity or item to select to be upgraded.

comparator : Literal['>', '<', '=', '==', '≥', '>=', '≤', '<=', '≠', '!=']¶

The comparison operation to use when determining which items/entities to upgrade.

Added in version 3.0.0: (Factorio 2.0)

extra_keys : dict[str, Any] | None¶

Serialized

This attribute is imported/exported from blueprint strings.

Any additional keys that are not recognized by Draftsman when loading from a raw JSON dictionary end up as keys in this attribute. Under normal circumstances, this field should always remain None, indicating that all fields provided were properly translated into the internal Python format.

If there are any values in extra_keys after being imported from a raw JSON dictionary, then (left alone) these values will also be exported back into an output JSON dictionary in order to keep import-export cycles stable. A side effect of this is that users can use this attribute to add additional fields that will end up in the output string, primarily for custom metadata that can be read by other tools:

>>> input_dict = {
...    "name": "wooden-chest",
...    "position": {"x": 0.5, "y": 0.5},
...    "unknown_key": "blah"
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"unknown_key": "blah"}
>>> container.extra_keys["custom"] = "data"
>>> container.to_dict()
{
    "name": "wooden-chest",
    "position": {"x": 0.5, "y": 0.5},
    "unknown_key": "blah",
    "custom": "data"
}

The structure of input keys are preserved, meaning you may have to recurse through keys to find the unknown data:

>>> input_dict = {
...     "name": "wooden-chest",
...     "position": {"x": 0.5, "y": 0.5},
...     "nested": {
...         "dictionary": "value"
...     }
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"nested": {"dictionary": "value"}}

Note

While Draftsman makes an effort to preserve keys that it doesn’t recognize, Factorio itself makes no such effort - so if you create a blueprint string with custom metadata and then import it into the game, that additional data will be stripped and cannot be retrieved when exporting a new string from the game.

module_filter : EntityFilter | None¶

When upgrading modules, this defines the specific entities to apply the upgrade to. None applies it to all entities.

Added in version 3.0.0: (Factorio 2.0)

name : str | None¶

Name of the item or entity being upgraded from.

quality : Literal[None, 'normal', 'uncommon', 'rare', 'epic', 'legendary', 'quality-unknown']¶

The item/entity quality to compare against.

Added in version 3.0.0: (Factorio 2.0)

type : Literal['entity', 'item']¶

The type of this particular mapping, either "entity" or "item".

classmethod from_dict(

d: dict,

version: tuple[int, ...] | None = None,

) → Self¶

Attempts to construct a new instance of this class from a Python dictionary in JSON format.

Parameters:

d: dict¶

The dictionary to interpret.

version: tuple[int, ...] | None = None¶

The Factorio version that the input data is compliant with.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

to_dict(

version: tuple[int, ...] | None = None,

exclude_none: bool = True,

exclude_defaults: bool = True,

) → dict¶

Export this object to a JSON dictionary, usually directly prior to encoding into the compressed blueprint string format.

Parameters:

version: tuple[int, ...] | None = None¶

Which Factorio version format this entity should be exported with. The same Draftsman object can be converted to many version-specific output dictionaries, each of which may have different structures.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

exclude_none: bool = True¶

Whether or not None properties should be omitted from the output string. For certain properties this option has no effect, as they either must always be present or never be present if None.

exclude_defaults: bool = True¶

Whether or not to exclude properties that are equivalent to their default values. Including these values in the generated output is redundant as Factorio will populate them automatically, but it is useful to disable for debug/illustation purposes.

validate(

mode: ValidationMode = ValidationMode.STRICT,

) → ValidationResult¶

Validates the called object against it’s known format.

Example:

>>> import draftsman
>>> from draftsman.constants import ValidationMode
>>> from draftsman.entity import Container
>>> from draftsman.error import DataFormatError
>>> c = Container("wooden-chest")
>>> with draftsman.validators.set_mode(ValidationMode.DISABLED):
...     c.bar = "incorrect"
>>> try:
...     c.validate().reissue_all()
... except DataFormatError as e:
...     print("wrong!")
wrong!

Parameters:

mode: ValidationMode = ValidationMode.STRICT¶

How strict to be when valiating the object, corresponding to the number and type of errors and warnings returned.

Returns:

A ValidationResult object, which contains all errors and warnings from the validation pass.

class UpgradePlanner(

label='',

label_color=None,

description='',

icons=NOTHING,

version=NOTHING,

index: ~typing.Annotated[int,

<draftsman.validators._AndValidator object at 0x7436dd5c5660>] | None = None,

item: str = 'upgrade-planner',

mappers=NOTHING,

*,

extra_keys: dict[str,

~typing.Any] | None = None,

)¶

Bases: Blueprintable

A Blueprintable used to upgrade and downgrade entities and items.

description : str¶

Serialized

This attribute is imported/exported from blueprint strings.

The description of the blueprintable. Visible when hovering over it when inside someone’s inventory. Has a maximum size of 500 bytes.

extra_keys : dict[str, Any] | None¶

Serialized

This attribute is imported/exported from blueprint strings.

Any additional keys that are not recognized by Draftsman when loading from a raw JSON dictionary end up as keys in this attribute. Under normal circumstances, this field should always remain None, indicating that all fields provided were properly translated into the internal Python format.

If there are any values in extra_keys after being imported from a raw JSON dictionary, then (left alone) these values will also be exported back into an output JSON dictionary in order to keep import-export cycles stable. A side effect of this is that users can use this attribute to add additional fields that will end up in the output string, primarily for custom metadata that can be read by other tools:

>>> input_dict = {
...    "name": "wooden-chest",
...    "position": {"x": 0.5, "y": 0.5},
...    "unknown_key": "blah"
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"unknown_key": "blah"}
>>> container.extra_keys["custom"] = "data"
>>> container.to_dict()
{
    "name": "wooden-chest",
    "position": {"x": 0.5, "y": 0.5},
    "unknown_key": "blah",
    "custom": "data"
}

The structure of input keys are preserved, meaning you may have to recurse through keys to find the unknown data:

>>> input_dict = {
...     "name": "wooden-chest",
...     "position": {"x": 0.5, "y": 0.5},
...     "nested": {
...         "dictionary": "value"
...     }
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"nested": {"dictionary": "value"}}

Note

While Draftsman makes an effort to preserve keys that it doesn’t recognize, Factorio itself makes no such effort - so if you create a blueprint string with custom metadata and then import it into the game, that additional data will be stripped and cannot be retrieved when exporting a new string from the game.

icons : list[Icon]¶

Serialized

This attribute is imported/exported from blueprint strings.

The visible icons of the blueprintable, as shown in the icon in Factorio’s GUI. A max of 4 Icon s are permitted.

Icons can also be specified more succinctly as a simple list of signal names:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint()
>>> blueprint.icons = ["transport-belt"]
>>> blueprint.icons
[Icon(index=0, signal=SignalID(name='transport-belt', type='item', quality='normal'))]

index : uint16 | None¶

Serialized

This attribute is imported/exported from blueprint strings.

The location of the blueprintable in a parent BlueprintBook. This member is automatically generated if omitted, but can be manually set with this attribute. This attribute has no meaning when the blueprintable is not located inside another blueprint book.

item : str¶

Serialized

This attribute is imported/exported from blueprint strings.

Always the name of the corresponding Factorio item to this blueprintable instance. Read only.

label : str¶

Serialized

This attribute is imported/exported from blueprint strings.

The user given name (title) of the blueprintable.

label_color : Color | None¶

Serialized

This attribute is imported/exported from blueprint strings.

The Color of the Blueprint’s label.

property mapper_count : _AndValidator object at 0x7436dd5c5990>]¶

The total number of unique mappings that this UpgradePlanner can have. Read only.

mappers : list[Mapper]¶

Serialized

This attribute is imported/exported from blueprint strings.

The list of mappings of one entity or item type to the other entity or item type.

Using set_mapping() will attempt to keep this list sorted by each mapping’s internal "index", but outside of this function this behavior is not required or enforced.

property root_item : 'upgrade_planner'¶

Serialized

This attribute is imported/exported from blueprint strings.

The “root” key of this Blueprintable’s dictionary form. For example, blueprints have the root_item key “blueprint”:

{
    "blueprint": { # <- this is the "root_item"
        ...
    }
}

All keys (except for index) are contained within this sub- dictionary.

version : uint64¶

Serialized

This attribute is imported/exported from blueprint strings.

The version of Factorio the Blueprint was created in.

The Blueprint version is a 64-bit integer, which is a bitwise-OR of four 16-bit numbers. You can interpret this number more clearly by decoding it with draftsman.utils.decode_version(), or you can use the functions version_tuple() or version_string() which will give you a more readable output. This version number defaults to the version of Factorio of Draftsman’s environment.

The version can be set either a 64-bit int in the format above, or as a sequence of ints (usually a list or tuple) which is then encoded into the combined representation. The sequence is defined as: [major_version, minor_version, patch, development_release] with patch and development_release defaulting to 0.

Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint()
>>> blueprint.version = (1, 0) # version 1.0.0.0
>>> assert blueprint.version == 281474976710656
>>> assert blueprint.version_tuple() == (1, 0, 0, 0)
>>> assert blueprint.version_string() == "1.0.0.0"

See also

https://wiki.factorio.com/Version_string_format

classmethod from_dict(

d: dict,

version: tuple[int, ...] | None = None,

) → Self¶

Attempts to construct a new instance of this class from a Python dictionary in JSON format.

Parameters:

d: dict¶

The dictionary to interpret.

version: tuple[int, ...] | None = None¶

The Factorio version that the input data is compliant with.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

classmethod from_string(string: str)¶

Creates a Blueprintable with the contents of string.

Raises UnknownKeywordWarning if there are any unrecognized keywords in the blueprint string for this particular blueprintable.

Parameters:

string: str¶

The Factorio-encoded blueprint string to decode.

Raises:

• MalformedBlueprintStringError – If the input string is not decodable to a JSON object.

• IncorrectBlueprintTypeError – If the input string is of a different type than the base class, such as trying to load the string of an upgrade planner into a Blueprint object.

pop_mapping(index: int) → Mapper¶

Removes a mapping at a specific mapper index. Note that this is not the position of the mapper in the mappers list; it is the value if "index" key associated with one or more mappers. If there are multiple mapper objects that share the same index, then the only the first one is removed.

Parameters:

index: int¶

The index of the mapping in the mapper to search.

Raises:

ValueError – If no matching mappers could be found that have a matching index.

remove_mapping(

source: str | UpgradeMapperSource,

destination: str | UpgradeMapperDestination,

index: int | None = None,

)¶

Removes a specified upgrade planner mapping. If index is not specified, the function searches for the first occurrence where both source and destination match. If index is also specified, the algorithm will try to remove the first occurrence where all 3 criteria match.

Note

index in this case refers to the index of the mapper in the UpgradePlanner’s GUI, not it’s position in the mappers list; these two numbers are potentially disjunct. For example, upgrade_planner.mappers[0][“index”] is not necessarily 0. If you want to remove the first entry in the mappers list, then you can simply do del upgrade_planner.mappers[0].

Parameters:

source: str | UpgradeMapperSource¶

The source entity/item specification.

destination: str | UpgradeMapperDestination¶

The destination entity/item specification.

index: int | None = None¶

The index of the mapping in the mapper to search.

Raises:

ValueError – If the specified mapping does not currently exist in the mappers list.

set_mapping(

source: str | UpgradeMapperSource,

destination: str | UpgradeMapperDestination,

index: int,

)¶

Sets a single mapping in the UpgradePlanner. Setting multiple mappers at the same index overwrites the entry at that index with the last set value. Both source and destination can be set to None which will create an unset mapping (and the resulting spot on the in-game GUI will be blank).

This function will also attempt to keep the list sorted by each mapper’s index key. This behavior is not enforced anywhere else, and if the mappers list is ever made unsorted, calling this function does not resort said list and does not guarantee a correct sorted result.

Parameters:

source: str | UpgradeMapperSource¶

The source entity/item specification.

destination: str | UpgradeMapperDestination¶

The destination entity/item specification.

index: int¶

The location in the upgrade planner’s mappers list.

to_dict(

version: tuple[int, ...] | None = None,

exclude_none: bool = True,

exclude_defaults: bool = True,

) → dict¶

Export this object to a JSON dictionary, usually directly prior to encoding into the compressed blueprint string format.

Parameters:

version: tuple[int, ...] | None = None¶

Which Factorio version format this entity should be exported with. The same Draftsman object can be converted to many version-specific output dictionaries, each of which may have different structures.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

exclude_none: bool = True¶

Whether or not None properties should be omitted from the output string. For certain properties this option has no effect, as they either must always be present or never be present if None.

exclude_defaults: bool = True¶

Whether or not to exclude properties that are equivalent to their default values. Including these values in the generated output is redundant as Factorio will populate them automatically, but it is useful to disable for debug/illustation purposes.

to_string(version: tuple[int] | None = None) → str¶

Returns this object as an encoded Factorio blueprint string.

Returns:

The zlib-compressed, base-64 encoded string.

Example:

>>> from draftsman.blueprintable import (
...     Blueprint, DeconstructionPlanner, UpgradePlanner, BlueprintBook
... )
>>> Blueprint(version=(1, 0)).to_string()
'0eNqrVkrKKU0tKMrMK1GyqlbKLEnNVbJCEtNRKkstKs7Mz1OyMrIwNDE3sTQ3Mzc0MDM1q60FAHmVE1M='
>>> DeconstructionPlanner(version=(1, 0)).to_string()
'0eNqrVkpJTc7PKy4pKk0uyczPiy/ISczLSy1SsqpWyixJzVWyQlOgC1Ogo1SWWlQMFFGyMrIwNDE3sTQ3Mzc0MDM1q60FAHp9Hf0='
>>> UpgradePlanner(version=(1, 0)).to_string()
'0eNqrViotSC9KTEmNL8hJzMtLLVKyqlbKLEnNVbKCyejCZHSUylKLijPz85SsjCwMTcxNLM3NzA0NzEzNamsBqdIX5Q=='
>>> BlueprintBook(version=(1, 0)).to_string()
'0eNqrVkrKKU0tKMrMK4lPys/PVrKqVsosSc1VskJI6IIldJTKUouKM/PzlKyMLAxNzE0szc3MDQ3MTM10lBKTSzLLUuMz81JSK5SsDGprATINHQI='

validate(

mode: ValidationMode = ValidationMode.STRICT,

) → ValidationResult¶

Validates the called object against it’s known format.

Example:

>>> import draftsman
>>> from draftsman.constants import ValidationMode
>>> from draftsman.entity import Container
>>> from draftsman.error import DataFormatError
>>> c = Container("wooden-chest")
>>> with draftsman.validators.set_mode(ValidationMode.DISABLED):
...     c.bar = "incorrect"
>>> try:
...     c.validate().reissue_all()
... except DataFormatError as e:
...     print("wrong!")
wrong!

Parameters:

mode: ValidationMode = ValidationMode.STRICT¶

How strict to be when valiating the object, corresponding to the number and type of errors and warnings returned.

Returns:

A ValidationResult object, which contains all errors and warnings from the validation pass.

version_string() → str¶

Returns the version of the Blueprintable in human-readable string.

Returns:

a str of 4 version numbers joined by a ‘.’ character.

Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint(version=(1, 2, 3))
>>> blueprint.version_string()
'1.2.3.0'

version_tuple() → tuple[~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7436dd5c5660>], ~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7436dd5c5660>], ~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7436dd5c5660>], ~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7436dd5c5660>]]¶

Returns the version of the Blueprintable as a 4-length tuple.

Returns:

A 4 length tuple in the format (major, minor, patch, dev_ver).

Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint(version=281474976710656)
>>> blueprint.version_tuple()
(1, 0, 0, 0)