0
# Record Writer
1

2
Low-level TensorFlow record format writer for direct event file management. Provides basic binary record writing capabilities with support for local filesystem, Amazon S3, and Google Cloud Storage backends.
3

4
## Capabilities
5

6
### Initialization
7

8
Creates a RecordWriter instance for writing binary protocol buffer records to various storage backends.
9

10
```python { .api }
11
class RecordWriter:
12
    def __init__(self, path: str):
13
        """
14
        Creates a RecordWriter for writing TensorFlow record format files.
15

16
        Parameters:
17
        - path: File path for writing records. Supports local paths, S3 ("s3://bucket/path"), 
18
                and Google Cloud Storage ("gs://bucket/path") URLs.
19
        """
20
```
21

22
### Record Writing
23

24
Write binary data records with CRC32C checksums for data integrity verification.
25

26
```python { .api }
27
def write(self, data: bytes):
28
    """
29
    Write a binary data record with length header and CRC32C checksums.
30

31
    Parameters:
32
    - data: Binary data to write as a record
33
    """
34
```
35

36
### File Management
37

38
Control file flushing and closing for data persistence and resource cleanup.
39

40
```python { .api }
41
def flush(self):
42
    """
43
    Flush any buffered data to the underlying storage.
44
    """
45

46
def close(self):
47
    """
48
    Close the record writer and release resources.
49
    """
50
```
51

52
## Cloud Storage Support
53

54
RecordWriter supports multiple storage backends through a plugin system:
55

56
### Amazon S3 Support
57

58
Requires `pip install boto3` for S3 functionality.
59

60
```python
61
from tensorboardX import RecordWriter
62

63
# Write to S3 bucket
64
writer = RecordWriter("s3://my-bucket/tensorboard/events.out.tfevents")
65
writer.write(event_data)
66
writer.close()
67
```
68

69
### Google Cloud Storage Support
70

71
Requires `pip install google-cloud-storage` for GCS functionality.
72

73
```python
74
from tensorboardX import RecordWriter
75

76
# Write to GCS bucket
77
writer = RecordWriter("gs://my-bucket/tensorboard/events.out.tfevents")
78
writer.write(event_data)
79
writer.close()
80
```
81

82
## Usage Examples
83

84
### Basic Local File Writing
85

86
```python
87
from tensorboardX import RecordWriter
88

89
# Create writer for local file
90
writer = RecordWriter("./logs/events.out.tfevents")
91

92
# Write binary protocol buffer data
93
event_data = b"serialized_protocol_buffer_data"
94
writer.write(event_data)
95

96
# Ensure data is written to disk
97
writer.flush()
98
writer.close()
99
```
100

101
### Advanced Usage with Context Manager
102

103
```python
104
from tensorboardX import RecordWriter
105

106
# Automatic resource cleanup
107
class RecordWriterContext:
108
    def __init__(self, path):
109
        self.writer = RecordWriter(path)
110
    
111
    def __enter__(self):
112
        return self.writer
113
    
114
    def __exit__(self, exc_type, exc_val, exc_tb):
115
        self.writer.close()
116

117
# Usage
118
with RecordWriterContext("./logs/events.out.tfevents") as writer:
119
    writer.write(event_data)
120
    # Automatically closed on exit
121
```
122

123
## Utility Functions
124

125
### Name Validation
126

127
Utility functions for TensorFlow-compatible name generation and validation.
128

129
```python { .api }
130
def make_valid_tf_name(name: str) -> str:
131
    """
132
    Convert arbitrary strings to valid TensorFlow operation names.
133

134
    Parameters:
135
    - name: Input name string
136

137
    Returns:
138
    - Valid TensorFlow operation name string
139
    """
140
```
141

142
### Storage Backend Registration
143

144
Functions for registering custom storage backends.
145

146
```python { .api }
147
def register_writer_factory(prefix: str, factory):
148
    """
149
    Register a custom writer factory for specific URL prefixes.
150

151
    Parameters:
152
    - prefix: URL prefix (e.g., "s3", "gs")
153
    - factory: Factory object with open() and directory_check() methods
154
    
155
    Raises:
156
    - ValueError: If prefix contains ':'
157
    """
158

159
def directory_check(path: str):
160
    """
161
    Initialize directory structure for the given path.
162

163
    Parameters:
164
    - path: Directory path to initialize
165
    """
166

167
def open_file(path: str):
168
    """
169
    Open a writer for the specified path using registered factories.
170

171
    Parameters:
172
    - path: File path, supports custom prefixes
173

174
    Returns:
175
    - File writer object
176
    """
177
```