pinboard-tools 0.1.10

A Python library for syncing and managing Pinboard bookmarks

pinboard-tools

A Python library for syncing and managing Pinboard bookmarks.

Features

• Efficient incremental sync with Pinboard.in API
• SQLite database for local bookmark storage
• Tag analysis and similarity detection
• Smart conflict resolution for sync operations
• Rate limiting and optimized API usage
• Chunking utilities for LLM processing

Installation

pip install pinboard-tools

Quick Start

from pinboard_tools import (
    init_database,
    get_session,
    BidirectionalSync,
)

# Initialize database
init_database("bookmarks.db")

# Create sync engine
db = get_session()
sync = BidirectionalSync(db=db, api_token="your-pinboard-api-token")

# Perform efficient incremental sync
stats = sync.sync()
print(f"Local to remote: {stats['local_to_remote']}")
print(f"Remote to local: {stats['remote_to_local']}")
print(f"Conflicts resolved: {stats['conflicts_resolved']}")

Core Components

Database Models

• Bookmark - Bookmark entity with all Pinboard fields
• Tag - Tag entity with normalization
• BookmarkTag - Many-to-many relationship
• SyncStatus - Track sync state

Sync Engine

• PinboardAPI - API client with rate limiting and incremental fetching
• BidirectionalSync - Efficient incremental sync with conflict resolution
• upsert_pinboard_post - Mirror a Pinboard API post into the local database

Tag Analysis

• TagSimilarityDetector - Find similar tags
• TagConsolidator - Merge duplicate tags

Utilities

• chunk_bookmarks_for_llm - Prepare data for LLM processing
• DateTime helpers for Pinboard format

Database Schema

The library uses a normalized SQLite schema:

-- See schema.sql for complete structure
bookmarks (url, title, description, tags, time, ...)
tags (name, normalized_name)
bookmark_tags (bookmark_id, tag_id)
sync_status (last_sync, last_update)

API Reference

Initialization

# Initialize database with schema
init_database(db_path: str)

# Get database session
with get_session() as session:
    # Use session for queries

Syncing

# Create sync client  
sync = BidirectionalSync(db=session, api_token="your-token")

# Efficient incremental sync (only fetches changed bookmarks)
stats = sync.sync()

# Sync only local changes to remote
stats = sync.sync(direction=SyncDirection.LOCAL_TO_REMOTE)

# Sync only remote changes to local
stats = sync.sync(direction=SyncDirection.REMOTE_TO_LOCAL)

Local mirroring

Use upsert_pinboard_post when another application has already written a bookmark to Pinboard and wants to keep the local SQLite database in step without running a full sync:

from pinboard_tools import PinboardAPI, get_session, init_database, upsert_pinboard_post

init_database("bookmarks.db")
db = get_session()
api = PinboardAPI("your-token")

api.add_post(
    url="https://example.com",
    description="Example",
    extended="A useful example.",
    tags="examples docs",
)
posts = api.get_post(url="https://example.com")
if posts:
    upsert_pinboard_post(db, posts[0])

The mirrored bookmark is marked synced, tags are normalized through the same tag tables as sync, and last_synced_at is updated.

Tag Analysis

# Find similar tags
detector = TagSimilarityDetector(session)
similar_groups = detector.find_similar_tags(threshold=0.8)

# Consolidate tags
consolidator = TagConsolidator(session)
consolidator.consolidate_tags(old_tag="python3", new_tag="python")

License

Apache License 2.0 - see LICENSE file for details