Version 2.0.0 Release

[redruin1]

2.0 Release

At this moment, Draftsman 2.0 is not quite feature complete, so please keep that in mind before upgrading. The vast majority of the module is tested and complete, but your mileage may vary when using the new Factorio 2.0 features. As a result, it might be best to consider Draftsman 2.0.X to be "unstable", until something like 2.1 or therabouts.

This document outlines what is different in the new version, why those things are different, an the direction that future changes to Draftsman will be directed.

Deferred Validation

A big problem with Draftsman 1.0 is that it doesn't provide any real provisions for users working with blueprint configurations that Draftsman has no knowledge of. For example, consider the following case where we try to import a modded entity under a vanilla Factorio configuration:

my_modded_blueprint = {
    "blueprint": {
        "item": "blueprint",
        "entities": [
            {
                "name": "my-modded-entity",
                "position": {"x": 0.5, "y": 0.5}
            }
        ]
    }
}

blueprint = Blueprint(my_modded_blueprint) # InvalidEntityError: 'my-modded-entity'

Draftsman complains because it doesn't recognize the entity, and thus cannot meaningfully check it's correctness. From Draftsman's perspective, this makes sense; what's the dimension of this entity? What does it collide with? Is it circuit connectable? What attributes does it have? What are their allowed values? Because Draftsman cannot validate this object to the caliber of an entity it does know, it decides to consider it a catastrophic error and defer to the user to either remove it or update Draftsman's environment.

This is great for a number of circumstances, such as the case where you thought you were operating in a modded context but actually weren't, or in the case where the entity's name was simply a misspelled version of a known entity, which you likely want to catch as early as possible.

The problem is that there are other situations where this is too restrictive. A user might very well want to just ignore any unknown entities/tiles and simply return a Blueprint with the known ones, which is in fact how Factorio itself behaves. Going further, you might want to actually preserve these modded entities in the created blueprint; you might want to swap the modded entity to a known one which Draftsman can handle, or maybe you don't want to touch the modded stuff at all and simply pass it to the game, asserting that they must be in a valid format and the game will know how to handle it even if Draftsman doesn't.

Because the members of draftsman.data are fully writable, you can add new entries in their corresponding dictionaries or lists to "trick" Draftsman into allowing these cases. Unfortunately, there are no helper methods which actually make this a palatable option. Care must be taken to provide all of the necessary information in the exact correct format Draftsman expects, which is also likely to be inconsistent across Draftsman versions to boot. The only real sanctioned way in Draftsman 1.0 for interacting with modded entities is to modify the entire data configuration by running draftsman-update (or the corresponding method in env.py). This is easy if you're creating the blueprint string yourself with a set of mods that you're actively playing with, but difficult if:

• You change your mod configuration to something different but still want to load the modded string under a different configuration,
• You receive the blueprint string from an external source which is running a different mod configuration (of which you may have no knowledge what mods were used!), or
• You want to keep the script simple, and have it work with any environment configuration so that anyone can simply just run the script, dammit.

Clearly, this is a design flaw due to a simplification set early on when designing the tool. Since Draftsman runs the data lifecycle to extract validation information and can do so dynamically, I assumed that all of the needed data would be available at the script runtime, when this is not truly the case. As a result, Draftsman 1.0 is essentially a "greedy" validator, requiring comprehensive information about the entire environment before running, which is useful in some settings, but not in others.

Another related flaw about Draftsman 1.0 is that even if you want Draftsman to panic, you cannot tell it when to do so. Suppose for example that we want to swap all instances of a particular modded entity from a blueprint, but we still want to error if we detect any other modded entities. We would like to then write something similar to this:

modded_string = "..."
blueprint = Blueprint(modded_string, validate=False)

for i, entity in blueprint.entities:
    if entity.name == "modded-lamp":
        blueprint.entities[i] = Lamp("small-lamp", position=entity.position)

blueprint.validate() # InvalidEntityError: 'my-modded-entity'

... but this is also impossible in Draftsman 1.0. Validation of the Blueprint always happens at construction, and cannot be deferred until later; the only other option is to modify the data going into Blueprint before constructing it, but this would be much more of a hassle and we wouldn't have access to all of the nice helper methods that Blueprint already provides, such as find_entities_filtered() or similar.

