`infinity_container`¶

class InfinityContainer( name: ~typing.Annotated[str, <function conditional.<locals>.decorator.<locals>.attr_validator at 0x7e1ce69271c0>] = NOTHING, id: str | None = None, position: Vector | tuple[int | float, int | float] = None, tile_position: Vector | tuple[int | float, int | float] = NOTHING, mirror: bool = False, quality: ~typing.Literal['normal', 'uncommon', 'rare', 'epic', 'legendary', 'quality-unknown'] = 'normal', item_requests: list[~draftsman.signatures.BlueprintInsertPlan] | None = NOTHING, tags: dict[str, ~typing.Any] | None = NOTHING, bar=None, filters: list[~draftsman.prototypes.infinity_container.InfinityContainer.Filter] = NOTHING, remove_unfiltered_items: bool = False, *, extra_keys: dict[str, ~typing.Any] | None = None, )¶

Bases: InventoryMixin, Entity

An entity used to create an infinite amount of any item.

class Filter(index: ~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7e1ce9d4e8c0>], name: ~typing.Annotated[str, <function conditional.<locals>.decorator.<locals>.attr_validator at 0x7e1ce6926f80>], quality: ~typing.Literal['normal', 'uncommon', 'rare', 'epic', 'legendary', 'quality-unknown'] = 'normal', count: ~typing.Annotated[int, <draftsman.validators._AndValidator object at 0x7e1ce9d4e980>] = 0, mode: ~typing.Literal['at-least', 'at-most', 'exactly'] = 'at-least', *, extra_keys: dict[str, ~typing.Any] | None = None)¶

Bases: Exportable

count : _AndValidator object at 0x7e1ce9d4e980>]¶: The amount of this item to keep in the entity, as discerned by ‘mode’.

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.

index : _AndValidator object at 0x7e1ce9d4e8c0>]¶: Where in the infinity containers GUI this filter will exist, 1-based.

mode : Literal['at-least', 'at-most', 'exactly']¶: What manner in which to create or remove this item from the entity. ‘at-least’ sets ‘count’ as a lower-bound, ‘at-most’ sets ‘count’ as an upper-bound, and exactly makes the quantity of this item match ‘count’ exactly.

name : attr_validator at 0x7e1ce6926f80>]¶: The name of the item to create/remove.

quality : Literal['normal', 'uncommon', 'rare', 'epic', 'legendary', 'quality-unknown']¶: The quality of the item to create/remove.

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.

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.

bar : uint16 | None¶

Serialized

This attribute is imported/exported from blueprint strings.

The limiting bar of the inventory. Used to prevent the final-most slots in the inventory from accepting new items.

Raises IndexWarning if the set value exceeds the Entity’s inventory_size attribute.

property circuit_connectable : bool¶

Whether or not this EntityLike can be connected using circuit wires.

Example:

>>> from draftsman.entity import *
>>> Beacon().circuit_connectable
False
>>> Inserter().circuit_connectable
True
>>> DeciderCombinator().circuit_connectable
True

property collision_mask : set[str]¶: The set of all collision layers that this Entity collides with, specified as strings. Equivalent to Factorio’s data.raw entry.

property collision_set : CollisionSet | None¶: The set of all CollisionShapes that this entity inherits. This set is dynamically updated based on the rotation or orientation of the entity, if applicable. If you want the collision shape of this entity that does not change via rotation or orientation, use static_collision_set instead.

property double_grid_aligned : bool¶: Whether or not this EntityLike is “double-grid-aligned”, which applies to entities which need to align with the rail grid.

property dual_circuit_connectable : bool¶

Whether or not this EntityLike has two circuit connection points.

Example:

>>> from draftsman.entity import *
>>> Beacon().dual_circuit_connectable
False
>>> Inserter().dual_circuit_connectable
False
>>> DeciderCombinator().dual_circuit_connectable
True

property dual_power_connectable : bool¶

Whether or not this EntityLike has two power connection points.

Example:

>>> from draftsman.entity import *
>>> Beacon().dual_power_connectable
False
>>> ElectricPole().dual_power_connectable
False
>>> PowerSwitch().dual_power_connectable
True

extra_keys : dict[str, Any] | None¶

Serialized

This attribute is imported/exported from blueprint strings.

>>> 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

filters : list[Filter]¶: Serialized

This attribute is imported/exported from blueprint strings.

The list of items to infinitely create or remove from this entity’s inventory.

See also

set_infinity_filter()

property flags : list[str] | None¶: A set of string flags which indicate a number of behaviors of this prototype.

See also

https://wiki.factorio.com/Types/EntityPrototypeFlags

property flippable : bool¶: Whether or not this entity can be mirrored in game using ‘F’ or ‘G’.

Warning

Work in progress. May be incorrect, especially for modded entities.

property global_position : Vector¶

