### Install uv and Setup Environment with uv

Source: https://github.com/rhettbull/osxmetadata/blob/master/README_DEV.md

Instructions for installing the uv package manager and setting up a Python virtual environment. It covers installing uv via curl, creating a virtual environment (optionally specifying a Python version), activating it, and installing project dependencies.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
cd /path/to/project
uv venv
uv venv --python 3.13
source .venv/bin/activate
uv pip install -r pyproject.toml --extra dev
uv sync --extra dev
```

--------------------------------

### Basic Metadata Operations with osxmetadata

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

Demonstrates fundamental operations like creating a file, initializing OSXMetaData, setting and getting author metadata, setting and accessing Finder comments, managing tags, and setting/getting due dates.

```python
import datetime
import pathlib
from osxmetadata import *

pathlib.Path("test_file.txt").touch()
md = OSXMetaData("test_file.txt")

# Setting and getting authors
md.set(kMDItemAuthors, ["Jane Smith", "John Doe"])
print(md.get(kMDItemAuthors))

# Setting and getting Finder comment
md.kMDItemFinderComment = "This is my comment"
print(md.kMDItemFinderComment)

# Managing tags
md.tags = [Tag("Test", FINDER_COLOR_NONE), Tag("ToDo", FINDER_COLOR_RED)]
print(md.tags)

# Setting and getting due date
md[kMDItemDueDate] = datetime.datetime(2022, 10, 1)
print(md[kMDItemDueDate])
```

--------------------------------

### Accessing Metadata via Shortcut Names

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

Illustrates how to use shortcut names (lowercase attribute names without 'kMDItem') to set and get metadata, providing a more concise syntax for common attributes like authors and due dates.

```python
from osxmetadata import *

md = OSXMetaData("test_file.txt")

# Using shortcut for authors
md.authors = ["Jane Smith", "John Doe"]
print(md.authors)

# Using shortcut for due date
import datetime
md.duedate = datetime.datetime(2022, 10, 1)
print(md.duedate)
```

--------------------------------

### Manage Extended Attributes with osxmetadata

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

Demonstrates how to read, write, and remove extended attributes using osxmetadata. It includes examples of using custom encode and decode functions to handle binary plist data.

```python
from osxmetadata import *
import plistlib
from plistlib import FMT_BINARY
from functools import partial

md = OSXMetaData("test_file.txt")
md.kMDItemWhereFroms = ["apple.com"]

# Define encoders/decoders for binary plists
decode = partial(plistlib.loads, fmt=FMT_BINARY)
encode = partial(plistlib.dumps, fmt=FMT_BINARY)

# Read and write extended attributes
md.get_xattr("com.apple.metadata:kMDItemWhereFroms", decode=decode)
md.set_xattr("com.apple.metadata:kMDItemWhereFroms", ["google.com"], encode=encode)

# Remove an attribute
md.remove_xattr("com.apple.metadata:kMDItemWhereFroms")
```

--------------------------------

### Build and Deploy Docs with mkdocs

Source: https://github.com/rhettbull/osxmetadata/blob/master/README_DEV.md

Commands to build the project's documentation using mkdocs and deploy it to GitHub Pages. The 'mkdocs build' command generates the static site, and 'mkdocs gh-deploy' handles the deployment.

```bash
mkdocs build
mkdocs gh-deploy
```

--------------------------------

### Build Package with doit

Source: https://github.com/rhettbull/osxmetadata/blob/master/README_DEV.md

This command initiates the build process for the osxmetadata package using doit. It will build the package and run the associated tests. Use 'doit list' to view all available tasks.

```bash
doit
doit list
```

--------------------------------

### Manage Finder Tags with osxmetadata

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

Demonstrates how to read and write Finder tags using the Tag namedtuple and color constants. It also shows how to access tag names and color labels via NSURL resource keys.

```python
from osxmetadata import *
md = OSXMetaData("test_file.txt")
# Setting tags using Tag namedtuple
md.tags = [Tag("Test", FINDER_COLOR_NONE), Tag("ToDo", FINDER_COLOR_RED)]

# Accessing via resource keys
print(md.NSURLTagNamesKey)
print(md.NSURLLabelNumberKey)
print(md.NSURLLocalizedLabelKey)
```

--------------------------------

### Run Tests with doit and pytest

Source: https://github.com/rhettbull/osxmetadata/blob/master/README_DEV.md

This command executes the 'test' task defined in the dodo.py file using doit. The task is configured to run pytest for package testing. Note that some tests may fail on specific macOS versions.

```bash
doit test
```

--------------------------------

### Checking Supported Metadata Attributes

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

Shows how to verify if specific metadata attribute names are supported by the osxmetadata library by checking against the `ALL_ATTRIBUTES` set.

```python
from osxmetadata import ALL_ATTRIBUTES

