Skip to main content

Performing Bookmark Operations

To perform various operations on bookmarks, such as creating, retrieving, updating, deleting, archiving, restoring, and searching, you interact with the BookmarkService. This service acts as a facade, handling validation, cache invalidation, and cross-entity operations.

Creating a Bookmark​

To create a new bookmark, use the create_bookmark method, providing a dictionary containing the bookmark's url and title, along with any optional fields.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

# Example data for a new bookmark
new_bookmark_data = {
    "url": "https://www.example.com/my-article",
    "title": "My Awesome Article",
    "description": "A great read about various topics.",
    "tags": ["python", "web-development"]
}

bookmark, error = bookmark_service.create_bookmark(new_bookmark_data)

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

The create_bookmark method returns a tuple containing the created Bookmark object and None on success, or None and an error message string on failure.

Retrieving Bookmarks​

You can retrieve a single bookmark by its ID or list multiple bookmarks with pagination and status filtering.

Retrieving a Single Bookmark​

Use get_bookmark with the bookmark's unique ID to retrieve a specific bookmark.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

bookmark_id_to_retrieve = "some-bookmark-id-123" # Replace with an actual bookmark ID
bookmark = bookmark_service.get_bookmark(bookmark_id_to_retrieve)

if bookmark:
    print(f"Found bookmark: {bookmark.title} (URL: {bookmark.url})")
else:
    print(f"Bookmark with ID '{bookmark_id_to_retrieve}' not found.")

Listing Bookmarks​

To get a list of bookmarks, use list_bookmarks. You can specify the page, per_page limit, and status (e.g., "active", "archived") to filter the results.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

# List the first 10 active bookmarks
bookmarks, total_count = bookmark_service.list_bookmarks(page=1, per_page=10, status="active")

print(f"Found {len(bookmarks)} active bookmarks (Total: {total_count}):")
for bookmark in bookmarks:
    print(f"- {bookmark.title} ({bookmark.url})")

# List archived bookmarks
archived_bookmarks, archived_count = bookmark_service.list_bookmarks(page=1, per_page=5, status="archived")
print(f"\nFound {len(archived_bookmarks)} archived bookmarks (Total: {archived_count}):")
for bookmark in archived_bookmarks:
    print(f"- {bookmark.title}")

The list_bookmarks method returns a tuple containing a list of Bookmark objects and the total count of matching bookmarks.

Updating a Bookmark​

To modify an existing bookmark, use update_bookmark with the bookmark's ID and a dictionary of the fields to update.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

bookmark_id_to_update = "some-bookmark-id-456" # Replace with an actual bookmark ID
update_data = {
    "title": "Updated Article Title",
    "description": "This description has been revised.",
    "tags": ["python", "machine-learning", "updated"]
}

updated_bookmark, error = bookmark_service.update_bookmark(bookmark_id_to_update, update_data)

if updated_bookmark:
    print(f"Bookmark updated successfully: {updated_bookmark.title}")
    print(f"New description: {updated_bookmark.description}")
else:
    print(f"Failed to update bookmark with ID '{bookmark_id_to_update}': {error}")

Similar to create_bookmark, this method returns the updated Bookmark object and None on success, or None and an error message on failure.

Deleting a Bookmark​

To permanently remove a bookmark, use the delete_bookmark method with its ID.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

bookmark_id_to_delete = "some-bookmark-id-789" # Replace with an actual bookmark ID

if bookmark_service.delete_bookmark(bookmark_id_to_delete):
    print(f"Bookmark with ID '{bookmark_id_to_delete}' deleted successfully.")
else:
    print(f"Failed to delete bookmark with ID '{bookmark_id_to_delete}'. It might not exist.")

The delete_bookmark method returns True if the bookmark was successfully deleted, False otherwise.

Archiving and Restoring Bookmarks​

Instead of permanent deletion, you can archive bookmarks to hide them from active lists and restore them later if needed.

Archiving a Bookmark​

To change a bookmark's status to archived, use archive_bookmark.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

bookmark_id_to_archive = "some-bookmark-id-101" # Replace with an actual bookmark ID
archived_bookmark = bookmark_service.archive_bookmark(bookmark_id_to_archive)

if archived_bookmark:
    print(f"Bookmark '{archived_bookmark.title}' archived. Status: {archived_bookmark.status}")
else:
    print(f"Failed to archive bookmark with ID '{bookmark_id_to_archive}'.")

This method returns the Bookmark object with its updated status if successful, or None if the bookmark was not found or could not be archived.

Restoring a Bookmark​

To revert an archived bookmark back to an active status, use restore_bookmark.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

bookmark_id_to_restore = "some-bookmark-id-101" # Use the ID of an archived bookmark
restored_bookmark = bookmark_service.restore_bookmark(bookmark_id_to_restore)

if restored_bookmark:
    print(f"Bookmark '{restored_bookmark.title}' restored. Status: {restored_bookmark.status}")
else:
    print(f"Failed to restore bookmark with ID '{bookmark_id_to_restore}'.")

This method returns the Bookmark object with its updated status if successful, or None if the bookmark was not found or could not be restored.

Searching for Bookmarks​

To find bookmarks that match a specific query, use the search method.

from app.services.bookmark_service import BookmarkService

bookmark_service = BookmarkService()

search_query = "python"
search_results = bookmark_service.search(query=search_query, limit=5)

print(f"Search results for '{search_query}':")
if search_results:
    for bookmark in search_results:
        print(f"- {bookmark.title} (URL: {bookmark.url})")
else:
    print("No bookmarks found matching the query.")

The search method returns a list of Bookmark objects that match the provided query, up to the specified limit.