Region

nbt.region Module

Handle a region file, containing 32x32 chunks. For more info of the region file format look: http://www.minecraftwiki.net/wiki/Region_file_format

nbt.region.SECTOR_LENGTH = 4096

Constant indicating the length of a sector. A Region file is divided in sectors of 4096 bytes each.

nbt.region.STATUS_CHUNK_OVERLAPPING = -5

Constant indicating an error status: the chunk is allocated to a sector already occupied by another chunk

nbt.region.STATUS_CHUNK_MISMATCHED_LENGTHS = -4

Constant indicating an error status: the region header length and the chunk length are incompatible

nbt.region.STATUS_CHUNK_ZERO_LENGTH = -3

Constant indicating an error status: chunk header has a 0 length

nbt.region.STATUS_CHUNK_IN_HEADER = -2

Constant indicating an error status: chunk inside the header of the region file

nbt.region.STATUS_CHUNK_OUT_OF_FILE = -1

Constant indicating an error status: chunk partially/completely outside of file

nbt.region.STATUS_CHUNK_OK = 0

Constant indicating an normal status: the chunk exists and the metadata is valid

nbt.region.STATUS_CHUNK_NOT_CREATED = 1

Constant indicating an normal status: the chunk does not exist

nbt.region.COMPRESSION_NONE = 0

Constant indicating that the chunk is not compressed.

nbt.region.COMPRESSION_GZIP = 1

Constant indicating that the chunk is GZip compressed.

nbt.region.COMPRESSION_ZLIB = 2

Constant indicating that the chunk is zlib compressed.

exception nbt.region.RegionFileFormatError(msg='')

Bases: Exception

Base class for all file format errors. Note: InconceivedChunk is not a child class, because it is not considered a format error.

__init__(msg='')

Initialize self. See help(type(self)) for accurate signature.

__str__()

Return str(self).

exception nbt.region.NoRegionHeader(msg='')

Bases: nbt.region.RegionFileFormatError

The size of the region file is too small to contain a header.

exception nbt.region.RegionHeaderError(msg='')

Bases: nbt.region.RegionFileFormatError

Error in the header of the region file for a given chunk.

exception nbt.region.ChunkHeaderError(msg='')

Bases: nbt.region.RegionFileFormatError

Error in the header of a chunk, included the bytes of length and byte version.

exception nbt.region.ChunkDataError(msg='')

Bases: nbt.region.RegionFileFormatError

Error in the data of a chunk.

exception nbt.region.InconceivedChunk(msg='')

Bases: LookupError

Specified chunk has not yet been generated.

__init__(msg='')

Initialize self. See help(type(self)) for accurate signature.

class nbt.region.ChunkMetadata(x, z)

Bases: object

Metadata for a particular chunk found in the 8 kiByte header and 5-byte chunk header.

__init__(x, z)

Initialize self. See help(type(self)) for accurate signature.

x = None

x-coordinate of the chunk in the file

z = None

z-coordinate of the chunk in the file

blockstart = None

start of the chunk block, counted in 4 kiByte sectors from the start of the file. (24 bit int)

blocklength = None

amount of 4 kiBytes sectors in the block (8 bit int)

timestamp = None

a Unix timestamps (seconds since epoch) (32 bits), found in the second sector in the file.

length = None

length of the block in bytes. This excludes the 4-byte length header, and includes the 1-byte compression byte. (32 bit int)

compression = None

type of compression used for the chunk block. (8 bit int).

• 0: uncompressed
• 1: gzip compression
• 2: zlib compression

status = None

status as determined from blockstart, blocklength, length, file size and location of other chunks in the file.

• STATUS_CHUNK_OVERLAPPING
• STATUS_CHUNK_MISMATCHED_LENGTHS
• STATUS_CHUNK_ZERO_LENGTH
• STATUS_CHUNK_IN_HEADER
• STATUS_CHUNK_OUT_OF_FILE
• STATUS_CHUNK_OK
• STATUS_CHUNK_NOT_CREATED

__str__()

Return str(self).

__repr__()

Return repr(self).

requiredblocks()

is_created()

return True if this chunk is created according to the header. This includes chunks which are not readable for other reasons.

class nbt.region.Location(x=None, y=None, z=None)

Bases: object

__init__(x=None, y=None, z=None)

Initialize self. See help(type(self)) for accurate signature.

__str__()

Return str(self).

class nbt.region.RegionFile(filename=None, fileobj=None)

Bases: object

A convenience class for extracting NBT files from the Minecraft Beta Region Format.

STATUS_CHUNK_OVERLAPPING = -5

Constant indicating an error status: the chunk is allocated to a sector already occupied by another chunk. Deprecated. Use nbt.region.STATUS_CHUNK_OVERLAPPING instead.

STATUS_CHUNK_MISMATCHED_LENGTHS = -4

Constant indicating an error status: the region header length and the chunk length are incompatible. Deprecated. Use nbt.region.STATUS_CHUNK_MISMATCHED_LENGTHS instead.

STATUS_CHUNK_ZERO_LENGTH = -3

