Tags Reference

module

nbtlib.tag

All the tag classes have a Base.parse() classmethod that reads nbt data from a file-like object and returns a tag instance. Tag instances can then write their binary representation back to file-like objects using the Base.write() method.

>>> fileobj = io.BytesIO(b"\x03\x00\x03foo\x00\x00\x00{\x00")
>>> data = Compound.parse(fileobj)
>>> data
Compound({'foo': Int(123)})

>>> fileobj = io.BytesIO()
>>> data.write(fileobj)
>>> fileobj.getvalue()
b'\x03\x00\x03foo\x00\x00\x00{\x00'

Each tag inherits from a closely equivalent python builtin. For instance, the Compound class inherits from the builtin dict type. This means that all the familiar operations available on the base type work out of the box on the derived tag instances.

Base type	Associated nbt tags
int	Byte Short Int Long
float	Float Double
str	String
numpy.ndarray	ByteArray IntArray LongArray
list	List
dict	Compound

Operator overloading works as expected with all tag types. Note that values are returned unwrapped.

>>> data = Compound({"foo": Int(123)})
>>> data["foo"] = Int(-1 * data["foo"])
>>> data["bar"] = String("hello")
>>> data
Compound({'foo': Int(-123), 'bar': String('hello')})

class nbtlib.tag.Base

Base class inherited by all nbt tags.

This class defines the API shared by all nbt tags. Derived classes that define a tag_id attribute are considered as concrete tag implementations and are registered in the all_tags registry. Concrete tag implementations inherit from both the Base class and their associated builtin data type.

all_tags

A dictionnary mapping tag ids to child classes.

>>> pprint(Base.all_tags)
{0: <class 'nbtlib.tag.End'>,
 1: <class 'nbtlib.tag.Byte'>,
 2: <class 'nbtlib.tag.Short'>,
 3: <class 'nbtlib.tag.Int'>,
 4: <class 'nbtlib.tag.Long'>,
 5: <class 'nbtlib.tag.Float'>,
 6: <class 'nbtlib.tag.Double'>,
 7: <class 'nbtlib.tag.ByteArray'>,
 8: <class 'nbtlib.tag.String'>,
 9: <class 'nbtlib.tag.List'>,
 10: <class 'nbtlib.tag.Compound'>,
 11: <class 'nbtlib.tag.IntArray'>,
 12: <class 'nbtlib.tag.LongArray'>}

The mapping is used by the get_tag() classmethod to retrieve the tag type when parsing the binary format.

tag_id

The id of the tag in the binary format.

>>> Int.tag_id
3

serializer

The name of the associated snbt serializer.

>>> Int.serializer
'numeric'

classmethod get_tag(tag_id)

Return the tag class corresponding to the given tag id.

>>> Base.get_tag(3)
<class 'nbtlib.tag.Int'>

Parameters

tag_id – The tag id must be valid otherwise the method raises a KeyError.

classmethod parse(fileobj, byteorder='big')

Parse data from a file-like object and return a tag instance.

The default implementation does nothing. Concrete tags override this method.

Parameters

• fileobj – A readable file-like object.

• byteorder –

  Whether the nbt data is big-endian or little-endian.

  >>> Int.parse(io.BytesIO(b"\x00\x00\x00\x01"))
  Int(1)
  >>> Int.parse(io.BytesIO(b"\x01\x00\x00\x00"), byteorder="little")
  Int(1)
  

write(fileobj, byteorder='big')

Write the binary representation of the tag to a file-like object.

The default implementation does nothing. Concrete tags override this method.

Parameters

• fileobj – A writable file-like object.

• byteorder –

  Whether the nbt data should be big-endian or little-endian.

  >>> big_endian = io.BytesIO()
  >>> little_endian = io.BytesIO()
  >>> Int(1).write(big_endian)
  >>> Int(1).write(little_endian, byteorder="little")
  >>> big_endian.getvalue()
  b'\x00\x00\x00\x01'
  >>> little_endian.getvalue()
  b'\x01\x00\x00\x00'
  

match(other)

Check whether the tag recursively matches a subset of values.

The default implementation checks that the tag_id of the argument matches and that the two instances are equal. Concrete tags override this method.

>>> data = Compound({
...     'foo': Int(42),
...     'hello': String('world')
... })
>>> data.match({'foo': 42})
True

snbt(indent=None, compact=False, quote=None)

Return the snbt literal corresponding to the tag instance.

