ds_store - Manipulate Finder .DS_Store files from Python¶
This document refers to version 1.3.1
What is this?¶
Historically the Mac OS Finder stored additional per-file information in a special Finder Info field in the HFS/HFS+ filesystem. It also held other information in a single file known as the Desktop Database.
Filesystems other than HFS obviously do not have the Finder Info structure,
and until recently support for extended attributes was rare. As a result, the
Mac OS X Finder was written to store the necessary information in hidden files
named .DS_Store, which it places into every directory where it needs to
store information.
The format of these files is, sadly, not documented by Apple. This is a pain
for software developers, who often distribute their software in Apple Disk
Image (or .dmg) files. Typically developers set an attractive background
on their disk images, increase the icon size and font size and often include a
link to the /Applications folder. Unfortunately, the only supported way
to set many of these things is via Finder itself. You might think that you
could drive Finder with AppleScript for this purpose, but this turns out to be
unreliable (Finder may not save the changes to the .DS_Store file
immediately), and worse still Apple has made changes to the information Finder
uses between versions of Mac OS X, such that setting some of these things on
newer versions of the OS X Finder will not set them for users of older
versions.
This module allows programmatic access to and construction of .DS_Store
files directly from Python, with no Mac OS X specific code involved.
Usage¶
Typical usage looks like this:
from ds_store import DSStore
with DSStore.open('/Users/alastair/.DS_Store', 'r+') as d:
# Position the icon for "foo.txt" at (128, 128)
d['foo.txt']['Iloc'] = (128, 128)
# Display the plists for this folder
print d['.']['bwsp']
print d['.']['icvp']
Importantly, deleting the DSStore object is not
sufficient to flush changes to disk. If you use the with syntax above,
changes you make to the .DS_Store file will automatically be persisted.
Otherwise, you will need to call flush()
or close() to flush your changes to disk.
Note that Finder generally places information about folders in the containing folder. The exception is that if it cannot write to the containing folder, or the folder in question is at the root of a volume, Finder will put the information in a record for “.” inside the folder to which it applies.
ds_store currently knows how to decode the following items
Code |
Type |
Python representation |
|---|---|---|
|
|
|
|
|
Property list ( |
|
|
Property list ( |
|
|
Property list ( |
|
|
Property list ( |
Items not in the list above will be returned as (type, value) tuples.
Supported type values are
Type |
Python representation |
|---|---|
|
Boolean ( |
|
Integer |
|
Integer |
|
Unicode string |
|
4-character byte string |
|
Integer |
|
Integer |
|
Byte string |
If ds_store happens across any other type code, it will raise
ValueError. This is unavoidable because the .DS_Store file
format does not include length information, so if we find a type code we do
not support, we cannot read the file.