`blueprintbook`

Contains the BlueprintBook class for easily creating and manipulating Factorio BlueprintBooks.

{
    "blueprint_book": {
        "item": "blueprint-book", # The associated item with this structure
        "label": str, # A user given name for this blueprint book planner
        "label_color": { # The overall color of the label
            "r": float[0.0, 1.0] or int[0, 255], # red
            "g": float[0.0, 1.0] or int[0, 255], # green
            "b": float[0.0, 1.0] or int[0, 255], # blue
            "a": float[0.0, 1.0] or int[0, 255]  # alpha (optional)
        }
        "icons": [ # A set of signals to act as visual identification
            {
                "signal": {"name": str, "type": str}, # Name and type of signal
                "index": int, # In range [1, 4], starting top-left and moving across
            },
            ... # Up to 4 icons total
        ],
        "description": str, # A user given description for this blueprint book
        "version": int, # The encoded version of Factorio this planner was created 
                        # with/designed for (64 bits)
        "active_index": int, # The currently selected blueprint in "blueprints"
        "blueprints": [ # A list of all Blueprintable objects this book contains
            {
                "item": "blueprint",
                ... # Any associated Blueprint key/values
            }, # or
            {
                "item": "deconstruction-planner",
                ... # Any associated DeconstructionPlanner key/values
            }, # or
            {
                "item": "upgrade-planner",
                ... # Any associated UpgradePlanner key/values
            }, # or
            {
                "item": "blueprint-book",
                ... # Any above key/values
            }
        ]
    }
}

class BlueprintBook(blueprint_book: str = None)

Bases: Blueprintable

Factorio Blueprint Book class. Contains a list of Blueprintable objects as well as some of it’s own metadata.

load_from_string(string: str) → None

Load the Blueprintable with the contents of string.

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

Parameters:

string – Factorio-encoded blueprint string.

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.

setup(**kwargs)

Setup the Blueprintable’s parameters with the input keywords as values. Primarily used by the constructor, but can be used at any time to set a large number of keys all at once.

Raises DraftsmanWarning if any of the input keywords are unrecognized.

Parameters:: kwargs – The dict of all keywords to set in the blueprint.

Note

Calling setup only sets the specified keys to their values, and everything else to either their defaults or None. In other words, the effect of calling setup multiple times is not cumulative, but rather set to the keys in the last call.

Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint()
>>> blueprint.setup(label="test")
>>> assert blueprint.label == "test"
>>> test_dict = {"description": "testing..."}
>>> blueprint.setup(**test_dict)
>>> assert blueprint.description == "testing..."
>>> assert blueprint.label == None # Gone!

to_dict() → dict

Returns the blueprint as a dictionary. Intended for getting the precursor to a Factorio blueprint string before encoding and compression takes place.

Returns:: The dict representation of the BlueprintBook.

to_string() → 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()
'0eNpdy0EKgCAQAMC/7Nkgw7T8TIQtIdga7tol/HtdunQdmBs2DJlYSg0SMy1nWomwgL+BUSTSzuCppqQgCh7gf6H7goILC78Cfpi0cWZ21unejra1B7C2I9M='
>>> UpgradePlanner({"version": (1, 0)}).to_string()
'0eNo1yksKgCAUBdC93LFBhmm5mRB6iGAv8dNE3Hsjz/h0tOSzu+lK0TFThu0oVGtgX2C5xSgQKj2wcy5zCnyUS3gZdjukMuo02shV73qMH4ZxHbs='
>>> BlueprintBook({"version": (1, 0)}).to_string()
'0eNqrVkrKKU0tKMrMK4lPys/PVrKqVsosSc1VskJI6IIldJQSk0syy1LjM/NSUiuUrAx0lMpSi4oz8/OUrIwsDE3MTSzNzcwNDcxMzWprAVWGHQI='

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()

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)

property active_index: int

The currently selected Blueprintable in the BlueprintBook. Zero-indexed, from 0 to len(blueprint_book.blueprints) - 1.

Getter:: Gets the index of the currently selected blueprint or blueprint book.
Setter:: Sets the index of the currently selected blueprint or blueprint book. If the value is None, active_index defaults to 0.
Type:: int
Raises:: TypeError – If set to anything other than an int or None.

property blueprints: BlueprintableList

The list of Blueprints or BlueprintBooks contained within this BlueprintBook.

Getter:: Gets the list of Blueprintables.
Setter:: Sets the list of Blueprintables. The list is initialized empty if set to None.
Type:: BlueprintableList
Raises:: TypeError – If set to anything other than list or None.

property description: str

The description of the blueprintable. Visible when hovering over it when inside someone’s inventory.

Getter:: Gets the description, or None if not set.
Setter:: Sets the description of the object. Removes the attribute if set to None.
Type:: str
Raises:: TypeError – If setting to anything other than a str or None.

property icons: list

The visible icons of the blueprintable, shown in as the objects icon.

Stored as a list of ICON objects, which are dicts that contain a SIGNAL_ID and an index key. Icons can be specified in this format, or they can be specified more succinctly with a simple list of signal names as strings.

All signal entries must be a valid signal ID. If the input format is a list of strings, the index of each item will be it’s place in the list + 1. A max of 4 icons are permitted.

Getter:: Gets the list if icons, or None if not set.
Setter:: Sets the icons of the Blueprint. Removes the attribute if set to None.
Type:: {"index": int, "signal": {"name": str, "type": str}}
Raises:: DataFormatError – If the set value does not match either of the specifications above.
Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint()
>>> blueprint.icons = ["transport-belt"]
>>> blueprint.icons
[{'index': 1, 'signal': {'name': 'transport-belt', 'type': 'item'}}]

property item: str

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

Type:: str
Example:

>>> from draftsman.blueprintable import (
...     Blueprint, DeconstructionPlanner, UpgradePlanner, BlueprintBook
... )
>>> Blueprint().item
'blueprint'
>>> DeconstructionPlanner().item
'deconstruction-planner'
>>> UpgradePlanner().item
'upgrade-planner'
>>> BlueprintBook().item
'blueprint-book'

property label: str

The user given name (title) of the blueprintable.

Getter:: Gets the label, or None if not set.
Setter:: Sets the label of this object.
Type:: str
Raises:: TypeError – When setting label to something other than str or None.

property label_color: dict

The color of the BlueprintBook’s label.

The label_color parameter exists in a dict format with the “r”, “g”, “b”, and an optional “a” keys. The color can be specified like that, or it can be specified more succinctly as a sequence of 3-4 numbers, representing the colors in that order.

The value of each of the numbers (according to Factorio spec) can be either in the range of [0.0, 1.0] or [0, 255]; if all the numbers are <= 1.0, the former range is used, and the latter otherwise. If “a” is omitted, it defaults to 1.0 or 255 when imported, depending on the range of the other numbers.

Getter:: Gets the color of the label, or None if not set.
Setter:: Sets the label color of the BlueprintBook.
Type:: dict{"r": number, "g": number, "b": number, Optional("a"): number}
Raises:: DataFormatError – If the input label_color does not match the above specification.
Example:

blueprint.label_color = (127, 127, 127)
print(blueprint.label_color)
# {'r': 127.0, 'g': 127.0, 'b': 127.0}

property version: int

The version of Factorio the Blueprint was created in/intended for.

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 that Draftsman is currently initialized with.

The version can be set either as said 64-bit int, or 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.

blueprintbook

`blueprintbook`