>>> Compound({"foo": Long(123)}).snbt()
'{foo: 123L}'
>>> Compound({"foo": Long(123)}).snbt(compact=True)
'{foo:123L}'
>>> print(Compound({"foo": Long(123)}).snbt(indent=4))
{
    foo: 123L
}

unpack(json=False)

Return the unpacked nbt value as an instance of the associated base type.

>>> Compound({"foo": Long(123)}).unpack()
{'foo': 123}

Parameters

json –

Whether the returned value should be json-serializable.

This argument will convert array tags into plain python lists instead of numpy arrays.

>>> Compound({"foo": ByteArray([1, 2, 3])}).unpack()
{'foo': array([1, 2, 3], dtype=int8)}
>>> Compound({"foo": ByteArray([1, 2, 3])}).unpack(json=True)
{'foo': [1, 2, 3]}

class nbtlib.tag.Numeric

Intermediate class that represents a numeric nbt tag.

This class inherits from the Base class and implements parse() and write() for all the numeric nbt tags using the fmt attribute.

Derived tags will use the numeric serializer and can specify a literal suffix with the suffix attribute.

fmt

The struct format used to pack and unpack the tag value.

>>> Int.fmt['big'].pack(1)
b'\x00\x00\x00\x01'
>>> Int.fmt['little'].pack(1)
b'\x01\x00\x00\x00'

suffix

The suffix used by the numeric snbt serializer.

>>> Long.suffix
'L'
>>> Long(123).snbt()
'123L'

classmethod parse(fileobj, byteorder='big')

Override Base.parse() for numeric tags.

write(fileobj, byteorder='big')

Override Base.write() for numeric tags.

class nbtlib.tag.NumericInteger(*args, **kwargs)

Intermediate class that represents a numeric integer nbt tag.

This class adds range checks to the Numeric class. It also inherits from int and raises an OutOfRange exception when the tag is instantiated with a value that can’t be represented by the associated struct format.

>>> Byte(127)
Byte(127)
>>> Byte(128)
Traceback (most recent call last):
...
nbtlib.tag.OutOfRange: Byte(128) is out of range

Concrete tag implementations deriving from this class also inherit utilities for interpreting the value of the tag as an unsigned integer.

>>> value = Byte.from_unsigned(255)
>>> value
Byte(-1)
>>> value.as_unsigned
255

range

The supported range of values.

>>> Byte.range
range(-128, 128)
>>> Int.range
range(-2147483648, 2147483648)

mask

The bit mask derived from the struct format.

>>> f'{Byte.mask:b}'
'11111111'

bits

The bit length derived from the struct format.

>>> Int.bits
32
>>> Long.bits
64

unpack(json=False)

Override Base.unpack() for numeric integer tags.

property as_unsigned

Interpret the value of the tag as an unsigned integer.

classmethod from_unsigned(value)

Encode an unsigned integer as an integer tag.

class nbtlib.tag.Byte(*args, **kwargs)

Nbt tag representing a signed byte.

class nbtlib.tag.Short(*args, **kwargs)

Nbt tag representing a signed 16 bit integer.

class nbtlib.tag.Int(*args, **kwargs)

Nbt tag representing a signed 32 bit integer.

class nbtlib.tag.Long(*args, **kwargs)

Nbt tag representing a signed 64 bit integer.

class nbtlib.tag.Float(x=0, /)

Nbt tag representing a single-precision floating point number.

unpack(json=False)

Override Base.unpack() for float tags.

class nbtlib.tag.Double(x=0, /)

Nbt tag representing a double-precision floating point number.

unpack(json=False)

Override Base.unpack() for double tags.

class nbtlib.tag.String

Nbt tag representing a string.

classmethod parse(fileobj, byteorder='big')

Override Base.parse() for string tags.

write(fileobj, byteorder='big')

Override Base.write() for string tags.

unpack(json=False)

Override Base.unpack() for string tags.

class nbtlib.tag.List(iterable=())

Nbt tag representing a list of other nbt tags.

Nbt lists are homogeneous and can only hold a single type of tag. This constraint is enforced by requiring the List class to be subclassed and define an appropriate subtype attribute. The class_getitem operator is defined so that List[TagName] returns a subclass with the subtype TagName.

>>> List[Int]
<class 'nbtlib.tag.List[Int]'>
>>> List[Int].subtype
<class 'nbtlib.tag.Int'>

The base class constructor returns an instance of the appropriate subtype if it can infer the subtype from the elements of the given iterable. Check out infer_list_subtype() for details.

>>> List([Int(123)])
List[Int]([Int(123)])

The class inherits from the Base class and the list builtin. The inherited mutating operations are overridden to include an isinstance check. For example, the append() method will raise an IncompatibleItemType exception if the list subtype doesn’t match the item type.