Constant indicating an error status: chunk header has a 0 length. Deprecated. Use nbt.region.STATUS_CHUNK_ZERO_LENGTH instead.

STATUS_CHUNK_IN_HEADER = -2

Constant indicating an error status: chunk inside the header of the region file. Deprecated. Use nbt.region.STATUS_CHUNK_IN_HEADER instead.

STATUS_CHUNK_OUT_OF_FILE = -1

Constant indicating an error status: chunk partially/completely outside of file. Deprecated. Use nbt.region.STATUS_CHUNK_OUT_OF_FILE instead.

STATUS_CHUNK_OK = 0

Constant indicating an normal status: the chunk exists and the metadata is valid. Deprecated. Use nbt.region.STATUS_CHUNK_OK instead.

STATUS_CHUNK_NOT_CREATED = 1

Constant indicating an normal status: the chunk does not exist. Deprecated. Use nbt.region.STATUS_CHUNK_NOT_CREATED instead.

__init__(filename=None, fileobj=None)

Read a region file by filename or file object. If a fileobj is specified, it is not closed after use; it is the callers responibility to close it.

metadata = None

dict containing ChunkMetadata objects, gathered from metadata found in the 8 kiByte header and 5-byte chunk header.

metadata[x, z]: ChunkMetadata()

header = None

dict containing the metadata found in the 8 kiByte header:

header[x, z]: (offset, sectionlength, timestamp, status)

Offset:	counts in 4 kiByte sectors, starting from the start of the file. (24 bit int)
Blocklength:	is in 4 kiByte sectors (8 bit int)
Timestamp:	is a Unix timestamps (seconds since epoch) (32 bits)
Status:	can be any of: STATUS_CHUNK_OVERLAPPING STATUS_CHUNK_MISMATCHED_LENGTHS STATUS_CHUNK_ZERO_LENGTH STATUS_CHUNK_IN_HEADER STATUS_CHUNK_OUT_OF_FILE STATUS_CHUNK_OK STATUS_CHUNK_NOT_CREATED

Deprecated. Use metadata instead.

chunk_headers = None

dict containing the metadata found in each chunk block:

chunk_headers[x, z]: (length, compression, chunk_status)

Chunk length:	in bytes, starting from the compression byte (32 bit int)
Compression:	is 1 (Gzip) or 2 (bzip) (8 bit int)
Chunk_status:	is equal to status in header.

If the chunk is not defined, the tuple is (None, None, STATUS_CHUNK_NOT_CREATED)

Deprecated. Use metadata instead.

loc = None

Optional: x,z location of a region within a world.

get_size()

Returns the file size in bytes.

close()

Clean up resources after use.

Note that the instance is no longer readable nor writable after calling close(). The method is automatically called by garbage collectors, but made public to allow explicit cleanup.

get_metadata()

Return a list of the metadata of each chunk that is defined in te regionfile. This includes chunks which may not be readable for whatever reason, but excludes chunks that are not yet defined.

get_chunks()

Return the x,z coordinates and length of the chunks that are defined in te regionfile. This includes chunks which may not be readable for whatever reason.

Warning: despite the name, this function does not actually return the chunk, but merely it’s metadata. Use get_chunk(x,z) to get the NBTFile, and then Chunk() to get the actual chunk.

This method is deprecated. Use get_metadata() instead.

get_chunk_coords()

Return the x,z coordinates and length of the chunks that are defined in te regionfile. This includes chunks which may not be readable for whatever reason.

This method is deprecated. Use get_metadata() instead.

iter_chunks()

Yield each readable chunk present in the region. Chunks that can not be read for whatever reason are silently skipped. Warning: this function returns a nbt.nbt.NBTFile object, use Chunk(nbtfile) to get a nbt.chunk.Chunk instance.

__iter__()

get_timestamp(x, z)

Return the timestamp of when this region file was last modified.

Note that this returns the timestamp as-is. A timestamp may exist, while the chunk does not, or it may return a timestamp of 0 even while the chunk exists.

To convert to an actual date, use datetime.fromtimestamp().

chunk_count()

Return the number of defined chunks. This includes potentially corrupt chunks.

get_blockdata(x, z)

Return the decompressed binary data representing a chunk.

May raise a RegionFileFormatError(). If decompression of the data succeeds, all available data is returned, even if it is shorter than what is specified in the header (e.g. in case of a truncated while and non-compressed data).

get_nbt(x, z)

Return a NBTFile of the specified chunk. Raise InconceivedChunk if the chunk is not included in the file.

get_chunk(x, z)

Return a NBTFile of the specified chunk. Raise InconceivedChunk if the chunk is not included in the file.

Note: this function may be changed later to return a Chunk() rather than a NBTFile() object. To keep the old functionality, use get_nbt().

write_blockdata(x, z, data, compression=2)

Compress the data, write it to file, and add pointers in the header so it can be found as chunk(x,z).

write_chunk(x, z, nbt_file)

Pack the NBT file as binary data, and write to file in a compressed format.

unlink_chunk(x, z)

Remove a chunk from the header of the region file. Fragmentation is not a problem, chunks are written to free sectors when possible.

__str__()

Return str(self).

__repr__()

Return repr(self).