0
# File Operations
1

2
Complete functionality for loading PO/POT files, MO files, and converting between formats. Includes automatic encoding detection, file format validation, and comprehensive file I/O operations.
3

4
## Capabilities
5

6
### Loading PO/POT Files
7

8
Load and parse PO (Portable Object) or POT (Portable Object Template) files from filesystem paths or string content.
9

10
```python { .api }
11
def pofile(pofile, **kwargs):
12
    """
13
    Convenience function that parses the po or pot file and returns a POFile instance.
14

15
    Parameters:
16
    - pofile (str): Full or relative path to the po/pot file or its content (data)
17
    - wrapwidth (int, optional): The wrap width, default 78
18
    - encoding (str, optional): The encoding to use, default None (auto-detected)
19
    - check_for_duplicates (bool, optional): Whether to check for duplicates, default False
20
    - klass (class, optional): Class to instantiate return value, default None (POFile)
21

22
    Returns:
23
    POFile: A POFile instance containing the parsed entries
24
    """
25
```
26

27
**Usage Examples:**
28

29
```python
30
import polib
31

32
# Load from file path
33
po = polib.pofile('messages.po')
34

35
# Load with custom encoding
36
po = polib.pofile('messages.po', encoding='utf-8')
37

38
# Load with duplicate checking enabled
39
po = polib.pofile('messages.po', check_for_duplicates=True)
40

41
# Load from string content
42
po_content = '''
43
msgid ""
44
msgstr ""
45
"Content-Type: text/plain; charset=UTF-8\\n"
46

47
msgid "Hello"
48
msgstr "Hola"
49
'''
50
po = polib.pofile(po_content)
51
```
52

53
### Loading MO Files
54

55
Load and parse binary MO (Machine Object) files from filesystem paths or binary content.
56

57
```python { .api }
58
def mofile(mofile, **kwargs):
59
    """
60
    Convenience function that parses the mo file and returns a MOFile instance.
61

62
    Parameters:
63
    - mofile (str): Full or relative path to the mo file or its content (string or bytes)
64
    - wrapwidth (int, optional): The wrap width, default 78
65
    - encoding (str, optional): The encoding to use, default None (auto-detected)
66
    - check_for_duplicates (bool, optional): Whether to check for duplicates, default False
67
    - klass (class, optional): Class to instantiate return value, default None (MOFile)
68

69
    Returns:
70
    MOFile: A MOFile instance containing the parsed entries
71
    """
72
```
73

74
**Usage Examples:**
75

76
```python
77
import polib
78

79
# Load from file path
80
mo = polib.mofile('messages.mo')
81

82
# Load with custom settings
83
mo = polib.mofile('messages.mo', encoding='utf-8', wrapwidth=100)
84

85
# Load from binary content
86
with open('messages.mo', 'rb') as f:
87
    mo_content = f.read()
88
mo = polib.mofile(mo_content)
89
```
90

91
### Saving PO Files
92

93
Save POFile instances to filesystem in PO format with complete metadata and formatting preservation.
94

95
```python { .api }
96
class POFile(list):
97
    def save(self, fpath=None, repr_method='__unicode__', newline=None):
98
        """
99
        Save the PO file to disk.
100

101
        Parameters:
102
        - fpath (str, optional): File path to save to, uses self.fpath if None
103
        - repr_method (str, optional): String representation method, default '__unicode__'
104
        - newline (str, optional): Line ending style, default None (system default)
105

106
        Returns:
107
        None
108
        """
109

110
    def save_as_mofile(self, fpath):
111
        """
112
        Save the PO file as a binary MO file.
113

114
        Parameters:
115
        - fpath (str): Path where the MO file will be saved
116

117
        Returns:
118
        None
119
        """
120
```
121

122
**Usage Examples:**
123

124
```python
125
import polib
126

127
# Load and modify PO file
128
po = polib.pofile('messages.po')
129
entry = po.find('Hello')
130
if entry:
131
    entry.msgstr = 'Hola'
132

133
# Save back to original file
134
po.save()
135

136
# Save to different file
137
po.save('messages_es.po')
138

139
# Convert and save as MO file
140
po.save_as_mofile('messages.mo')
141
```
142

143
### Saving MO Files
144

145
Save MOFile instances to filesystem in binary MO format or convert to PO format.
146

