0
# Code Synchronization
1

2
Synchronize between notebooks and plain Python source code for IDE compatibility. The synchronization system enables two-way sync between notebook cells and Python modules, allowing developers to use IDEs while maintaining notebook-driven development.
3

4
## Capabilities
5

6
### Main Synchronization Function
7

8
Update notebooks from changes made to Python source files.
9

10
```python { .api }
11
def nbdev_update():
12
    """
13
    Update notebooks from source code changes.
14
    
15
    Synchronizes notebooks with changes made to Python modules,
16
    updating notebook cells with modified functions, classes,
17
    and other code elements that were changed in the exported
18
    Python files.
19
    """
20
```
21

22
**Usage Example:**
23

24
```python
25
from nbdev.sync import nbdev_update
26

27
# After editing Python files in your IDE
28
nbdev_update()
29
# This updates the corresponding notebook cells
30
```
31

32
### Import Management
33

34
Convert between different import styles for better IDE support.
35

36
```python { .api }
37
def absolute_import(name: str, fname: str, level: int = 0):
38
    """
39
    Convert to absolute imports.
40
    
41
    Args:
42
        name: Import name to convert
43
        fname: Source file name
44
        level: Relative import level
45
        
46
    Returns:
47
        Absolute import statement suitable for IDE tools
48
        
49
    Converts relative imports to absolute imports for better
50
    IDE support and static analysis tools.
51
    """
52
```
53

54
**Usage Example:**
55

56
```python
57
from nbdev.sync import absolute_import
58

59
# Convert relative import to absolute
60
abs_import = absolute_import('core', 'mylib/utils.py', level=1)
61
print(abs_import)  # 'mylib.core' instead of '.core'
62
```
63

64
## Synchronization Process
65

66
### Two-Way Sync Workflow
67

68
1. **Notebook → Python**: Export notebook cells to Python modules
69
2. **Edit in IDE**: Modify Python files using IDE features
70
3. **Python → Notebook**: Update notebooks with IDE changes
71

72
```python
73
from nbdev.export import nb_export
74
from nbdev.sync import nbdev_update
75

76
# Step 1: Export notebooks to Python
77
nb_export()
78

79
# Step 2: Edit Python files in your IDE
80
# ... make changes to .py files ...
81

82
# Step 3: Sync changes back to notebooks
83
nbdev_update()
84
```
85

86
### What Gets Synchronized
87

88
The sync system handles:
89

90
- **Function definitions**: Updates function code and signatures
91
- **Class definitions**: Syncs class methods and attributes  
92
- **Documentation**: Updates docstrings and comments
93
- **Imports**: Maintains import statements
94
- **Variable assignments**: Syncs module-level variables
95

96
### What Doesn't Get Synchronized
97

98
- **Cell outputs**: Execution results remain in notebooks
99
- **Markdown cells**: Text content stays in notebooks
100
- **Cell metadata**: Notebook-specific metadata preserved
101
- **Cell order**: Notebook structure maintained
102

103
## IDE Integration
104

105
### Supported Workflows
106

107
**VS Code Integration:**
108
```python
109
# Install Python extension for VS Code
110
# Edit .py files with full IntelliSense
111
# Use nbdev_update() to sync back to notebooks
112
```
113

114
**PyCharm Integration:**
115
```python
116
# Open exported Python modules in PyCharm
117
# Use refactoring tools, debugger, etc.
118
# Sync changes back with nbdev_update()
119
```
120

121
**Vim/Emacs Integration:**
122
```python
123
# Edit Python files with preferred editor
124
# Use language servers for Python support
125
# Sync back to notebooks when done
126
```
127

128
### Import Resolution
129

130
The sync system handles complex import scenarios:
131

132
```python
133
from nbdev.sync import absolute_import
134

135
# Handles relative imports
136
from .core import function_name
137

138
# Converts to absolute for IDE support
139
from mypackage.core import function_name
140

141
# Maintains compatibility with notebook environment
142
```
143

144
## Configuration
145

146
Synchronization respects project configuration:
147

148
```ini
149
# In settings.ini
150
lib_path = mylib
151
nbs_path = notebooks
152

153
# Sync will update notebooks in nbs_path based on 
154
# changes to Python files in lib_path
155
```
156

157
## Advanced Usage
158

159
### Selective Synchronization
160

