🔍 Code Extractor

A dataclass that represents a versioned snapshot of a document, capturing its structure, metadata, and change history at a specific point in time.

Purpose

DocumentVersion serves as a version control mechanism for documents, storing complete snapshots of document state including title, description, sections, and metadata. It enables tracking document evolution over time, maintaining audit trails, and supporting rollback functionality. Each version is uniquely identified and timestamped, with support for serialization to/from dictionary format for persistence.

Source Code

class DocumentVersion:
    """Version history for document structure and metadata"""
    version_id: str
    document_id: str
    title: str
    description: str
    sections: List[Dict] = None  # Snapshot of document sections at this version
    timestamp: datetime = None
    author: str = ""
    change_summary: str = ""
    version_number: int = 1
    
    def __post_init__(self):
        if self.timestamp is None:
            self.timestamp = datetime.now()
        if self.sections is None:
            self.sections = []
    
    def to_dict(self) -> Dict:
        return {
            'version_id': self.version_id,
            'document_id': self.document_id,
            'title': self.title,
            'description': self.description,
            'sections': self.sections,
            'timestamp': self.timestamp.isoformat(),
            'author': self.author,
            'change_summary': self.change_summary,
            'version_number': self.version_number
        }
    
    @classmethod
    def from_dict(cls, data: Dict) -> 'DocumentVersion':
        return cls(
            version_id=data['version_id'],
            document_id=data['document_id'],
            title=data['title'],
            description=data['description'],
            sections=data.get('sections', []),
            timestamp=datetime.fromisoformat(data['timestamp']),
            author=data.get('author', ''),
            change_summary=data.get('change_summary', ''),
            version_number=data.get('version_number', 1)
        )

Parameters

Name	Type	Default	Kind
bases	-	-

Parameter Details

version_id: Unique identifier for this specific version. Should be a unique string (e.g., UUID) to distinguish this version from all others.

document_id: Identifier of the parent document this version belongs to. Links the version to its source document.

title: The title of the document at this version. Captures the document's title as it existed at version creation time.

description: The description of the document at this version. Captures the document's description as it existed at version creation time.

sections: Optional list of dictionaries representing the document's sections at this version. Defaults to empty list if not provided. Each dict should contain section data structure.

timestamp: Optional datetime when this version was created. Automatically set to current time if not provided during initialization.

author: Optional string identifying who created this version. Defaults to empty string if not provided.

change_summary: Optional string describing what changed in this version. Defaults to empty string if not provided.

version_number: Optional integer representing the sequential version number. Defaults to 1 if not provided.

Return Value

Instantiation returns a DocumentVersion object with all attributes initialized. The to_dict() method returns a dictionary representation with timestamp converted to ISO format string. The from_dict() class method returns a new DocumentVersion instance reconstructed from dictionary data.

Class Interface

Methods

Attributes

Name	Type	Description	Scope
version_id	str	Unique identifier for this version instance	instance
document_id	str	Identifier of the parent document this version belongs to	instance
title	str	Document title at this version	instance
description	str	Document description at this version	instance
sections	List[Dict]	Snapshot of document sections structure at this version, defaults to empty list	instance
timestamp	datetime	When this version was created, automatically set to current time if not provided	instance
author	str	Identifier of the person who created this version, defaults to empty string	instance
change_summary	str	Description of changes made in this version, defaults to empty string	instance
version_number	int	Sequential version number, defaults to 1	instance

Dependencies

• datetime
• typing
• dataclasses

Required Imports

from datetime import datetime
from typing import List, Dict
from dataclasses import dataclass

Usage Example

from datetime import datetime
from typing import List, Dict
from dataclasses import dataclass

# Create a new document version
version = DocumentVersion(
    version_id='v1-uuid-123',
    document_id='doc-456',
    title='My Document',
    description='A sample document',
    sections=[{'id': 's1', 'content': 'Section 1'}],
    author='john.doe',
    change_summary='Initial version',
    version_number=1
)

# Convert to dictionary for storage
version_dict = version.to_dict()
print(version_dict['timestamp'])  # ISO format timestamp

# Reconstruct from dictionary
restored_version = DocumentVersion.from_dict(version_dict)
print(restored_version.title)  # 'My Document'
print(restored_version.version_number)  # 1

Best Practices

• Always provide a unique version_id (consider using uuid.uuid4().hex) to avoid version conflicts
• Use the from_dict() class method when deserializing from storage rather than manual construction
• The sections attribute stores a snapshot - ensure you deep copy section data to avoid unintended mutations
• Timestamp is automatically set to current time if not provided, but can be explicitly set for historical imports
• Version numbers should be sequential and managed by the calling code - the class doesn't auto-increment
• The to_dict() method converts timestamp to ISO format string for JSON serialization compatibility
• When creating versions, always provide meaningful change_summary and author for audit purposes
• This is an immutable snapshot - create new DocumentVersion instances rather than modifying existing ones

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Document 78.8% similar

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

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

• class DocumentVersion_v1 78.5% similar

  Model representing a specific version of a controlled document.

  From: /tf/active/vicechatdev/CDocs/models/document.py

• class TextSectionVersion 76.1% similar

  A dataclass representing a single version in the history of a text section's content, tracking changes, authorship, and timestamps.

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

• class DocumentSection_v1 67.1% similar

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

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

• class DocumentSection 61.3% 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 DocumentVersion:
    """Version history for document structure and metadata"""
    version_id: str
    document_id: str
    title: str
    description: str
    sections: List[Dict] = None  # Snapshot of document sections at this version
    timestamp: datetime = None
    author: str = ""
    change_summary: str = ""
    version_number: int = 1
    
    def __post_init__(self):
        if self.timestamp is None:
            self.timestamp = datetime.now()
        if self.sections is None:
            self.sections = []
    
    def to_dict(self) -> Dict:
        return {
            'version_id': self.version_id,
            'document_id': self.document_id,
            'title': self.title,
            'description': self.description,
            'sections': self.sections,
            'timestamp': self.timestamp.isoformat(),
            'author': self.author,
            'change_summary': self.change_summary,
            'version_number': self.version_number
        }
    
    @classmethod
    def from_dict(cls, data: Dict) -> 'DocumentVersion':
        return cls(
            version_id=data['version_id'],
            document_id=data['document_id'],
            title=data['title'],
            description=data['description'],
            sections=data.get('sections', []),
            timestamp=datetime.fromisoformat(data['timestamp']),
            author=data.get('author', ''),
            change_summary=data.get('change_summary', ''),
            version_number=data.get('version_number', 1)
        )