Read and write meta data, such as tags/keywords, Finder comments, etc. on MacOS files
Project description
osxmetadata
What is osxmetadata?
osxmetadata provides a simple interface to access various metadata about MacOS / OS X files. Currently supported metadata attributes include tags/keywords, Finder comments, authors, etc.
Why this package?
Apple provides rich support for file metadata through various metadata extended attributes MacOS provides tools to view and set these various metadata attributes. For example, mdls
lists metadata associated with a file and xattr
allows the user to set extended attributes. However, neither of these tools makes it easy to modify. xattr
, for example, can set metadata attributes but requires the value be in the form of a plist which is impractical. osxmetadata
makes it easy to to manipulate the MacOS metadata attributes, either programmatically or through a command line tool.
Supported operating systems
Only works on MacOS. Requires Python 3.6+.
Installation instructions
osxmetadata uses setuptools, thus simply run:
python setup.py install
Command Line Usage
Installs command line tool called osxmetadata which provides a simple interface to view/edit metadata supported by osxmetadata.
If you only care about the command line tool, I recommend installing with pipx
The command line tool can also be run via python -m osxmetadata
. Running it with no arguments or with --help option will print a help message:
Usage: osxmetadata [OPTIONS] FILE
Read/write metadata from file(s).
Options:
-v, --version Show the version and exit.
-w, --walk Walk directory tree, processing each file in the
tree
--set ATTRIBUTE VALUE Set ATTRIBUTE to VALUE
--list List all metadata attributes for FILE
--clear ATTRIBUTE Remove attribute from FILE
--append ATTRIBUTE VALUE Append VALUE to ATTRIBUTE
--get ATTRIBUTE Get value of ATTRIBUTE
--remove ATTRIBUTE VALUE Remove VALUE from ATTRIBUTE; only applies to
multi-valued attributes
--update ATTRIBUTE VALUE Update ATTRIBUTE with VALUE; for multi-valued
attributes, this adds VALUE to the attribute if
not already in the list
--help Show this message and exit.
Valid attributes for ATTRIBUTE: Each attribute has a short name, a constant
name, and a long constant name. Any of these may be used for ATTRIBUTE
For example: --set findercomment "Hello world"
or: --set kMDFinderComment "Hello world"
or: --set com.apple.metadata:kMDItemFinderComment "Hello world"
Attributes that are strings can only take one value for --set; --append will
append to the existing value. Attributes that are arrays can be set multiple
times to add to the array: e.g. --set keywords 'foo' --set keywords 'bar' will
set keywords to ['foo', 'bar']
Short Name Description
authors kMDItemAuthors, com.apple.metadata:kMDItemAuthors; The
author, or authors, of the contents of the file. An array of
strings.
comment kMDItemComment, com.apple.metadata:kMDItemComment; A comment
related to the file. This differs from the Finder comment,
kMDItemFinderComment. A string.
copyright kMDItemCopyright, com.apple.metadata:kMDItemCopyright; The
copyright owner of the file contents. A string.
creator kMDItemCreator, com.apple.metadata:kMDItemCreator;
Application used to create the document content (for example
“Word”, “Pages”, and so on). A string.
description kMDItemDescription, com.apple.metadata:kMDItemDescription; A
description of the content of the resource. The description
may include an abstract, table of contents, reference to a
graphical representation of content or a free-text account
of the content. A string.
downloadeddate kMDItemDownloadedDate,
com.apple.metadata:kMDItemDownloadedDate; The date the item
was downloaded. A date in ISO 8601 format: e.g.
2000-01-12T12:00:00 or 2000-12-31 (ISO 8601 w/o time zone)
findercomment kMDItemFinderComment,
com.apple.metadata:kMDItemFinderComment; Finder comments for
this file. A string.
headline kMDItemHeadline, com.apple.metadata:kMDItemHeadline; A
publishable entry providing a synopsis of the contents of
the file. A string.
keywords kMDItemKeywords, com.apple.metadata:kMDItemKeywords;
Keywords associated with this file. For example, “Birthday”,
“Important”, etc. This differs from Finder tags
(_kMDItemUserTags) which are keywords/tags shown in the
Finder and searchable in Spotlight using "tag:tag_name"An
array of strings.
tags _kMDItemUserTags, com.apple.metadata:_kMDItemUserTags;
Finder tags; searchable in Spotlight using "tag:tag_name".
If you want tags/keywords visible in the Finder, use this
instead of kMDItemKeywords.
wherefroms kMDItemWhereFroms, com.apple.metadata:kMDItemWhereFroms;
Describes where the file was obtained from (e.g. URL
downloaded from). An array of strings.
Supported Attributes
Information about commonly used MacOS metadata attributes is available from Apple.
osxmetadata
currently supports the following metadata attributes:
Constant | Short Name | Long Constant | Description |
---|---|---|---|
kMDItemAuthors | authors | com.apple.metadata:kMDItemAuthors | The author, or authors, of the contents of the file. An array of strings. |
kMDItemComment | comment | com.apple.metadata:kMDItemComment | A comment related to the file. This differs from the Finder comment, kMDItemFinderComment. A string. |
kMDItemCopyright | copyright | com.apple.metadata:kMDItemCopyright | The copyright owner of the file contents. A string. |
kMDItemCreator | creator | com.apple.metadata:kMDItemCreator | Application used to create the document content (for example “Word”, “Pages”, and so on). A string. |
kMDItemDescription | description | com.apple.metadata:kMDItemDescription | A description of the content of the resource. The description may include an abstract, table of contents, reference to a graphical representation of content or a free-text account of the content. A string. |
kMDItemDownloadedDate | downloadeddate | com.apple.metadata:kMDItemDownloadedDate | The date the item was downloaded. A date in ISO 8601 format: e.g. 2000-01-12T12:00:00 or 2000-12-31 (ISO 8601 w/o time zone) |
kMDItemFinderComment | findercomment | com.apple.metadata:kMDItemFinderComment | Finder comments for this file. A string. |
kMDItemHeadline | headline | com.apple.metadata:kMDItemHeadline | A publishable entry providing a synopsis of the contents of the file. A string. |
kMDItemKeywords | keywords | com.apple.metadata:kMDItemKeywords | Keywords associated with this file. For example, “Birthday”, “Important”, etc. This differs from Finder tags (_kMDItemUserTags) which are keywords/tags shown in the Finder and searchable in Spotlight using "tag:tag_name"An array of strings. |
_kMDItemUserTags | tags | com.apple.metadata:_kMDItemUserTags | Finder tags; searchable in Spotlight using "tag:tag_name". If you want tags/keywords visible in the Finder, use this instead of kMDItemKeywords. |
kMDItemWhereFroms | wherefroms | com.apple.metadata:kMDItemWhereFroms | Describes where the file was obtained from (e.g. URL downloaded from). An array of strings. |
Example uses of the package
Using the command line tool to set metadata:
Set Finder tags to Test, append "John Doe" to list of authors, clear (delete) description, set finder comment to "Hello World":
osxmetadata --set tags Test --append authors "John Doe" --clear description --set findercomment "Hello World" ~/Downloads/test.jpg
Walk a directory tree and add the Finder tag "test" to every file:
osxmetadata --append tags "Test" --walk ~/Downloads
Using the programmatic interface
There are two ways to access metadata using the programmatic interface. First, an OSXMetaData object will create properties for each supported attribute using the "Short name" in table above. For example:
from osxmetadata import *
fname = 'foo.txt'
meta = OSXMetaData(fname)
meta.description = "This is my document."
meta.tags.update("Foo")
meta.authors = ["John Doe","Jane Smith"]
The second way to access metadata is using methods from OSXMetaData to get/set/update etc. the various attributes. The various methods take the name of the attribute to be operated on which can be specified using either the short name, constant, or long constant from the table above. osxmetadata
also exports constants with the same name as specified in the Apple documentation and the table above, for example, kMDItemDescription
.
from osxmetadata import *
fname = 'foo.txt'
meta = OSXMetaData(fname)
description = meta.get_attribute(kMDItemDescription)
meta.set_attribute(kMDItemCreator,"OSXMetaData")
meta.append_attribute("tags",["Blue"])
meta.update_attribute("com.apple.metadata:kMDItemKeywords",["Foo"])
meta.append_attribute("findercomment","Goodbye")
meta.clear_attribute("tags")
Tags
Accessed via OSXMetaData.tags. Represents Finder tags (_kMDItemUserTags).
Behaves mostly like a set with following methods:
- update (sets multiple tags)
- add (add a single tag)
- += (add a single tag)
- remove (raises error if tag not present)
- discard (does not raise error if tag not present)
- clear (removes all tags)
To replace all tags with a new set of tags, use clear() then update()
Duplicate tags will be ignored.
The standard OS X Finder color labels are handled via tags. For example, setting a tag name of Gray, Green, Purple, Blue, Yellow, Red, or Orange will also set the equivalent Finder color label. This is consistent with how the Finder works. If a file has a color label, it will be returned as a tag of the corresponding color name when reading from OSXMetaData.tags
>>> from osxmetadata import OSXMetaData
>>> md = OSXMetaData('foo.txt')
>>> md.tags.update('Foo','Gray','Red','Test')
>>> print(md.tags)
Foo, Gray, Red, Test
#Standard Mac Finder color labels are normalized
>>> md.tags.add('PURPLE')
>>> print(md.tags)
Foo, Purple, Red, Test, Gray
>>> md.tags.add('FOOBAR')
>>> print(md.tags)
Foo, Purple, Red, Test, Gray, FOOBAR
>>> md.tags += 'MyCustomTag'
>>> print(md.tags)
Foo, Purple, Red, Test, Gray, MyCustomTag, FOOBAR
>>> md.tags.remove('Purple')
>>> print(md.tags)
Foo, Red, Test, Gray, MyCustomTag, FOOBAR
>>> md.tags.remove('Purple')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "osxmetadata/osxmetadata.py", line 148, in remove
tags.remove(self.__tag_normalize(tag))
KeyError: 'Purple\n3'
>>> md.tags.discard('Purple')
>>> md.tags.discard('Red')
>>> print(md.tags)
Foo, Test, Gray, MyCustomTag, FOOBAR
>>> len(md.tags)
5
>>> md.tags.clear()
>>> print(md.tags)
>>> len(md.tags)
0
>>>
Usage Notes
Changes are immediately written to the file. For example, OSXMetaData.tags.add("Foo") immediately writes the tag 'Foo' to the file.
Metadata is refreshed from disk every time a class property is accessed.
This will only work on file systems that support Mac OS X extended attributes.
Dependencies
Acknowledgements
This module was inspired by osx-tags by "Ben S / scooby". I leveraged osx-tags to bootstrap the design of this module. I wanted a more general OS X metadata library so I rolled my own. This module is published under the same MIT license as osx-tags.
To set the Finder comments, I use py-applescript by "Raymond Yee / rdhyee". Rather than import this module, I included the entire module (which is published as public domain code) in a private module to prevent ambiguity with other applescript modules on PyPi. py-applescript uses a native bridge via PyObjC and is very fast compared to the other osascript based modules.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for osxmetadata-0.98.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0c6456e490419ed974095bbb3f9e28403f87e080f22319c0ef9cc6e9bbdfc5b6 |
|
MD5 | c2ded295002d66e84118b33f4483a1ef |
|
BLAKE2b-256 | a436b4755ec73b06b94d051366e8d5b08477eb3d792b6fee49c51c9d8390de04 |