The “global”, or root-most position of the Entity. This value is always equivalent to position, unless the entity exists inside of a containing Collection - if it does, then it’s global position is equivalent to the sum of all parent positions plus it’s own position.

For example, if an Entity exists within a Group at position (5, 5) and the Group.position is (5, 5), the global_position of the Entity will be (10, 10).

id : str | None¶: A unique string ID associated with this entity. IDs can be anything, though there can only be one entity with a particular ID in a Collection.

property inventory_bar_enabled : bool | None¶: Whether or not this Entity has its inventory limiting bar enabled. Returns None if this entity is not recognized by Draftsman.

item_requests : list[BlueprintInsertPlan]¶

Serialized

This attribute is imported/exported from blueprint strings.

A list of items to deliver to the entity. Not to be confused with logistics requests (which are persistent), item requests are only fulfilled once when the entity is first constructed. Most notably, modules are requested to entities with this field.

For user-friendly ways to modify this array, see set_item_request() and request_modules().

mirror : bool¶: Serialized

This attribute is imported/exported from blueprint strings.

Whether or not this blueprint is mirrored horizontally or vertically, specifically in regards to it’s fluid inputs/outputs.

Added in version 3.0.0: (Factorio 2.0)

name : EntityID¶: Serialized

This attribute is imported/exported from blueprint strings.

The name of the entity.

property parent : Collection | None¶: The parent Collection object that contains the entity, or None if the entity does not currently exist within an Collection.

position : _PosVector¶

Serialized

This attribute is imported/exported from blueprint strings.

The “canonical” position of the Entity, or the one that Factorio uses. Positions of most entities are located at their center, which can either be in the middle of a tile or on it’s transition, depending on the Entity’s tile_width and tile_height.

This property is updated in tandem with tile_position, so using them both interchangeably is both allowed and encouraged.

Raises:: DraftsmanError – If the entities position is modified when inside a Collection, which is forbidden.

property power_connectable : bool¶

Whether or not this EntityLike can be connected using power wires.

Example:

>>> from draftsman.entity import *
>>> Beacon().power_connectable
False
>>> ElectricPole().power_connectable
True
>>> PowerSwitch().power_connectable
True

property prototype : dict¶: The prototype dictionary extracted from Factorio’s data.raw for this entity. If this entity’s name does not correspond to an entry under the current environment, an empty dict is returned instead.

quality : QualityID¶

Serialized

This attribute is imported/exported from blueprint strings.

The quality of this entity. Can modify certain other attributes of the entity in (usually) positive ways.

Draftsman will automatically scale attributes based on quality value when appropriate. For example:

>>> from draftsman.entity import Container
>>> c = Container("steel-chest", quality="normal")
>>> c.size
48
>>> c.quality_affects_inventory_size
True
>>> c.quality = "legendary"
>>> c.size
120

Added in version 3.0.0: (Factorio 2.0)

property quality_affects_inventory_size : bool | None¶: Whether or not the quality of this entity modifies its inventory size.

remove_unfiltered_items : bool¶: Serialized

This attribute is imported/exported from blueprint strings.

Whether or not to remove items that exceed the amounts specified in filters.

property rotatable : bool¶

Whether or not this EntityLike has the capability of being rotated. This does not mean that blueprints containing these entities cannot be rotated; rather, it just means they will only ever have one orientation.

For example, it’s impossible for a Factorio Reactor to be oriented, so Reactor.rotatable always returns False.

property similar_entities : list[str]¶: Returns a list of strings representing the names of entities that share the same type as this one.

property size : _AndValidator object at 0x7e1ce9d4e8c0>] | None¶

The number of inventory slots that this entity has. If quality_affects_inventory_size is True for this entity, then the returned value is scaled by the quality of the entity. If the current quality of this entity is unrecognized by the current environment, then the base, un-scaled inventory size is returned.

If this entity is unrecognized by the current environment, this attribute returns None.

property slots_occupied : int¶: The number of inventory slots filled by the item requests for this entity. Useful for quickly determining the capacity of the chest after the item requests have been delivered.

property square : bool¶: Whether or not the tile width of this entity matches it’s tile height, giving it a square footprint.

property static_collision_set : CollisionSet | None¶: The set of all CollisionShapes that this entity inherits. This set is always the shape of the entity with it’s default orientation (typically facing north) and does not change when the entity is rotated/flipped. If you want the collision shape of this entity that does change when rotated, use collision_set instead.

property static_tile_height : int¶: The height of the entity irrespective of it’s current orientation. Equivalent to the tile_width when the entity is facing north.

property static_tile_width : int¶: The width of the entity irrespective of it’s current orientation. Equivalent to the tile_width when the entity is facing north.

property surface_conditions : dict | None¶

Gets the dictionary of surface constraints which apply when placing this entity. A missing entry in this dict means that this entity has no restriction for that particular property type.