Finally, a user may also desire more control of the manner and types of warnings/errors which are issued. Some users might want to check just the format of the input data so that no fields have the incorrect type; others might want a comprehensive analysis of all of the field values, to check for redundancies or conceptual faults, treating Draftsman like a blueprint linter. You might want to treat errors as warnings, or warnings as errors, or perhaps ignore validation completely. What validation should do is more than a simple "yes" or "no", and so a big goal for 2.0 was to not only allow users to control when they can validate their inputs but also configure it to behave exactly as they want.

As a result, in Draftsman 2.0 all Draftsman objects now have a validate() function which can be used to check their contents at any point after they're created. The function takes a ValidationMode parameter, which is an enum which indicates the strictness of the validation, which controls the type and quantity of errors and warnings:

• NONE: No validation whatsoever. Every attribute remains exactly as it was; even values in a known shorthand format are not converted. Impossible to know whether or not this object will import into Factorio when using this mode. This tells Draftsman to simply treat every object verbatim.
• MINIMUM: Only returns formatting errors, where data members are of incorrect types. For example, if you set the name of an entity to an integer, this would raise a DataFormatError. Besides this, no other warnings or errors are issued. This tells Draftsman to error if the object is in a form that it absolutely knows will NOT import into Factorio.
• STRICT: This is the default mode, most closely related to the behavior of Draftsman 1.0. It returns all above errors, as well as most of the errors and warnings most users of the module will be familiar with, in addition to a few new ones. For example, if Draftsman now encounters an entity it doesn't recognize, it issues a UnknownEntityWarning instead of an InvalidEntityError; Draftsman doesn't know about this entity, but it may import into Factorio if the game happens to know about it.
• PEDANTIC: Issues all above errors and warnings, as well as providing more linting-like behavior as well. A good example is setting the limiting bar of a container beyond it's total inventory slots; this creates no issue when importing into the game, and the container behaves as if the bar was set at that point; but it might indicate a conceptual failure from the programmers perspective or a simple mistake, and as such it will raise a BarWarning if detected under this validation mode.

Instead of raising the errors and warnings in place, validate() returns a wrapper object called a ValidationResult. This object contains an error_list and a warning_list attribute, which can be read, modified, iterated over, saved for later, or any combination thereof. This gives the user the ability to convert errors into warnings or warnings into errors, and it allows Draftsman to retain it's previous concepts of "Factorio-safety" and "Factorio-correctness" as the default while still allowing users to deviate from this behavior if required.

Most commonly, you'll probably end up writing something like this snippet, which simply reissues any detected errors or warnings found with a blueprint:

blueprint = Blueprint()

# Construct the blueprint in some way...

result = blueprint.validate(mode=ValidationMode.STRICT)
for error in result.error_list:
    raise error
for warning in result.warning_list:
    warnings.warn(warning)

Because this particular mnemonic is likely to appear a lot, it's implemented as a helper method called reissue_all():

blueprint = Blueprint()

# Construct the blueprint in some way...

blueprint.validate(mode=ValidationMode.STRICT).reissue_all() # Identical to the above

Creating a ValidationResult object also makes it very easy to add other similar helper methods like this one as well as additional functionality later on without breaking code in written in earlier versions of 2.0.

Similar to their prior behavior, all Blueprintable and Entity subclasses still support validation during construction, with the addition of now being able to configure exactly how using the new keyword argument validate:

messed_up_data = {
    "name": "unknown", # Should raise a warning
    "tags": "incorrect" # Should raise an error
}

container = Container(**messed_up_data, validate=ValidationMode.NONE) # No issues!
assert container.name == "unknown"
assert container.tags == "incorrect"
assert container.to_dict() == { # Even serialization still works
    "name": "unknown",
    "tags": "incorrect"
}

# Now validate it
result = container.validate()
assert len(result.error_list) == 1

In addition to the validate parameter, both Blueprintable and Entity subclasses also have a validate_assignment parameter, which configures whether or not to run validation when assigning an attribute of the object:

