### Install pinboard-tools from source

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/installation.rst

Clones the pinboard-tools repository from GitHub, navigates into the directory, synchronizes dependencies using uv, and installs the package in editable mode.

```bash
git clone https://github.com/your-username/pinboard-tools.git
cd pinboard-tools
uv sync
uv run pip install -e .
```

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

### Install pinboard-tools from PyPI

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/installation.rst

Installs the pinboard-tools package using pip from the Python Package Index, which is the recommended installation method.

```bash
pip install pinboard-tools
```

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

### Install pinboard-tools for development

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/installation.rst

Clones the pinboard-tools repository and synchronizes all dependencies, including development-specific ones, using uv.

```bash
git clone https://github.com/your-username/pinboard-tools.git
cd pinboard-tools
uv sync --dev
```

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

### Verify pinboard-tools installation

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/installation.rst

Imports the pinboard_tools package and prints its version to confirm successful installation.

```python
import pinboard_tools
print(pinboard_tools.__version__)
```

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

### Quick Start: Initialize Database and Sync Pinboard Bookmarks

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/README.md

Demonstrates how to initialize the local SQLite database, set up the Pinboard API client, and perform a bidirectional sync of bookmarks using the pinboard-tools library. Replace 'your-pinboard-api-token' with your actual Pinboard API token.

```python
from pinboard_tools import (
    init_database,
    get_session,
    PinboardAPI,
    BidirectionalSync,
)

# Initialize database
init_database("bookmarks.db")

# Set up API client
api = PinboardAPI(api_token="your-pinboard-api-token")

# Create sync engine
with get_session() as session:
    sync = BidirectionalSync(session, api)
    
    # Perform full sync
    stats = sync.sync()
    print(f"Added: {stats['added']}, Updated: {stats['updated']}")
```

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

### Complete Pinboard Bidirectional Sync Example with Error Handling and Logging in Python

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/examples/basic-sync.rst

This comprehensive example demonstrates a full synchronization workflow, including environment variable setup for API token, database initialization, and a bidirectional sync with conflict resolution. It incorporates robust error handling and provides detailed logging of sync results, ensuring a complete and reliable operation.

```python
#!/usr/bin/env python3
"""
Complete sync example with error handling and logging.
"""
   
import os
import sys
from pinboard_tools import BidirectionalSync, init_database
from pinboard_tools.sync.bidirectional import SyncDirection, ConflictResolution

def main():
    # Get API token from environment
    api_token = os.getenv("PINBOARD_API_TOKEN")
    if not api_token:
        print("Error: PINBOARD_API_TOKEN environment variable not set")
        sys.exit(1)
       
    try:
        # Initialize database
        db_path = "bookmarks.db"
        init_database(db_path)
        print(f"Database initialized: {db_path}")
           
        # Create sync client
        sync = BidirectionalSync(api_token=api_token)
        print("Sync client created")
           
        # Perform sync
        print("Starting sync...")
        results = sync.sync(
            direction=SyncDirection.BIDIRECTIONAL,
            conflict_resolution=ConflictResolution.NEWEST_WINS,
            dry_run=False
        )
           
        # Report results
        print("\nSync Results:")
        print(f"  Local → Remote: {results['local_to_remote']}")
        print(f"  Remote → Local: {results['remote_to_local']}")
        print(f"  Conflicts: {results['conflicts_resolved']}")
        print(f"  Errors: {results['errors']}")
           
        if results['errors'] == 0:
            print("\n✅ Sync completed successfully!")
        else:
            print(f"\n⚠️  Sync completed with {results['errors']} errors")
               
    except Exception as e:
        print(f"\n❌ Sync failed: {e}")
        sys.exit(1)

if __name__ == "__main__":
    main()
```

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

### Install pinboard-tools Python Library

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/README.md

Instructions to install the pinboard-tools library using pip, the Python package installer. This command will download and install the package and its dependencies from PyPI.

```bash
pip install pinboard-tools
```

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

### Perform Basic Bidirectional Sync with Pinboard in Python

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/examples/basic-sync.rst

