syntax Package

syntax Package

Utilities relating to low-level NBT syntax.

The package currently consists of a single module, plus a class that used to be a module:

• tags provides object-oriented NBT encoding and decoding.
• ids provides tag ID’s (e.g. ids.TAG_Byte is 1).

class nbtparse.syntax.ids

Bases: enum.IntEnum

Defines various tag ID’s.

Formerly a module, now implemented as a class. This provides various benefits while retaining compatibility and a straightforward interface.

TAG_Byte = <ids.TAG_Byte: 1>

ID of a TAG_Byte

TAG_Byte_Array = <ids.TAG_Byte_Array: 7>

ID of a TAG_Byte_Array

TAG_Compound = <ids.TAG_Compound: 10>

ID of a TAG_Compound

TAG_Double = <ids.TAG_Double: 6>

ID of a TAG_Double

TAG_End = <ids.TAG_End: 0>

ID of a TAG_End

TAG_Float = <ids.TAG_Float: 5>

ID of a TAG_Float

TAG_Int = <ids.TAG_Int: 3>

ID of a TAG_Int

TAG_Int_Array = <ids.TAG_Int_Array: 11>

ID of a TAG_Int_Array

TAG_List = <ids.TAG_List: 9>

ID of a TAG_List

TAG_Long = <ids.TAG_Long: 4>

ID of a TAG_Long

TAG_Short = <ids.TAG_Short: 2>

ID of a TAG_Short

TAG_String = <ids.TAG_String: 8>

ID of a TAG_String

tags Module

Types for the various NBT tags.

Every tag type has a corresponding Pythonic class. Most of these are subclasses of various built-in classes with additional NBT encoding and decoding functionality. Generally speaking, TAG_Foo‘s counterpart will be called FooTag. Most tags are immutable and hashable, and use a values-based definition of equality. They generally mimic the behavior of the corresponding built-in class closely if not actually inheriting from it.

The tags all inherit from AbstractTag, an abstract mixin class. AbstractTag provides some method implementations and a great deal of high-level documentation; if a particular tag’s documentation is unclear, consult AbstractTag as well.

This module will also log the encoding and decoding process via logging; the logger has the same name as the module. Since encoding and decoding are generally very low-level processes, nearly everything is logged at the DEBUG level; some irregularities when decoding are logged at WARNING, and irregularities while encoding will instead generate ordinary warnings (i.e. warnings.warn()). See the logging documentation for instructions on how to access this data or ignore it.

class nbtparse.syntax.tags.AbstractTag

Bases: object

Abstract mixin class for tags.

All NBT tags inherit from AbstractTag.

encode_named(name: str, output: io.BufferedIOBase, errors: str='strict') → int

Encode this tag with a name (e.g. in a TAG_Compound).

Name should be a unicode object, not a string.

errors will be used in encoding the name and payload of this tag.

Note

output.write() must perform any buffering that may be necessary to the underlying I/O; it should write its entire argument, unless something has gone wrong. io.BufferedIOBase and its subclasses satisfy this requirement when in non-interactive mode, but may raise BlockingIOError if in non-blocking mode. If you want to use non-blocking I/O here, consider using asyncio.run_in_executor() to run the blocking I/O on a separate thread or in a separate process.

tag_id

The ID of this tag (e.g. 1 for a TAG_Byte).

class nbtparse.syntax.tags.ByteArrayTag

Bases: nbtparse.syntax.tags.AbstractTag, bytes

Represents a TAG_Byte_Array.

Derives from bytes, and can be used anywhere that bytes would be valid.

Note that this is generally not used to represent text because it lacks encoding information; see StringTag for that.

tag_id

Equal to ids.TAG_Byte_Array.

class nbtparse.syntax.tags.ByteTag(value)

Bases: nbtparse.syntax.tags._IntegralTag

Represents a TAG_Byte.

Acts like a numerical type in every respect except that it doesn’t pass explicit type checks.

tag_id

Equal to ids.TAG_Byte.

class nbtparse.syntax.tags.CompoundTag

Bases: nbtparse.syntax.tags.AbstractTag, dict

Represents a TAG_Compound.

Unlike most other tags, this tag is mutable and unhashable.

Derives from dict and may be used in place of one.

Keys are names, values are tags.