print("kMDItemDueDate" in ALL_ATTRIBUTES)
print("NSURLTagNamesKey" in ALL_ATTRIBUTES)
print("findercomment" in ALL_ATTRIBUTES)
```

--------------------------------

### Set Finder Comments via AppleScript

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

Shows how to set and retrieve Finder comments. Note that setting comments relies on AppleScript and may trigger permission prompts.

```python
from osxmetadata import *
md = OSXMetaData("test_file.txt")
md.kMDItemFinderComment = "Hello World!"
print(md.findercomment)
```

--------------------------------

### Handle Date and Time Metadata

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

Illustrates how to set date-time attributes using Python's datetime objects. The library handles conversion between timezone-aware objects and the internal UTC storage format.

```python
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)
```

--------------------------------

### Generate Changelog with auto-changelog

Source: https://github.com/rhettbull/osxmetadata/blob/master/README_DEV.md

This command generates a changelog using the auto-changelog tool. It ignores commits matching the 'CHANGELOG' pattern and limits the output to the last 5 entries. This is useful for maintaining release notes.

```bash
auto-changelog --ignore-commit-pattern CHANGELOG -l 5
```

--------------------------------

### Metadata Attributes

Source: https://github.com/rhettbull/osxmetadata/blob/master/README.md

This section details various metadata attributes available for files on macOS. These attributes can be queried to retrieve information about documents, images, movies, and other file types.

```APIDOC
## Metadata Attributes

### Description
This document outlines common metadata attributes used by macOS, often prefixed with `kMDItem`. These attributes provide detailed information about file content, creation, and properties.

### Method
GET (Implied - for querying metadata)

### Endpoint
`/path/to/file?metadata=<attribute_name>` (Conceptual endpoint for querying specific attributes)

### Parameters
#### Query Parameters
- **metadata** (string) - Optional - The name of the metadata attribute to query (e.g., `kMDItemNumberOfPages`, `kMDItemPixelWidth`).

#### Request Body
None

### Response
#### Success Response (200)
- **attribute_value** (various) - The value of the requested metadata attribute. The type depends on the attribute (string, number, list of strings).

#### Response Example
```json
{
  "kMDItemNumberOfPages": 5,
  "kMDItemPixelWidth": 1920,
  "kMDItemPublishers": ["Example Publisher"]
}
```

### Available Metadata Attributes:

- **namedlocation** (`kMDItemNamedLocation`)
  - Type: string
  - Description: The name of the location or point of interest associated with the item. The name may be user provided.

- **numberofpages** (`kMDItemNumberOfPages`)
  - Type: number
  - Description: Number of pages in the document.

- **organizations** (`kMDItemOrganizations`)
  - Type: list of strings
  - Description: The company or organization that created the document.

- **orientation** (`kMDItemOrientation`)
  - Type: number
  - Description: The orientation of the document contents. Possible values are 0 (landscape) and 1 (portrait).

- **originalformat** (`kMDItemOriginalFormat`)
  - Type: string
  - Description: Original format of the movie.

- **originalsource** (`kMDItemOriginalSource`)
  - Type: string
  - Description: Original source of the movie.

- **pageheight** (`kMDItemPageHeight`)
  - Type: number
  - Description: Height of the document page, in points (72 points per inch). For PDF files this indicates the height of the first page only.

- **pagewidth** (`kMDItemPageWidth`)
  - Type: number
  - Description: Width of the document page, in points (72 points per inch). For PDF files this indicates the width of the first page only.

- **participants** (`kMDItemParticipants`)
  - Type: list of strings
  - Description: The list of people who are visible in an image or movie or written about in a document.

- **path** (`kMDItemPath`)
  - Type: string
  - Description: The complete path to the file.

- **performers** (`kMDItemPerformers`)
  - Type: list of strings
  - Description: Performers in the movie.

- **phonenumbers** (`kMDItemPhoneNumbers`)
  - Type: list of strings
  - Description: Phone numbers related to this item.

- **pixelcount** (`kMDItemPixelCount`)
  - Type: number
  - Description: The total number of pixels in the contents. Same as kMDItemPixelWidth x kMDItemPixelHeight.

- **pixelheight** (`kMDItemPixelHeight`)
  - Type: number
  - Description: The height, in pixels, of the contents. For example, the image height or the video frame height.

- **pixelwidth** (`kMDItemPixelWidth`)
  - Type: number
  - Description: The width, in pixels, of the contents. For example, the image width or the video frame width.

- **producer** (`kMDItemProducer`)
  - Type: string
  - Description: Producer of the content.

- **profilename** (`kMDItemProfileName`)
  - Type: string
  - Description: The name of the color profile used by the document contents.

- **projects** (`kMDItemProjects`)
  - Type: list of strings
  - Description: The list of projects that this file is part of. For example, if you were working on a movie all of the files could be marked as belonging to the project "My Movie".

- **publishers** (`kMDItemPublishers`)
  - Type: list of strings
  - Description: The entity responsible for making the resource available. For example, a person, an organization, or a service. Typically, the name of a publisher should be used to indicate the entity.

```

--------------------------------

### Bump Minor Version with bump2version

Source: https://github.com/rhettbull/osxmetadata/blob/master/README_DEV.md

This command bumps the minor version of the package using bump2version. It first performs a dry run to show changes and then applies them. This updates the __version__ constant and the pyproject.toml file.

```bash
bumpversion minor --verbose --dry-run
bumpversion minor --verbose
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.