osxmetadata

osxmetadata is a Python library that provides a unified interface to access and manipulate various macOS file metadata attributes. While Apple's native APIs (like MDItem or NSURL) make it easy to read metadata, they often lack public interfaces to write/set it (e.g., for authors or Finder tags). osxmetadata bridges this gap using a combination of documented and undocumented APIs to allow both viewing and editing of attributes like:

• Tags/Keywords
• Finder comments
• Authors
• Other MDItem Spotlight metadata

Requirements:

• Operating System: macOS 10.15 or later (tested on macOS 13.5.1 Ventura).
• Python Version: 3.10+.

Attributes like kMDItemDueDate or kMDItemDownloadedDate return datetime.datetime objects. These objects are timezone-naive and represent the local timezone. You can pass timezone-aware datetime objects when setting these attributes, and they will be converted appropriately.

from osxmetadata import *
import datetime

md = OSXMetaData("test_file.txt")
# Setting a naive datetime
md.kMDItemDueDate = datetime.datetime(2022, 10, 1)

# Setting a timezone-aware datetime
md.kMDItemDownloadedDate = datetime.datetime(2022, 10, 1, tzinfo=datetime.timezone.utc)

Finder tags (the tags attribute) can include both a name and an optional color. To specify a color, append a comma followed by the color name to the tag name.

Format: TagName,colorname Valid colors: gray, green, purple, blue, yellow, red, orange.

If no color is specified, the tag will automatically inherit whatever color is already assigned to that tag name in Finder.

# Example: Set a red tag named 'Project'
osxmetadata --set tags Project,red FILE

When using --set or --append, you can identify attributes using their short name, constant name, or long constant name.

Examples of attribute naming:

• --set findercomment "Hello world"
• --set kMDItemFinderComment "Hello world"
• --set com.apple.metadata:kMDItemFinderComment "Hello world"

Behavior for different attribute types:

• String attributes: --set overwrites the existing value. --append adds to the existing value.
• Array/Multi-value attributes: You can specify --set multiple times to build an array (e.g., --set keywords foo --set keywords bar results in ['foo', 'bar']). This does not overwrite existing values; it adds to them. Use --append to add a value only if it is not already present.

For every kMDItem attribute, osxmetadata defines a lowercase "shortcut name" that can be used as a class attribute. For example, kMDItemAuthors can be accessed via .authors and kMDItemDueDate via .duedate.

from osxmetadata import *
md = OSXMetaData("test_file.txt")

# Shortcut for kMDItemAuthors
md.authors = ["Jane Smith", "John Doe"]

# Shortcut for kMDItemDueDate
md.duedate = datetime.datetime(2022, 10, 1)

The library currently supports accessing and manipulating several types of macOS file metadata, including:

• Tags/Keywords: Finder tags used for file organization.
• Finder Comments: Textual comments attached to files in Finder.
• Authors: Metadata identifying the creators of a file.
• Other attributes: Various other macOS-specific file metadata.

To set up a local development environment, use uv to manage the virtual environment and dependencies. Follow these steps:

1. Install uv using the official installer.
2. Create a virtual environment using uv venv (you can specify a version with --python 3.13).
3. Activate the environment.
4. Install dependencies, including development extras, using uv pip install or uv sync.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install dependencies with dev extras
uv sync --extra dev

For a clean installation that manages its own virtual environment, use pipx. This is recommended if you want to use the osxmetadata command-line tool directly from your terminal.

1. Install Homebrew (if not already installed) from https://brew.sh/.
2. Install pipx via Homebrew: brew install pipx.
3. Install osxmetadata: pipx install osxmetadata.
4. To upgrade: pipx upgrade osxmetadata.

brew install pipx
pipx install osxmetadata
# To upgrade
pipx upgrade osxmetadata

To build the package and run the tests simultaneously, run the doit command. You can inspect all available tasks defined in dodo.py by running doit list.

doit
# To see available tasks
doit list