container1 = Container(validate_assignment=ValidationMode.STRICT) # Default, 1.0 behavior

container1.name = TypeError          # Raises an error because of type mismatch
container1.name = "unknown"          # Raises a warning because it's not recognized
container1.name = "electric-furnace" # Raises a warning because it's not a Container

# `validate_assignment` can be set at any point in the objects lifetime
container1.validate_assignment = ValidationMode.NONE

container1.name = TypeError          # Nothing
container1.name = "unknown"          # Nothing
container1.name = "electric-furnace" # Nothing

# `validate_assignment` is a per-instance attribute, so individual entities/blueprints can have their own validation severity
container2 = Container(validate_assignment=ValidationMode.STRICT)

assert container.validate_assignment is not container2.validate_assignment

In an effort to provide more flexibility while still keeping the API consistent across many different functions and attributes, Draftsman now has 3 "categories" of manipulating data for all the validatable types:

1. Dict-like modification, such as entity["member"] = ...; This mode is guaranteed to not run validation ever, regardless of the value of validate_assignment, and does not abide by shorthand formats. As a consequence, this method is also guaranteed to be computationally cheap.
2. Attribute access, such as entity.member = ...; The behavior of this mode is configurable, depending on the value of validate_assignment. Usually the most terse syntax.
3. Helper function, such as entity.set_member(...); This mode is guaranteed to run validation always, regardless of the value of validate_assignment. Also potentially provides additional functionality, such as setting defaults or formatting complex structures such as conditions, connections, etc.

And finally, for those who just want to update Draftsman's data on the fly, there are now helper methods for all the class types in draftsman.data which allow you to add new or modify existing data:

from draftsman.data import entities
from draftsman.entity import Container

entities.add_entity(
    name="new-container",
    entity_type="container",
    collision_box=((-0.4, -0.4), (0.4, 0.4)),
    inventory_size=100
    # Any other relevant keyword arguments can be provided and will be added to
    # the raw data entry
)

# "new-container" is now in all the correct places
assert "new-container" in entities.raw
assert "new-container" in entities.containers
# (NOTE: sort order is not currently preserved when adding at runtime)
# (This is harder than it sounds so I'm posteponing this until later)

container = Container("new-container")
assert (container.tile_width, container.tile_height) == (1, 1)
assert container.position == Vector(0.5, 0.5)
assert container.inventory_size == 100

# "new-container" will persist until the script ends

These methods are provided as a way to allow Draftsman to remain maximally strict against unknown data, but permit the user to quickly update said data just for the scope of a single script. This is provided mainly as a stopgap for cases where only a few entities/tiles are needed, which may be faster and/or simpler than grabbing the mod files themselves and running draftsman-update. In a future version, it might also make sense to have draftsman-update call these functions, meaning that this becomes the dedicated way to add/modify the Draftsman configuration dynamically (and thus only one place where it can break).

These new features will allow users of 2.0 to have much more control of the manner in which their structures are validated, hopefully making the module much more useful for a variety of new tasks. Of course, there is tons of room for improvement even with these additions, but while I can't quite remove it from the TODO list I feel much more comfortable now kicking that can down the road.

Validation is now done with pydantic instead of schema

All of the above magic is facilitated with the Pydantic validation library. schema was showing it's inflexibility, was lacking a number of features I was looking for, and was altogether not very fast, so I started looking for a good replacement. I went through a number of different libraries before I finally settled on Pydantic; the primary reasons were:

