Metadata-Version: 2.1
Name: nbtlib
Version: 1.3.0
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
Description: # 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)
        
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
