0
# WebAssets
1

2
A comprehensive media asset management system for Python web development that enables developers to merge, compress, and optimize JavaScript and CSS files. WebAssets offers a flexible bundle-based architecture for defining asset groups, supports numerous built-in filters for processing assets, and integrates seamlessly with popular web frameworks through dedicated adapters.
3

4
## Package Information
5

6
- **Package Name**: webassets
7
- **Language**: Python
8
- **Installation**: `pip install webassets`
9
- **Dependencies**: `pyyaml>=6.0.2`, `zope-dottedname>=6.0`
10

11
## Core Imports
12

13
```python
14
from webassets import Bundle, Environment
15
from webassets.filter import get_filter, register_filter
16
from webassets.loaders import YAMLLoader, PythonLoader, GlobLoader
17
```
18

19
For command-line usage:
20
```bash
21
webassets build
22
```
23

24
## Basic Usage
25

26
```python
27
from webassets import Environment, Bundle
28

29
# Create an environment (manages bundles and configuration)
30
env = Environment('./static', '/static')
31

32
# Define a JavaScript bundle
33
js_bundle = Bundle(
34
    'jquery.js',
35
    'app.js',
36
    'utils.js',
37
    filters='jsmin',
38
    output='gen/packed.js'
39
)
40

41
# Define a CSS bundle
42
css_bundle = Bundle(
43
    'style.css',
44
    'layout.css',
45
    filters='cssmin',
46
    output='gen/packed.css'
47
)
48

49
# Register bundles with the environment
50
env.register('js_all', js_bundle)
51
env.register('css_all', css_bundle)
52

53
# Build bundles (creates optimized output files)
54
js_bundle.build()
55
css_bundle.build()
56

57
# Get URLs for templates
58
js_urls = js_bundle.urls()
59
css_urls = css_bundle.urls()
60
```
61

62
## Architecture
63

64
WebAssets follows a modular architecture centered around three core concepts:
65

66
- **Environment**: Central configuration manager that owns bundles and processing settings
67
- **Bundle**: Asset grouping unit that defines input files, filters, and output destinations
68
- **Filter**: Processing plugin that transforms assets (minification, compilation, optimization)
69

70
This design enables flexible asset pipelines where bundles can be nested arbitrarily, filters can be chained for complex transformations, and the entire system integrates cleanly with web frameworks through environment adapters.
71

72
## Capabilities
73

74
### Bundle Management
75

76
Core functionality for creating, configuring, and managing asset bundles that group related files together for processing.
77

78
```python { .api }
79
class Bundle:
80
    def __init__(self, *contents, **options): ...
81
    def build(self, force=None, output=None, disable_cache=None): ...
82
    def urls(self, *args, **kwargs): ...
83
    def bind(self, env): ...
84
    def resolve_contents(self, ctx=None, force=False): ...
85
    def resolve_output(self, ctx=None, version=None): ...
86
    def get_version(self, ctx=None, refresh=False): ...
87
    def id(self): ...
88
    def iterbuild(self, ctx): ...
89

90
def get_all_bundle_files(bundle, ctx=None): ...
91
```
92

93
[Bundle Management](./bundle-management.md)
94

95
### Environment Configuration
96

97
Environment management for configuring asset processing, including directory paths, URL mapping, caching, and version management.
98

99
```python { .api }
100
class Environment:
101
    def __init__(self, directory=None, url=None, **more_config): ...
102
    def register(self, name, *args, **kwargs): ...
103
    def add(self, *bundles): ...
104
    def append_path(self, path, url=None): ...
105
    
106
    # Properties
107
    @property
108
    def load_path(self): ...
109
    @property
110
    def resolver(self): ...
111
    @property
112
    def updater(self): ...
113
    @property
114
    def versioner(self): ...
115
    @property
116
    def manifest(self): ...
117
    @property
118
    def cache(self): ...
119
```
120

121
[Environment Configuration](./environment-configuration.md)
122

123
### Filter System
124

125
Comprehensive filter ecosystem for asset transformation including minification, compilation, preprocessing, and optimization.
126

127
```python { .api }
128
class Filter:
129
    def input(self, _in, out, **kw): ...
130
    def output(self, _in, out, **kw): ...
131
    def setup(self): ...
132

133
def get_filter(f, *args, **kwargs): ...
134
def register_filter(f): ...
135
```
136

