Step by Step Guide to Building an OmniFocus API Integration in Python

Aug 15, 2024 • 5 minute read

Introduction

Hey there, fellow developer! Ready to supercharge your productivity with OmniFocus? Let's dive into building a Python integration with the OmniFocus API. This powerful tool will let you manage tasks programmatically, opening up a world of automation possibilities.

Prerequisites

Before we jump in, make sure you've got:

A Python environment (3.7+ recommended)
An OmniFocus API key (grab one from your OmniFocus account settings)

Got those? Great! Let's get coding.

Setting up the project

First things first, let's set up our project:

mkdir omnifocus-integration
cd omnifocus-integration
python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
pip install requests oauthlib

Authenticating with the OmniFocus API

OmniFocus uses OAuth 2.0 for authentication. Here's a quick implementation:

from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'

client = BackendApplicationClient(client_id=client_id)
oauth = OAuth2Session(client=client)
token = oauth.fetch_token(token_url='https://api.omnigroup.com/oauth/token', client_id=client_id, client_secret=client_secret)

Pro tip: Store your tokens securely and implement a refresh mechanism!

Basic API Operations

Now for the fun part - let's interact with our tasks:

base_url = 'https://api.omnigroup.com/omnifocus/v1'

# Fetch tasks
response = oauth.get(f'{base_url}/tasks')
tasks = response.json()

# Create a task
new_task = {'name': 'Build awesome OmniFocus integration', 'note': 'It's going to be epic!'}
response = oauth.post(f'{base_url}/tasks', json=new_task)

# Update a task
task_id = 'TASK_ID'
updates = {'completed': True}
response = oauth.patch(f'{base_url}/tasks/{task_id}', json=updates)

# Delete a task
response = oauth.delete(f'{base_url}/tasks/{task_id}')

Advanced Features

Want to level up? Let's play with projects and tags:

# Create a project
new_project = {'name': 'World Domination'}
response = oauth.post(f'{base_url}/projects', json=new_project)

# Add a tag
new_tag = {'name': 'Urgent'}
response = oauth.post(f'{base_url}/tags', json=new_tag)

# Assign a tag to a task
task_id = 'TASK_ID'
tag_id = 'TAG_ID'
response = oauth.post(f'{base_url}/tasks/{task_id}/tags/{tag_id}')

Error Handling and Best Practices

Always expect the unexpected:

try:
    response = oauth.get(f'{base_url}/tasks')
    response.raise_for_status()
except requests.exceptions.RequestException as e:
    print(f"Oops! API request failed: {e}")

# Respect rate limits
time.sleep(1)  # Simple but effective

Building a Simple CLI Tool

Let's wrap this up in a neat CLI package:

import click

@click.group()
def cli():
    pass

@cli.command()
@click.option('--name', prompt='Task name')
def add_task(name):
    new_task = {'name': name}
    response = oauth.post(f'{base_url}/tasks', json=new_task)
    click.echo(f"Task added: {response.json()['id']}")

if __name__ == '__main__':
    cli()

Testing the Integration

Don't forget to test! Here's a simple unit test to get you started:

import unittest

class TestOmniFocusIntegration(unittest.TestCase):
    def test_add_task(self):
        new_task = {'name': 'Test task'}
        response = oauth.post(f'{base_url}/tasks', json=new_task)
        self.assertEqual(response.status_code, 201)

if __name__ == '__main__':
    unittest.main()

Conclusion

And there you have it! You've just built a powerful OmniFocus integration in Python. The possibilities are endless - from automating your workflow to building complex productivity systems. What will you create?

Resources

Now go forth and conquer your tasks like a pro! Happy coding!