1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
# Python API for Silver-Platter
This document describes the Python API for Silver-Platter, which provides programmatic access to Silver-Platter's functionality for automating code changes across repositories.
## Installation
```bash
pip install silver-platter
```
## Overview
The Python API allows you to:
- Create workspaces for making changes to repositories
- Commit changes with appropriate metadata
- Publish changes as pull requests or direct pushes
- Handle Debian package repositories with specialized support
## Core Classes
### Workspace
The `Workspace` class is the primary interface for making changes to repositories. It exists in two forms:
* `silver_platter.Workspace` - For generic projects
* `silver_platter.debian.Workspace` - For Debian packages (with additional Debian-specific methods)
### Basic Usage
```python
from silver_platter import Workspace
# Create workspace from URL
with Workspace.from_url("https://github.com/user/repo") as ws:
# Make changes in ws.path
with open(os.path.join(ws.path, "README.md"), "a") as f:
f.write("\n## New Section\n")
# Commit if there are changes
if ws.any_branch_changes():
ws.commit(message="Add new section to README")
ws.publish(mode="propose")
```
### Debian Package Example
```python
from silver_platter.debian import Workspace
import subprocess
with Workspace.from_apt_package(package="dulwich") as ws:
# Make changes using Debian tools
subprocess.check_call(['dch', 'Fix important bug'], cwd=ws.path)
# Commit using debcommit-like behavior
ws.commit()
# Create merge proposal
ws.publish(mode='propose')
```
## Key Methods
### Workspace Creation
- `Workspace.from_url(url)` - Create workspace from repository URL
- `Workspace.from_apt_package(package)` - Create workspace for Debian package (Debian workspace only)
### Change Detection
- `ws.any_branch_changes()` - Check if there are any uncommitted changes
- `ws.changes_since_base()` - Check for changes since the base revision
- `ws.changes_since_main()` - Check for changes since the main branch
### Publishing Changes
- `ws.publish(mode, ...)` - Publish changes
- `mode='propose'` - Create a merge/pull request
- `mode='push'` - Push directly to the branch
- `mode='attempt-push'` - Try pushing, fall back to propose if needed
## Advanced Features
### Working with Resume Branches
When creating a workspace, you can resume from a previous branch:
```python
with Workspace(
main_branch=main,
resume_branch=previous_branch,
cached_branch=cache
) as ws:
# Continue work from previous branch
...
```
### Custom Merge Proposals
```python
def get_description():
return "This PR fixes issue #123\n\nDetailed description..."
def get_title():
return "Fix: Resolve critical bug in parser"
result = publish_changes(
local_branch=ws.local_tree.branch,
main_branch=ws.main_branch,
mode="propose",
name="fix-parser-bug",
get_proposal_description=get_description,
get_proposal_title=get_title,
labels=["bug", "critical"],
reviewers=["reviewer1", "reviewer2"]
)
```
## Error Handling
```python
from silver_platter import (
EmptyMergeProposal,
InsufficientChangesForNewProposal
)
try:
ws.publish(mode="propose")
except EmptyMergeProposal:
print("No changes to propose")
except InsufficientChangesForNewProposal:
print("Changes too small for a new proposal")
```
## Integration with Codemods
For running codemods that follow the Silver-Platter protocol, see the [Codemod Protocol](codemod-protocol.md) documentation.
## Complete Example
```python
from silver_platter import Workspace
import os
import subprocess
def update_dependencies(repo_url):
"""Update dependencies in a repository."""
with Workspace.from_url(repo_url) as ws:
# Run dependency update tool
subprocess.run(
["npm", "update"],
cwd=ws.path,
check=True
)
# Check if package-lock.json changed
if ws.any_branch_changes():
# Commit the changes
ws.commit(message="Update npm dependencies")
# Create pull request
result = ws.publish(
mode="propose",
name="update-dependencies",
description="Automated dependency update",
labels=["dependencies", "automated"]
)
print(f"Created PR: {result.proposal.url}")
else:
print("No dependency updates needed")
# Use it
update_dependencies("https://github.com/user/my-project")
```
## See Also
- [Main Documentation](README.md) - Overview and CLI usage
- [Codemod Protocol](codemod-protocol.md) - Writing compatible codemods
- [API Reference](https://pypi.org/project/silver-platter/) - Full API documentation on PyPI
|
