A python package to read and edit nbt data
Project description
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.