user_canvas_version.py

Overview

The user_canvas_version.py file defines a service class, UserCanvasVersionService, responsible for managing versions of user canvases stored in the database. It provides functionality to retrieve multiple versions associated with a specific user canvas and to clean up old versions beyond a certain threshold (20 versions).

This service extends a generic CommonService which likely provides common database operations. It interacts directly with the UserCanvasVersion database model and uses the Peewee ORM for querying and managing data.

Classes and Methods

Class: UserCanvasVersionService

Inheritance:
Inherits from CommonService

Purpose:
Manages CRUD and retrieval operations related to the UserCanvasVersion model, focusing on listing versions by canvas ID and deleting excess versions to maintain version limits.

Properties

• model (class variable):
  The Peewee model class associated with this service, set to UserCanvasVersion.

Methods

list_by_canvas_id(cls, user_canvas_id)

@classmethod
@DB.connection_context()
def list_by_canvas_id(cls, user_canvas_id)

• Description:
  Retrieves all versions of a user canvas filtered by the given user_canvas_id. Returns a Peewee SelectQuery object containing the selected fields for each matching version. If no versions are found or an error occurs, returns None.

• Parameters:

  • user_canvas_id (int): The identifier for the user canvas whose versions are being requested.

• Returns:

  • SelectQuery of UserCanvasVersion entries (with selected fields: id, create_time, title, create_date, update_date, user_canvas_id, update_time)

  • None if no records exist or an exception occurs.

• Usage Example:

versions = UserCanvasVersionService.list_by_canvas_id(123)
if versions:
    for version in versions:
        print(f"Version ID: {version.id}, Title: {version.title}")
else:
    print("No versions found for this canvas.")

• Implementation details:
  Uses the Peewee ORM's select() with explicit field selection for optimization, and filters records by user_canvas_id. Decorated with @DB.connection_context() to ensure database connection management.

delete_all_versions(cls, user_canvas_id)

@classmethod
@DB.connection_context()
def delete_all_versions(cls, user_canvas_id)

• Description:
  Deletes older versions of a user canvas if the total count exceeds 20, retaining only the latest 20 versions. This helps to manage storage and maintain performance by limiting version history size.

• Parameters:

  • user_canvas_id (int): The identifier for the user canvas whose old versions should be pruned.

• Returns:

  • True if the operation completes (even if no deletions were needed)

  • None if no records exist or an exception occurs.

• Usage Example:

result = UserCanvasVersionService.delete_all_versions(123)
if result:
    print("Old versions deleted successfully or no excess versions to delete.")
else:
    print("Failed to delete old versions or no versions found.")

• Implementation details:

  • Queries all versions for the given user_canvas_id ordered by create_time descending (newest first).

  • Checks if the count exceeds 20; if so, collects IDs of versions beyond the 20th index for deletion.

  • Calls the inherited delete_by_ids method (from CommonService) to delete the older versions in batch.

  • Decorated with @DB.connection_context() for connection management.

Important Implementation Details

• Database connection management:
  Both class methods are decorated with @DB.connection_context(), which handles connection opening and closing automatically, ensuring safe and efficient database interactions.

• Error handling:
  Methods catch DoesNotExist and generic exceptions, returning None in error cases to indicate failure or absence of data. This pattern promotes graceful degradation but requires calling code to check for None.

• Version retention policy:
  delete_all_versions enforces a hard cap of 20 versions per user canvas. This cap is enforced by deleting older versions beyond the 20 most recent, using the create_time to determine recency.

Interaction with Other System Components

• Database Models:
  Uses the UserCanvasVersion model imported from api.db.db_models. This model represents the database schema for user canvas versions.

• CommonService:
  Inherits from CommonService (imported from api.db.services.common_service), which likely provides generic CRUD operations such as delete_by_ids. This promotes code reuse and consistency across services.

• Database Connection (DB):
  Uses the DB object for database connection context management, ensuring that each method runs within an active connection.

• ORM Layer:
  Relies on Peewee ORM for querying, filtering, and manipulating database records.

Diagram: Class Structure of UserCanvasVersionService

classDiagram
    class CommonService {
        +delete_by_ids(ids: List[int])
        ...
    }

    class UserCanvasVersionService {
        +model = UserCanvasVersion
        +list_by_canvas_id(user_canvas_id: int)
        +delete_all_versions(user_canvas_id: int)
    }

    UserCanvasVersionService --|> CommonService

Summary

The user_canvas_version.py file defines a specialized service class focused on managing user canvas version records in the database. It provides methods to list all versions for a given canvas and to prune older versions beyond a limit of 20 to optimize storage and performance. This service leverages the Peewee ORM and inherits from a common service base to maximize code reuse and maintain database connection safety.

If you need further details about the UserCanvasVersion model or CommonService methods, reviewing related files in api.db would provide deeper insights.