Text Imp

Python bindings for iMessage and Contacts database access. Requires MacOS and full file system access to run.

Requirements

• Python >= 3.8
• macOS (for iMessage database access)
• uv package manager (recommended) or pip

Installation

This package requires Python 3.8 or later. We recommend using uv for package management.

Using uv (Recommended)

uv pip install text_imp

Using pip

pip install text_imp

Development Setup

1. Clone the repository:

git clone https://github.com/yourusername/text_imp.git
cd text_imp

2. Install uv if you haven't already:

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

3. Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

# Install the package in editable mode with all dependencies
uv pip install -e .

Usage Example

import text_imp

# Get messages
messages = text_imp.get_messages()
print(messages)

# Get contacts
contacts = text_imp.get_contacts()
print(contacts)

# Get attachments
attachments = text_imp.get_attachments()
print(attachments)

# To join with messages table, use guid version of
# attachments with message guid
attachments_with_id = get_attachments_with_guid()
print(attachments_with_id)

# Get chats
chats = text_imp.get_chats()
print(chats)

# Get  handles
handles = text_imp.get_handles()
print(handles)

# Get chat handles
chat_handles = text_imp.get_chat_handles()
print(handles)

Example Data

Each function returns a Polars DataFrame with structured data. Here are examples of what the returned data looks like:

Messages DataFrame

Columns: date, text, is_from_me, handle_id, chat_id, guid, thread_originator_guid, thread_originator_part, service_type, variant, expressive, announcement_type, num_attachments, is_deleted, group_title, is_edited, is_tapback, is_reply, num_replies, date_delivered, date_read, is_url, has_replies, body

Contacts DataFrame

Columns: contact_id, first_name, last_name, state, city, normalized_contact_id

Attachments DataFrame

Columns: rowid, filename, uti, mime_type, transfer_name, emoji_description, is_sticker, path, extension, display_filename, file_size

Chats DataFrame

Columns: rowid, chat_identifier, service_name, display_name, name, resolved_display_name

Handles DataFrame

Columns: rowid, id, person_centric_id

Chat Handles DataFrame

Columns: chat_id, handle_id

Project Structure

text_imp/
├── src/           # Rust source code
├── text_imp/      # Python package directory
├── examples/      # Usage examples
├── tests/         # Test files
├── Cargo.toml     # Rust dependencies and configuration
└── pyproject.toml # Python package configuration

Building from Source

The package uses Maturin for building the Rust extensions. To build from source:

# Using uv
uv pip install -e .

# Or verify the installation
uv run --with text_imp --no-project -- python -c "import text_imp"

Troubleshooting

If you encounter the error AttributeError: module 'text_imp' has no attribute 'get_messages', try the following:

1. Make sure you're on macOS (this package only works on macOS)
2. Reinstall the package:

uv pip uninstall text_imp
uv pip install text_imp

3. If installing from source, rebuild the package:

uv pip install -e .