147
```python { .api }
148
class MOFile(list):
149
    def save(self, fpath=None):
150
        """
151
        Save the MO file to disk in binary format.
152

153
        Parameters:
154
        - fpath (str, optional): File path to save to, uses self.fpath if None
155

156
        Returns:
157
        None
158
        """
159

160
    def save_as_pofile(self, fpath):
161
        """
162
        Save the MO file as a PO file.
163

164
        Parameters:
165
        - fpath (str): Path where the PO file will be saved
166

167
        Returns:
168
        None
169
        """
170
```
171

172
**Usage Examples:**
173

174
```python
175
import polib
176

177
# Load MO file
178
mo = polib.mofile('messages.mo')
179

180
# Save back to MO format
181
mo.save()
182

183
# Save to different MO file
184
mo.save('messages_backup.mo')
185

186
# Convert and save as PO file
187
mo.save_as_pofile('recovered.po')
188
```
189

190
### Metadata Access Methods
191

192
Access file metadata through dedicated methods that provide structured access to header information.
193

194
```python { .api }
195
class POFile(list):
196
    def metadata_as_entry(self):
197
        """
198
        Return the file metadata as a POEntry instance.
199

200
        Returns:
201
        POEntry: Entry containing metadata with empty msgid and metadata as msgstr
202
        """
203

204
    def ordered_metadata(self):
205
        """
206
        Return ordered metadata as list of tuples.
207

208
        Returns:
209
        list: List of (metadata_name, metadata_value) tuples in order
210
        """
211
```
212

213
**Usage Examples:**
214

215
```python
216
import polib
217

218
po = polib.pofile('messages.po')
219

220
# Get metadata as POEntry
221
metadata_entry = po.metadata_as_entry()
222
print(metadata_entry.msgstr)  # Contains formatted metadata
223

224
# Get ordered metadata tuples
225
metadata_list = po.ordered_metadata()
226
for name, value in metadata_list:
227
    print(f"{name}: {value}")
228
    
229
# Example output:
230
# Content-Type: text/plain; charset=UTF-8
231
# Language: es_ES
232
# Last-Translator: John Doe <john@example.com>
233
```
234

235
### File Properties and Metadata
236

237
Access and modify file-level properties and metadata for both PO and MO files.
238

239
```python { .api }
240
# POFile properties
241
class POFile(list):
242
    fpath: str                    # File path
243
    wrapwidth: int               # Line wrap width (default 78)
244
    encoding: str                # File encoding
245
    check_for_duplicates: bool   # Whether to check for duplicates when adding entries
246
    header: str                  # File header string
247
    metadata: dict               # Metadata dictionary (e.g., {'Language': 'es', 'MIME-Version': '1.0'})
248
    metadata_is_fuzzy: bool      # Whether metadata header is marked as fuzzy
249

250
# MOFile properties  
251
class MOFile(list):
252
    fpath: str           # File path
253
    wrapwidth: int       # Line wrap width
254
    encoding: str        # File encoding
255
    magic_number: int    # MO file magic number (0x950412de)
256
    version: int         # MO file version
257
```
258

259
**Usage Examples:**
260

261
```python
262
import polib
263

264
# Work with PO file metadata
265
po = polib.pofile('messages.po')
266

267
# Access metadata
268
print(po.metadata)  # {'Language': 'es', 'Content-Type': 'text/plain; charset=UTF-8', ...}
269
print(po.encoding)  # 'utf-8'
270
print(po.header)    # Full header string
271

272
# Modify metadata
273
po.metadata['Last-Translator'] = 'John Doe <john@example.com>'
274
po.metadata['Language'] = 'es_ES'
275

276
# Work with MO file properties
277
mo = polib.mofile('messages.mo')
278
print(f"MO file magic number: {hex(mo.magic_number)}")
279
print(f"MO file version: {mo.version}")
280

281
# File paths
282
print(po.fpath)  # Path to the loaded PO file
283
print(mo.fpath)  # Path to the loaded MO file
284
```
285

286
### Binary Conversion
287

288
Convert POFile instances to binary format for MO file generation.
289

290
```python { .api }
291
class POFile(list):
292
    def to_binary(self):
293
        """
294
        Return the binary representation of the PO file (MO format).
295

296
        Returns:
297
        bytes: Binary MO file content
298
        """
299
```
300

301
**Usage Examples:**
302

303
```python
304
import polib
305

306
# Load PO file and get binary representation
307
po = polib.pofile('messages.po')
308
binary_data = po.to_binary()
309

310
# Write binary data to MO file manually
311
with open('messages.mo', 'wb') as f:
312
    f.write(binary_data)
313

314
# This is equivalent to:
315
po.save_as_mofile('messages.mo')
316
```