NBT Library V3
Why is this needed?
V1 of the NBT library did some things that in hindsight were a bad idea.
V3 of the NBT library is a large overhaul that adds a number of features and removes some as well.
V2 is a bridge between the versions. It has all the good parts of V3 the bad parts of V1 depreciated.
This means that the old code should, for the most part, continue to work but with a lot of warnings in the console.
If you are a code author you should look over the changelog and your code and update it to use the new API.
Changelog
Class Names
Renamed classes to be more pythonic eg Tag_Compound has been renamed to CompoundTag. The old names sill exist and can be used and will not be depreciated.
String Encoding
Added string encoder and decoder function inputs. String encoding varies between platforms so this needed to be customisable.
Comparison Operators
`a == b` and other comparison operators will only return True if the two objects have the same type.
This was changed to fix key clashing issues in dictionaries and contains issues in containers.
Python Type Mimicing
Previously attempts were made to make the objects behave like the python type but this became inpractical.
As a result lots of methods have been depreciated and will be removed.
To access the python object use py_int, py_float, py_str, py_dict, py_list or np_array.
Note np_array gives the same buffer but the rest are immutable or are copies of the data.
Save methods
All tags now have save_to and to_nbt methods. Previously the NBTFile class was required to use these methods.
Int Tags
Lots of methods have been depreciated.
Float Tags
Lots of methods have been depreciated.
StringTag
- Now stores all data as a string again.
- py_bytes has been removed.
- Custom encoder and decoder is used to encode and decode the string.
- Initialiser does not take bytes as input any more. str(value) is used.
- Lots of methods have been depreciated.
CompoundTag
- Custom encoder and decoder is used to encode and decode the key.
- Added `get_{tag}` and `setdefault_{tag}` typed variants.
ListTag
- Added `get_{tag}` typed variants.
Array Tags
- No longer tries to behave like a numpy array.
- Lots of methods have been depreciated.
NBTFile
- The NBTFile has been renamed to NamedTag. The old name is depreciated.
- An NBTFile could only contain a CompoundTag and had methods to behave like a CompoundTag. These methods have been depreciated.
- In the future the NamedTag will behave like a NamedTuple(name, tag)
- A NamedTag can contain any of the data types. `{type}` methods have been added to make sure the type is as expected.
- value property has been depreciated and replaced with `tag` to be clearer or use `{type}` for a typed variant.
- Added to_nbt method which returns the data encoded in binary format. Like save_to but only returns the bytes.
load
The `load` function has been split into two functions. `load` will continue to handle loading a single NBT structure and `load_many` will handle loading a sequence of structures. This means the return type is indpendent of the inputs.