0
# Display Operations
1

2
User interface operations for interactive virtual host selection and management. These functions provide the interactive components needed when multiple virtual hosts match a domain or when user input is required.
3

4
## Capabilities
5

6
### Virtual Host Selection Interface
7

8
Interactive selection interface for choosing from multiple virtual host options.
9

10
```python { .api }
11
def select_vhost_multiple(vhosts: Optional[Iterable[VirtualHost]]) -> list[VirtualHost]:
12
    """Select multiple virtual hosts for certificate installation.
13
    
14
    Presents an interactive interface allowing users to select which virtual hosts
15
    should receive certificate installation when multiple options are available.
16
    Used when domain matching returns multiple potential targets.
17
    
18
    Args:
19
        vhosts: Available virtual hosts to choose from
20
        
21
    Returns:
22
        List of VirtualHost objects selected by user for certificate installation
23
        
24
    Raises:
25
        errors.PluginError: If no virtual hosts are provided or selection fails
26
    """
27
```
28

29
## Usage Examples
30

31
### Interactive Virtual Host Selection
32

33
```python
34
from certbot_nginx._internal.display_ops import select_vhost_multiple
35
from certbot_nginx._internal.parser import NginxParser
36

37
# Initialize parser and get virtual hosts
38
parser = NginxParser('/etc/nginx')
39
parser.load()
40
all_vhosts = parser.get_vhosts()
41

42
# Filter virtual hosts matching domain
43
domain = "example.com"
44
matching_vhosts = [vhost for vhost in all_vhosts 
45
                   if domain in vhost.names or 
46
                   any(domain in name for name in vhost.names)]
47

48
if len(matching_vhosts) > 1:
49
    # Present selection interface to user
50
    selected_vhosts = select_vhost_multiple(matching_vhosts)
51
    print(f"User selected {len(selected_vhosts)} virtual hosts")
52
    
53
    for vhost in selected_vhosts:
54
        print(f"Selected: {vhost.display_repr()}")
55
else:
56
    # Single match or no matches - no selection needed
57
    selected_vhosts = matching_vhosts
58
```
59

60
### Integration with Configurator
61

62
```python
63
from certbot_nginx._internal.configurator import NginxConfigurator
64
from certbot_nginx._internal.display_ops import select_vhost_multiple
65

66
# When configurator finds multiple matches
67
configurator = NginxConfigurator(config, name='nginx')
68
configurator.prepare()
69

70
# Get candidates for certificate installation
71
candidates = configurator.choose_vhosts('example.com')
72

73
if len(candidates) > 1:
74
    # Let user choose which ones to use
75
    selected = select_vhost_multiple(candidates)
76
    
77
    # Deploy certificates to selected virtual hosts
78
    for vhost in selected:
79
        # Deploy certificate logic here
80
        print(f"Deploying certificate to {vhost.filep}")
81
```
82

83
## User Interface Behavior
84

85
The `select_vhost_multiple` function provides:
86

87
1. **Clear Options Display**: Shows virtual host details including:
88
   - File path and location
89
   - Server names and aliases
90
   - Listen addresses and ports
91
   - SSL configuration status
92

93
2. **Multiple Selection**: Allows users to select multiple virtual hosts for batch certificate installation
94

95
3. **Validation**: Ensures at least one virtual host is selected before proceeding
96

97
4. **Error Handling**: Provides clear error messages for invalid selections
98

99
## Integration Points
100

101
Display operations integrate with:
102

103
- **NginxConfigurator**: Called when virtual host selection is ambiguous
104
- **Certificate Deployment**: Used before deploying certificates to multiple hosts
105
- **Enhancement Application**: Used when applying enhancements to multiple virtual hosts
106
- **Challenge Configuration**: Used when setting up challenges across multiple hosts
107

108
## Error Handling
109

110
```python
111
from certbot import errors
112

113
try:
114
    selected_vhosts = select_vhost_multiple(candidates)
115
except errors.PluginError as e:
116
    print(f"Selection failed: {e}")
117
    # Handle selection failure
118
except KeyboardInterrupt:
119
    print("Selection cancelled by user")
120
    # Handle user cancellation
121
```
122

123
The display operations module ensures a smooth user experience when the nginx plugin encounters situations requiring user input or clarification.