Core Library

Overview

open-note-core is the core abstraction layer for Open Note's opennote extension tools, providing a unified interface for note operations.

Installation

pip install open-note-core

Core Concepts

Note

from open_note_core import Note

note = Note(
    id="uuid",
    title="Title",
    content="Content",
    created_at="2024-01-01T00:00:00Z",
    updated_at="2024-01-01T00:00:00Z"
)

Category

from open_note_core import Category

category = Category(
    id="uuid",
    name="Category name",
    parent_id=None  # Parent category ID
)

Tag

from open_note_core import Tag

tag = Tag(
    id="uuid",
    name="Tag name"
)

API Reference

NoteService

Note operation service.

create_note

def create_note(
    title: str,
    content: str,
    category_id: str | None = None,
    tags: list[str] | None = None
) -> Note

Create a new note.

get_note

def get_note(note_id: str) -> Note | None

Get a single note.

update_note

def update_note(
    note_id: str,
    title: str | None = None,
    content: str | None = None
) -> Note

Update a note.

delete_note

def delete_note(note_id: str) -> bool

Delete a note.

list_notes

def list_notes(
    category_id: str | None = None,
    tags: list[str] | None = None,
    limit: int = 20,
    offset: int = 0
) -> list[Note]

Get a list of notes.

CategoryService

Category operation service.

create_category

def create_category(
    name: str,
    parent_id: str | None = None
) -> Category

get_category_tree

def get_category_tree() -> list[CategoryNode]

Get the category tree.

TagService

Tag operation service.

add_tag

def add_tag(note_id: str, tag_name: str) -> Tag

remove_tag

def remove_tag(note_id: str, tag_id: str) -> bool

get_note_tags

def get_note_tags(note_id: str) -> list[Tag]

Data Models

Note

Field	Type	Description
id	str	Unique identifier
title	str	Title
content	str	Content
created_at	datetime	Creation time
updated_at	datetime	Update time
category_id	str | None	Category ID
source	str	Source (manual/clipboard/url/file)

Category

Field	Type	Description
id	str	Unique identifier
name	str	Name
parent_id	str | None	Parent category ID

Tag

Field	Type	Description
id	str	Unique identifier
name	str	Name

Error Handling

from open_note_core import NoteNotFoundError, ValidationError

try:
    note = service.get_note("invalid-id")
except NoteNotFoundError:
    print("Note does not exist")
except ValidationError as e:
    print(f"Validation error: {e}")

Examples

Complete Workflow

from open_note_core import OpenNoteCore

# Initialize
core = OpenNoteCore(database_url="sqlite:///notes.db")

# Create a category
work_category = core.categories.create(name="Work")

# Create a note
note = core.notes.create(
    title="Meeting Notes",
    content="Discussion content...",
    category_id=work_category.id,
    tags=["important", "todo"]
)

# Get the note
fetched = core.notes.get_note(note.id)

# Update the note
updated = core.notes.update_note(note.id, content="Updated content")

# Search
results = core.notes.list_notes(tags=["important"])

# Delete
core.notes.delete_note(note.id)

Extension

Implement a custom storage backend:

from open_note_core import BaseNoteRepository

class MyRepository(BaseNoteRepository):
    def create(self, note: Note) -> Note:
        # Custom implementation
        pass
    
    def get(self, note_id: str) -> Note | None:
        # Custom implementation
        pass