0
# Gist Operations
1

2
Complete gist management including creation, editing, forking, commenting, file operations, and gist discovery.
3

4
## Capabilities
5

6
### Gist Access & Listing
7

8
Core operations for accessing and listing gists.
9

10
```python { .api }
11
class GitHub:
12
    def gist(self, id):
13
        """
14
        Get a gist by ID.
15
        
16
        Args:
17
            id (str): Gist ID
18
            
19
        Returns:
20
            Gist: Gist object or None if not found
21
        """
22

23
    def gists(self, type="owner"):
24
        """
25
        List the authenticated user's gists.
26
        
27
        Args:
28
            type (str): Gist type ('owner', 'public')
29
            
30
        Returns:
31
            iterator: Iterator of Gist objects
32
        """
33

34
    def gists_by(self, username, since=None):
35
        """
36
        List a user's public gists.
37
        
38
        Args:
39
            username (str): GitHub username
40
            since (str, optional): ISO 8601 timestamp
41
            
42
        Returns:
43
            iterator: Iterator of Gist objects
44
        """
45

46
    def public_gists(self, since=None):
47
        """
48
        List all public gists.
49
        
50
        Args:
51
            since (str, optional): ISO 8601 timestamp
52
            
53
        Returns:
54
            iterator: Iterator of Gist objects
55
        """
56

57
    def starred_gists(self):
58
        """
59
        List gists starred by the authenticated user.
60
        
61
        Returns:
62
            iterator: Iterator of Gist objects
63
        """
64
```
65

66
**Usage Examples:**
67

68
```python
69
import github3
70

71
gh = github3.login(token='your_token')
72

73
# Get a specific gist
74
gist = gh.gist('gist_id_here')
75
print(f"Gist: {gist.description}")
76
print(f"Files: {list(gist.files.keys())}")
77

78
# List user's gists
79
for gist in gh.gists():
80
    print(f"{gist.id}: {gist.description}")
81

82
# List public gists by user
83
for gist in gh.gists_by('octocat'):
84
    print(f"{gist.id}: {gist.description} - {gist.created_at}")
85
```
86

87
### Gist Creation & Management
88

89
Creating and managing gists.
90

91
```python { .api }
92
class GitHub:
93
    def create_gist(self, description, files, public=True):
94
        """
95
        Create a new gist.
96
        
97
        Args:
98
            description (str): Gist description
99
            files (dict): Dictionary of filename -> file content
100
            public (bool): Whether gist is public
101
            
102
        Returns:
103
            Gist: Created gist object
104
        """
105

106
class Gist:
107
    def edit(self, description=None, files=None):
108
        """
109
        Edit this gist.
110
        
111
        Args:
112
            description (str, optional): New description
113
            files (dict, optional): File updates
114
                - filename -> {'content': 'new content'} to update
115
                - filename -> {'filename': 'new_name', 'content': 'content'} to rename and update
116
                - filename -> None to delete
117
            
118
        Returns:
119
            bool: True if successful
120
        """
121

122
    def delete(self):
123
        """
124
        Delete this gist.
125
        
126
        Returns:
127
            bool: True if successful
128
        """
129
```
130

131
**Usage Examples:**
132

133
```python
134
# Create a gist with multiple files
135
files = {
136
    'hello.py': 'print("Hello, World!")',
137
    'README.md': '# My Gist\nThis is a sample gist.'
138
}
139
gist = gh.create_gist(
140
    description='Sample Python script',
141
    files=files,
142
    public=True
143
)
144
print(f"Created gist: {gist.html_url}")
145

146
# Edit the gist
147
gist.edit(
148
    description='Updated sample Python script',
149
    files={
150
        'hello.py': {'content': 'print("Hello, GitHub!")'},
151
        'new_file.txt': {'content': 'This is a new file.'},
152
        'README.md': None  # Delete this file
153
    }
154
)
155
```
156

157
### Gist Forking
158

159
Forking gists to create your own copies.
160

161
```python { .api }
162
class Gist:
163
    def create_fork(self):
164
        """
165
        Fork this gist.
166
        
167
        Returns:
168
            Gist: Forked gist object
169
        """
170

171
    def forks(self):
172
        """
173
        List forks of this gist.
174
        
175
        Returns:
176
            iterator: Iterator of GistFork objects
177
        """
178

179
    def is_starred(self):
180
        """
181
        Check if the authenticated user has starred this gist.
182
        
183
        Returns:
184
            bool: True if starred
185
        """
186

187
    def star(self):
188
        """
189
        Star this gist.
190
        
191
        Returns:
192
            bool: True if successful
193
        """
194

195
    def unstar(self):
196
        """
197
        Unstar this gist.
198
        
199
        Returns:
200
            bool: True if successful
201
        """
202
```
203

204
### Gist Comments
205

206
Managing comments on gists.
207