>>> strings = List[String]()
>>> strings.append(Int(123))
Traceback (most recent call last):
...
nbtlib.tag.IncompatibleItemType: Int(123) should be a String tag

To make things a bit more ergonomic, arbitrary python objects are transparently converted to the list subtype.

>>> strings.append(String("foo"))
>>> strings.append("bar")
>>> strings
List[String]([String('foo'), String('bar')])

However, note that impossible conversions raise a CastError.

>>> List[Int](["foo"])
Traceback (most recent call last):
...
nbtlib.tag.CastError: Couldn't cast 'foo' to Int

Finally, list tags support path indexing. Check out the path documentation for more details.

>>> compounds = List([
...     Compound({"foo": Int(123)}),
...     Compound({"foo": Int(456)}),
... ])
>>> compounds[Path("[{foo: 456}]")]
Compound({'foo': Int(456)})

subtype

alias of nbtlib.tag.End

static infer_list_subtype(items)

Infer a list subtype from a list of items.

>>> List.infer_list_subtype([Int(123)])
<class 'nbtlib.tag.Int'>

This method is used by the base List constructor to figure out the subtype of the List subclass that should be returned.

Parameters

items –

Can be any kind of iterable containing at least one tag instance and zero or more python objects convertible to the type of the tag instance.

>>> List.infer_list_subtype([123, Int(456)])
<class 'nbtlib.tag.Int'>

classmethod parse(fileobj, byteorder='big')

Override Base.parse() for list tags.

write(fileobj, byteorder='big')

Override Base.write() for list tags.

match(other)

Override Base.match() for list tags.

The method returns True if all the elements the iterable appear at least once in the current instance.

>>> List[Int]([1, 2, 3]).match([3, 1])
True

unpack(json=False)

Override Base.unpack() for list tags.

find(key, default=None)

Return the first recursively matching tag.

>>> tag = parse_nbt("[{data: {value: 42}}, {data: {value: 7}}]")
>>> tag.find(Path("data.value"))
Int(42)
>>> tag.find("value")
Int(42)

Parameters

• index – Can be a string, an integer, a slice or an instance of nbtlib.path.Path.

• default – Returned when the element could not be found.

get(index, default=None)

Return the element at the specified index.

Parameters

• index – Can be an integer, a slice or an instance of nbtlib.path.Path.

• default – Returned when the element could not be found.

get_all(index)

Return all the elements matching the specified index.

Parameters

index – Can be an integer, a slice or an instance of nbtlib.path.Path.

append(value)

Override list.append to include isinstance check and auto conversion.

extend(iterable)

Override list.extend to include isinstance check and auto conversion.

insert(index, value)

Override list.insert to include isinstance check and auto conversion.

classmethod cast_item(item)

Cast list item to the appropriate tag type.

>>> List[Int].cast_item(123)
Int(123)

Parameters

item – Can be any object convertible to the current tag type. If the conversion fails, the method raises a CastError.

class nbtlib.tag.Compound

Nbt tag that represents a mapping of strings to other nbt tags.

The class inherits from the Base class and the dict builtin. Compound tag instances support path indexing. Check out the path documentation for more details.

>>> compound = Compound({'foo': Compound({'bar': Int(123)})})
>>> compound[Path("foo.bar")]
Int(123)

end_tag

Bytes used to mark the end of the compound.

classmethod parse(fileobj, byteorder='big')

Override Base.parse() for compound tags.

write(fileobj, byteorder='big')

Override Base.write() for compound tags.

match(other)

Override Base.match() for compound tags.

The method returns True if each key-value pair in the dictionnary is present in the current instance.

>>> compound = Compound({"foo": Int(123), "bar": Int(456)})
>>> compound.match({"foo": Int(123)})
True

unpack(json=False)

Override Base.unpack() for compound tags.

find(key, default=None)

Return the first recursively matching tag.

>>> tag = parse_nbt("{foo: {bar: [{value: 42}, {value: 7}]}}")
>>> tag.find(Path("[1].value"))
Int(7)
>>> tag.find("value")
Int(42)

Parameters

• index – Can be a string, an integer, a slice or an instance of nbtlib.path.Path.

• default – Returned when the element could not be found.

get(key, default=None)

Get the element with the specified key.

Parameters

• key – Can be a string or an instance of nbtlib.path.Path.

• default – Returned when the element could not be found.

get_all(key)

Return all the elements matching the specified key.

Parameters

index – Can be a string or an instance of nbtlib.path.Path.