• Pydantic schemas are defined using Python type hints instead of a custom internal language specific to the library, making it easier for other maintainers to contribute to the project and generally make the whole validation code much easier on the eyes.
• Pydantic allows to specify custom validation functions which can be run at basically any point during the validation step; before, after, during, and can even stop validation altogether halfway through. With conditional enabling/disabling of these functions, it should also be possible to make version specific checks to allow for not only consistent validation, but also validation specific to a particular Factorio version. Perhaps even users themselves could add their own custom validation functions; I'm still exploring the possibilities. Even if I don't stick with Pydantic ultimately (it has some problems I've yet to resolve), I firmly believe any future solution will need to have something like this in place.
• Warnings and errors are all integrated into one system, instead of having split and competing ones. In addition, all validation uses the same backend, which means that not only does entity.items = {...} issue the same warnings as entity.set_items(...), but they both use the exact same code which is defined in one place, eliminating most of the bugs relating to validation being inconsistently performed.
• Pydantic supports JSON schema generation, meaning that you can take any Pydantic model and output an accurate JSON schema dictionary which describes it's exact format. This can then be extracted and used with any compliant JSON schema library to validate inputs of any Factorio blueprint string structure. Draftsman objects now have a json_schema() static method which can be used to dump this to a dictionary which can then be exported to other software. Furthermore, with a little bit of help it's highly likely that you could generate a human readable digest out of this information automatically, since the schema includes data type, value ranges, allowed values, etc. Because of this, almost all fields are given custom descriptions to not only make this feasible, but also highly likely in the future.

Additionally, the backend of Pydantic is written in Rust, which theoretically might lead to a considerable performance improvement (which was another longstanding issue with Draftsman), though due to the increased complexity of the validation, benchmarks will have to made to get any concrete conclusions. See the performance section below for more info on that.

Because Pydantic uses type hints to express it's schemas, this means that the new minimum Python version required will be Python 3.7. This also allows Draftsman to use a number of modern Python goodies that were previously precluded from it due to it's backwards compatibility restrictions. I honestly doubt there was anyone using my library on a version of Python prior to 3.7 anyway, but in case there was, Draftsman 1.0 will retain it's Python 2.0 compatibility and remain available on PYPI and under the 1.0 branch on Github. 1.0 will still receive bugfixes for the forseeable future, but all new features and the majority of new development will likely only exist on the main (2.0) branch going forward.

RailPlanner, Schedule, WaitConditions, and TrainConfiguration (finally)

Another longstanding weak point of Draftsman was it's rudimentary API when interacting with rails, trains, and their schedules. In 2.0, this area has seen large improvements.

For placing rails, the long in-development RailPlanner class is now feature functional. It allows you to draw rail paths using turtle-like commands, entirely similar to how the game itself does it:

from draftsman.blueprintable import Blueprint
from draftsman.rail import RailPlanner # New access point for rail related classes

# Create a new RailPlanner
# The name here refers to the vanilla rails, but you can change this to work with
# modded rails as well
planner = RailPlanner(name="rail")

# RailPlanners have a head position and direction, and can move forward, left, or right
planner.head_position = (0, 0)
planner.head_direction = Direction.SOUTH
planner.move_forward(5) # Place 5 straight rails southward
planner.turn_right()    # Turn 45 degrees to the right
planner.turn_left(3)    # Turn 135 degrees to the left, so we're now facing East
planner.move_forward(10)

# The head can be "picked-up" and oriented at any point
planner.head_position = (10, 10)
planner.head_direction = Direction.EAST
planner.move_forward(5)

# RailPlanners can also place rail signals (on either side of the track)...
planner.add_signal(entity="rail-signal")
planner.add_signal(entity="rail-chain-signal", right=False)
planner.move_forward(5)

# or train stops (on either side of the track)
planner.add_station(entity="train-stop", station="Name of Station")
planner.move_forward(5)

# Both of the above methods also allow you to pass in an existing entity instance
from draftsman.entity import TrainStop
configured_stop = TrainStop()
configured_stop.station = "Configured Station"
configured_stop.read_from_train = True
planner.add_station(entity=configured_stop)

# Now we can simply add the planner to a blueprint
blueprint = Blueprint()
blueprint.entities.append(planner)
print(blueprint.to_string())

RailPlanner is a superclass of Group, so all of the convenience methods available to it are provided as well, such as filtered searching, transformations, as well as positioning the entire set of rails all at once.

TrainConfiguration allows you to specify a sequence of rolling stock in the community-accepted syntax for describing trains:

from draftsman.rail import TrainConfiguration
from draftsman.entity import Locomotive, CargoWagon

# Trains are defined from left to right where left is the front of the train
config = TrainConfiguration("1-4")

# `cars` is a list of rolling stock corresponding to each car, where the 
# beginning of the list is the beginning of the train
print(len(config.cars)) # 5

# entries in `cars` are regular entities, which means they support everything
# you would expect:
# Request fuel to the locomotive
assert isinstance(config.cars[0], Locomotive)
config.cars[0].set_item_request("nuclear-fuel", 3) 
# Set the limiting bar for every following cargo wagon
for i in range(1, len(config.cars)):
    assert isinstance(config.cars[i], CargoWagon)
    config.cars[i].bar = 5

# You can also get things like the amount of rails needed to place this train in
# a straight line, which is useful for RailPlanner
print(config.rail_length) # 18

The syntax that Draftsman uses is a superset of the community version, which allows enough flexibility to specify any arbitrary train format. See examples/train_configuration_usage.py for much more info about that syntax and how it works.

Once you have a train, you likely want to give it a schedule. Conditions are specified with WaitCondition and WaitConditions objects:

from draftsman.rail import Schedule, WaitCondition

# Create a schedule object
schedule = Schedule()

# Individual conditions can be specified with particular parameters
cargo_full = WaitCondition("full")
cargo_empty = WaitCondition("empty")
inactivity = WaitCondition("inactivity", ticks=300) # 5 seconds

# To make it easier to specify multiple conditions together, `WaitConditions`
# objects can be made by combining wait conditions with AND and OR bitwise 
# operators
station_a_conditions = cargo_full | inactivity

# Adds a stop at station(s) with name "A"
schedule.append_stop(name="A", wait_conditions=station_a_conditions)
# This method correctly handles receiving a single WaitCondition object as well
schedule.append_stop("B", cargo_empty)

Then it can simply be added to a blueprint in 2 convenient ways:

# Simply adds a train going straight at a particular position and direction
blueprint.add_train_at_position(config, (10, 10), Direction.NORTH, schedule)

# Finds a particular station in the blueprint and places the train behind it
blueprint.add_train_at_station(config, blueprint.entities["station_entity"], schedule)

# (NOTE: neither function handles curves when placed on rails, at time of writing)

schedule can of course be omitted in case don't want the train to be set with a schedule. If you do specify a schedule, the schedule object will be added to the blueprint's schedules list, which can be inspected or modified in many different ways.

# Import a blueprint with trains with schedules
blueprint = Blueprint("...")

# Delete all schedules
blueprint.schedules = []

# ... or remove all trains from each schedule, but save the schedules themselves
for schedule in blueprint.schedules:
    schedule.locomotives = []

# ... or add a new schedule and change every train with an existing schedule to
# use the new schedule
new_schedule = Schedule()

for schedule in blueprint.schedules:
    new_schedule.locomotives += schedule.locomotives
    schedule.locomotives = []

blueprint.schedules.append(new_schedule)

# etc...

If you find a particular locomotive in a blueprint that you want to give a particular schedule, you can use the new set_train_schedule() helper method:

locos = blueprint.find_entities_filtered(type="locomotive")

# This function not only sets the schedule of these particular locomotives, but
# also traverses any connected train cars and sets any connected locomotives to
# have the same schedule as well
blueprint.set_train_schedule(locos, some_schedule)

You can also use the newly added find_trains_filtered() function to grab a very particular set of trains in a blueprint/group:

# Get all trains with a particular schedule less than 5 wagons long and give them
# a new schedule
trains = blueprint.find_trains_filtered(schedule=some_schedule, train_length=(0, 5))
for train in trains:
    blueprint.set_train_schedule(train, new_schedule)

# Remove all trains with a different schedule
trains = blueprint.find_trains_filtered(schedule=some_other_schedule)
for train in trains:
    blueprint.remove_train(train)

For more detail on how to use all the features of the new rail-oriented classes, see the examples folder.

draftsman-update Command changed to draftsman Command

draftsman-update has now been changed to be the more generic entry point draftsman:

    > draftsman-update -h
usage: draftsman [-h] [-p GAME_PATH] [-m MODS_PATH] [-v] {list,mod-settings,enable,disable,version,factorio-version,update} ...

A command-line utility for reporting and manipulating Draftsman's source data.

positional arguments:
  {list,mod-settings,enable,disable,version,factorio-version,update}
                        Operation:
    list                Lists information about all mods in the current environment.
    mod-settings        Displays all custom mod settings in `mod-settings.dat`, if present.
    enable              Enables a mod or mods.
    disable             Disables a mod or mods.
    version             Displays the current Draftsman version.
    factorio-version    Displays or sets the current version of Factorio's data.
    update              Updates Draftsman's environment by emulating Factorio's data lifecycle.

options:
  -h, --help            show this help message and exit
  -p GAME_PATH, --game-path GAME_PATH
                        The path to the data folder of the game; defaults to: `[python_install]/site-packages/draftsman/factorio-data`. If you own the game, you can pass in the folder where Factorio is installed, which will  
                        give you the ability to extract asset data in addition to prototype data.
  -m MODS_PATH, --mods-path MODS_PATH
                        The path to search for (user) mods; defaults to `[python_install]/site-packages/draftsman/factorio-mods`.
  -v, --verbose         Report additional information to stdout when available.

draftsman list lists all the detected mods at a given GAME_PATH and MODS_PATH:

    > draftsman list 
✓ (dir) base               2.0.29
✓ (dir) core                    -
✓ (dir) elevated-rails     2.0.29
✓ (dir) quality            2.0.29
✓ (dir) space-age          2.0.29

    > draftsman --verbose list
on? ┃ type  ┃ name           ┃ version ┃ location
━━━━╋━━━━━━━╋━━━━━━━━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✓  ┃ (dir) ┃ base           ┃  2.0.29 ┃ D:/SourceCode/repos/Python/factorio-draftsman/draftsman/factorio-data/base
 ✓  ┃ (dir) ┃ core           ┃       - ┃ D:/SourceCode/repos/Python/factorio-draftsman/draftsman/factorio-data/core
 ✓  ┃ (dir) ┃ elevated-rails ┃  2.0.29 ┃ D:/SourceCode/repos/Python/factorio-draftsman/draftsman/factorio-data/elevated-rails
 ✓  ┃ (dir) ┃ quality        ┃  2.0.29 ┃ D:/SourceCode/repos/Python/factorio-draftsman/draftsman/factorio-data/quality
 ✓  ┃ (dir) ┃ space-age      ┃  2.0.29 ┃ D:/SourceCode/repos/Python/factorio-draftsman/draftsman/factorio-data/space-age
...

draftsman enable/disable quickly enables or disables specific mods:

    > draftsman disable elevated-rails quality space-age

    > draftsman list
✓ (dir) base               2.0.29
✓ (dir) core                    -
  (dir) elevated-rails     2.0.29
  (dir) quality            2.0.29
  (dir) space-age          2.0.29

draftsman factorio-version allows you to view the current version of factorio-data, and even allows you to specify a specific version of it using git tags:

    > draftsman factorio-version
Factorio 2.0.28

    > draftsman -v factorio-version 1.0.0
Current Factorio version: 2.0.28
Different Factorio version requested:
        (2.0.28) -> (1.0.0)
Changed to Factorio version 1.0.0

    > draftsman -v factorio-version latest
Current Factorio version: 1.0.0
Different Factorio version requested:
        (1.0.0) -> (2.0.28)
Changed to Factorio version 2.0.28

And finally, draftsman-update has been renamed to the almost identical draftsman update:

    > draftsman -v update     
Discovering mods...

✓ (dir) base               2.0.29
✓ (dir) core                    -
✓ (dir) elevated-rails     2.0.29
✓ (dir) quality            2.0.29
✓ (dir) space-age          2.0.29

Determining dependency tree...

base
          core
elevated-rails
          base >= 2.0.0
quality
          base >= 2.0.0
space-age
          base >= 2.0.0
          elevated-rails >= 2.0.0
          quality >= 2.0.0

Load order:
['core', 'base', 'elevated-rails', 'quality', 'space-age']

SETTINGS.LUA:
SETTINGS-UPDATES.LUA:
SETTINGS-FINAL-FIXES.LUA:
DATA.LUA:
        mod: core
        mod: base
        mod: elevated-rails
        mod: quality
        mod: space-age
DATA-UPDATES.LUA:
        mod: base
        mod: quality
        mod: space-age
DATA-FINAL-FIXES.LUA:

Extracting data...

Extracted mods...
Extracted entities...
Extracted fluids...
Extracted instruments...
Extracted items...
Extracted modules...
Extracted planets...
Extracted recipes...
Extracted signals...
Extracted tiles...

Update finished.
hella slick; nothing broke!

Splitting functionality out into a more generic command makes much more sense from a user interface perspective and it makes it very easy to add new functionality and/or commands going forward. I already have some plans to implement recursive enable/disable, and or a method to fully configure mod settings from the CLI... but I'll add those features when somebody actually requests them.

Numerous Additional Quality of Life Features

2.0 also provides a number of features over 1.0 that should allow to write much more ergonomic code:

1. Direction and Orientation are now more than just normal enumerations, and support all of the methods supported with the Factorio Standard Library:

>>> from draftsman.constants import Direction, Orientation
>>> Direction.NORTH.opposite()
<Direction.SOUTH: 4>
>>> Direction.NORTH.next()
<Direction.EAST: 2>
>>> Direction.NORTH.previous(eight_way=True)
<Direction.NORTHWEST: 7>
>>> Direction.NORTH.to_vector()
<Vector>(0, -1)
>>> Direction.NORTH.to_orientation()
<Orientation.NORTH: 0.0>
>>> Orientation.NORTH.to_direction()
<Direction.NORTH: 0>
>>> Orientation.NORTH.to_vector(magnitude=10)
<Vector>(0, -10)

The Ticks constant class has also been added, which should make translating time-based periods much easier:

from draftsman.constants import Ticks

assert Ticks.SECOND == 60
assert 5 * Ticks.SECOND == 300
print(Ticks.__members__.keys()) # dict_keys(['SECOND', 'MINUTE', 'HOUR', 'DAY'])

# You can even convert `timedeltas` to ticks
from datetime import datetime
t1 = datetime.strptime("10:15:04", "%H:%M:%S")
t2 = datetime.strptime("10:19:27", "%H:%M:%S")
td = t2 - t1
print(Ticks.from_timedelta(td)) # 15780

And a whole lot more. In the effort of getting this version out as soon as possible, there are a lot of TODOs in function descriptions. Expect those to clear up over the coming weeks, at least as soon as all the bugs are worked out.

Future work

• While validation is a lot better now and much more flexible, it's not quite perfect. Using pydantic still has some limitations which make the whole process rather unweildly still in the backend, which I dislike. Furthermore, after discussing the issue with the maintainers it doesn't seem like the features I want will likely make it into the package anytime soon. There are also other things like valiation caching which I would like to implement, but are entirely outside the scope of all the validation libraries I've investigated so far. This implies that I'll have to in essence roll my own, which I am intentionally avoiding.
• The scope of this module has increased in functionality, but perhaps too much to justify it all existing under one umbrella. All of the validation stuff is very convenient in lots of circumstances, but not all circumstances; sometimes you might want just the data extraction and blueprint manipulation without the "linting" that a validator would provide. Furthermore, perhaps even the data extraction could be it's own separate entity; lots of projects might want to emulate Factorio's load process to get correct data.raw, and might not even necessarily want blueprint string manipulation. Fragmenting Draftsman into multiple components that can be integrated individually seems a smarter solution than the massive file glob I've currently developed.
• I would like to eventually support previous iterations of the blueprint string format, if enough interest is there.

Instead of being tacked onto the README, The list of things TODO has now moved to a dedicated document, with more information about each component. If you're interested in contributing, it should now be easier to see my intentions for the project going forward.

[gavinp]

Awesome work!

Nit: I'm not sure you meant "pneumonic". I'm not sure mnemonic would be right either. Consider idiom?

[redruin1]

Fixed. I did mean mnemonic, in that it should be "easy to recite and remember", but I'm a dropout programmer not an English major.

[gavinp]

Cheers from a dropout mathematician/philosopher.

All is well.