0
# Workbook Management
1

2
Core workbook functionality for creating, configuring, and managing Excel files. The Workbook class is the main entry point for XlsxWriter and provides methods for creating worksheets, formats, charts, and managing global workbook settings.
3

4
## Capabilities
5

6
### Workbook Creation and Closing
7

8
Create and finalize Excel workbooks with optional configuration settings.
9

10
```python { .api }
11
class Workbook:
12
    def __init__(self, filename, options=None):
13
        """
14
        Create a new Excel workbook.
15
        
16
        Args:
17
            filename (str): The name of the new Excel file to create
18
            options (dict, optional): Workbook options including:
19
                - constant_memory: Enable memory optimization mode
20
                - tmpdir: Directory for temporary files
21
                - date_1904: Use 1904 date system
22
                - default_date_format: Default date format string
23
                - remove_timezone: Remove timezone from datetime objects
24
                - nan_inf_to_errors: Convert NaN/Inf to Excel errors
25
                - strings_to_numbers: Convert number strings to numbers
26
                - strings_to_formulas: Convert formula strings to formulas
27
                - strings_to_urls: Convert URL strings to hyperlinks
28
                - use_future_functions: Enable future Excel functions
29
                - max_url_length: Maximum URL length
30
                - nan_inf_to_errors: Handle NaN/Inf values
31
        """
32
        
33
    def close(self):
34
        """
35
        Close the workbook and write the Excel file.
36
        
37
        This method writes all worksheets and metadata to the Excel file
38
        and must be called to save the workbook properly.
39
        """
40
```
41

42
### Worksheet Management
43

44
Create and manage worksheets within the workbook.
45

46
```python { .api }
47
def add_worksheet(self, name=None, worksheet_class=None):
48
    """
49
    Add a new worksheet to the workbook.
50
    
51
    Args:
52
        name (str, optional): Name for the worksheet. Auto-generated if None
53
        worksheet_class (class, optional): Custom worksheet class to use
54
        
55
    Returns:
56
        Worksheet: The created worksheet object
57
    """
58

59
def add_chartsheet(self, name=None, chartsheet_class=None):
60
    """
61
    Add a new chartsheet to the workbook.
62
    
63
    Args:
64
        name (str, optional): Name for the chartsheet. Auto-generated if None
65
        chartsheet_class (class, optional): Custom chartsheet class to use
66
        
67
    Returns:
68
        Chartsheet: The created chartsheet object
69
    """
70

71
def worksheets(self):
72
    """
73
    Get a list of all worksheets in the workbook.
74
    
75
    Returns:
76
        list: List of worksheet objects
77
    """
78

79
def get_worksheet_by_name(self, name):
80
    """
81
    Get a worksheet by its name.
82
    
83
    Args:
84
        name (str): Name of the worksheet to retrieve
85
        
86
    Returns:
87
        Worksheet: The worksheet object or None if not found
88
    """
89
```
90

91
### Format and Chart Creation
92

93
Create formatting and chart objects for use throughout the workbook.
94

95
```python { .api }
96
def add_format(self, properties=None):
97
    """
98
    Create a new Format object for cell formatting.
99
    
100
    Args:
101
        properties (dict, optional): Dictionary of format properties
102
        
103
    Returns:
104
        Format: A new format object that can be applied to cells
105
    """
106

107
def add_chart(self, options):
108
    """
109
    Create a new Chart object.
110
    
111
    Args:
112
        options (dict): Chart options including:
113
            - type: Chart type ('column', 'line', 'pie', 'scatter', etc.)
114
            - subtype: Chart subtype for specific variations
115
            
116
    Returns:
117
        Chart: A chart object of the specified type
118
    """
119

120
def get_default_url_format(self):
121
    """
122
    Get the default hyperlink format.
123
    
124
    Returns:
125
        Format: The default blue, underlined hyperlink format
126
    """
127
```
128

129
### Workbook Properties and Settings
130

131
Configure workbook-level properties and settings.
132

133
```python { .api }
134
def set_properties(self, properties):
135
    """
136
    Set document properties for the workbook.
137
    
138
    Args:
139
        properties (dict): Document properties including:
140
            - title: Document title
141
            - subject: Document subject  
142
            - author: Document author
143
            - manager: Document manager
144
            - company: Company name
145
            - category: Document category
146
            - keywords: Document keywords
147
            - comments: Document comments
148
            - status: Document status
149
            - hyperlink_base: Base URL for relative hyperlinks
150
            - created: Creation date (datetime object)
151
    """
152

153
def set_custom_property(self, name, value, property_type=None):
154
    """
155
    Set a custom document property.
156
    
157
    Args:
158
        name (str): Property name
159
        value: Property value (str, int, float, bool, or datetime)
160
        property_type (str, optional): Force property type
161
    """
162

163
def set_calc_mode(self, mode, calc_id=None):
164
    """
165
    Set the calculation mode for the workbook.
166
    
167
    Args:
168
        mode (str): Calculation mode ('automatic', 'manual', 'automatic_except_tables')
169
        calc_id (int, optional): Calculation chain ID
170
    """
171

172
def define_name(self, name, formula):
173
    """
174
    Create a defined name in the workbook.
175
    
176
    Args:
177
        name (str): The defined name
178
        formula (str): The formula or range the name refers to
179
    """
180
```
181