This example shows how to execute a basic bidirectional synchronization using the `BidirectionalSync` client. It syncs all changes between the local database and Pinboard, then prints a summary of the synchronized bookmarks, conflicts, and errors.

```python
# Sync all changes
results = sync.sync()
   
print(f"Local to remote: {results['local_to_remote']} bookmarks")
print(f"Remote to local: {results['remote_to_local']} bookmarks")
print(f"Conflicts resolved: {results['conflicts_resolved']}")
print(f"Errors: {results['errors']}")
```

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

### Install Pinboard Tools Library

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/index.rst

Installs the Pinboard Tools Python library using pip, the standard Python package installer.

```bash
pip install pinboard-tools
```

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

### Build and Test Python Package Locally

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/RELEASING.md

This snippet outlines the steps for locally building and testing the Python package before a release. It covers using `uv build` to create distribution artifacts, `twine check` to validate them, and a sequence of commands to install the built wheel in a new virtual environment for verification.

```bash
# Build the package
uv build

# Check the build
uv run --with twine twine check dist/*

# Test installation in a new environment
cd /tmp
python -m venv test-env
source test-env/bin/activate
pip install /path/to/pinboard-tools/dist/pinboard_tools-0.1.2-py3-none-any.whl
python -c "import pinboard_tools; print(pinboard_tools.__version__)"
```

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

### Update Project Version Locally with bump-my-version

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/RELEASING.md

This snippet demonstrates how to install and use the `bump-my-version` tool to manually increment the project's version number (patch, minor, or major) before a release. It shows how to check the current version and apply the desired bump type.

```bash
# Install bump-my-version if needed
pip install bump-my-version

# Check current version
bump-my-version show current_version

# Bump version (choose one)
bump-my-version bump patch  # 0.1.1 -> 0.1.2
bump-my-version bump minor  # 0.1.1 -> 0.2.0
bump-my-version bump major  # 0.1.1 -> 1.0.0
```

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

### Handle Pinboard Sync Errors Gracefully in Python

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/examples/basic-sync.rst

This snippet provides an example of robust error handling during synchronization operations. It wraps the sync call in a `try-except` block to catch general exceptions and checks the `results['errors']` count to report any issues that occurred during the sync process.

```python
try:
    results = sync.sync()
       
    if results['errors'] > 0:
        print(f"Warning: {results['errors']} errors occurred during sync")
    else:
        print("Sync completed successfully!")
           
except Exception as e:
    print(f"Sync failed: {e}")
```

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

### Execute One-Way Pinboard Synchronization in Python

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/examples/basic-sync.rst

This example demonstrates how to control the direction of synchronization, allowing updates only from local to remote or remote to local. It uses the `SyncDirection` enum to specify the desired sync flow, preventing bidirectional changes.

```python
from pinboard_tools.sync.bidirectional import SyncDirection

# Only upload local changes to Pinboard
results = sync.sync(direction=SyncDirection.LOCAL_TO_REMOTE)
   
# Only download changes from Pinboard
results = sync.sync(direction=SyncDirection.REMOTE_TO_LOCAL)
```

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

### Initialize Pinboard Sync Client and Database in Python

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/examples/basic-sync.rst

This snippet demonstrates how to set up the `pinboard-tools` environment. It initializes a local SQLite database for bookmarks and creates a `BidirectionalSync` client using your Pinboard API token, preparing for synchronization operations.

```python
from pinboard_tools import BidirectionalSync, init_database

# Initialize database
init_database("my_bookmarks.db")

# Create sync client with your API token
sync = BidirectionalSync(api_token="your_username:your_api_token")
```

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

### API Reference: Database Initialization and Session Management

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/README.md

Documents the `init_database` function for setting up the SQLite database schema and `get_session` for obtaining a database session to interact with the local bookmark store. These are fundamental for any database operations.

```APIDOC
init_database(db_path: str)
  Description: Initializes the SQLite database schema at the specified path.
  Parameters:
    db_path (str): The file path for the SQLite database.

get_session()
  Description: Provides a context manager for an active database session.
  Returns: A context manager that yields a SQLAlchemy Session object.
```

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

### Perform Bidirectional Sync with Pinboard Tools

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/index.rst