merge(other)

Recursively merge tags from another dictionnary.

>>> compound = Compound({
...     "value": Compound({"foo": Int(123), "bar": Int(456)}),
... })
>>> compound.merge({
...     "value": {"bar": Int(-1), "hello": String("world")},
... })
>>> compound["value"]
Compound({'foo': Int(123), 'bar': Int(-1), 'hello': String('world')})

Parameters

other – Can be a builtin dict or an instance of Compound.

with_defaults(other)

Return a new compound with recursively applied default values.

>>> compound = Compound({
...     "value": Compound({"foo": Int(123), "bar": Int(456)}),
... })
>>> new_compound = compound.with_defaults({
...     "value": {"bar": Int(-1), "hello": String("world")},
... })
>>> new_compound["value"]
Compound({'bar': Int(456), 'hello': String('world'), 'foo': Int(123)})

Parameters

other – Can be a builtin dict or an instance of Compound.

class nbtlib.tag.End(*args, **kwargs)

Nbt tag used to mark the end of compound tags.

End tags are the markers that terminate compound tags in the binary format. They need to exist as a type but can’t be used on their own so manual instantiation raises an EndInstantiation exception.

>>> End()
Traceback (most recent call last):
...
nbtlib.tag.EndInstantiation: End tags can't be instantiated

class nbtlib.tag.Array(value=None, *, length=0, byteorder='big')

Intermediate class that represents an array nbt tag.

Array tags are represented by numpy arrays. This class combines the Base class with the numpy ndarray type and implements parse() and write() depending on a few additional attributes.

Derived tags will use the array serializer and can specify an array prefix with the array_prefix attribute.

item_type

The numpy array data type.

>>> IntArray.item_type['big']
dtype('>i4')
>>> IntArray.item_type['little']
dtype('int32')

array_prefix

The literal array prefix.

>>> IntArray.array_prefix
'I'
>>> IntArray([1, 2, 3]).snbt()
'[I; 1, 2, 3]'

wrapper

The tag used to wrap the integer.

>>> IntArray.wrapper
<class 'nbtlib.tag.Int'>
>>> IntArray([1, 2, 3])[0]
Int(1)

classmethod parse(fileobj, byteorder='big')

Override Base.parse() for array tags.

write(fileobj, byteorder='big')

Override Base.write() for array tags.

unpack(json=False)

Override Base.unpack() for array tags.

class nbtlib.tag.ByteArray(value=None, *, length=0, byteorder='big')

Nbt tag representing an array of signed bytes.

wrapper

alias of nbtlib.tag.Byte

class nbtlib.tag.IntArray(value=None, *, length=0, byteorder='big')

Nbt tag representing an array of signed 32 bit integers.

wrapper

alias of nbtlib.tag.Int

class nbtlib.tag.LongArray(value=None, *, length=0, byteorder='big')

Nbt tag representing an array of signed 64 bit integers.

wrapper

alias of nbtlib.tag.Long

exception nbtlib.tag.EndInstantiation

Raised when trying to instantiate an End tag.

exception nbtlib.tag.OutOfRange(value)

Raised when a numeric value is out of range.

Converting builtin int instances to numeric nbt tags can fail if the tag type isn’t big enough.

>>> Byte(127)
Byte(127)
>>> Byte(128)
Traceback (most recent call last):
...
nbtlib.tag.OutOfRange: Byte(128) is out of range

exception nbtlib.tag.IncompatibleItemType(item, subtype)

Raised when a list item is incompatible with the subtype of the list.

Unlike builtin python lists, list tags are homogeneous so adding an incompatible item to the list raises an error.

>>> List([String("foo"), Int(123)])
Traceback (most recent call last):
...
nbtlib.tag.IncompatibleItemType: Int(123) should be a String tag

exception nbtlib.tag.CastError(obj, tag_type)

Raised when an object couldn’t be converted to the appropriate tag type.

Casting occurs when adding items to list tags and nbt schema instances. If the item couldn’t be converted to the required type, the conversion raises an error.

>>> integers = List[Int]()
>>> integers.append("foo")
Traceback (most recent call last):
...
nbtlib.tag.CastError: Couldn't cast 'foo' to Int

Note that casting only occurs when the value is an unwrapped python object. Incompatible tags will raise an IncompatibleItemType exception.

>>> strings = List[String]()
>>> strings.append(123)
>>> strings
List[String]([String('123')])
>>> strings.append(Int(123))
Traceback (most recent call last):
...
nbtlib.tag.IncompatibleItemType: Int(123) should be a String tag