0
# Program Interface
1

2
TensorBoard's program interface provides command-line application functionality and server management capabilities. It includes the main TensorBoard application class, server abstractions, and process lifecycle management for running TensorBoard instances.
3

4
## Capabilities
5

6
### Main Application Class
7

8
The core TensorBoard application that handles configuration, plugin loading, and server lifecycle.
9

10
```python { .api }
11
class TensorBoard:
12
    """
13
    Main TensorBoard application class.
14
    
15
    Handles server configuration, plugin management, and application lifecycle.
16
    """
17
    
18
    def __init__(self, plugins=None, assets_zip_provider=None, server_class=None):
19
        """
20
        Initialize TensorBoard application.
21
        
22
        Args:
23
            plugins (list, optional): List of plugin instances to load
24
            assets_zip_provider (callable, optional): Provider for static assets
25
            server_class (class, optional): Custom server implementation class
26
        """
27
    
28
    def configure(self, **kwargs):
29
        """
30
        Configure the TensorBoard application.
31
        
32
        Args:
33
            **kwargs: Configuration options including:
34
                - logdir (str): Path to log directory
35
                - port (int): Server port number
36
                - host (str): Server host address
37
                - reload_interval (int): Log reload interval in seconds
38
                - max_reload_threads (int): Maximum reload thread count
39
                - path_prefix (str): URL path prefix
40
                - window_title (str): Browser window title
41
        """
42
    
43
    def main(self, argv=None):
44
        """
45
        Main entry point for command-line usage.
46
        
47
        Args:
48
            argv (list, optional): Command-line arguments. If None, uses sys.argv
49
            
50
        Returns:
51
            int: Exit code (0 for success, non-zero for error)
52
        """
53
    
54
    def launch(self):
55
        """
56
        Launch the TensorBoard server.
57
        
58
        Starts the web server and begins serving TensorBoard interface.
59
        This method blocks until the server is stopped.
60
        """
61
```
62

63
### Server Abstractions
64

65
Abstract base classes for implementing custom TensorBoard servers.
66

67
```python { .api }
68
class TensorBoardServer:
69
    """
70
    Abstract base class for TensorBoard server implementations.
71
    
72
    Defines the interface that server implementations must provide.
73
    """
74
    
75
    def serve_forever(self):
76
        """
77
        Abstract method to start serving and block until stopped.
78
        
79
        Must be implemented by subclasses to provide server functionality.
80
        """
81

82
class WerkzeugServer(TensorBoardServer):
83
    """
84
    Default Werkzeug-based server implementation.
85
    
86
    Provides threaded WSGI server functionality using Werkzeug.
87
    """
88
```
89

90
### Subcommand Framework
91

92
Framework for extending TensorBoard with additional subcommands.
93

94
```python { .api }
95
class TensorBoardSubcommand:
96
    """
97
    Abstract base class for TensorBoard subcommands.
98
    
99
    Enables extending TensorBoard with additional command-line functionality.
100
    """
101
    
102
    def run(self, args, unknown_args):
103
        """
104
        Abstract method to execute the subcommand.
105
        
106
        Args:
107
            args: Parsed command-line arguments
108
            unknown_args: Unparsed command-line arguments
109
            
110
        Must be implemented by subclasses.
111
        """
112
```
113

114
### Server Exceptions
115

116
Exception classes for server-related errors.
117

118
```python { .api }
119
class TensorBoardServerException(Exception):
120
    """Base exception class for server-related errors."""
121

122
class TensorBoardPortInUseError(TensorBoardServerException):
123
    """Exception raised when the requested port is already in use."""
124
```
125

126
### Utility Functions
127

128
Helper functions for enhanced server functionality.
129

130
```python { .api }
131
def with_port_scanning(cls):
132
    """
133
    Class decorator that adds port scanning functionality.
134
    
135
    Args:
136
        cls: Server class to decorate
137
        
138
    Returns:
139
        Decorated class with automatic port scanning when primary port is unavailable
140
    """
141
```
142

143
## Usage Examples
144

145
### Basic Server Launch
146

147
```python
148
from tensorboard.program import TensorBoard
149

150
# Create and configure TensorBoard
151
tb = TensorBoard()
152
tb.configure(
153
    logdir='./logs',
154
    port=6006,
155
    host='localhost',
156
    reload_interval=30
157
)
158

159
# Launch the server (blocks until stopped)
160
tb.launch()
161
```
162

163
### Command-Line Integration
164

165
```python
166
import sys
167
from tensorboard.program import TensorBoard
168

169
# Create TensorBoard instance
170
tb = TensorBoard()
171

172
# Run as command-line application
173
exit_code = tb.main(sys.argv[1:])
174
sys.exit(exit_code)
175
```
176

177
### Custom Plugin Configuration
178

179
```python
180
from tensorboard.program import TensorBoard
181
from tensorboard.plugins.scalar import scalars_plugin
182
from tensorboard.plugins.histogram import histograms_plugin
183

184
# Configure with specific plugins
185
plugins = [
186
    scalars_plugin.ScalarsPlugin(),
187
    histograms_plugin.HistogramsPlugin()
188
]
189

190
tb = TensorBoard(plugins=plugins)
191
tb.configure(logdir='./logs', port=6006)
192
tb.launch()
193
```
194

195
### Advanced Server Configuration
196

197
```python
198
from tensorboard.program import TensorBoard, WerkzeugServer
199

200
# Use custom server class
201
tb = TensorBoard(server_class=WerkzeugServer)
202
tb.configure(
203
    logdir='./multi_run_logs',
204
    port=6007,
205
    host='0.0.0.0',  # Accept connections from any host
206
    path_prefix='/tensorboard',  # Serve under URL prefix
207
    window_title='ML Experiment Dashboard',
208
    max_reload_threads=10
209
)
210

211
tb.launch()
212
```
213

214
### Error Handling
215

216
```python
217
from tensorboard.program import TensorBoard, TensorBoardPortInUseError
218

219
tb = TensorBoard()
220
tb.configure(logdir='./logs', port=6006)
221

222
try:
223
    tb.launch()
224
except TensorBoardPortInUseError:
225
    print("Port 6006 is already in use")
226
    # Try alternative port
227
    tb.configure(port=6007)
228
    tb.launch()
229
except KeyboardInterrupt:
230
    print("TensorBoard stopped by user")
231
```
232

233
### Port Scanning
234

235
```python
236
from tensorboard.program import TensorBoard, with_port_scanning
237

238
# Automatically scan for available ports if primary port is busy
239
@with_port_scanning
240
class AutoPortTensorBoard(TensorBoard):
241
    pass
242

243
tb = AutoPortTensorBoard()
244
tb.configure(logdir='./logs', port=6006)  # Will try 6006, 6007, 6008, etc.
245
tb.launch()
246
```
247

248
The program interface provides the foundation for TensorBoard's command-line functionality and server management, enabling both standalone usage and integration into larger applications or workflows.