If this entity has no constraints whatsoever, an empty dictionary is returned. If this entity is unrecognized by Draftsman, None is returned.

tags : dict[str, Any] | None¶: Serialized

This attribute is imported/exported from blueprint strings.

Tags associated with this Entity ghosts. Commonly used by mods to add custom data to a particular Entity when exporting and importing Blueprint strings.

property tile_height : int¶: The height of the entity in tiles, taking into account it’s current orientation.

tile_position : _TileVector¶

The tile-position of the Entity. The tile position is the position according the the LuaSurface tile grid, and is the top left corner of the top-leftmost tile that the Entity overlaps.

This property is updated in tandem with position, so using them both interchangeably is both allowed and encouraged.

Raises:: DraftsmanError – If the entities position is modified when inside a Collection, which is forbidden.

property tile_width : int¶: The width of the entity in tiles, taking into account it’s current orientation.

property type : str | None¶: The type of the Entity. Equivalent to the key found in Factorio’s data.raw. Mostly equivalent to the type of the entity instance, though there are some differences, as noted here. Can be used as a criteria to search with in Collection.find_entities_filtered(). Returns None if this entity’s name is not recognized when created without validation.

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.

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.

get() → Entity | list[Entity]¶

Gets this Entity. Redundant for regular instances of Entity, but is needed for Collections like Group.

This function resolves some abstract EntityLike object (which can have no direct relation to Factorio whatsoever) to one or more valid Factorio-importable Entity instances.

Returns:: One or more Entity instances that represents this entire EntityLike.

get_world_bounding_box() → AABB | None¶: Gets the world-space coordinates AABB that completely encompasses the collision_set of this SpatialLike. Returns None if the collision set of the target object is unknown.

get_world_collision_set() → CollisionSet¶

Get’s the world-space coordinate CollisionSet of the object, AKA the collection of all shapes that this EntityLike interacts with.

Returns:: A copy of this objects CollisionSet with the correct world-space location.

is_placable_on(planet_name: str) → bool¶

Check to see if this entity is placable on a particular planet. If the surface_conditions of this entity are unknown, then this function always returns True.

Parameters:

planet_name: str¶: The name of the planet being checked, such as "nauvis" or "vulcanus".

Returns:

True if the entity can be placed on this surface, False otherwise.

mergable_with(other: Entity) → bool¶

Checks to see if an entity is “mergable” with another entity. This means that if a certain set of criteria is met, the attributes of other will be combined to the attributes of this entity. This is useful for mimicking cases where entities of the same name and type are placed on top of each other, merging them together into a single entity with shared attributes.

For the full list of all merging rules, see (TODO).

Note

This function does not actually merge the two, it simply checks to see if such a merge is considered valid. To actually merge the two entities use merge().

Parameters:

other: Entity¶: The other EntityLike to check against.

Returns:

True if they can be merged, False otherwise.

merge( other: InfinityContainer, )¶

Changes the attributes of the calling entity with the attributes of the passed in entity. The attributes of other take precedence over the attributes of the calling entity. They can be either copied or merged together, depending on the specific attribute being merged.

For the full list of all merging rules, see (TODO).

Parameters:

other: InfinityContainer¶: The other EntityLike to merge with.

Sets an infinity filter.

Parameters:

index: int¶: The index of the filter to set.
item: str | None¶: The name of the item to filter.
mode: 'at-least' | 'at-most' | 'exactly' | None = 'at-least'¶: The manner in which to set the filter. Can be one of "at-least", "at-most", or "exactly".
count: int | None = None¶: The amount of the item to request. If set to None, the amount set will default to the stack size of name, if name can be deduced to a valid item. Otherwise count will default to 0.

Creates a construction request for an item. Removes the item request if count is set to 0 or None.

Parameters:

item: str¶: The string name of the requested item.
count: int | None = None¶: The desired amount of that item. If omitted a count of 0 will be assumed.
quality: 'normal' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'quality-unknown' = 'normal'¶: The quality of the requested item.
inventory: InventoryType = 1¶: The particular InventoryType to request this item to, since entities (as of Factorio 2.0) can have more than one distinct inventory to request items to. If omitted, it will default to 1, which is usally the “primary” inventory.
slot: int | None = None¶: The particular slot in the inventory to place the item. The next empty slot will be chosen automatically if omitted.

Raises:

TypeError – If item is anything other than a str, or if count is anything other than an int or None.
InvalidItemError – If item is not a valid item name.
ValueError – If count is less than zero.

to_dict( version: tuple[int, ...] | None = None, exclude_none: bool = True, exclude_defaults: bool = True, entity_number: int | None = None, )¶

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

Parameters:

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

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¶

entity_number: int | None = None¶

What numeric index this entity should be given, used for when resolving associations into concrete integer indexes. If omitted (usually when debugging), no "entity_number" key is provided to the output dict.

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.

infinity_container¶

`infinity_container`¶