`filter_inserter`

class FilterInserter(name: str = 'filter-inserter', **kwargs: dict)

Bases: FiltersMixin, StackSizeMixin, CircuitReadHandMixin, InserterModeOfOperationMixin, CircuitConditionMixin, LogisticConditionMixin, ControlBehaviorMixin, CircuitConnectableMixin, DirectionalMixin, Entity

An entity that can move items between machines, and has the ability to only move specific items.

Note

In Factorio, the Inserter prototype includes both regular and filter inserters. In Draftsman, inserters are split into two different classes, Inserter and FilterInserter

classmethod dump_format() → dict

Dumps a JSON-serializable representation of the Entity’s exports dictionary, primarily for user interpretation.

Returns:: A JSON dictionary containing the names of each valid key, a short description of their purpose, and whether or not they’re considered optional.

get() → Entity | list[Entity]: TODO

classmethod get_format() → str

Produces a pretty string representation of meth:dump_format. Work in progress.

Returns:: A formatted string that can be output to stdout or file.

get_world_bounding_box(): Gets the world-space coordinates AABB that completely encompasses the collision_set of this SpatialLike. Behaves similarly to the old function get_area(), except now it correctly handles non-AABB collision shapes.

get_world_collision_set() → CollisionSet

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

Returns:: A new CollisionSet with it’s content’s copied.

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 two entities use merge().

Parameters:: other – The other EntityLike to check against.
Returns:: True if they can be merged, False otherwise.

merge(other: FilterInserter) → None

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 – The other EntityLike to merge with.

on_insert(parent: EntityCollection) → None: TODO

on_remove(parent: EntityCollection) → None: TODO

remove_circuit_condition() → None: Removes the circuit condition of the Entity. Does nothing if the Entity has no circuit condition to remove.

remove_logistic_condition() → None: Removes the logistic condition of the Entity. Does nothing if the Entity has no logistic condition to remove.

set_circuit_condition(a: str | None = None, cmp: str = '<', b: str | int = 0) → None

Sets the circuit condition of the Entity.

cmp can be specified as stored as the single unicode character which is used by Factorio, or you can use the Python formatted 2-character equivalents:

# One of:
[">", "<", "=",  "≥",  "≤",  "≠"]
# Or, alternatively:
[">", "<", "==", ">=", "<=", "!="]

If specified in the second format, they are converted to and stored as the first format.

Parameters:

a – The string name of the first signal.
cmp – The operation to use, as specified above.
b – The string name of the second signal, or some 32-bit constant.

Raises:

DataFormatError – If a is not a valid signal name, if cmp is not a valid operation, or if b is neither a valid signal name nor a constant.

set_item_filter(index: int, item: str) → None

Sets one of the item filters of the Entity. index in this function is in 0-based notation.

Parameters:

index – The index of the filter to set.
item – The string name of the item to filter.

Raises:

IndexError – If index is set to a value exceeding or equal to filter_count.
InvalidItemError – If item is not a valid item name.

set_item_filters(filters: list) → None

Sets all of the item filters of the Entity.

filters can be either of the following 2 formats:

[{"index": int, "name": item_name_1}, ...]
# Or
[item_name_1, item_name_2, ...]

With the first format, the “index” key is in 1-based notation. With the second format, the index of each item is set to it’s position in the list. filters can also be None, which will wipe all item filters that the Entity has.

Parameters:

filters – The item filters to give the Entity.

Raises:

DataFormatError – If the filters argument does not match the specification above.
IndexError – If the index of one of the entries exceeds or equals the filter_count of the Entity.
InvalidItemError – If the item name of one of the entries is not valid.

set_logistic_condition(a: str | None = None, cmp: str = '<', b: str | int = 0) → None

Sets the logistic condition of the Entity.

cmp can be specified as stored as the single unicode character which is used by Factorio, or you can use the Python formatted 2-character equivalents:

# One of:
[">", "<", "=",  "≥",  "≤",  "≠"]
# Or, alternatively:
[">", "<", "==", ">=", "<=", "!="]

If specified in the second format, they are converted to and stored as the first format.

Parameters:

a – The string name of the first signal.
cmp – The operation to use, as specified above.
b – The string name of the second signal, or some 32-bit constant.

Raises:

DataFormatError – If a is not a valid signal name, if cmp is not a valid operation, or if b is neither a valid signal name nor a constant.

to_dict() → dict

Converts the Entity to its JSON dict representation. The keys returned are determined by the contents of the exports dictionary and their criteria functions.

A attribute from the Entity will be included as a key in the output dict if both of the following conditions are met:

The attribute is in the exports dictionary
The associated criteria function is either not present or returns True. This is used to avoid including excess keys, keeping Blueprint string size down.