Demonstrates how to initialize a local SQLite database, create a sync client using your Pinboard API token, and perform a bidirectional synchronization of bookmarks between your local database and Pinboard.in.

```python
from pinboard_tools import BidirectionalSync, init_database

# Initialize database
init_database("bookmarks.db")

# Create sync client
sync = BidirectionalSync(api_token="your_pinboard_token")

# Perform bidirectional sync
results = sync.sync()
print(f"Synced {results['local_to_remote']} local changes")
print(f"Synced {results['remote_to_local']} remote changes")
```

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

### API Documentation: pinboard_tools.sync.api.PinboardAPI Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/sync.rst

Documents the `PinboardAPI` class, which serves as the primary interface for programmatic interaction with the Pinboard.in service. This class encapsulates methods for making API requests, such as adding, deleting, or querying bookmarks.

```APIDOC
class pinboard_tools.sync.api.PinboardAPI:
  # All public, undocumented, and inherited members are included.
```

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

### Initialize SQLite Database for Pinboard Tools

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/configuration.rst

Before using the Pinboard Tools library, the SQLite database needs to be initialized. This snippet demonstrates how to initialize the database using the `init_database` function, allowing for both default and custom file path configurations.

```python
from pinboard_tools import init_database

# Initialize with default location
init_database()

# Or specify a custom path
init_database("/path/to/your/bookmarks.db")
```

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

### Simulate Pinboard Sync with Dry Run in Python

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/examples/basic-sync.rst

This snippet illustrates how to perform a dry run synchronization, allowing you to preview changes without actually modifying data. It uses the `dry_run=True` parameter to show the number of local and remote changes that *would* be synced.

```python
# Dry run - shows what would be synced
results = sync.sync(dry_run=True)
   
print("Dry run results:")
print(f"Would sync {results['local_to_remote']} local changes")
print(f"Would sync {results['remote_to_local']} remote changes")
```

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

### Pinboard-Tools SQLite Database Schema Overview

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/README.md

Overview of the main tables used in the pinboard-tools SQLite database for storing bookmarks, tags, and sync status. The full schema definition is available in the `schema.sql` file within the project repository.

```sql
-- 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: Pinboard API Client and Bidirectional Sync

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/README.md

Details the `PinboardAPI` class for interacting with the Pinboard.in service and the `BidirectionalSync` class for performing synchronized updates between the local database and Pinboard. This section covers client creation and sync execution.

```APIDOC
PinboardAPI(api_token: str)
  Description: Client for interacting with the Pinboard.in API, including rate limiting.
  Parameters:
    api_token (str): Your Pinboard API token (format: "username:token").

BidirectionalSync(session, api)
  Description: Engine for performing bidirectional synchronization between the local database and Pinboard.in.
  Parameters:
    session: An active SQLAlchemy database session.
    api: An instance of PinboardAPI.

  Methods:
    sync(full_sync: bool = False)
      Description: Performs a synchronization operation.
      Parameters:
        full_sync (bool, optional): If True, performs a full sync; otherwise, an incremental sync. Defaults to False.
      Returns: A dictionary containing sync statistics (e.g., 'added', 'updated', 'deleted').
```

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

### Documenting Python Display Utilities API

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/utils.rst

This snippet provides API documentation for the `pinboard_tools.utils.display` module, detailing its public members, undocumented members, and class inheritance structure. It serves as a reference for functions and classes related to display formatting operations within the `pinboard-tools` library.

```APIDOC
.. automodule:: pinboard_tools.utils.display
   :members:
   :undoc-members:
   :show-inheritance:
```

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

### Documenting Python DateTime Utilities API

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/utils.rst

This snippet provides API documentation for the `pinboard_tools.utils.datetime` module, detailing its public members, undocumented members, and class inheritance structure. It serves as a reference for functions and classes related to date and time operations within the `pinboard-tools` library.

```APIDOC
.. automodule:: pinboard_tools.utils.datetime
   :members:
   :undoc-members:
   :show-inheritance:
