Package: rsrcfork
A pure Python, cross-platform library/tool for reading Macintosh resource data, as stored in resource forks and.rsrcfiles.Resource forks were an important part of the Classic Mac OS, where they provided a standard way to store structured file data, metadata and application resources. This usage continued into Mac OS X (now called macOS) for backward compatibility, but over time resource forks became less commonly used in favor of simple data fork-only formats, application bundles, and extended attributes.As of OS X 10.8 and the deprecation of the Carbon API, macOS no longer provides any officially supported APIs for using and manipulating resource data. Despite this, parts of macOS still support and use resource forks, for example to store custom file and folder icons set by the user.FeaturesPure Python, cross-platform - no native Mac APIs are used.Provides both a Python API and a command-line tool.Resource data can be read from either the resource fork or the data fork.On Mac systems, the correct fork is selected automatically when reading a file. This allows reading both regular resource forks and resource data stored in data forks (as with.rsrcand similar files).On non-Mac systems, resource forks are not available, so the data fork is always used.Compressed resources (supported by System 7 through Mac OS 9) are automatically decompressed.Only the standard System 7.0 resource compression methods are supported. Resources that use non-standard decompressors cannot be decompressed.Objectreprs are REPL-friendly: all relevant information is displayed, and long data is truncated to avoid filling up the screen by accident.RequirementsPython 3.6 or later. No other libraries are required.Installationrsrcforkis availableon PyPIand can be installed usingpip:python3-mpipinstallrsrcforkAlternatively you can download the source code manually, and run this command in the source code directory to install it:python3-mpipinstall.ExamplesSimple example>>>importrsrcfork>>>rf=rsrcfork.open("/Users/Shared/Test.textClipping")>>>rf<rsrcfork.ResourceFileat0x1046e6048,attributesResourceFileAttrs.0,containing4resourcetypes:[b'utxt',b'utf8',b'TEXT',b'drag']>>>>rf[b"TEXT"]<rsrcfork.ResourceFile._LazyResourceMapat0x10470ed30containingoneresource:rsrcfork.Resource(type=b'TEXT',id=256,name=None,attributes=ResourceAttrs.0,data=b'Here is some text')>Automatic selection of data/resource fork>>>importrsrcfork>>>datarf=rsrcfork.open("/System/Library/Fonts/Monaco.dfont")# Resources in data fork>>>datarf._stream<_io.BufferedReadername='/System/Library/Fonts/Monaco.dfont'>>>>resourcerf=rsrcfork.open("/Users/Shared/Test.textClipping")# Resources in resource fork>>>resourcerf._stream<_io.BufferedReadername='/Users/Shared/Test.textClipping/..namedfork/rsrc'>Command-line interface$python3-mrsrcfork/Users/Shared/Test.textClipping4resourcetypes:'utxt':1resources:(256):34bytes'utf8':1resources:(256):17bytes'TEXT':1resources:(256):17bytes'drag':1resources:(128):64bytes$python3-mrsrcfork/Users/Shared/Test.textClipping"'TEXT' (256)"Resource'TEXT'(256):17bytes:000000004865726520697320736f6d6520746578|Hereissometex|0000001074|t|00000011LimitationsThis library only understands the resource file’s general structure, i. e. the type codes, IDs, attributes, and data of the resources stored in the file. The data of individual resources is provided in raw bytes form and is not processed further - the format of this data is specific to each resource type.Definitions of common resource types can be found inside Carbon and related frameworks in Apple’s macOS SDKs as.rfiles, a format roughly similar to C struct definitions, which is used by theRezandDeRezcommand-line tools to de/compile resource data. There doesn’t seem to be an exact specification of this format, and most documentation on it is only available inside old manuals for MPW (Macintosh Programmer’s Workshop) or similar development tools for old Mac systems. Some macOS text editors, such as BBEdit/TextWrangler and TextMate support syntax highlighting for.rfiles.Writing resource data is not supported at all.Further info on resource filesFor technical info and documentation about resource files and resources, see the“resource forks” section of the mac_file_format_docs repo.ChangelogVersion 1.8.0Removed the old (non-subcommand-based) CLI syntax.Added filtering support to thelistsubcommand.Added aresource-infosubcommand to display technical information about resources (more detailed than what is displayed bylistandread).Added araw-compress-infosubcommand to display technical header information about standalone compressed resource data.Made the library PEP 561-compliant by adding a py.typed file.Fixed an incorrectAssertionErrorwhen using the--no-decompresscommand-line options.Version 1.7.0Added araw-decompresssubcommand to decompress compressed resource data stored in a standalone file rather than as a resource.Optimized lazy loading ofResourceobjects. Previously, resource data would be read from disk whenever aResourceobject was looked up, even if the data itself is never used. Now the resource data is only loaded once thedata(ordata_raw) attribute is accessed.The same optimization applies to thenameattribute, although this is unlikely to make a difference in practice.As a result, it is no longer possible to constructResourceobjects without a resource file. This was previously possible, but had no practical use.Fixed a small error in the'dcmp' (0)decompression implementation.Version 1.6.0Added a new subcommand-based command-line syntax to thersrcforktool, similar to other CLI tools such asgitordiskutil.This subcommand-based syntax is meant to replace the old CLI options, as the subcommand structure is easier to understand and more extensible in the future.Currently there are three subcommands:listto list resources in a file,readto read/display resource data, andread-headerto read a resource file’s header data. These subcommands can be used to perform all operations that were also available with the old CLI syntax.The old CLI syntax is still supported for now, but it will be removed soon.The new syntax no longer supports reading CLI arguments from a file (using@args_file.txt), abbreviating long options (e. g.--no-dinstead of--no-decompress), or the short option-finstead of--fork. If you have a need for any of these features, please open an issue.Version 1.5.0Added stream-based decompression methods to thersrcfork.compressmodule.The internal decompressor implementations have been refactored to use streams.This allows for incremental decompression of compressed resource data. In practice this has no noticeable effect yet, because the mainrsrcforkAPI doesn’t support incremental reading of resource data.Fixed the command line tool always displaying an incorrect error “Cannot specify an explicit fork when reading from stdin” when using-(stdin) as the input file.Version 1.4.0Addedlengthandlength_rawattributes toResource. These attributes are equivalent to thelenofdataanddata_rawrespectively, but may be faster to access.Currently, the only optimized case islengthfor compressed resources, but more optimizations may be added in the future.Added acompressed_infoattribute toResourcethat provides access to the header information of compressed resources.Improved handling of compressed resources when listing resource files with the command line tool.Metadata of compressed resources is now displayed even if no decompressor implementation is available (as long as the compressed data header can be parsed).Performance has been improved - the data no longer needs to be fully decompressed to get its length, this information is now read from the header.The'dcmp'ID used to decompress each resource is displayed.Fixed an incorrectoptions.packagesinsetup.cfg, which made the library unusable except when installing from source using--editable.FixedResourceFile.__enter__returningNone, which made it impossible to useResourceFileproperly in awithstatement.Fixed various minor errors reported by type checking withmypy.Version 1.3.0.post1Fixed an incorrectoptions.packagesinsetup.cfg, which made the library unusable except when installing from source using--editable.Version 1.2.0.post1Fixed an incorrectoptions.packagesinsetup.cfg, which made the library unusable except when installing from source using--editable.Version 1.3.0Added a--groupcommand line option to group resources in list format by type (the default), ID, or with no grouping.Added adump-textoutput format to the command line tool. This format is identical todump, but instead of a hex dump, it outputs the resource data as text. The data is decoded as MacRoman and classic Mac newlines (\r) are translated. This is useful for examining resources that contain mostly plain text.Changed the command line tool to sort resources by type and ID, and added a--no-sortoption to disable sorting and output resources in file order (which was the previous behavior).Renamed thersrcfork.Resourceattributesresource_typeandresource_idtotypeandid, respectively. The old names have been deprecated and will be removed in the future, but are still supported for now.Changed--format=dumpoutput to matchhexdump-C’s format - spacing has been adjusted, and multiple subsequent identical lines are collapsed into a single*.Version 1.2.0Added support for compressed resources.Compressed resource data is automatically decompressed, both in the Python API and on the command line.This is technically a breaking change, since in previous versions the compressed resource data was returned directly. However, this change will not affect end users negatively, unless one has already implemented custom handling for compressed resources.Currently, only the three standard System 7.0 compression formats ('dcmp'IDs 0, 1, 2) are supported. Attempting to access a resource compressed in an unsupported format results in aDecompressError.To access the raw resource data as stored in the file, without automatic decompression, use theres.data_rawattribute (for the Python API), or the--no-decompressoption (for the command-line interface). This can be used to read the resource data in its compressed form, even if the compression format is not supported.Improved automatic data/resource fork selection for files whose resource fork contains invalid data.This fixes reading certain system files with resource data in their data fork (such as HIToolbox.rsrc in HIToolbox.framework, or .dfont fonts) on recent macOS versions (at least macOS 10.14, possibly earlier). Although these files have no resource fork, recent macOS versions will successfully open the resource fork and return garbage data for it. This behavior is now detected and handled by using the data fork instead.Replaced thersrcforkparameter ofrsrcfork.open/ResourceFork.openwith a newforkparameter.forkaccepts string values (like the command line--forkoption) rather thanrsrcfork’s hard to understandNone/True/False.The oldrsrcforkparameter has been deprecated and will be removed in the future, but for now it still works as before.Added an explanatory message when a resource filter on the command line doesn’t match any resources in the resource file. Previously there would either be no output or a confusing error, depending on the selected--format.Changed resource type codes and names to be displayed in MacRoman instead of escaping all non-ASCII characters.Cleaned up the resource descriptions in listings and dumps to improve readability. Previously they included some redundant or unnecessary information - for example, each resource with no attributes set would be explicitly marked as “no attributes”.Unified the formats of resource descriptions in listings and dumps, which were previously slightly different from each other.Improved error messages when attempting to read multiple resources using--format=hexor--format=raw.Fixed reading from non-seekable streams not working for some resource files.Removed theallow_seekparameter ofResourceFork.__init__and the--read-modecommand line option. They are no longer necessary, and were already practically useless before due to non-seekable stream reading being broken.Version 1.1.3.post1Fixed a formatting error in the README.rst to allow upload to PyPI.Version 1.1.3Note: This version is not available on PyPI, see version 1.1.3.post1 changelog for details.Added a setuptools entry point for the command-line interface. This allows calling it using justrsrcforkinstead ofpython3-mrsrcfork.Changed the default value ofResourceFork.__init__’sclosekeyword argument fromTruetoFalse. This matches the behavior of classes likezipfile.ZipFileandtarfile.TarFile.FixedResourceFork.openandResourceFork.__init__not closing their streams in some cases.Refactored the singlersrcfork.pyfile into a package. This is an internal change and should have no effect on how thersrcforkmodule is used.Version 1.1.2Added support for the resource file attributes “Resources Locked” and “Printer Driver MultiFinder Compatible” from ResEdit.Added more dummy constants for resource attributes with unknown meaning, so that resource files containing such attributes can be loaded without errors.Version 1.1.1Fixed overflow issue with empty resource files or empty resource type entriesChanged_hexdumpto behave more likehexdump-CVersion 1.1.0Added a command-line interface - runpython3-mrsrcfork--helpfor more infoVersion 1.0.0Initial version