In addition, a second function may be provided to have a formatting step to alter either the key and/or its value, which gets inserted into the output dict.

Returns:: The exported JSON-dict representation of the Entity.

property circuit_connectable: bool

Whether or not this EntityLike can be connected using circuit wires. Not exported; read only.

Type:: bool

property circuit_stack_size_enabled: bool

Sets if the inserter’s stack size is controlled by circuit signal.

Getter:: Gets whether or not the circuit stack size is enabled, or None if not set.
Setter:: Sets whether or not the circuit stack size is enabled. Removes the key if set to None.
Type:: bool
Raises:: TypeError – If set to anything other than a bool or None.

property circuit_wire_max_distance: int

The maximum distance that this entity can reach for circuit connections. Not exported; read only.

Type:: float

property collision_mask: set

The set of all collision layers that this Entity collides with, specified as strings. Equivalent to Factorio’s data.raw equivalent. Not exported; read only.

Type:: set{str}

property collision_set: CollisionSet: TODO

property connect_to_logistic_network: str

Whether or not this entity should use it’s logistic network condition to control its operation (if it has one).

Getter:: Gets the value of connect_to_logistic_network, or None if not set.
Setter:: Sets the value of connect_to_logistic_network. Removes the key if set to None.
Type:: bool
Raises:: TypeError – If set to anything other than a bool or None.

property connections: dict

Connections dictionary. Primarily holds information about the Entity’s circuit connections (as well as copper wire connections).

Type:: See draftsman.signatures.CONNECTIONS
Raises:: DataFormatError – If set to anything that does not match the format of draftsman.signatures.CONNECTIONS.

property control_behavior: dict

The control_behavior of the Entity.

Getter:: Gets the control_behavior.
Setter:: Sets the control_behavior. Gets set to an empty dict if set to None.
Type:: See draftsman.signatures.CONTROL_BEHAVIOR
Raises:: DataFormatError – If set to anything that does not match the CONTROL_BEHAVIOR signature.

property direction: Direction

The direction that the Entity is facing. An Entity’s “front” is usually the direction of it’s outputs, if it has any.

For some entities, this attribute may be redundant; for example, the direction value for an AssemblingMachine only matters if the machine has a fluid input or output.

Raises DirectionWarning if set to a diagonal direction. For 8-way rotations, ensure that the Entity inherits EightwayDirectionalMixin.

Getter:

Gets the direction that the Entity is facing.

Setter:

Sets the direction of the Entity. Defaults to Direction.NORTH if set to None.

Type:

Direction

Raises:

DraftsmanError – If the direction is set while inside an Collection, which is forbidden.
ValueError – If set to anything other than a Direction, or its equivalent int.

property double_grid_aligned: bool

Whether or not this EntityLike is “double-grid-aligned”, which applies to a number of rail entities. Not exported; read only.

Type:: bool

property dual_circuit_connectable: bool

Whether or not this EntityLike has two circuit connection points. Not exported; read only.

Type:: bool

property dual_power_connectable: bool

Whether or not this EntityLike has two power connection points. Not exported; read only.

Type:: bool

property filter_count: int

The number of filter slots that this Entity has in total. Equivalent to the "filter_count" key in Factorio’s data.raw. Not exported; read only.

Type:: int

property filter_mode: str

The mode that the filter is set to. Can be either "whitelist" or "blacklist".

Getter:

Gets the filter mode.

Setter:

Sets the filter mode.

Type:

str

Raises:

ValueError – If set to a str that is neither "whitelist" nor "blacklist".
TypeError – If set to anything other than a str or None.

property flippable: bool: Whether or not this entity can be mirrored in game using ‘F’ or ‘G’. Not exported; read only.

Note

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

property global_position: dict

The “global”, or root-most position of the Entity. This value is always equivalent to position(), unless the entity exists inside an EntityCollection. 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 exists at (5, 5), the global_position of the Entity will be (10, 10).

This is used to get an entity’s “actual” position in a blueprint, used when adding to a SpatialHashMap and when querying the entity by region. This attribute is always exported, but renamed to “position”; read only.

Type:: dict{"x": float, "y": float}

property hidden: bool

Whether or not this Entity is considered “hidden”, as specified in it’s flags in Factorio’s data.raw. Not exported; read only.

Note

“Hidden” in this context is somewhat unintuitive, as items you might think would be considered hidden may not be. Ship wreckage entities, for example, are not considered “hidden”, even though the only way to access them is with the editor. Keep this in mind when querying this attribute, especially since this discrepancy might be considered a bug later on.

filter_inserter

`filter_inserter`