common_service.py

Overview

common_service.py defines the CommonService class, a foundational service layer component that encapsulates common database operations using the Peewee ORM. It provides a standardized interface for Create, Read, Update, and Delete (CRUD) operations, batch processing, filtering, and querying across all database models in the InfiniFlow application.

By centralizing these operations, the class promotes code reuse, consistency, and maintainability for all service classes that interact with the database models. Subclasses should specify their target Peewee model by setting the model attribute.

Class: CommonService

Description

A base service class offering generic database operation methods for Peewee models. It supports single and batch CRUD operations, flexible queries with filtering and ordering, and utility methods to handle large input lists by chunking.

Attributes

Methods

query(cls, cols=None, reverse=None, order_by=None, **kwargs)

Executes a flexible query on the model with optional column selection, sorting, and filter criteria.

• Parameters:

  • cols (list, optional): List of column names to select. Defaults to all columns if None.

  • reverse (bool, optional): If True, sort descending; if False, ascending. No effect if order_by is None.

  • order_by (str, optional): Column name to order results by.

  • **kwargs: Additional filter conditions as keyword arguments.

• Returns:

  • peewee.ModelSelect: Query result set matching criteria.

• Usage Example:

  users = CommonService.query(cols=['id', 'name'], order_by='create_time', reverse=True, status='active')
  

get_all(cls, cols=None, reverse=None, order_by=None)

Fetches all records from the model's table with optional column selection and ordering. Defaults to ordering by create_time if reverse is specified but order_by is not.

• Parameters:

  • cols (list, optional): Columns to select.

  • reverse (bool, optional): Sort order flag.

  • order_by (str, optional): Column to order by.

• Returns:

  • peewee.ModelSelect: Query containing all records.

• Notes:

  • If reverse is True and order_by is not provided or invalid, orders by create_time descending.

get(cls, **kwargs)

Retrieve a single record matching the filter criteria.

• Parameters:

  • **kwargs: Filter conditions.

• Returns:

  • Model instance representing the found record.

• Raises:

  • peewee.DoesNotExist if no matching record found.

get_or_none(cls, **kwargs)

Retrieve a single record matching filters or return None if not found.

• Parameters:

  • **kwargs: Filter conditions.

• Returns:

  • Model instance or None.

• Usage Example:

  user = CommonService.get_or_none(id='1234')
  if user:
      print(user.name)
  else:
      print("User not found")
  

save(cls, **kwargs)

Create and save a new record to the database, forcing an insert operation.

• Parameters:

  • **kwargs: Field values for the new record.

• Returns:

  • Model instance of the saved record.

• Notes:

  • Unlike insert, this method does not automatically set timestamps or IDs.

insert(cls, **kwargs)

Insert a new record with automatic ID generation and timestamp fields.

• Parameters:

  • **kwargs: Field values.

• Returns:

  • Model instance of the created record.

• Implementation Details:

  • If id is not provided, generates a UUID.

  • Automatically sets create_time, create_date, update_time, and update_date.

insert_many(cls, data_list, batch_size=100)

Batch insert multiple records efficiently.

• Parameters:

  • data_list (list of dict): List of records to insert.

  • batch_size (int, optional): Number of records per batch (default 100).

• Behavior:

  • Sets creation timestamps for each record.

  • Uses Peewee's batch insert with transaction support.

• Usage Example:

  records = [{'name': 'Alice'}, {'name': 'Bob'}]
  CommonService.insert_many(records, batch_size=50)
  

update_many_by_id(cls, data_list)

Update multiple records identified by their IDs.

• Parameters:

  • data_list (list of dict): Each dict must include 'id' and updated field values.

• Behavior:

  • Updates update_time and update_date for each record.

  • Executes update queries within a transaction.

update_by_id(cls, pid, data)

Update a single record by its ID.

• Parameters:

  • pid: Record ID.

  • data (dict): Fields to update.

• Returns:

  • Number of records updated (should be 0 or 1).

• Behavior:

  • Sets update_time and update_date.

get_by_id(cls, pid)

Retrieve a single record by ID.

• Parameters:

  • pid: Record ID.

• Returns:

  • Tuple (success: bool, record: Model or None)

• Notes:

  • Returns (False, None) if not found or error occurs.

get_by_ids(cls, pids, cols=None)

