Loading and Editing Files¶

module

The library supports reading and writing nbt data in all its forms and treats everything as uncompressed big-endian nbt by default.

You can load nbt files with the load() function.

>>> nbtlib.load("docs/hello_world.nbt")
<File 'hello world': Compound({...})>

The function will figure out by itself if the file is gzipped before loading it. You can set the byteorder parameter to "little" if the file is little-endian.

>>> nbtlib.load("docs/hello_world_little.nbt", byteorder="little")
<File 'hello world': Compound({...})>

You can create new nbt files by instantiating the File class with the desired nbt data and calling the File.save() method.

>>> nbt_file = nbtlib.File({"demo": Compound({"counter": Int(0)})})
>>> nbt_file.save("docs/demo.nbt")
>>> nbtlib.load("docs/demo.nbt")
<File 'demo': Compound({'counter': Int(0)})>

The File.save() method can output gzipped or little-endian nbt by using the gzipped and byteorder arguments respectively.

>>> demo = nbtlib.load("docs/demo.nbt")

>>> # overwrite
>>> demo.save()

>>> # make a gzipped copy
>>> demo.save("docs/demo_copy.nbt", gzipped=True)

>>> # convert the file to little-endian
>>> demo.save("docs/demo_little.nbt", byteorder="little")

nbtlib.nbt.load(filename, *, gzipped=None, byteorder='big')¶

Load the nbt file at the specified location.

>>> nbt_file = nbtlib.load("docs/bigtest.nbt")
>>> nbt_file["stringTest"]
String('HELLO WORLD THIS IS A TEST STRING ÅÄÖ!')

The function returns an instance of the dict-like File class holding all the data that could be parsed from the binary file. You can retrieve items with the index operator just like with regular python dictionaries.

Note that the File instance can be used as a context manager. The File.save() method is called automatically at the end of the with statement.

>>> with nbtlib.load("docs/demo.nbt") as demo:
...     demo["counter"] = nbtlib.Int(demo["counter"] + 1)

Parameters

gzipped –
Whether the file is gzipped or not.

If the argument is not specified, the function will read the magic number of the file to figure out if the file is gzipped.
```
>>> filename = "docs/hello_world.nbt"
>>> nbt_file = nbtlib.load(filename, gzipped=False)
>>> nbt_file.gzipped
False
```
The function simply delegates to File.load() when the argument is specified explicitly.
byteorder –
Whether the file is big-endian or little-endian.

The default value is "big" so files are interpreted as big-endian if the argument is not specified. You can set the argument to "little" to handle little-endian nbt data.
```
>>> filename = "docs/hello_world_little.nbt"
>>> nbt_file = nbtlib.load(filename, byteorder="little")
>>> nbt_file.byteorder
'little'
```

class nbtlib.nbt.File(*args, gzipped=False, byteorder='big', filename=None, root_name='')¶

Class representing a compound nbt file.

>>> nbt_file = nbtlib.File({
...     "Data": nbtlib.Compound({
...         "hello": nbtlib.String("world")
...    })
... })

The class inherits from Compound, so all the builtin dict operations inherited by the nbtlib.tag.Compound class are also available on File instances.

>>> nbt_file.items()
dict_items([('Data', Compound({'hello': String('world')}))])
>>> nbt_file["Data"]
Compound({'hello': String('world')})

You can write nbt data to an already opened file-like object with the inherited nbtlib.tag.Compound.write() method.

>>> fileobj = io.BytesIO()
>>> nbt_file.write(fileobj)
>>> fileobj.getvalue()
b'\n\x00\x04Data\x08\x00\x05hello\x00\x05world\x00'

If you need to load files from an already opened file-like object, you can use the inherited nbtlib.tag.Compound.parse() classmethod.

>>> fileobj.seek(0)
0
>>> nbtlib.File.parse(fileobj) == nbt_file
True

filename¶

The name of the file, None by default. The attribute is set automatically when the file is returned from the load() helper function and can also be set in the constructor.

>>> nbt_file.filename is None
True
>>> nbtlib.load("docs/demo.nbt").filename
'docs/demo.nbt'

gzipped¶

Boolean indicating if the file is gzipped. The attribute can also be set in the constructor. New files are uncompressed by default.

>>> nbtlib.File(nbt_file, gzipped=True).gzipped
True

byteorder¶

The byte order, either "big" or "little". The attribute can also be set in the constructor. New files are big-endian by default.

>>> nbtlib.File(nbt_file, byteorder="little").byteorder
'little'

classmethod parse(fileobj, byteorder='big')¶: Override nbtlib.tag.Base.parse() for nbt files.

write(fileobj, byteorder='big')¶: Override nbtlib.tag.Base.write() for nbt files.

classmethod from_fileobj(fileobj, byteorder='big')¶

Load an nbt file from a proper file object.

The method is used by the load() helper function when the gzipped keyword-only argument is not specified explicitly.

Parameters

fileobj – Can be either a standard io.BufferedReader for uncompressed nbt or a gzip.GzipFile for gzipped nbt data. The function simply calls the inherited nbtlib.tag.Compound.parse() classmethod and sets the filename and gzipped attributes depending on the argument.
byteorder – Can be either "big" or "little". The argument is forwarded to nbtlib.tag.Compound.parse().

classmethod load(filename, gzipped, byteorder='big')¶

Read, parse and return the nbt file at the specified location.

The method is used by the load() helper function when the gzipped keyword-only argument is specified explicitly. The function opens the file and uses from_fileobj() to return the File instance.

Parameters

filename – The name of the file.
gzipped – Whether the file is gzipped or not.
byteorder – Can be either "big" or "little".

save(filename=None, *, gzipped=None, byteorder=None)¶

Write the file at the specified location.

The method is called without any argument at the end of with statements when the File instance is used as a context manager.

>>> with demo:
...     demo['counter'] = nbtlib.Int(0)

This essentially overwrites the file at the end of the with statement.

Parameters

filename – The name of the file. Defaults to the instance’s filename attribute.
gzipped – Whether the file should be gzipped. Defaults to the instance’s gzipped attribute.
byteorder – Whether the file should be big-endian or little-endian. Defaults to the instance’s byteorder attribute.