182
### Window and Display Settings
183

184
Control workbook window appearance and behavior.
185

186
```python { .api }
187
def set_size(self, width, height):
188
    """
189
    Set the size of the workbook window in pixels.
190
    
191
    Args:
192
        width (int): Window width in pixels
193
        height (int): Window height in pixels
194
    """
195

196
def set_tab_ratio(self, tab_ratio=None):
197
    """
198
    Set the ratio between worksheet tabs and horizontal scrollbar.
199
    
200
    Args:
201
        tab_ratio (float): Ratio from 0.0 to 1.0 (default 0.6)
202
    """
203

204
def read_only_recommended(self):
205
    """
206
    Set the workbook to open with a read-only recommendation dialog.
207
    """
208
```
209

210
### VBA and Macro Support
211

212
Add VBA projects and macros to the workbook.
213

214
```python { .api }
215
def add_vba_project(self, vba_project, is_stream=False):
216
    """
217
    Add a VBA project to the workbook.
218
    
219
    Args:
220
        vba_project (str or bytes): Path to VBA file or VBA binary data
221
        is_stream (bool): True if vba_project is binary data
222
    """
223

224
def add_signed_vba_project(self, vba_project, signature, project_is_stream=False, signature_is_stream=False):
225
    """
226
    Add a signed VBA project to the workbook.
227
    
228
    Args:
229
        vba_project (str or bytes): Path to VBA file or VBA binary data
230
        signature (str or bytes): Path to signature file or signature data
231
        project_is_stream (bool): True if vba_project is binary data
232
        signature_is_stream (bool): True if signature is binary data
233
    """
234

235
def set_vba_name(self, name=None):
236
    """
237
    Set the VBA code name for the workbook.
238
    
239
    Args:
240
        name (str, optional): VBA code name for the workbook
241
    """
242
```
243

244
### File Options
245

246
Configure file-level options and optimizations.
247

248
```python { .api }
249
def use_zip64(self):
250
    """
251
    Enable ZIP64 extensions for large files (>4GB).
252
    
253
    This allows creation of Excel files larger than the 4GB ZIP file limit
254
    but requires Excel 2010 or later to read the files.
255
    """
256

257
def get_image_index(self, image):
258
    """
259
    Get the index of an embedded image.
260
    
261
    Args:
262
        image (Image): The image object to lookup
263
        
264
    Returns:
265
        int: The image index for internal reference
266
        
267
    Note: This is an internal method used by the embed_image functionality.
268
    """
269

270
def has_images(self):
271
    """
272
    Check if the workbook has embedded images.
273
    
274
    Returns:
275
        bool: True if workbook contains embedded images, False otherwise
276
        
277
    Note: This is an internal method used to optimize file creation.
278
    """
279
```
280

281
## Usage Examples
282

283
### Basic Workbook Operations
284

285
```python
286
import xlsxwriter
287

288
# Create workbook with options
289
workbook = xlsxwriter.Workbook('example.xlsx', {
290
    'constant_memory': True,  # Memory optimization
291
    'default_date_format': 'dd/mm/yy'
292
})
293

294
# Add worksheets
295
sheet1 = workbook.add_worksheet('Data')
296
sheet2 = workbook.add_worksheet('Analysis')
297

298
# Create formats
299
bold = workbook.add_format({'bold': True})
300
currency = workbook.add_format({'num_format': '$#,##0.00'})
301

302
# Set properties
303
workbook.set_properties({
304
    'title': 'Sales Report',
305
    'author': 'John Doe',
306
    'company': 'Example Corp'
307
})
308

309
# Close and save
310
workbook.close()
311
```
312

313
### Chart Creation
314

315
```python
316
# Create different chart types
317
chart1 = workbook.add_chart({'type': 'column'})
318
chart2 = workbook.add_chart({'type': 'line'})
319
chart3 = workbook.add_chart({'type': 'pie'})
320

321
# Configure and insert charts
322
chart1.add_series({'values': '=Sheet1!B2:B5'})
323
worksheet.insert_chart('D2', chart1)
324
```
325

326
### VBA Project Integration
327

328
```python
329
# Add VBA project from file
330
workbook.add_vba_project('macros.bin')
331

332
# Set VBA code name
333
workbook.set_vba_name('ThisWorkbook')
334
```