The new syntax supports the same operations as the old syntax, but is
clearer to understand and more extensible in the future. The old syntax
is still supported for now.
The old names ("system" and "application" compression) were not really
accurate in all cases, so the compression types are now referred to by
their number.
The non-stream-based APIs still exist as before and are not deprecated,
they just act as thin wrappers around the stream-based API.
The main rsrcfork module doesn't use the stream-based APIs yet, because
it reads each resource's data all at once and not incrementally.
This is a little more complex than with the other decompressors,
because .dcmp2 has to behave differently when at the byte before EOF.
Checking whether this is the case requires lookahead, which is not easy
to do with a plain IO stream.
Some buffered IO streams provide a peek method for lookahead, but
others don't (such as io.BytesIO). There is no standard way to wrap an
already buffered IO stream to add a peek method, so we need a custom
wrapper class and helper function for this purpose.
The decompression code is more readable this way, because the
compressed data needs to be processed sequentially. It also allows
moving the length check and some debug logging into an outer generator.
This also allows incremental decompression, but this doesn't have any
practical advantage, because the compressed resource data is all read
at once (there is no API for opening resources as streams), and
resources are not very large anyway.
The leading underscore is meant to distinguish private (for internal
use only) APIs from public (for external use) APIs. One can argue about
where the line between public and private should be, but if something
is used from other modules (as with read_variable_length_integer) it's
not really private IMHO.
In scripts (like __main__) it also doesn't make much sense to use
leading underscores, because the entire file is never meant to be used
by external code.
Previously, the types of instance attributes were annotated with the
first assignment of each attribute. The standard way to annotate
instance attributes is to do so at class level without assigning any
value.
According to https://bugs.python.org/issue35089, typing.io should not
be used anymore, and the types that it contains should be accessed
through the main typing module instead.
For compressed resources, the value of the length attribute can be
accessed much more quickly than the data itself (because it only
requires parsing the header, rather than decompressing the entire
data). This is used to speed up listing of compressed resources on the
command line.
The length_raw attribute is added for symmetry, although it is not
specifically optimized in any case yet.
All decompressors now have exactly the same signature (as a result,
each decompressor now has to check itself that the header type is
correct). This allows the decompressors to be stored in a simple
dictionary, which makes the lookup process much simpler.
In preparation for #3, the compressed resource data headers are parsed
and stored as proper objects. For now these objects are only used
internally by the decompression code, but in the future they can be
exposed.
In most cases the file order is not important and the unsorted output
hurts readability. The performance impact of sorting is relatively
small and barely noticeable even with large resource files.
Previously all non-ASCII characters were hex-escaped on output.
However, many resource files use MacRoman characters in resource names
and sometimes in resource types, so it makes sense to use MacRoman in
the interest of readability.
Previously, when some aspect of a resource's metadata was not present
(e. g. a resource with no name), the description would
explicitly point this out (and e. g. say "unnamed"). Now missing parts
of the metadata are simply omitted from the description, resulting in
cleaner output in many cases.
The resource description formats used by the listings and dumps have
also been unified. Previously the descriptions were structured slightly
differently in each case; this is now no longer the case.
