nbtlib 1.3.0

A python package to read and edit nbt data

nbtlib

A python library to read and edit nbt data. Requires python 3.6.

Features

• Create, read and edit nbt files
• Supports gzipped and uncompressed files
• Supports big-endian and little-endian files
• Parse and serialize raw nbt data
• Define tag schemas that automatically enforce predefined tag types
• Convert nbt between binary form and literal notation
• Includes a CLI to quickly perform read/write/merge operations

Installation

The package can be installed with pip.

$ pip install nbtlib

Basic usage

The following examples will give you a very basic overview of what you can do. For more advanced examples, check out the "Usage" notebook in the docs folder.

Reading files

Reading files can be done directly with the load() function. The root property contains the root nbt tag. Every nbt tag inherits from its python counterpart so you can use all the usual builtin operations on nbt tags.

from nbtlib import nbt

nbt_file = nbt.load('bigtest.nbt')
assert nbt_file.root['intTest'] == 2147483647

Here, we can see that Compound tag instances can be used just like regular python dictionaries, and that checking equality works out of the box.

For more details check out the "Usage" notebook.

Editing files

You can use nbt files as context managers in order to save modifications automatically at the end of the with block.

from nbtlib import nbt
from nbtlib.tag import *

with nbt.load('demo.nbt') as demo:
    demo.root['counter'] = Int(demo.root['counter'] + 1)

You can also use the save() method.

from nbtlib import nbt
from nbtlib.tag import *

demo = nbt.load('demo.nbt')
demo.root['counter'] = Int(demo.root['counter'] + 1)
demo.save()

For more details check out the "Usage" notebook.

Using schemas

A schema lets you create compound tags that enforce a specific tag type for any given key.

from nbtlib import schema
from nbtlib.tag import *

MySchema = schema('MySchema', {
    'foo': String,
    'bar': Short
})

my_object = MySchema({'foo': 'hello world', 'bar': 21})
assert isinstance(my_object['foo'], String)

Nbt literals

nbtlib also defines utilities to deal with literal nbt data. For instance, you can parse nbt literals using the parse_nbt() function.

from nbtlib import parse_nbt
from nbtlib.tag import *

my_compound = parse_nbt('{foo:[hello,world],bar:[I;1,2,3]}')
assert my_compound == Compound({
    'foo': List[String](['hello', 'world']),
    'bar': IntArray([1, 2, 3])
})

Command-line interface

The package comes with a small CLI that makes it easy to quickly perform basic operations on nbt files.

$ nbt --help
usage: nbt [-h] (-r | -w <nbt> | -m <nbt>) [--plain] [--little] <file>

Perform basic operations on nbt files.

positional arguments:
  <file>      the target file

optional arguments:
  -h, --help  show this help message and exit
  -r          read nbt data from a file
  -w <nbt>    write nbt to a file
  -m <nbt>    merge nbt into an nbt file
  --plain     don't use gzip compression
  --little    use little-endian format

Read nbt data

You can read nbt files by using the -r option. This will print the literal notation of the binary nbt data.

$ nbt -r demo.nbt
{counter:42}

You can use the following command if you want to save the output into a file.

$ nbt -r my_file.nbt > my_file.txt

Write nbt data

You can write nbt data to a file by using the -w option. This will convert the literal nbt notation to its binary form and save it in the specified file.

$ nbt -w '{foo:[1,2,3],bar:{hello:[B;1b,1b,0b,1b]}}' my_file.nbt

The file will be created if it doesn't already exist.

Merge nbt data

Finally, you can merge some nbt data into an already existing file by using the -m option. This will recursively update the file with the values parsed from the literal argument.

$ nbt -m '{bar:{"new key":56f}}' my_file.nbt

You can check the result by using the -r option.

$ nbt -r my_file.nbt
{foo:[1,2,3],bar:{hello:[B;1b,1b,0b,1b],"new key":56.0f}}

Here, the compound values that aren't present in the input literal are left untouched. Using the -w option instead of -m would overwrite the whole file.

Compression and byte order

By default, the CLI will assume that you're working with gzipped nbt files. If you want to read, write or merge uncompressed nbt files, you can use the --plain option. Similarly, the default byte order is big-endian so you'll need to use the --little option to perform operations on little-endian files.

Reading

$ nbt -r my_file.nbt --plain --little
{name:"Reading from an uncompressed little-endian file"}

Writing

$ nbt -w '{name:"Writing in an uncompressed little-endian file"}' my_file.nbt --plain --little

Merging

$ nbt -m '{name:"Merging in an uncompressed little-endian file"}' my_file.nbt --plain --little

Contributing

Contributions are welcome. Unit tests are built with pytest. You can run the test suite with tox. First, make sure that tox is installed in your virtual environment.

$ pip install tox

You should now be able to run the tests with tox.

$ tox

---

License - MIT