dolor.nbt¶

NBT marshaling.

See https://wiki.vg/NBT for a specification of the format.

class Tag(value=None, *, root_name=None)[source]¶

Bases: abc.ABC

An NBT tag.

Parameters

value (any, optional) – The tag’s value. If unspecified, then the default value will be used.
root_name (str, optional) – The root name of the tag. If specified, then the tag will be treated as a root tag.

id¶

The tag’s id. If None, then the tag will not be used in marshaling.

Type: int or None

type¶

The tag’s underlying type. Used to automatically pack and unpack the raw data of the tag. Must be able to be used without a specified TypeContext.

Type: subclass of Type

value¶

The tag’s value.

Type: any

root_name¶

The tag’s root name. If not None, then the tag will be treated as a root tag.

Type: str or None

classmethod from_id(id)[source]¶

Gets the tag whose id is id.

Will search through the subclasses of Tag, ignoring subclasses whose id attribute is None.

Parameters: id (int) – The id to look for.
Returns: The tag whose id is id.
Return type: subclass of Tag

Examples

>>> import dolor
>>> dolor.nbt.Tag.from_id(0)
<class 'dolor.nbt.End'>

pack()[source]¶

Packs the tag.

Does not include the id. Use dump() for a complete dump.

Returns: The packed tag.
Return type: bytes

classmethod unpack(buf, *, root=False)[source]¶

Unpacks a buffer into a tag.

Does not include the id. Use load() to properly unpack NBT data.

Parameters

buf (file object or bytes or bytearray) – The buffer to unpack.
root (bool, optional) – Whether the tag is a root tag.

Returns

The unpacked tag.

Return type

Tag

class End(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.misc.EmptyType

class Byte(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.numeric.Byte

class Short(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.numeric.Short

class Int(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.numeric.Int

class Long(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.numeric.Long

class Float(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.numeric.Float

class Double(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.numeric.Double

class ByteArray(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.array.Byte[Int]

class String(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.string.String(65535)

class List(tag_or_value=None, *args, **kwargs)[source]¶

Bases: dolor.nbt.Tag

A List tag.

Parameters

tag_or_value (subclass of Tag or list) –
If a subclass of Tag, then a new subclass of List will be generated with its tag attribute set to tag_or_value.

Otherwise, __init__() will continue on as normal.
*args – Forwarded to __init__().
**kwargs – Forwarded to __init__().

tag¶

The tag of the values of this List.

Type: subclass of Tag

value¶

A list of values for tag.

Type: list

class Compound(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

A Compound tag.

value¶

A dictionary whose keys are str objects and whose values are Tag objects.

Type: dict

class IntArray(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.array.Int[Int]

class LongArray(value=None, *, root_name=None)[source]¶

Bases: dolor.nbt.Tag

type¶: alias of dolor.types.array.Long[Int]

load(f)[source]¶

Loads a complete NBT dump into a Tag.

Parameters

f (pathlike or bytes or bytearray or file object) –

If a pathlike, then the path to the file to read from. Otherwise the data to load.

The data may be uncompressed, gzip’d, or zlib’d.

Returns

The loaded tag.

Return type

Tag

Examples

>>> import dolor
>>> dolor.nbt.load(b"\x08\x00\x04test\x00\x0eThis is a test")
String(root_name='test', 'This is a test')

dump(obj, f=None, *, compression=None)[source]¶

Dumps a root tag into a binary dump.

Parameters

obj (Tag) – The root tag to dump.
f (file object, optional) – The file object to dump to. If unspecified, the dumped data will instead be returned.
compression (function or any, optional) –
The compression used to compress the dumped data. If unspecified, the data won’t be compressed.

If a function, then the data will be passed to it and the return value will be treated as the new, compressed data.

Otherwise, the compress attribute of compression will be used as the compression function, allowing you to pass a module like gzip as compression.

Returns

If f is unspecified, then bytes will be returned. Otherwise how many bytes were written to f will be returned.

Return type

bytes or int

Raises

ValueError – If obj is not a root tag.

Examples

>>> import dolor
>>> import gzip
>>> import io
>>> tag = dolor.nbt.String("This is a test", root_name="test")
>>> dolor.nbt.dump(tag)
b'\x08\x00\x04test\x00\x0eThis is a test'
>>> dolor.nbt.dump(tag, compression=gzip) 
b'\x1f\x8b\x08\x00u;\xfa_\x02\xff\xe3``)I-.a\xe0\x0b\xc9\xc8,V\x00\xa2D\x05\x10\x1f\x00(\x9a)|\x17\x00\x00\x00'
>>> f = io.BytesIO()
>>> dolor.nbt.dump(tag, f)
23
>>> f.getvalue()
b'\x08\x00\x04test\x00\x0eThis is a test'