0
# Pygifsicle
1

2
Python package wrapping the gifsicle library for editing and optimizing GIF images. Provides a simple Python interface to the powerful gifsicle command-line tool, enabling GIF optimization and manipulation from Python scripts.
3

4
## Package Information
5

6
- **Package Name**: pygifsicle
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install pygifsicle`
10
- **External Dependency**: gifsicle binary (automatically installed on macOS via brew)
11

12
## Core Imports
13

14
```python
15
from pygifsicle import gifsicle, optimize
16
```
17

18
## Basic Usage
19

20
```python
21
from pygifsicle import optimize
22

23
# Simple optimization - overwrites original file
24
optimize("my_animation.gif")
25

26
# Optimization with destination file
27
optimize("source.gif", "optimized.gif")
28

29
# Using pathlib Path objects
30
from pathlib import Path
31
source_path = Path("animations/big_file.gif")
32
dest_path = Path("animations/small_file.gif")
33
optimize(source_path, dest_path)
34
```
35

36
## Capabilities
37

38
### GIF Optimization
39

40
Optimizes GIF files using gifsicle with the `--optimize` flag enabled. This is the most common use case for reducing GIF file sizes while maintaining visual quality.
41

42
```python { .api }
43
def optimize(source: Union[str, Path], destination: Optional[str] = None, **kwargs) -> None:
44
    """
45
    Optimize given gif using gifsicle with optimize flag enabled.
46

47
    Parameters:
48
    - source: Union[str, Path] - Path to gif image to optimize
49
    - destination: Optional[str] - Output path (defaults to overwrite source)
50
    - **kwargs - Additional arguments passed to gifsicle function (colors, options)
51

52
    Raises:
53
    - ValueError: If source path doesn't exist or is not a gif file
54
    - FileNotFoundError: If gifsicle binary is not found on system
55
    """
56
```
57

58
### General GIF Processing
59

60
Provides full access to gifsicle functionality with customizable options, colors, and processing parameters. Supports single files, multiple files, and file merging operations.
61

62
```python { .api }
63
def gifsicle(
64
    sources: Union[List[str], str, List[Path], Path],
65
    destination: Optional[str] = None,
66
    optimize: bool = False,
67
    colors: int = 256,
68
    options: Optional[List[str]] = None,
69
) -> None:
70
    """
71
    Apply gifsicle with given options to image at given paths.
72

73
    Parameters:
74
    - sources: Union[List[str], str, List[Path], Path] - Path or paths to gif(s) to process
75
    - destination: Optional[str] - Output path (defaults to overwrite first source)
76
    - optimize: bool - Whether to add optimize flag (default: False)
77
    - colors: int - Number of colors to use, must be power of 2 (default: 256)
78
    - options: Optional[List[str]] - Additional gifsicle command-line options
79

80
    Raises:
81
    - ValueError: If source path doesn't exist, source is not a gif, or destination is not a gif
82
    - FileNotFoundError: If gifsicle binary is not found on system
83
    """
84
```
85

86
## Usage Examples
87

88
### Single File Optimization
89

90
```python
91
from pygifsicle import optimize
92

93
# Optimize in place
94
optimize("animation.gif")
95

96
# Optimize to new file
97
optimize("large_animation.gif", "small_animation.gif")
98
```
99

100
### Advanced Processing with Custom Options
101

102
```python
103
from pygifsicle import gifsicle
104

105
# Merge multiple GIFs into one optimized file
106
gifsicle(
107
    sources=["part1.gif", "part2.gif", "part3.gif"],
108
    destination="merged.gif",
109
    optimize=True,
110
    colors=128,
111
    options=["--verbose"]
112
)
113

114
# Process with custom color reduction
115
gifsicle(
116
    sources="input.gif",
117
    destination="output.gif",
118
    colors=64,
119
    options=["--lossy=80"]
120
)
121
```
122

123
### Using Path Objects
124

125
```python
126
from pygifsicle import optimize, gifsicle
127
from pathlib import Path
128

129
# With Path objects
130
input_file = Path("animations/source.gif")
131
output_file = Path("animations/optimized.gif")
132

133
optimize(input_file, output_file)
134

135
# Multiple Path objects
136
sources = [Path("gif1.gif"), Path("gif2.gif")]
137
gifsicle(sources, destination="combined.gif", optimize=True)
138
```
139

140
## Types
141

142
```python { .api }
143
from typing import Union, List, Optional
144
from pathlib import Path
145

146
# Core types used in the API
147
str = str  # Built-in string type
148
Path = pathlib.Path  # pathlib Path objects for file paths
149
Union[str, Path] = Union[str, Path]  # Either string or Path object
150
List[str] = List[str]  # List of strings
151
Optional[str] = Optional[str]  # Optional string parameter
152
```
153

154
## Error Handling
155

156
### ValueError
157

158
Raised when:
159
- Source file path does not exist
160
- Source file is not a GIF image (doesn't end with .gif)
161
- Destination path is not a GIF image
162

163
### FileNotFoundError
164

165
Raised when the gifsicle binary is not found on the system. The error message includes installation instructions:
166
- macOS: Automatically installed via brew during pip install
167
- Linux: Install via `sudo apt-get install gifsicle` (Ubuntu/Debian) or equivalent
168
- Windows: Download from https://eternallybored.org/misc/gifsicle/
169

170
## Installation Requirements
171

172
### Python Dependencies
173
- Python 3.x
174
- Standard library only (typing, subprocess, os, pathlib)
175

176
### System Dependencies
177
- **gifsicle binary**: Must be installed and available in system PATH
178
- Installation is automatically attempted on macOS via brew
179
- Manual installation required on Linux and Windows (instructions provided during pip install)
180

181
## Common Patterns
182

183
### Batch Processing
184

185
```python
186
from pygifsicle import optimize
187
import os
188

189
# Optimize all GIFs in a directory
190
gif_dir = "animations/"
191
for filename in os.listdir(gif_dir):
192
    if filename.endswith(".gif"):
193
        filepath = os.path.join(gif_dir, filename)
194
        optimize(filepath)
195
```
196

197
### Error Handling
198

199
```python
200
from pygifsicle import optimize
201

202
try:
203
    optimize("animation.gif")
204
except FileNotFoundError:
205
    print("gifsicle not installed. Please install gifsicle binary.")
206
except ValueError as e:
207
    print(f"Invalid file: {e}")
208
```