🔍 Code Extractor

A dataclass representing a reference to a section (TextSection or DataSection) within a document structure, supporting hierarchical organization and section type differentiation.

Purpose

DocumentSection serves as a lightweight reference object that points to actual content sections within a document. It manages metadata about section positioning, hierarchy, type (text or data), and whether the section is an original or a copy. This class enables flexible document structure management with support for legacy data migration and serialization to/from dictionaries.

Source Code

class DocumentSection:
    """Reference to a section (TextSection or DataSection) within a document structure"""
    id: str
    section_id: str  # Can reference either TextSection.id or DataSection.id
    section_type: SectionType = SectionType.TEXT  # Default to TEXT for backward compatibility
    position: int = 0
    parent_id: Optional[str] = None  # For hierarchical structure
    is_copy: bool = False  # True if this is a copy, not the original
    
    def to_dict(self) -> Dict:
        result = asdict(self)
        result['section_type'] = self.section_type.value
        return result
    
    @classmethod
    def from_dict(cls, data: Dict) -> 'DocumentSection':
        if 'text_section_id' in data:  # Handle legacy data
            data['section_id'] = data['text_section_id']
            data.pop('text_section_id')
        
        # Handle missing section_type for legacy data
        if 'section_type' not in data:
            data['section_type'] = SectionType.TEXT
        elif isinstance(data['section_type'], str):
            data['section_type'] = SectionType(data['section_type'])
            
        return cls(**data)

Parameters

Name	Type	Default	Kind
bases	-	-

Parameter Details

id: Unique identifier for this DocumentSection reference instance

section_id: The ID of the actual section being referenced (can point to either a TextSection.id or DataSection.id)

section_type: Enum value indicating whether this references a TEXT or DATA section (defaults to SectionType.TEXT for backward compatibility)

position: Integer representing the order/position of this section within its parent or document (defaults to 0)

parent_id: Optional string ID of the parent section for hierarchical document structures (None if top-level)

is_copy: Boolean flag indicating whether this section reference is a copy (True) or the original (False), defaults to False

Return Value

Instantiation returns a DocumentSection object with all specified attributes. The to_dict() method returns a dictionary representation with section_type converted to its string value. The from_dict() class method returns a new DocumentSection instance constructed from dictionary data.

Class Interface

Methods

Attributes

Name	Type	Description	Scope
id	str	Unique identifier for this DocumentSection reference instance	instance
section_id	str	ID of the actual section being referenced (TextSection.id or DataSection.id)	instance
section_type	SectionType	Enum indicating whether this references a TEXT or DATA section, defaults to TEXT	instance
position	int	Order/position of this section within its parent or document, defaults to 0	instance
parent_id	Optional[str]	ID of the parent section for hierarchical structures, None for top-level sections	instance
is_copy	bool	Flag indicating whether this is a copy (True) or original reference (False), defaults to False	instance

Dependencies

• dataclasses
• typing
• enum

Required Imports

from dataclasses import dataclass, asdict
from typing import Dict, Optional
from enum import Enum

Usage Example

from dataclasses import dataclass
from typing import Dict, Optional
from enum import Enum

class SectionType(Enum):
    TEXT = 'text'
    DATA = 'data'

@dataclass
class DocumentSection:
    id: str
    section_id: str
    section_type: SectionType = SectionType.TEXT
    position: int = 0
    parent_id: Optional[str] = None
    is_copy: bool = False
    
    def to_dict(self) -> Dict:
        from dataclasses import asdict
        result = asdict(self)
        result['section_type'] = self.section_type.value
        return result
    
    @classmethod
    def from_dict(cls, data: Dict) -> 'DocumentSection':
        if 'text_section_id' in data:
            data['section_id'] = data['text_section_id']
            data.pop('text_section_id')
        if 'section_type' not in data:
            data['section_type'] = SectionType.TEXT
        elif isinstance(data['section_type'], str):
            data['section_type'] = SectionType(data['section_type'])
        return cls(**data)

# Create a new section reference
section = DocumentSection(
    id='doc_sec_001',
    section_id='text_sec_123',
    section_type=SectionType.TEXT,
    position=1,
    parent_id='parent_sec_001',
    is_copy=False
)

# Serialize to dictionary
section_dict = section.to_dict()
print(section_dict)

# Deserialize from dictionary
restored_section = DocumentSection.from_dict(section_dict)

# Handle legacy data
legacy_data = {
    'id': 'doc_sec_002',
    'text_section_id': 'old_text_123',
    'position': 2
}
legacy_section = DocumentSection.from_dict(legacy_data)

Best Practices

• Always use from_dict() class method when deserializing from stored data to ensure proper handling of legacy formats
• The section_type field provides backward compatibility by defaulting to TEXT, but explicitly set it for new instances
• Use position attribute to maintain consistent ordering of sections within a document
• The is_copy flag should be set to True when creating duplicate references to distinguish from originals
• parent_id enables hierarchical structures; set to None for top-level sections
• When serializing with to_dict(), the section_type enum is automatically converted to its string value for storage
• The class handles migration from legacy 'text_section_id' field to the newer 'section_id' field automatically
• This is a reference object, not the actual content holder; use section_id to retrieve the actual TextSection or DataSection

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class DocumentSection 85.5% similar

  A class representing a section within a complex document, supporting hierarchical structure with headers, text content, and references.

  From: /tf/active/vicechatdev/vice_ai/complex_app.py

• class Document 77.0% similar

  A dataclass representing a document with hierarchical structure, versioning, metadata, and collaboration features.

  From: /tf/active/vicechatdev/vice_ai/models.py

• class TextSection 76.7% similar

  A dataclass representing a text section entity with versioning, chat interface, data analysis capabilities, and metadata management.

  From: /tf/active/vicechatdev/vice_ai/models.py

• class ComplexDocument 72.1% similar

  A class representing a complex document with multiple sections, supporting section management, references, metadata, and serialization capabilities.

  From: /tf/active/vicechatdev/vice_ai/complex_app.py

• class DataSection 71.2% similar

  A dataclass representing a dedicated data analysis section that stores analysis results, plots, dataset information, and conclusions separately from text content.

  From: /tf/active/vicechatdev/vice_ai/models.py

class DocumentSection:
    """Reference to a section (TextSection or DataSection) within a document structure"""
    id: str
    section_id: str  # Can reference either TextSection.id or DataSection.id
    section_type: SectionType = SectionType.TEXT  # Default to TEXT for backward compatibility
    position: int = 0
    parent_id: Optional[str] = None  # For hierarchical structure
    is_copy: bool = False  # True if this is a copy, not the original
    
    def to_dict(self) -> Dict:
        result = asdict(self)
        result['section_type'] = self.section_type.value
        return result
    
    @classmethod
    def from_dict(cls, data: Dict) -> 'DocumentSection':
        if 'text_section_id' in data:  # Handle legacy data
            data['section_id'] = data['text_section_id']
            data.pop('text_section_id')
        
        # Handle missing section_type for legacy data
        if 'section_type' not in data:
            data['section_type'] = SectionType.TEXT
        elif isinstance(data['section_type'], str):
            data['section_type'] = SectionType(data['section_type'])
            
        return cls(**data)