Add examples directory with Wikipedia fixture annotations

[rdhyee]

Overview

Create an examples/ directory demonstrating the hypothesisapi library capabilities. Use a hybrid approach:

• Read-only examples: Use public fixture annotations on Wikipedia
• Write examples: Self-contained create/update/delete cycles

Why Wikipedia for Fixtures

• Sustainability: Stable, long-lived platform
• Versioned URLs: Permanent revision links (oldid=...) for testing anchor stability
• Content drift testing: Demonstrates real-world annotation behavior when underlying content changes
• Educational: Meta-relevant content (annotating articles about annotation)

Phase 1: Create Fixture Annotations

Target page: Web annotation

URL Variants to Annotate

• Current page URL: https://en.wikipedia.org/wiki/Web_annotation
• Permanent revision URL: https://en.wikipedia.org/w/index.php?title=Web_annotation&oldid=XXXXXXX (get current revision ID)
• Internet Archive snapshot: Submit to Wayback Machine, annotate archived version

Fixture Annotations to Create

All tagged #hypothesisapi-example for easy discovery:

• Simple text annotation - Note without highlight (page note)
• Highlight with comment - Tests text anchoring on a specific passage
• Multi-tag annotation - Tags: #hypothesisapi-example, #test-fixture, #web-annotation
• Reply annotation - Demonstrates threading (reply to another fixture)
• Private annotation - In "Only Me" group for authenticated access testing

Phase 2: Write Examples

Basic Operations (Read-only, use fixtures)

• 01_read_annotation.py - Fetch and display a single annotation by ID
• 02_collection_stats.py - Get statistics about your annotation collection
• 03_search_by_uri.py - Find all annotations on a specific webpage
• 04_search_by_tag.py - Find annotations by tag (demo with #hypothesisapi-example)

Creating and Managing Annotations (Self-contained)

• 05_create_annotation.py - Create annotation → display → offer to delete
• 06_update_annotation.py - Create → update text/tags → display diff → cleanup
• 07_delete_annotation.py - Create temporary annotation → delete with confirmation

Bulk Operations

• 08_export_annotations.py - Export to JSON/CSV (runs on user's own data)
• 09_bulk_tag_update.py - Self-contained: create several → bulk update tags → cleanup

Groups

• 10_list_groups.py - List groups with details (read-only)
• 11_create_private_group.py - Create group → display → offer to delete
• 12_group_annotations.py - Search annotations in a specific group

Profile and Discovery

• 13_profile_info.py - Display Hypothesis profile information
• 14_recent_activity.py - Show most recent annotations with context

Phase 3: Documentation

• examples/README.md - Overview, setup instructions, fixture explanation
• examples/FIXTURES.md - Document fixture annotation IDs and their purpose
• Update main README.md to reference examples

Implementation Notes

Authentication Pattern

# Examples should support both env var and 1Password
import os
api_key = os.environ.get("HYPOTHESIS_API_KEY")
if not api_key:
    print("Set HYPOTHESIS_API_KEY or run with: op run --env HYPOTHESIS_API_KEY='op://...' -- python example.py")

Fixture Discovery

# Examples can find fixtures by tag
FIXTURE_TAG = "hypothesisapi-example"
fixtures = list(api.search(tag=FIXTURE_TAG, limit=20))

Self-Contained Pattern

# Create → use → cleanup pattern
annotation = api.create({"uri": "...", "text": "temporary test"})
try:
    # ... demo operations ...
finally:
    if input("Delete test annotation? [y/N] ").lower() == 'y':
        api.delete(annotation["id"])

Acceptance Criteria

• All examples run successfully with valid API key
• Read-only examples work with fixture annotations
• Self-contained examples clean up after themselves
• Examples include helpful output and comments
• README explains how to run examples