208
```python { .api }
209
class Gist:
210
    def comments(self):
211
        """
212
        List comments on this gist.
213
        
214
        Returns:
215
            iterator: Iterator of GistComment objects
216
        """
217

218
    def create_comment(self, body):
219
        """
220
        Create a comment on this gist.
221
        
222
        Args:
223
            body (str): Comment text
224
            
225
        Returns:
226
            GistComment: Created comment object
227
        """
228

229
class GistComment:
230
    def edit(self, body):
231
        """
232
        Edit this comment.
233
        
234
        Args:
235
            body (str): New comment text
236
            
237
        Returns:
238
            bool: True if successful
239
        """
240

241
    def delete(self):
242
        """
243
        Delete this comment.
244
        
245
        Returns:
246
            bool: True if successful
247
        """
248
```
249

250
### Gist History
251

252
Accessing gist revision history.
253

254
```python { .api }
255
class Gist:
256
    def history(self):
257
        """
258
        Get revision history for this gist.
259
        
260
        Returns:
261
            list: List of GistHistory objects
262
        """
263

264
    def revision(self, sha):
265
        """
266
        Get a specific revision of this gist.
267
        
268
        Args:
269
            sha (str): Revision SHA
270
            
271
        Returns:
272
            Gist: Gist object at specified revision
273
        """
274
```
275

276
### Gist Files
277

278
Accessing individual gist files.
279

280
```python { .api }
281
class Gist:
282
    def files(self):
283
        """
284
        Get files in this gist.
285
        
286
        Returns:
287
            dict: Dictionary of filename -> GistFile objects
288
        """
289

290
class GistFile:
291
    def content(self):
292
        """
293
        Get the raw content of this file.
294
        
295
        Returns:
296
            str: File content
297
        """
298
```
299

300
## Gist Model Classes
301

302
```python { .api }
303
class Gist:
304
    """Full gist object with all data and methods."""
305
    id: str
306
    description: str
307
    public: bool
308
    owner: 'User'
309
    user: 'User'  # Alias for owner
310
    files: dict  # filename -> GistFile
311
    truncated: bool
312
    comments: int
313
    comments_url: str
314
    html_url: str
315
    git_pull_url: str
316
    git_push_url: str
317
    created_at: str
318
    updated_at: str
319
    
320
    def edit(self, **kwargs): ...
321
    def delete(self): ...
322
    def create_fork(self): ...
323
    def create_comment(self, body): ...
324
    def star(self): ...
325
    def is_starred(self): ...
326

327
class ShortGist:
328
    """Abbreviated gist object for listings."""
329
    id: str
330
    description: str
331
    public: bool
332
    owner: 'ShortUser'
333
    files: dict
334
    created_at: str
335
    updated_at: str
336

337
class GistFile:
338
    """Individual file in a gist."""
339
    filename: str
340
    type: str
341
    language: str
342
    raw_url: str
343
    size: int
344
    truncated: bool
345
    content: str
346
    
347
    def content(self): ...
348

349
class ShortGistFile:
350
    """Abbreviated gist file object."""
351
    filename: str
352
    type: str
353
    size: int
354

355
class GistComment:
356
    """Comment on a gist."""
357
    id: int
358
    url: str
359
    body: str
360
    user: 'User'
361
    created_at: str
362
    updated_at: str
363
    
364
    def edit(self, body): ...
365
    def delete(self): ...
366

367
class GistHistory:
368
    """Gist revision history entry."""
369
    version: str
370
    user: 'User'
371
    change_status: dict  # additions, deletions, total
372
    committed_at: str
373
    url: str
374

375
class GistFork:
376
    """Fork of a gist."""
377
    id: str
378
    url: str
379
    user: 'User'
380
    created_at: str
381
    updated_at: str
382
```
383

384
## Usage Patterns
385

386
### Creating Multi-File Gists
387

388
```python
389
# Create a gist with multiple related files
390
files = {
391
    'script.py': '''
392
#!/usr/bin/env python3
393
"""Sample script"""
394
print("Hello, World!")
395
''',
396
    'requirements.txt': 'requests>=2.25.0\nclick>=7.0',
397
    'README.md': '''
398
# Sample Script
399

400
This is a sample Python script.
401

402
## Usage
403

404
```bash
405
python script.py
406
```
407
'''
408
}
409

410
gist = gh.create_gist(
411
    description='Sample Python project',
412
    files=files,
413
    public=True
414
)
415
```
416
417
### Gist as Pastebin
418

419
```python
420
# Quick code sharing
421
code = '''
422
def fibonacci(n):
423
    if n <= 1:
424
        return n
425
    return fibonacci(n-1) + fibonacci(n-2)
426
'''
427

428
gist = gh.create_gist(
429
    description='Fibonacci function',
430
    files={'fibonacci.py': code},
431
    public=False  # Private gist
432
)
433
print(f"Share this link: {gist.html_url}")
434
```