137
Built-in filters include JavaScript minifiers (JSMin, UglifyJS, Closure), CSS processors (CSSMin, CleanCSS, AutoPrefixer), and preprocessors (Sass, Less, TypeScript, Babel).
138

139
[Filter System](./filter-system.md)
140

141
### Configuration Loading
142

143
Flexible configuration loading from YAML files, Python modules, and programmatic sources.
144

145
```python { .api }
146
class YAMLLoader:
147
    def __init__(self, file_or_filename): ...
148
    def load_bundles(self): ...
149
    def load_environment(self): ...
150

151
class PythonLoader: ...
152
class GlobLoader: ...
153
```
154

155
[Configuration Loading](./configuration-loading.md)
156

157
### Caching and Versioning
158

159
Advanced caching and versioning system for optimizing build performance and managing asset updates.
160

161
```python { .api }
162
class FilesystemCache: ...
163
class MemoryCache: ...
164

165
def get_cache(cache_option, env=None): ...
166

167
class TimestampVersion: ...
168
class HashVersion: ...
169
class FileManifest: ...
170
```
171

172
[Caching and Versioning](./caching-versioning.md)
173

174
### Command Line Interface
175

176
Comprehensive command-line tools for building assets, managing bundles, and integrating with deployment workflows.
177

178
```python { .api }
179
class CommandLineEnvironment: ...
180
class BuildCommand: ...
181

182
def main(argv=None): ...
183
```
184

185
Command-line usage:
186
```bash
187
webassets build
188
webassets watch
189
webassets clean
190
```
191

192
[Command Line Interface](./command-line.md)
193

194
### Framework Integration
195

196
Extensions and adapters for integrating with popular Python web frameworks.
197

198
```python { .api }
199
class AssetsExtension: ...  # Jinja2 integration
200
class Jinja2Loader: ...
201

202
def assets(): ...  # Template function
203
```
204

205
[Framework Integration](./framework-integration.md)
206

207
### Updater System
208

209
Auto-rebuild system that determines when bundles need rebuilding based on timestamps, bundle definitions, and dependencies.
210

211
```python { .api }
212
class BaseUpdater:
213
    def needs_rebuild(self, bundle, ctx): ...
214
    def build_done(self, bundle, ctx): ...
215

216
class TimestampUpdater(BaseUpdater):
217
    id = 'timestamp'
218
    def check_timestamps(self, bundle, ctx, o_modified=None): ...
219

220
class AlwaysUpdater(BaseUpdater):
221
    id = 'always'
222

223
def get_updater(updater_id): ...
224
```
225

226
[Updater System](./updater-system.md)
227

228
### Merge System
229

230
Core functionality for managing asset content through data abstractions (hunks) and filter application tools.
231

232
```python { .api }
233
class BaseHunk:
234
    def data(self): ...
235
    def save(self, filename): ...
236

237
class FileHunk(BaseHunk): ...
238
class UrlHunk(BaseHunk): ...
239
class MemoryHunk(BaseHunk): ...
240

241
class FilterTool:
242
    def apply(self, hunk, filters, type, kwargs=None): ...
243
    def apply_func(self, filters, type, args, kwargs=None, cache_key=None): ...
244

245
def merge(hunks, separator=None): ...
246
def merge_filters(filters1, filters2): ...
247
```
248

249
[Merge System](./merge-system.md)
250

251
### Utilities
252

253
Essential utility functions including path operations, context managers, object resolution, and security features.
254

255
```python { .api }
256
def hash_func(data): ...
257
def common_path_prefix(paths, sep=os.path.sep): ...
258
def is_url(s): ...
259

260
@contextlib.contextmanager
261
def working_directory(directory=None, filename=None): ...
262

263
def make_option_resolver(clazz=None, attribute=None, classes=None, allow_none=True, desc=None): ...
264
def RegistryMetaclass(clazz=None, attribute=None, allow_none=True, desc=None): ...
265
def cmp_debug_levels(level1, level2): ...
266

267
def calculate_sri(data): ...
268
def calculate_sri_on_file(file_name): ...
269
```
270

271
[Utilities](./utilities.md)
272

273
## Types
274

275
```python { .api }
276
class BundleError(Exception): ...
277
class BuildError(BundleError): ...
278
class FilterError(BuildError): ...
279
class RegisterError(Exception): ...
280
class EnvironmentError(Exception): ...
281
class VersionIndeterminableError(Exception): ...
282
class LoaderError(Exception): ...
283
class CommandError(Exception): ...
284
class ImminentDeprecationWarning(Warning): ...
285
```