```

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

### Documenting Python Chunking Utilities API

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/utils.rst

This snippet provides API documentation for the `pinboard_tools.utils.chunking` module, detailing its public members, undocumented members, and class inheritance structure. It serves as a reference for functions and classes related to data chunking operations within the `pinboard-tools` library.

```APIDOC
.. automodule:: pinboard_tools.utils.chunking
   :members:
   :undoc-members:
   :show-inheritance:
```

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

### Commit and Push Version Changes to Git

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/RELEASING.md

After manually updating the project version, this snippet provides the necessary Git commands to stage the modified `pyproject.toml` and `pinboard_tools/__init__.py` files, commit the version change with an informative message, and push the updates to the main branch of the remote repository.

```bash
git add pyproject.toml pinboard_tools/__init__.py
git commit -m "chore: bump version to $(bump-my-version show current_version)"
git push origin main
```

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

### Authenticate Pinboard API Token

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/configuration.rst

To interact with the Pinboard.in API, an API token is required. This snippet shows how to initialize the `BidirectionalSync` client directly with your Pinboard API token, which follows the `username:TOKEN` format. It also demonstrates how to set and retrieve the token using an environment variable for secure and flexible configuration.

```python
from pinboard_tools import BidirectionalSync

# Initialize sync client
sync = BidirectionalSync(api_token="your_username:your_token")
```

```bash
export PINBOARD_API_TOKEN="your_username:your_token"
```

```python
import os
from pinboard_tools import BidirectionalSync

token = os.getenv("PINBOARD_API_TOKEN")
sync = BidirectionalSync(api_token=token)
```

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

### API Documentation: pinboard_tools.sync.bidirectional.BidirectionalSync Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/sync.rst

Documents the `BidirectionalSync` class, which handles bidirectional synchronization between a local database and Pinboard.in. This class provides the core logic for managing the sync process, including member functions for initiating and controlling synchronization flows.

```APIDOC
class pinboard_tools.sync.bidirectional.BidirectionalSync:
  # All public, undocumented, and inherited members are included.
```

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

### API Definition: pinboard_tools.database.models.bookmark_from_row Function

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the bookmark_from_row helper function, used to convert a database row into a Bookmark object.

```APIDOC
Function: pinboard_tools.database.models.bookmark_from_row
```

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

### API Definition: pinboard_tools.database.models.Bookmark Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the Bookmark model, including its members and inheritance hierarchy, used for managing individual bookmarks in the database.

```APIDOC
Class: pinboard_tools.database.models.Bookmark
  Members: All public and undocumented members
  Inheritance: Shown
```

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

### API Definition: pinboard_tools.database.models.init_database Function

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the init_database function, used to initialize the SQLite database schema and connection.

```APIDOC
Function: pinboard_tools.database.models.init_database
```

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

### Pinboard Tools Database Schema Reference

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/configuration.rst

The Pinboard Tools library utilizes a normalized SQLite database schema. This section outlines the primary tables and their roles, including `bookmarks` for main storage, `tags` for normalized tags, `bookmark_tags` for many-to-many relationships, and `bookmarks_fts` for full-text search capabilities.

```APIDOC
Database Schema:
- bookmarks: Main bookmark storage
- tags: Normalized tag storage
- bookmark_tags: Many-to-many relationship table
- bookmarks_fts: Full-text search virtual table
```

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

### API Definition: pinboard_tools.database.queries Module

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the pinboard_tools.database.queries module, including its members and inheritance hierarchy, which contains database query functions.

```APIDOC
Module: pinboard_tools.database.queries
  Members: All public and undocumented members
  Inheritance: Shown
```

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

### API Documentation: pinboard_tools.sync.api.PinboardAPIError Exception

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/sync.rst

Documents the `PinboardAPIError` exception, which is raised to indicate errors encountered during operations with the Pinboard.in API. This exception provides a structured way to handle API-specific failures.

```APIDOC
class pinboard_tools.sync.api.PinboardAPIError(Exception):
  # All public, undocumented, and inherited members are included.
