Skip to main content

Managing Bookmark Records

In etchblok-test-api, the BookmarkRepository class provides an in-memory data access layer for managing bookmark records. It serves as the central point for persisting and retrieving Bookmark entities, though it is important to note that data is lost when the application process restarts.

Saving and Updating Bookmarks​

To persist a new bookmark or update an existing one, use the save_bookmark method. This method accepts a Bookmark instance and stores it in the internal dictionary using its ID as the key.

from app.models.bookmark import Bookmark
from app.db.repository import BookmarkRepository

repo = BookmarkRepository()

# Create a new bookmark
new_bookmark = Bookmark(
    url="https://example.com",
    title="Example Domain",
    description="A simple example site"
)
repo.save_bookmark(new_bookmark)

# Update an existing bookmark
bookmark = repo.get_bookmark(new_bookmark.id)
if bookmark:
    bookmark.title = "Updated Example Title"
    repo.save_bookmark(bookmark)

Retrieving and Listing Bookmarks​

You can retrieve a single bookmark by its ID or fetch a paginated list of bookmarks with optional status filtering.

Fetching by ID​

The get_bookmark method returns the Bookmark instance if found, or None if it does not exist.

bookmark = repo.get_bookmark("some-id-123")
if bookmark:
    print(f"Found: {bookmark.title}")

Listing with Pagination and Filters​

The list_bookmarks method returns a tuple containing a slice of bookmarks and the total count of matching records. By default, it sorts bookmarks by their created_at timestamp in descending order.

# Get the first page of active bookmarks
bookmarks, total = repo.list_bookmarks(
    page=1, 
    per_page=10, 
    status="active"
)

print(f"Showing {len(bookmarks)} of {total} active bookmarks.")

Deleting Bookmark Records​

etchblok-test-api distinguishes between "hard" and "soft" deletes.

Hard Delete (Repository Level)​

The delete_bookmark method in BookmarkRepository performs a hard delete, permanently removing the record from the in-memory storage.

# Permanently remove a bookmark
existed = repo.delete_bookmark("some-id-123")
if existed:
    print("Bookmark was removed from storage.")

Soft Delete (Service Level)​

In contrast, the BookmarkService implements a soft-delete pattern by moving bookmarks to a "trashed" state rather than removing them from the repository.

# Soft-delete via BookmarkService
# This calls bookmark.trash() and then repo.save_bookmark(bookmark)
service.delete_bookmark("some-id-123")

Filtering by Tags​

If you need to find all bookmarks associated with a specific tag, use get_bookmarks_with_tag. This is frequently used during tag deletion to ensure associated bookmarks are updated.

tag_id = "work-tag-id"
bookmarks = repo.get_bookmarks_with_tag(tag_id)

for bookmark in bookmarks:
    print(f"Bookmark '{bookmark.title}' has tag {tag_id}")

Troubleshooting and Gotchas​

  • In-Memory Storage: The BookmarkRepository does not persist data to disk. All bookmarks, tags, and collections are cleared when the application restarts.
  • Manual Updates: When modifying a Bookmark object directly, you must call save_bookmark to ensure the changes are reflected in the repository, especially if you are using the BookmarkService which relies on the repository for its cache invalidation logic.
  • Status Validation: The status parameter in list_bookmarks expects a string that matches a value in BookmarkStatus (e.g., "active", "archived", "trashed"). If an invalid status string is provided, the filter is ignored and all bookmarks are returned.