🔍 Code Extractor

Retrieves all pending (and optionally completed) document reviews assigned to a specific user, with support for date filtering and pagination.

Purpose

This function serves as a controller action to fetch a user's review assignments from the document review system. It's designed for UI display, providing a filtered and formatted list of reviews that need the user's attention. The function supports filtering by review status, date range, and implements pagination for large result sets. It's typically used in dashboard views or review management interfaces where users need to see their assigned document reviews.

Source Code

def get_user_pending_reviews(
    user: DocUser,
    include_completed: bool = False,
    date_from: Optional[str] = None,
    date_to: Optional[str] = None,
    limit: int = 100,
    offset: int = 0
) -> Dict[str, Any]:
    """
    Get all pending reviews for a user.
    
    Args:
        user: User to get reviews for
        include_completed: Whether to include completed reviews
        date_from: Optional start date for filter (ISO format)
        date_to: Optional end date for filter (ISO format)
        limit: Maximum results to return
        offset: Number of results to skip
        
    Returns:
        Dictionary with user's pending reviews
    """
    try:
        # Determine status filter
        status_filter = ["PENDING", "ACTIVE"]
        if include_completed:
            status_filter.append("COMPLETED")
        
        # Get user's reviewer assignments
        assignments = get_user_assigned_reviews(
            user=user,
            status_filter=status_filter,
            limit=limit,
            offset=offset
        )
        
        # Extract assignments from result
        result_assignments = assignments.get('assignments', [])
        
        # Process for UI display
        reviews = []
        for assignment_data in result_assignments:
            # Check date filters if provided
            if date_from or date_to:
                # Get review cycle dates
                review_cycle = assignment_data.get('review_cycle', {})
                initiated_date = review_cycle.get('initiated_date')
                
                # Skip if before date_from
                if date_from and initiated_date and initiated_date < date_from:
                    continue
                    
                # Skip if after date_to
                if date_to and initiated_date and initiated_date > date_to:
                    continue
            
            # Prepare review data for UI
            reviews.append({
                'review': assignment_data.get('review_cycle', {}),
                'document': assignment_data.get('document', {}),
                'reviewer': assignment_data.get('assignment', {})
            })
        
        return {
            'success': True,
            'count': len(reviews),
            'total': assignments.get('total', 0),
            'reviews': reviews
        }
        
    except Exception as e:
        logger.error(f"Error getting user pending reviews: {e}")
        raise BusinessRuleError(f"Failed to get pending reviews: {e}")

Parameters

Parameter Details

user: DocUser object representing the user whose pending reviews should be retrieved. This is the authenticated user whose reviewer assignments will be queried.

include_completed: Boolean flag (default: False) that determines whether to include reviews with 'COMPLETED' status in addition to 'PENDING' and 'ACTIVE' reviews. Set to True to show historical completed reviews.

date_from: Optional ISO format date string (e.g., '2024-01-01') that filters out reviews initiated before this date. If None, no lower date bound is applied.

date_to: Optional ISO format date string (e.g., '2024-12-31') that filters out reviews initiated after this date. If None, no upper date bound is applied.

limit: Integer (default: 100) specifying the maximum number of review results to return. Used for pagination to control response size.

offset: Integer (default: 0) specifying how many results to skip before returning data. Used with limit for pagination (e.g., offset=100 with limit=100 gets results 101-200).

Return Value

Type: Dict[str, Any]

Returns a dictionary with keys: 'success' (bool, always True on success), 'count' (int, number of reviews in current page after filtering), 'total' (int, total number of assignments before date filtering), and 'reviews' (list of dicts). Each review dict contains 'review' (review cycle data), 'document' (document metadata), and 'reviewer' (assignment details). On error, raises BusinessRuleError exception.

Dependencies

• logging
• uuid
• os
• typing
• datetime
• traceback
• CDocs

Required Imports

from typing import Dict, Any, Optional
from CDocs.models.user_extensions import DocUser
from CDocs.controllers import log_controller_action, BusinessRuleError
import logging

Usage Example

from CDocs.models.user_extensions import DocUser
from CDocs.controllers.review_controller import get_user_pending_reviews

# Get current user (assume authenticated)
user = DocUser.query.get(user_id)

# Get pending reviews only
result = get_user_pending_reviews(user=user)
print(f"Found {result['count']} pending reviews")

# Get all reviews including completed, with date filter
result = get_user_pending_reviews(
    user=user,
    include_completed=True,
    date_from='2024-01-01',
    date_to='2024-12-31',
    limit=50,
    offset=0
)

# Process reviews for display
for review_data in result['reviews']:
    review_cycle = review_data['review']
    document = review_data['document']
    assignment = review_data['reviewer']
    print(f"Review for document: {document.get('title')}")
    print(f"Status: {assignment.get('status')}")

Best Practices

• Always handle the BusinessRuleError exception that may be raised on failure
• Use pagination (limit/offset) when dealing with users who may have many review assignments
• Date filters (date_from, date_to) should be in ISO format strings for consistent filtering
• The function performs date filtering after retrieving assignments, so the 'count' may be less than 'limit' when date filters are applied
• The 'total' count reflects pre-date-filter results, useful for pagination UI but may not match 'count' when date filters are active
• Ensure the user object is properly authenticated and authorized before calling this function
• The decorator log_controller_action will automatically log this action, so no additional logging is needed for audit purposes
• Consider the performance impact of large result sets; use appropriate limit values based on UI requirements

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_user_pending_approvals 84.2% similar

  Retrieves all pending approval assignments for a specific user, with optional filtering by completion status and date range, returning structured approval data for UI display.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller.py

• function get_user_assigned_reviews 73.1% similar

  Retrieves all review assignments for a specific user with optional filtering by status, including associated review cycle, document, and version details.

  From: /tf/active/vicechatdev/CDocs/controllers/review_controller.py

• function get_user_pending_approvals_v1 69.5% similar

  Retrieves a filtered list of approval cycles pending action from a specific user, ensuring the user has current approval authority for each returned item.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller_bis.py

• function get_user_assigned_approvals 69.2% similar

  Retrieves and paginates approval cycles assigned to a specific user, with optional filtering by status and completion state.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller_bis.py

• function get_user_assigned_approvals_v1 60.9% similar

  Retrieves all approval assignments for a specific user with optional filtering by status, including associated approval cycles, documents, and version information.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller.py