161
```python
162
from nbdev.sync import nbdev_update
163
from pathlib import Path
164

165
# Update specific notebook
166
# (implementation varies - this shows the concept)
167
specific_nb = Path('notebooks/01_core.ipynb')
168
nbdev_update()  # Updates all notebooks including specific_nb
169
```
170

171
### Integration with Development Workflow
172

173
```python
174
from nbdev.sync import nbdev_update
175
from nbdev.export import nb_export
176
from nbdev.test import nbdev_test
177

178
def development_cycle():
179
    """Complete development cycle with sync."""
180
    
181
    # 1. Export notebooks to Python
182
    print("Exporting notebooks...")
183
    nb_export()
184
    
185
    # 2. Now edit Python files in your IDE
186
    print("Edit Python files in your IDE, then press Enter...")
187
    input()
188
    
189
    # 3. Sync changes back to notebooks
190
    print("Syncing changes back to notebooks...")
191
    nbdev_update()
192
    
193
    # 4. Run tests to verify everything works
194
    print("Running tests...")
195
    nbdev_test()
196
    
197
    print("Development cycle complete!")
198

199
development_cycle()
200
```
201

202
### Handling Conflicts
203

204
When synchronization encounters conflicts:
205

206
```python
207
# If sync detects conflicts, manual resolution may be needed
208
# The system will typically:
209
# 1. Warn about conflicts
210
# 2. Preserve notebook structure
211
# 3. Update code content where possible
212
# 4. Leave markers for manual review
213
```
214

215
## Best Practices
216

217
### Recommended Workflow
218

219
1. **Start with notebooks**: Write and test code in notebooks
220
2. **Export frequently**: Use `nb_export()` regularly
221
3. **IDE editing**: Make larger refactors in IDE
222
4. **Sync back**: Use `nbdev_update()` to bring changes back
223
5. **Test**: Always run `nbdev_test()` after syncing
224

225
### File Organization
226

227
```
228
project/
229
├── notebooks/          # Source notebooks
230
│   ├── 01_core.ipynb
231
│   └── 02_utils.ipynb
232
├── mylib/             # Exported Python modules
233
│   ├── core.py        # From 01_core.ipynb
234
│   └── utils.py       # From 02_utils.ipynb
235
└── settings.ini       # Configuration
236
```
237

238
### Team Collaboration
239

240
```python
241
# Team workflow with sync
242
from nbdev.sync import nbdev_update
243
from nbdev.export import nb_export
244

245
# Before starting work
246
nbdev_update()  # Get latest notebook updates
247

248
# After making changes in IDE
249
nb_export()     # Export to Python for others
250
# Commit both notebooks and Python files
251

252
# After pulling from team
253
nbdev_update()  # Update notebooks with team changes
254
```
255

256
### Automated Synchronization
257

258
```bash
259
# Git hooks can automate sync
260
# Pre-commit hook:
261
nbdev_export
262

263
# Post-merge hook:
264
nbdev_update
265
```
266

267
## Integration with Other nbdev Features
268

269
### With Testing
270

271
```python
272
from nbdev.sync import nbdev_update
273
from nbdev.test import nbdev_test
274

275
# After syncing, run tests
276
nbdev_update()
277
nbdev_test()  # Verify sync didn't break anything
278
```
279

280
### With Documentation
281

282
```python
283
from nbdev.sync import nbdev_update
284
from nbdev.doclinks import nbdev_export
285

286
# Sync and regenerate docs
287
nbdev_update()
288
nbdev_export()  # Update documentation
289
```
290

291
### With Cleaning
292

293
```python
294
from nbdev.sync import nbdev_update
295
from nbdev.clean import nbdev_clean
296

297
# Clean notebooks after sync
298
nbdev_update()
299
nbdev_clean()  # Clean up metadata
300
```
301

302
**Complete Sync Example:**
303

304
```python
305
from nbdev.sync import nbdev_update, absolute_import
306
from nbdev.export import nb_export
307
from nbdev.config import get_config
308

309
# Check configuration
310
config = get_config()
311
print(f"Syncing between {config.nbs_path} and {config.lib_path}")
312

313
# Export notebooks to enable IDE editing
314
nb_export()
315
print("Python modules ready for IDE editing")
316

317
# After editing in IDE, sync back
318
print("After editing Python files, sync back to notebooks:")
319
nbdev_update()
320
print("Notebooks updated with IDE changes")
321
```