Incomplete documentation for parsing raw nbt data

[nwesterhausen]

I have raw nbt data for chunks from a region file that I am not sure how to correctly parse using NBTLib. It seems the only way to parse raw nbt is to send a file. It would be better to not create a file for each chunk.

Here is the code I use to parse the region file and create the raw nbt data: https://gist.github.com/nwesterhausen/527fb947d4432c1f40c06dca07cb9253

If I take the output of get_data(0,0) for one of my region files and save it as a binary file, I can open the binary file using NBTLib and it seems to have parsed it correctly (no errors). I think this could be as easy as another entry point besides File or load.

I'd appreciate any thoughts on this.

[nwesterhausen]

I discovered I can use nbtlib.File.from_buffer() and provide an io.BytesIO(rawNbt) as the buffer.

Thanks for this high quality tool 😄

[vberlier]

You're welcome! One point I'd definitely like to improve is the documentation. Right now, I don't feel like the "Usage" notebook is enough. It covers a decent surface of the API. but it's more of a general guide, not an API reference.

For instance, the notebook doesn't mention that every tag type can be parsed from a file-like object and write its nbt data to a file-like object.

>>> foo = Compound({'hello': String('world')})
>>> b = BytesIO()
>>> foo.write(b)
>>> b.getvalue()
b'\x08\x00\x05hello\x00\x05world\x00'
>>> b.seek(0)
0
>>> Compound.parse(b)
Compound({'hello': String('world')})

Because nbt files are really just compound tags, the File class simply inherits the write method and the parse classmethod from the Compound class. That's why the notebook shows the following code example even though the File class doesn't implement parse itself.

with open('nbt_files/hello_world.nbt', 'rb') as f:
    hello_world = File.parse(f)

from_buffer is not properly documented anywhere so I'd recommend using parse instead. There's nothing wrong with the function, it's just that it's used internally by the nbtlib.load function, and is meant to deal more specifically with io.BufferedReader and gzip.GzipFile file objects. I know that some people rely on it, which is kind of unfortunate, but File.parse is the function you're looking for.

[vberlier]

I'm reopening the issue because incomplete documentation is actually kind of a problem.

[nwesterhausen]

Thanks. I've updated my program to use Compound.parse based on what you've said. I had to take into account the empty root tag instead of just using .root but that isn't a big deal. I think it makes sense to use Compound in this case because I'm not opening a file, it's literally the chunk nbt data as a compound.

[vberlier]

The File class is not much more than a compound tag with a .root property and two extra methods: .load(filename, ...) and .save(filename, ...). So yeah, if you don't need to interact with the filesystem, there's nothing wrong with using Compound.parse directly. It's up to you. :+1:

[ch-yx]

Thanks for your code to parse the region file. Do you have code to build/edit region files?

[nwesterhausen]

@ch-yx no, my project was only related to reading the region files.

[Column01]

Any updates on better documentation? Would be very helpful :D

[ch-yx]

The File class is not much more than a compound tag with a .root property and two extra methods: .load(filename, ...) and .save(filename, ...). So yeah, if you don't need to interact with the filesystem, there's nothing wrong with using Compound.parse directly. It's up to you. 👍

For people who don`t know,there is a difference between File and standard Compound. File lacks an END tag at the end.

a typical nbt file { "" : { "actual" : "data" }

The name of the root compound is ignored. minecraft leave it blank in practice.

[vberlier]

There's now a work in progress documentation on github pages https://vberlier.github.io/nbtlib/

I'll try to keep updating it regularly.