Metadata-Version: 2.1
Name: nbtlib
Version: 1.3.2
Summary: A python package to read and edit nbt data
Home-page: https://github.com/vberlier/nbtlib
Author: Valentin Berlier
Author-email: berlier.v@gmail.com
License: MIT
Keywords: nbt schema minecraft package library parser reader module
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy (==1.16.1)

# nbtlib

[![Build Status](https://travis-ci.org/vberlier/nbtlib.svg?branch=master)](https://travis-ci.org/vberlier/nbtlib)
[![PyPI](https://img.shields.io/pypi/v/nbtlib.svg)](https://pypi.org/project/nbtlib/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nbtlib.svg)](https://pypi.org/project/nbtlib/)

> A python library to read and edit [nbt data](http://wiki.vg/NBT). 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`.

```bash
$ 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](https://github.com/vberlier/nbtlib/blob/master/docs/Usage.ipynb)"
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.

```python
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](https://github.com/vberlier/nbtlib/blob/master/docs/Usage.ipynb)"
notebook.

### Editing files

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

```python
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.

```python
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](https://github.com/vberlier/nbtlib/blob/master/docs/Usage.ipynb)"
notebook.

### Using schemas

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

```python
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.

```python
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.

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

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

```bash
$ 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.

```bash
$ 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.

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

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

```bash
$ 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**

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

**Writing**

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

**Merging**

```bash
$ 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.

```bash
$ pip install tox
```

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

```bash
$ tox
```

----

License - [MIT](https://github.com/vberlier/nbtlib/blob/master/LICENSE)


