`entitylist`

class EntityList(parent: EntityCollection = None, initlist: Any = None)

Bases: MutableSequence

Custom object for storing sequences of EntityLike.

Contains all the functionality of a normal list. Adds the ability to index with id strings, as well as extra framework for interfacing with EntityCollection classes.

append(name: str | EntityLike, copy: bool = True, merge: bool = False, **kwargs: dict) → None

Appends the EntityLike to the end of the sequence.

Supports an optional shorthand where you can specify the string name of an Entity as entity and any keyword arguments, which are appended to the constructor of that entity.

Parameters:

name – Either a string reprenting the name of an Entity, or an EntityLike instance.
copy – Whether or not to create a copy of the passed in EntityLike. If entitylike is in string shorthand, this option is ignored and a new instance is always created.
merge – Whether or not to merge entities of the same type at the same position. Merged entities share non-overlapping attributes and prefer the attributes of the last entity added. Useful for merging things like rails or power-poles on the edges of tiled blueprints.
kwargs – Any other keyword arguments to pass to the constructor in string shorthand.

Note

Keyword arguments are only considered if entity is a string:

test_inserter = Inserter("fast-inserter")
blueprint.entities.append(test_inserter, id="test")
# Prints "None" because id was never set in test_inserter
print(blueprint.entities[-1].id)

Example:

blueprint = Blueprint()
assert isinstance(blueprint.entities, EntityList)

# Append Entity instance
blueprint.entities.append(Container("steel-chest"))
assert blueprint.entities[-1].name == "steel-chest"

# Append shorthand
blueprint.entities.append("wooden-chest", tile_position=(1, 1))
assert blueprint.entities[-1].name == "wooden-chest"
assert blueprint.entities[-1].tile_position == {"x": 1, "y": 1}

# Key indexing
blueprint.entities.append(
    TransportBelt(id = "some_id", tile_position=(1, 0))
)
assert isinstance(blueprint.entities["some_id"], TransportBelt)

# No copy
inserter = Inserter("fast-inserter", tile_position=(0, 1))
blueprint.entities.append(inserter, copy=False)
inserter.stack_size_override = 1
assert inserter is blueprint.entities[-1]
assert blueprint.entities[-1].stack_size_override == 1

check_entitylike(entitylike: EntityLike) → None

A set of universal checks that all EntityLike`s have to follow if they are to be added to this ``EntityList`.

Raises HiddenEntityWarning if the EntityLike being checked is marked as hidden.

Parameters:

entitylike – EntityLike instance to check.

Raises:

TypeError – If entitylike is not an EntityLike instance.
DuplicateIDError – If entitylike.id is already taken in the EntityList.

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values): S.extend(iterable) – extend sequence by appending elements from the iterable

get_pair(item: int | str) → tuple[int, str]

Takes either an index or a key, finds the converse entry associated with it, and returns them both as a pair.

Parameters:: item – Either an integer index or a string key.
Returns:: A tuple of the format (index, key).
Raises:: KeyError – If key item is not found in the key mapping dictionaries in the EntityList.

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(idx: int, name: str | EntityLike, copy: bool = True, merge: bool = False, **kwargs: dict) → None

Inserts an EntityLike into the sequence.

Supports an optional shorthand where you can specify the string name of an Entity as entity and any keyword arguments, which are appended to the constructor of that entity.

Parameters:

idx – The integer index to put the EntityLike.
name – Either a string reprenting the name of an Entity, or an EntityLike instance.
copy – Whether or not to create a copy of the passed in EntityLike. If entitylike is in string shorthand, this option is ignored and a new instance is always created.
merge – Whether or not to merge entities of the same type at the same position. Merged entities share non-overlapping attributes and prefer the attributes of the last entity added. Useful for merging things like rails or power-poles on the edges of tiled blueprints.
kwargs – Any other keyword arguments to pass to the constructor in string shorthand.

Note

Keyword arguments are only considered if entity is a string:

test_inserter = Inserter("fast-inserter")
blueprint.entities.insert(0, test_inserter, id="test")
# Prints "None" because id was never set in test_inserter
print(blueprint.entities[-1].id)

Example:

blueprint = Blueprint()
assert isinstance(blueprint.entities, EntityList)

# Insert Entity instance
blueprint.entities.insert(0, Container("steel-chest"))
assert blueprint.entities[0].name == "steel-chest"

# Insert shorthand
blueprint.entities.insert(1, "wooden-chest", tile_position=(1, 1))
assert blueprint.entities[1].name == "wooden-chest"
assert blueprint.entities[1].tile_position == {"x": 1, "y": 1}

# Key indexing
blueprint.entities.insert(
    0, TransportBelt(id = "some_id", tile_position=(1, 0))
)
assert isinstance(blueprint.entities["some_id"], TransportBelt)

# No copy
inserter = Inserter("fast-inserter", tile_position=(0, 1))
blueprint.entities.insert(0, inserter, copy=False)
inserter.stack_size_override = 1
assert inserter is blueprint.entities[0]
assert blueprint.entities[0].stack_size_override == 1

pop([index]) → item -- remove and return item at index (default last).: Raise IndexError if list is empty or index is out of range.

recursive_remove(item: EntityLike) → None: Removes an EntityLike from the EntityList. Recurses through any subgroups to see if item is there, removing the root-most entity first.

remove(value): S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

remove_key(key: str) → None

Shorthand to remove key from the key mapping dictionaries. Does nothing if key is None.

Parameters:: key – The string to remove.
Raises:: KeyError – If attempting to remove a key that does not exist in the EntityList.

reverse(): S.reverse() – reverse IN PLACE

set_key(key: str, value: EntityLike) → None

Shorthand to set key in the key mapping dictionaries to point to value.

Parameters:

key – A str to associate with value.
value – An EntityLike instance to associate with key.

Raises:

DuplicateIDError – If key already exists within the EntityList.
IndexError – If value is not found within the EntityList.

entitylist

`entitylist`