Retrieve multiple records by a list of IDs.

• Parameters:

  • pids (list): Record IDs.

  • cols (list, optional): Columns to select.

• Returns:

  • Peewee query object with matching records.

delete_by_id(cls, pid)

Delete a record by its ID.

• Parameters:

  • pid: Record ID.

• Returns:

  • Number of records deleted (0 or 1).

delete_by_ids(cls, pids)

Delete multiple records by their IDs.

• Parameters:

  • pids (list): IDs of records to delete.

• Returns:

  • Number of records deleted.

filter_delete(cls, filters)

Delete records matching given filter conditions.

• Parameters:

  • filters (list): Peewee filter expressions.

• Returns:

  • Number of records deleted.

filter_update(cls, filters, update_data)

Update records matching given filters.

• Parameters:

  • filters (list): Peewee filter expressions.

  • update_data (dict): Fields to update.

• Returns:

  • Number of records updated.

cut_list(tar_list, n)

Static utility to split a list into chunks of size n.

• Parameters:

  • tar_list (list): List to split.

  • n (int): Chunk size.

• Returns:

  • List of tuples, each containing a chunk of n elements.

• Usage Example:

  chunks = CommonService.cut_list([1,2,3,4,5], 2)
  # chunks => [(1,2), (3,4), (5,)]
  

filter_scope_list(cls, in_key, in_filters_list, filters=None, cols=None)

Retrieve records where a field matches any value in a large list with optional extra filters and column selection.

• Parameters:

  • in_key (str): Field name for the SQL IN clause.

  • in_filters_list (list): List of values to match.

  • filters (list, optional): Additional Peewee filter expressions.

  • cols (list, optional): Columns to select.

• Returns:

  • List of matching model instances.

• Implementation Details:

  • Splits large in_filters_list into chunks of 20 to avoid query parameter limits.

  • Executes multiple queries and aggregates results.

Important Implementation Details

• Database Context Management:
  All class methods interacting with the database are decorated with @DB.connection_context(), ensuring they execute within a proper database connection context.

• Automatic Timestamps and UUIDs:
  Methods like insert and insert_many automatically populate UUID IDs and timestamps (create_time, create_date, update_time, update_date) using utility functions imported from api.utils.

• Batch Processing:
  insert_many and update_many_by_id methods leverage Peewee's atomic transactions and batch operations for efficient bulk inserts and updates.

• Flexible Filtering:
  Methods accept arbitrary keyword arguments or explicit Peewee filter expressions to support complex query conditions.

• Error Handling:
  get_or_none gracefully handles DoesNotExist exceptions, returning None instead of raising.

Interaction with Other Parts of the System

• Database Models (api.db.db_models):
  The model attribute is expected to be a Peewee model class imported from api.db.db_models. This file depends on those model definitions for database schema and ORM mappings.

• Utility Functions (api.utils):
  Functions such as get_uuid(), current_timestamp(), and datetime_format() are used for generating IDs and timestamp fields consistently.

• Database Connection (DB):
  The DB object manages database connection contexts, ensuring thread-safe and transactional execution of queries.

• Subclasses:
  Other service classes in the application inherit from CommonService and specify their own model to gain standardized database operation methods.

Visual Diagram

classDiagram
    class CommonService {
        - model
        + query(cols=None, reverse=None, order_by=None, **kwargs)
        + get_all(cols=None, reverse=None, order_by=None)
        + get(**kwargs)
        + get_or_none(**kwargs)
        + save(**kwargs)
        + insert(**kwargs)
        + insert_many(data_list, batch_size=100)
        + update_many_by_id(data_list)
        + update_by_id(pid, data)
        + get_by_id(pid)
        + get_by_ids(pids, cols=None)
        + delete_by_id(pid)
        + delete_by_ids(pids)
        + filter_delete(filters)
        + filter_update(filters, update_data)
        + cut_list(tar_list, n)
        + filter_scope_list(in_key, in_filters_list, filters=None, cols=None)
    }

Summary

The CommonService class in common_service.py serves as a reusable, consistent service layer for database operations in the InfiniFlow application. With comprehensive support for CRUD, batch processing, filtering, and ordering, it abstracts away repetitive database code and enforces best practices such as transactional safety and automatic metadata management. This class is designed to be subclassed with specific Peewee models to provide tailored data access layers across the system.