Skip to main content

Managing Bookmark Records

To manage bookmark records in this project, you use the BookmarkRepository class. This repository provides a clean abstraction for persisting and retrieving bookmarks, tags, and collections from an in-memory data store.

Creating and Updating Bookmarks​

The save_bookmark method handles both the creation of new bookmarks and the updating of existing ones. Since the repository is in-memory, changes are persisted immediately to the internal dictionary.

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

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
new_bookmark.title = "Updated Example Title"
repo.save_bookmark(new_bookmark)

Retrieving Bookmarks​

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

# Retrieve a single bookmark by ID
bookmark = repo.get_bookmark("some-id-123")
if bookmark:
    print(f"Found: {bookmark.title}")

# List bookmarks with pagination and status filtering
# Returns a tuple: (list_of_items, total_count)
items, total = repo.list_bookmarks(
    page=1, 
    per_page=10, 
    status="active"
)

for item in items:
    print(f"{item.id}: {item.title}")

The list_bookmarks method automatically sorts results by created_at in descending order. Supported status filters are defined in BookmarkStatus (active, archived, trashed).

Deleting Bookmarks​

The repository provides a delete_bookmark method for "hard" deletion, which removes the record entirely from memory.

# Hard delete a bookmark
success = repo.delete_bookmark("some-id-123")
if success:
    print("Bookmark removed from storage.")

Note: In this project, "soft" deletion (moving to trash) is typically handled at the model level by changing the status and then calling save_bookmark.

Managing Tags and Collections​

The repository also manages related entities like Tag and Collection. You can use similar CRUD methods for these types and query bookmarks associated with specific tags.

from app.models.tag import Tag

# Save a new tag
tag = Tag(name="Python", color="#3776ab")
repo.save_tag(tag)

# Find all bookmarks associated with a specific tag
bookmarks = repo.get_bookmarks_with_tag(tag.id)
for b in bookmarks:
    print(f"Bookmark with tag {tag.name}: {b.title}")

# Delete a tag
repo.delete_tag(tag.id)

Troubleshooting and Gotchas​

  • In-Memory Storage: The BookmarkRepository uses in-memory dictionaries (_bookmarks, _tags, _collections). All data is lost when the application process restarts.
  • No Transactions: Mutation methods like save_bookmark persist immediately. There is no built-in support for rolling back changes if a subsequent operation fails.
  • Cascading Deletes: When deleting a tag via delete_tag, the repository does not automatically remove that tag ID from bookmarks. You must manually iterate through bookmarks and call bookmark.remove_tag(tag_id) before saving them back to the repository, as seen in BookmarkService.delete_tag.
  • Pagination Index: The page argument in list_bookmarks is 1-based. Passing 0 or a negative number will result in incorrect slicing of the data.