The terminating TAG_End is handled automatically; you do not need to worry about it.

This implementation does not preserve the order of the tags; this is explicitly permitted under the NBT standard.

tag_id

Equal to ids.TAG_Compound.

class nbtparse.syntax.tags.DoubleTag(value)

Bases: nbtparse.syntax.tags._RealTag

Represents a TAG_Double.

Acts like a numerical type in every respect except that it doesn’t pass explicit type checks.

tag_id

Equal to ids.TAG_Double.

class nbtparse.syntax.tags.EndTag

Bases: nbtparse.syntax.tags.AbstractTag

Represents a TAG_End.

EndTags always compare equal to one another, are immutable and hashable, and are considered False by bool(). Subclassing it is probably not a great idea.

For all practical purposes, you can think of EndTag() as the tag equivalent of None.

You probably won’t need this very often; TAG_End mostly only shows up as the terminating sentinel value for TAG_Compound, and CompoundTag handles that automatically. It’s here if you need it, though.

encode_named(name: str, output: io.BufferedIOBase, errors: str='strict') → int

Writes a single null byte to output.

tag_id

Equal to ids.TAG_End.

class nbtparse.syntax.tags.FloatTag(value)

Bases: nbtparse.syntax.tags._RealTag

Represents a TAG_Float.

Acts like a numerical type in every respect except that it doesn’t pass explicit type checks.

tag_id

Equal to ids.TAG_Float.

class nbtparse.syntax.tags.IntArrayTag

Bases: nbtparse.syntax.tags.AbstractTag, list

Represents a TAG_Int_Array.

Unlike most other tags, this tag is mutable and unhashable.

Derives from list and may be used in place of one.

tag_id

Equal to ids.TAG_Int_Array.

class nbtparse.syntax.tags.IntTag(value)

Bases: nbtparse.syntax.tags._IntegralTag

Represents a TAG_Int.

Acts like a numerical type in every respect except that it doesn’t pass explicit type checks.

tag_id

Equal to ids.TAG_Int.

class nbtparse.syntax.tags.ListTag(iterable=None, content_id=None)

Bases: nbtparse.syntax.tags.AbstractTag, list

Represents a TAG_List.

Unlike most other tags, this tag is mutable and unhashable.

instance.content_id identifies the type of the tags listed in this tag. During initialization, ListTag will attempt to guess content_id if it is not provided. If the list is empty, it defaults to None and the list will not be encodable.

content_id

Identifies the tag id of the tags listed in this TAG_List.

Starts at None if the list was initially empty and a content_id was not provided. While this is None, the tag cannot be encoded.

tag_id

Equal to ids.TAG_List.

class nbtparse.syntax.tags.LongTag(value)

Bases: nbtparse.syntax.tags._IntegralTag

Represents a TAG_Long.

Acts like a numerical type in every respect except that it doesn’t pass explicit type checks.

tag_id

Equal to ids.TAG_Long.

class nbtparse.syntax.tags.ShortTag(value)

Bases: nbtparse.syntax.tags._IntegralTag

Represents a TAG_Short.

Acts like a numerical type in every respect except that it doesn’t pass explicit type checks.

tag_id

Equal to ids.TAG_Short.

class nbtparse.syntax.tags.StringTag

Bases: nbtparse.syntax.tags.AbstractTag, str

Represents a TAG_String.

Derives from str and can be used anywhere that str is valid.

tag_id

Equal to ids.TAG_String.

nbtparse.syntax.tags.decode_named(input: io.BufferedIOBase, errors: str='strict')

Decode a named tag from input and returns (name, tag).

Errors will be passed to the Unicode decoder when decoding the name and payload.

Note

input.read() must perform any buffering that may be necessary to the underlying I/O; if it returns less data than was requested, that will be interpreted as EOF. io.BufferedIOBase and its subclasses satisfy this requirement when in non-interactive mode, but may raise BlockingIOError if in non-blocking mode. If you want to use non-blocking I/O here, consider using asyncio.run_in_executor() to run the blocking I/O on a separate thread or in a separate process.

nbtparse.syntax.tags.decode_payload(input, tag_id: int, errors: str='strict') → nbtparse.syntax.tags.AbstractTag

Decode a payload with tag ID tag_id.

Helper function to look up the appropriate class and call its _decode_payload() method.