Type safety

[ItsDrike]

Right now, our implementation simply returns dict[str, Any] objects from both load_version and load_common_data. This isn't great, and we could benefit from a more structured approach.

We will first need to decide on the approach for this though:

• Do we create custom python classes that hold the data (dataclasses/pydantic)
• Do we just make a bunch of typeddict definitions that match the file structure

As this is the primary reason why this library is not ready for stable use yet, after implementing this, we can shift from the Development Status :: 2 - Pre-Alpha to Development Status :: 4 - Beta.

[ItsDrike]

Another option would also be to try to dynamically generate typings based on the json schemas in the minecraft-base repository, as those are provided. If we went this route, it would likely mean the TypedDict approach, as with that, we can simply cast the serialized type as being of that schema, though it should technically also be possible to generate proper dataclasses/pydantic classes too if we really wanted to.

This is actually what node-minecraft-data is doing: https://github.com/PrismarineJS/node-minecraft-data/blob/master/typings/generate-typings.js

[ItsDrike]

After some deliberation and experimentation, I decided that going with custom pydantic model classes will probably be the best approach. Pydantic allows us to easily construct the instances from the dict objects. It also allows the model to contain some validation rules that match the JSON schemas and can ensure the data is what we expect it to be (providing better confidence in what the individual fields can hold for users).

The drawback of this approach is the fact that it will require more maintaining, since any schema changes will mean having to update the models manually. That said, because the test suite runs against every version in the minecraft-data repository, and the updates of this repository do happen automatically, it will be fairly easy for us to notice if the model no longer matches the data.

Since we will be using pydantic, we're going from accessing the fields using __getattr__ to regular attribute access. This is a breaking change. It's acceptable, as it's still fairly early within the development phase of minebase and it's worth the benefit.

Finally, this approach will also include transforming the names from camelCase to snake_case, since we will be accessing the fields as attributes and camelCase goes against pythonic naming practices. Pydantic makes this a fairly easy to implement change.

---

Comparison with the other approaches and reasoning behind this decision:

• Using simple dataclasses would be possible too, however, we would need to write our own classmethod constructors to build these classes from the dict structures. This wouldn't be terrible, but with the amount of different nested models, it would be annoying. Dataclasses also make it a lot more complex to implement validation, whereas pydantic has first-class support for this. This makes pydantic the obvious choice against simple dataclasses. I also briefly considered the attrs library, but pydantic still wins by a large margin there.
• The bigger question here was definitely between pydantic and pure TypedDict definitions. What convinced me to go with pydantic was the fact that it will give us a proper custom class to work, complete with the possibility to cleanly deprecate fields, create aliases, or property fields (which might prove especially useful when implementing Consider adding auto-generated indexes #17). The validation support was also a benefit, though it definitely wasn't the main reason. The annoying thing is that we won't be able to perform automatic generation of these TypedDict models and using pydantic will generally lead us to a more complex approach, but I do think that it's worth it.