```

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

### API Definition: pinboard_tools.database.models.bookmark_tag_from_row Function

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the bookmark_tag_from_row helper function, used to convert a database row into a BookmarkTag object.

```APIDOC
Function: pinboard_tools.database.models.bookmark_tag_from_row
```

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

### API Documentation for TagConsolidator Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/analysis.rst

Documents the `TagConsolidator` class, designed for consolidating tags. This section provides details on its public members and inheritance structure.

```APIDOC
Class: pinboard_tools.analysis.consolidation.TagConsolidator
  Purpose: Provides tools for consolidating tags.
  Members: All public members are documented.
  Inheritance: Shows inheritance hierarchy.
```

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

### API Reference: Tag Similarity Detection and Consolidation

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/README.md

Describes the `TagSimilarityDetector` for identifying similar tags based on a threshold and `TagConsolidator` for merging duplicate tags within the local database. These tools help maintain a clean and organized tag system.

```APIDOC
TagSimilarityDetector(session)
  Description: Detects similar tags within the local database.
  Parameters:
    session: An active SQLAlchemy database session.

  Methods:
    find_similar_tags(threshold: float = 0.8)
      Description: Finds groups of tags that are similar based on a given threshold.
      Parameters:
        threshold (float, optional): The similarity threshold (0.0 to 1.0) for grouping tags. Defaults to 0.8.
      Returns: A list of lists, where each inner list contains similar tag names.

TagConsolidator(session)
  Description: Provides functionality to merge or consolidate duplicate tags.
  Parameters:
    session: An active SQLAlchemy database session.

  Methods:
    consolidate_tags(old_tag: str, new_tag: str)
      Description: Replaces all occurrences of an old tag with a new tag across bookmarks.
      Parameters:
        old_tag (str): The tag name to be replaced.
        new_tag (str): The tag name to replace 'old_tag' with.
```

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

### API Documentation for TagSimilarityDetector Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/analysis.rst

Documents the `TagSimilarityDetector` class, which provides functionalities for identifying and analyzing similarities between tags. This section details its public members and inheritance structure.

```APIDOC
Class: pinboard_tools.analysis.similarity.TagSimilarityDetector
  Purpose: Detects similarity between tags.
  Members: All public members are documented.
  Inheritance: Shows inheritance hierarchy.
```

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

### API Definition: pinboard_tools.database.models.BookmarkRow Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the BookmarkRow type, including its members, representing a row structure for bookmark data.

```APIDOC
Class: pinboard_tools.database.models.BookmarkRow
  Members: All public and undocumented members
```

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

### API Definition: pinboard_tools.database.models.Tag Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the Tag model, including its members and inheritance hierarchy, used for managing tags associated with bookmarks.

```APIDOC
Class: pinboard_tools.database.models.Tag
  Members: All public and undocumented members
  Inheritance: Shown
```

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

### API Definition: pinboard_tools.database.models.BookmarkTag Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the BookmarkTag model, including its members and inheritance hierarchy, representing the many-to-many relationship between bookmarks and tags.

```APIDOC
Class: pinboard_tools.database.models.BookmarkTag
  Members: All public and undocumented members
  Inheritance: Shown
```

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

### API Definition: pinboard_tools.database.models.SyncStatus Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the SyncStatus model, including its members and inheritance hierarchy, used to track the synchronization status of the database.

```APIDOC
Class: pinboard_tools.database.models.SyncStatus
  Members: All public and undocumented members
  Inheritance: Shown
```

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

### API Definition: pinboard_tools.database.models.BookmarkTagRow Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the BookmarkTagRow type, including its members, representing a row structure for bookmark-tag relationship data.

```APIDOC
Class: pinboard_tools.database.models.BookmarkTagRow
  Members: All public and undocumented members
```

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

### API Documentation: pinboard_tools.sync.bidirectional.ConflictResolution Enum

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/sync.rst

Documents the `ConflictResolution` enumeration, which specifies strategies for resolving data conflicts that may arise during synchronization (e.g., preferring local changes, preferring remote changes). This enum's members define the available conflict resolution methods.

```APIDOC
class pinboard_tools.sync.bidirectional.ConflictResolution:
  # All public, undocumented, and inherited members are included.
