Building Your First Library

This tutorial walks you through building a small personal library in etchblok-test-api. You will learn how to initialize the core service, create categorized bookmarks, and organize them into collections.

Prerequisites

To follow this tutorial, you need the etchblok-test-api package installed in your environment. The library relies on flask and standard Python dataclasses.

Step 1: Initialize the Bookmark Service

The BookmarkService is the primary entry point for etchblok-test-api. It acts as a facade, orchestrating the repository, search index, and cache. Because it is implemented as a singleton, you can instantiate it anywhere in your application to access the same underlying data.

from app.services.bookmark_service import BookmarkService

# Initialize the service facade
service = BookmarkService()

Step 2: Create a Categorized Tag

Before creating a bookmark, you should define a category using a Tag. Tags in etchblok-test-api support visual metadata like colors and descriptions.

from app.models.tag import TagColor

# Create a 'Research' tag with a blue color
tag, error = service.create_tag({
    "name": "Research",
    "color": TagColor.BLUE.value,
    "description": "Links related to ongoing projects"
})

if error:
    print(f"Failed to create tag: {error}")
else:
    print(f"Created tag: {tag.name} (ID: {tag.id})")

Note: etchblok-test-api reserves certain tag names for system use. Attempting to create a tag named all, untagged, archived, or trash will result in a validation error.

Step 3: Create a Bookmark with the Tag

Now you can create a bookmark and associate it with the tag you just created. The create_bookmark method validates that the URL is well-formed (starting with http:// or https://) and that a title is provided.

# Create a bookmark associated with the 'Research' tag
bookmark_data = {
    "url": "https://developer.mozilla.org/",
    "title": "MDN Web Docs",
    "description": "Resources for developers, by developers.",
    "tags": [tag.id]
}

bookmark, error = service.create_bookmark(bookmark_data)

if error:
    print(f"Failed to create bookmark: {error}")
else:
    print(f"Created bookmark: {bookmark.title} (ID: {bookmark.id})")

Step 4: Organize into a Manual Collection

Collections allow you to group related bookmarks. In etchblok-test-api, a MANUAL collection requires you to explicitly add bookmarks by their ID.

from app.models.collection import CollectionType

# Create a new manual collection
collection, error = service.create_collection({
    "name": "Web Development",
    "type": CollectionType.MANUAL.value
})

if collection:
    # Add the bookmark to the collection
    success = service.add_to_collection(collection.id, bookmark.id)
    
    if success:
        print(f"Added '{bookmark.title}' to '{collection.name}'")

Warning: If you create a SMART collection by setting the type to smart and providing a filter_rule, the add_to_collection method will return False. Smart collections are populated automatically based on their rules and do not support manual additions.

Step 5: Verify Your Library

Finally, you can retrieve the collection to verify that your bookmark is correctly organized. The Collection model provides a size property and a bookmark_ids list.

# Retrieve the collection and check its contents
my_collection = service.get_collection(collection.id)

if my_collection:
    print(f"Collection '{my_collection.name}' now contains {my_collection.size} item(s).")
    
    # List all bookmarks in the library to see the status
    bookmarks, total = service.list_bookmarks(status="active")
    for b in bookmarks:
        print(f"[{b.status.value}] {b.title} - Tags: {b.tags}")

Complete Example

Here is the full script combining all the steps above:

from app.services.bookmark_service import BookmarkService
from app.models.tag import TagColor
from app.models.collection import CollectionType

def build_library():
    service = BookmarkService()

    # 1. Create Tag
    tag, _ = service.create_tag({
        "name": "Research",
        "color": TagColor.BLUE.value
    })

    # 2. Create Bookmark
    bookmark, _ = service.create_bookmark({
        "url": "https://developer.mozilla.org/",
        "title": "MDN Web Docs",
        "tags": [tag.id]
    })

    # 3. Create Collection
    collection, _ = service.create_collection({
        "name": "Web Development",
        "type": CollectionType.MANUAL.value
    })

    # 4. Add to Collection
    service.add_to_collection(collection.id, bookmark.id)

    # 5. Result
    final_col = service.get_collection(collection.id)
    print(f"Library built: {final_col.name} has {final_col.size} bookmarks.")

if __name__ == "__main__":
    build_library()

Next Steps

• Explore Smart Collections by creating a collection with a filter_rule (e.g., a keyword that matches bookmark titles).
• Use service.search("query") to perform full-text searches across your new library.
• Manage bookmark lifecycles using service.archive_bookmark(id) or service.delete_bookmark(id).