Coverage for pydantic_ai_jupyter / models.py: 100%

1""" 

2This module provides a framework for creating dynamic, interactive displays in Jupyter notebooks 

3and potentially other environments that support HTML rendering. It is designed to facilitate the 

4creation of rich, live-updating visualizations for data models, leveraging the capabilities of 

5IPython's display system. 

6 

7Key Components: 

8 

9- View: An abstract base class that serves as the foundation for creating view models. These 

10 view models are designed to encapsulate data and logic for rendering visual representations of 

11 that data in environments that support HTML, such as Jupyter notebooks. ViewModel provides 

12 mechanisms for displaying and updating these visual representations dynamically, enhancing 

13 interactivity and user engagement. 

14 

15- AutoView: A concrete implementation of ViewModel that automatically updates its display 

16 whenever its attributes change. This is particularly useful for creating reactive interfaces 

17 where changes to the underlying data model should be immediately reflected in the display 

18 without requiring explicit calls to update the view. 

19 

20Usage: 

21 

22The module is intended to be used in environments that support HTML rendering and IPython's 

23display capabilities. Users can extend the ViewModel class to create custom view models tailored 

24to their specific visualization needs, implementing the `render` method to define how data should 

25be represented visually. AutoViewModel can be used for more dynamic scenarios where the display 

26should react to changes in the view model's state automatically. 

27 

28Example: 

29 

30Below is a simplified example of how to create a custom ViewModel for displaying a message: 

31 

32 class MessageViewModel(ViewModel): 

33 message: str 

34 

35 def render(self) -> str: 

36 return f"<h1>{self.message}</h1>" 

37 

38 msg_view = MessageViewModel(message="Hello, World!") 

39 msg_view.display() 

40 

41This example creates a simple view model for displaying a message in a heading element. The 

42`render` method returns the HTML representation of the message, which is then displayed in the 

43notebook. 

44 

45Note: 

46 

47This module requires an environment that supports the IPython display system and HTML rendering, 

48such as Jupyter notebooks. It is not intended for use in non-interactive Python scripts or 

49environments that do not support these capabilities. 

50""" 

51 

52import uuid 

53from abc import ABC, abstractmethod 

54from typing import Union 

55 

56from IPython.display import display 

57from pydantic import BaseModel, Field 

58 

59from .decorators import renderable 

60from .protocols import HTMLRepresentable, MarkdownRepresentable 

61 

62 

63@renderable 

64class View(ABC, BaseModel): 

65 """ 

66 An abstract base class for view models designed for displaying objects 

67 within Jupyter notebooks or other environments that support HTML rendering. 

68 

69 This class provides a structure for creating and updating displays with 

70 dynamic content, leveraging HTML rendering for rich display capabilities. 

71 

72 Attributes: 

73 display_id (str): A unique identifier for the display instance, used to 

74 manage updates to the display in a notebook environment. 

75 

76 Methods: 

77 display(): Displays the current object in the notebook. If the object is 

78 already displayed, this method updates the existing display. 

79 update(): Updates the existing display with the current state of the object. 

80 render(): An abstract method that subclasses must implement, returning the 

81 content to be displayed as either a string of HTML or an object 

82 that implements the HTMLRepresentable protocol. 

83 """ 

84 

85 display_id: str = Field(default_factory=lambda: str(uuid.uuid4()), exclude=True) 

86 

87 def display(self) -> None: 

88 """ 

89 Display or the object in a Jupyter notebook or similar environment. 

90 

91 This method leverages the display_id to manage the lifecycle of the display, 

92 allowing for updates to an existing display without creating a new one. 

93 """ 

94 display(self, display_id=self.display_id) 

95 

96 def update(self) -> None: 

97 """ 

98 Update the display with the current state of the object. 

99 

100 This method is intended to be called after modifications to the object 

101 to refresh the display in the notebook environment. 

102 """ 

103 display(self, update=True, display_id=self.display_id) 

104 

105 @abstractmethod 

106 def render(self) -> Union[str, HTMLRepresentable, MarkdownRepresentable]: 

107 """ 

108 Render the object for display. 

109 

110 This is an abstract method that subclasses must implement to define how 

111 the object is rendered for display. The method must return either a string 

112 of HTML or an object that implements the HTMLRepresentable protocol. 

113 

114 Returns: 

115 Union[str, HTMLRepresentable]: The content to be displayed, either 

116 directly as HTML or through an object 

117 that can render itself as HTML. 

118 """ 

119 ...