```

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

### API Definition: pinboard_tools.database.models.tag_from_row Function

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the tag_from_row helper function, used to convert a database row into a Tag object.

```APIDOC
Function: pinboard_tools.database.models.tag_from_row
```

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

### API Definition: pinboard_tools.database.models.get_session Function

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the get_session function, used to retrieve a database session for performing operations.

```APIDOC
Function: pinboard_tools.database.models.get_session
```

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

### Configure Pinboard Sync Direction

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/configuration.rst

The `BidirectionalSync` client allows flexible control over the synchronization direction. This snippet illustrates how to specify whether to perform a bidirectional sync (default), sync only local changes to remote, or only remote changes to local, using the `SyncDirection` enum.

```python
from pinboard_tools import BidirectionalSync
from pinboard_tools.sync.bidirectional import SyncDirection

sync = BidirectionalSync(api_token="your_token")

# Bidirectional sync (default)
sync.sync(direction=SyncDirection.BIDIRECTIONAL)

# Only sync local changes to remote
sync.sync(direction=SyncDirection.LOCAL_TO_REMOTE)

# Only sync remote changes to local
sync.sync(direction=SyncDirection.REMOTE_TO_LOCAL)
```

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

### API Definition: pinboard_tools.database.models.Database Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the Database connection class, including its members and inheritance hierarchy, responsible for managing the SQLite database connection.

```APIDOC
Class: pinboard_tools.database.models.Database
  Members: All public and undocumented members
  Inheritance: Shown
```

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

### Configure Pinboard Sync Conflict Resolution

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/configuration.rst

When conflicts arise during synchronization, the `BidirectionalSync` client offers various resolution strategies. This snippet demonstrates how to configure conflict resolution using the `ConflictResolution` enum, allowing choices like newest timestamp wins, always using local or remote versions, or manual user prompting.

```python
from pinboard_tools.sync.bidirectional import ConflictResolution

# Newest timestamp wins (default)
sync.sync(conflict_resolution=ConflictResolution.NEWEST_WINS)

# Always use local version
sync.sync(conflict_resolution=ConflictResolution.LOCAL_WINS)

# Always use remote version
sync.sync(conflict_resolution=ConflictResolution.REMOTE_WINS)

# Manual resolution (prompts user)
sync.sync(conflict_resolution=ConflictResolution.MANUAL)
```

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

### API Documentation: pinboard_tools.sync.bidirectional.SyncDirection Enum

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/sync.rst

Documents the `SyncDirection` enumeration, defining the possible directions for synchronization operations (e.g., local to remote, remote to local). This enum's members represent the distinct synchronization flow types.

```APIDOC
class pinboard_tools.sync.bidirectional.SyncDirection:
  # All public, undocumented, and inherited members are included.
```

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

### API Definition: pinboard_tools.database.models.TagMerge Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the TagMerge model, including its members and inheritance hierarchy, used for tracking tag merge operations.

```APIDOC
Class: pinboard_tools.database.models.TagMerge
  Members: All public and undocumented members
  Inheritance: Shown
```

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

### Access Pinboard API Rate Limit Constant

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/guide/configuration.rst

The Pinboard Tools library automatically manages Pinboard's API rate limiting, ensuring a minimum of 3 seconds between requests and handling 429 errors with automatic retries. This snippet demonstrates how to access the `PINBOARD_RATE_LIMIT_SECONDS` constant, which defines the configured delay between API calls.

```python
from pinboard_tools.sync.api import PINBOARD_RATE_LIMIT_SECONDS

print(f"Rate limit: {PINBOARD_RATE_LIMIT_SECONDS} seconds between requests")
```

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

### API Definition: pinboard_tools.database.models.TagRow Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the TagRow type, including its members, representing a row structure for tag data.

```APIDOC
Class: pinboard_tools.database.models.TagRow
  Members: All public and undocumented members
```

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

### API Definition: pinboard_tools.database.models.TagMergeRow Class

Source: https://github.com/kevinmcmahon/pinboard-tools/blob/main/docs/api/database.rst

Defines the API for the TagMergeRow type, including its members, representing a row structure for tag merge data.

```APIDOC
Class: pinboard_tools.database.models.TagMergeRow
  Members: All public and undocumented members
```

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