Incomplete documentation for parsing raw nbt data about nbtlib HOT 10 OPEN

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

Thanks for this high quality tool 😄

from nbtlib.

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.

from nbtlib.

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

from nbtlib.

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.

from nbtlib.

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. 👍

from nbtlib.

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

from nbtlib.

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

from nbtlib.

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

from nbtlib.

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.

from nbtlib.

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

I'll try to keep updating it regularly.

from nbtlib.