twoolie/NBT — pull request #69 by macfreek (2013-08-29 19:33:41+00:00)
Title: Improvements for nbt.region.RegionFile

After reviewing nbt.region.py, I wrote 65 unit tests, about 50% of them failed. So I more or less ended up writing rewriting RegionFile. This is a summary of all changes. If you think these changes are worthwhile, I'll commit the pull request after my holiday.

The next step is to make some minor changes and verify the documentation and release version 1.4. After that I am likely to changes tabs to spaces. The constant change is too annoying, and of the projects I work on this is the only one that still uses tabs.

### Bug Fixes

* Fixed a bug that corrupted the file when writing a chunk that was between
4093 and 4096 bytes after compression.
* Now possible to write and immediately read chunks in region files.
* Allow increase in region file size.
* Support writing to corrupt region files, working around corrupt parts.
* Replace all `import *` with specific imports.
* Allow trailing slash in world folder in example scripts

### New Features

* Rewrote chunk writing algorithm in nbt.region
* Support reading uncompressed chunks in region files.
* Added detection for overlapping chunks in region files.
* Added RegionFileFormatError exception.
* Allow easy iteration over chunks in a RegionFile:
`for chunk in RegionFile(filename)`
* RegionFile.iter_chunks() now silently ignore unreadable chunks.
* Truncate region file size when possible.
* Add RegionFile.get_chunk_metadata() method.
* Expose more detailed read and write methods in RegionFile: get_blockdata(),
get_nbt(), get_chunk(), write_blockdata(), write_chunk().
* Better display of filenames in NBTFile and RegionFiles when initialised with
a fileobject.

### Backward Incompatible Changes

* RegionFile.get_chunk() raises InconceivedChunk when a chunk does not exist
instead of returning None.
* Exceptions raised while reading chunks are always a RegionFileFormatError or
subclass thereof. GZip, zlib and nbt.MalformedFileError are no longer raised.
* init_header(), parse_header() and parse_chunk_headers() in RegionFile are no
longer public methods.

### Deprecated features

* Constants in nbt.region moved to module level. They are still available in
the class for backwards compatibility.
* `nbt.region.RegionFile.header` and `nbt.region.RegionFile.chunk_headers` are
deprecated in favour of `nbt.region.RegionFile.metadata`. They are still
available for backward compatibility.
* Deprecate `RegionFile.get_chunks()` and `RegionFile.get_chunk_coords()` in
favour of `RegionFile.get_metadata()`.
* RegionFile.get_chunk() method may later be changed to return a Chunk() object.
Use RegionFile.get_nbt() to retain the current behaviour.

### Changes in Auxiliary Scripts

* Automatic testing now also runs example scripts
* Automatic testing now also runs Python 3.3
* Code for automatic documentation generation forked in a seperate package,
sphinxcontrib-restbuilder.
* Automatic testing for Python 2.6 now requires unittest2 package.
* Documented automatic code generation
* Simplified Makefile for documentation generation.