0
# Configuration and Utilities
1
2
System configuration, metadata information, string cache management, API extensions, and plugin support for customizing Polars behavior and extending functionality.
3
4
## Capabilities
5
6
### Configuration Management
7
8
Global configuration system for controlling display formatting, performance settings, and runtime behavior.
9
10
```python { .api }
11
class Config:
12
"""
13
Global configuration manager for Polars settings.
14
15
Controls display formatting, performance parameters, and debugging options.
16
"""
17
18
def set_fmt_float(self, fmt: FloatFmt = "mixed") -> type[Config]:
19
"""
20
Set float formatting option.
21
22
Parameters:
23
- fmt: Float format ("mixed", "full", or custom format string)
24
25
Returns:
26
Config class for method chaining
27
"""
28
29
def set_fmt_str_lengths(self, n: int) -> type[Config]:
30
"""
31
Set maximum string length for display.
32
33
Parameters:
34
- n: Maximum string length
35
36
Returns:
37
Config class for method chaining
38
"""
39
40
def set_tbl_cols(self, n: int) -> type[Config]:
41
"""
42
Set maximum number of columns to display.
43
44
Parameters:
45
- n: Maximum number of columns
46
47
Returns:
48
Config class for method chaining
49
"""
50
51
def set_tbl_rows(self, n: int) -> type[Config]:
52
"""
53
Set maximum number of rows to display.
54
55
Parameters:
56
- n: Maximum number of rows
57
58
Returns:
59
Config class for method chaining
60
"""
61
62
def set_tbl_width_chars(self, width: int) -> type[Config]:
63
"""
64
Set table width in characters.
65
66
Parameters:
67
- width: Table width in characters
68
69
Returns:
70
Config class for method chaining
71
"""
72
73
def set_tbl_formatting(self, formatting: TableFormatNames) -> type[Config]:
74
"""
75
Set table formatting style.
76
77
Parameters:
78
- formatting: Table format style
79
80
Returns:
81
Config class for method chaining
82
"""
83
84
def set_streaming_chunk_size(self, size: int) -> type[Config]:
85
"""
86
Set streaming chunk size for processing.
87
88
Parameters:
89
- size: Chunk size in bytes
90
91
Returns:
92
Config class for method chaining
93
"""
94
95
def set_verbose(self, active: bool = True) -> type[Config]:
96
"""
97
Set verbose logging mode.
98
99
Parameters:
100
- active: Enable verbose logging
101
102
Returns:
103
Config class for method chaining
104
"""
105
106
def load(self, file: str | Path) -> type[Config]:
107
"""
108
Load configuration from JSON file.
109
110
Parameters:
111
- file: Path to configuration file
112
113
Returns:
114
Config class for method chaining
115
"""
116
117
def save(self, file: str | Path, *, set_as_default: bool = False) -> type[Config]:
118
"""
119
Save current configuration to JSON file.
120
121
Parameters:
122
- file: Path to save configuration
123
- set_as_default: Set as default configuration
124
125
Returns:
126
Config class for method chaining
127
"""
128
129
def restore_defaults(self) -> type[Config]:
130
"""
131
Restore default configuration settings.
132
133
Returns:
134
Config class for method chaining
135
"""
136
137
@contextlib.contextmanager
138
def __call__(self, **kwargs: Any) -> Config:
139
"""
140
Context manager for temporary configuration changes.
141
142
Parameters:
143
- kwargs: Configuration parameters to set temporarily
144
145
Returns:
146
Config context manager
147
"""
148
```
149
150
### Meta Information
151
152
Functions for retrieving information about the Polars installation and runtime environment.
153
154
```python { .api }
155
def build_info() -> dict[str, Any]:
156
"""
157
Get build information for the Polars installation.
158
159
Returns:
160
Dictionary containing build details (version, commit, features, etc.)
161
"""
162
163
def show_versions() -> None:
164
"""
165
Print version information for Polars and optional dependencies.
166
167
Displays versions of Polars, Python, and installed optional packages.
168
"""
169
170
def get_index_type() -> str:
171
"""
172
Get the index type used by this Polars build.
173
174
Returns:
175
Index type ("UInt32" for standard, "UInt64" for u64-idx variant)
176
"""
177
178
def thread_pool_size() -> int:
179
"""
180
Get the size of the global thread pool.
181
182
Returns:
183
Number of threads in the global thread pool
184
"""
185
186
def threadpool_size() -> int:
187
"""
188
Get the size of the global thread pool (alias for thread_pool_size).
189
190
Returns:
191
Number of threads in the global thread pool
192
"""
193
```
194
195
### String Cache Management
196
197
Global string cache for optimizing categorical data operations across DataFrames.
198
199
```python { .api }
200
class StringCache:
201
"""
202
Context manager for enabling and disabling the global string cache.
203
204
Categorical columns created under the same global string cache have
205
the same underlying physical value when string values are equal, allowing
206
concatenation and join operations.
207
"""
208
209
def __enter__(self) -> StringCache:
210
"""Enable the global string cache."""
211
212
def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
213
"""Disable and clear the global string cache."""
214
215
def enable_string_cache() -> None:
216
"""
217
Enable the global string cache.
218
219
This allows categorical columns with the same string values
220
to be concatenated or joined.
221
"""
222
223
def disable_string_cache() -> None:
224
"""
225
Disable and clear the global string cache.
226
227
This frees memory used by the string cache but prevents
228
categorical operations across separately created DataFrames.
229
"""
230
231
def using_string_cache() -> bool:
232
"""
233
Check if the global string cache is currently enabled.
234
235
Returns:
236
True if the global string cache is enabled
237
"""
238
```
239
240
### API Extensions
241
242
Functions for registering custom namespaces to extend Polars classes with user-defined functionality.
243
244
```python { .api }
245
def register_dataframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
246
"""
247
Register a custom namespace for DataFrame objects.
248
249
Parameters:
250
- name: Namespace name (will be accessible as df.name)
251
252
Returns:
253
Decorator function for namespace class
254
"""
255
256
def register_lazyframe_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
257
"""
258
Register a custom namespace for LazyFrame objects.
259
260
Parameters:
261
- name: Namespace name (will be accessible as lf.name)
262
263
Returns:
264
Decorator function for namespace class
265
"""
266
267
def register_series_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
268
"""
269
Register a custom namespace for Series objects.
270
271
Parameters:
272
- name: Namespace name (will be accessible as s.name)
273
274
Returns:
275
Decorator function for namespace class
276
"""
277
278
def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
279
"""
280
Register a custom namespace for Expr objects.
281
282
Parameters:
283
- name: Namespace name (will be accessible as expr.name)
284
285
Returns:
286
Decorator function for namespace class
287
"""
288
```
289
290
### Plugin Support
291
292
System for registering and using external plugin functions written in Rust.
293
294
```python { .api }
295
def register_plugin_function(
296
*,
297
plugin_path: Path | str,
298
function_name: str,
299
args: IntoExpr | Iterable[IntoExpr],
300
kwargs: dict[str, Any] | None = None,
301
is_elementwise: bool = False,
302
changes_length: bool = False,
303
returns_scalar: bool = False,
304
cast_to_supertype: bool = False,
305
input_wildcard_expansion: bool = False,
306
pass_name_to_apply: bool = False,
307
use_abs_path: bool = False
308
) -> Expr:
309
"""
310
Register a plugin function from a dynamic library.
311
312
Parameters:
313
- plugin_path: Path to the plugin dynamic library or directory
314
- function_name: Name of the Rust function to register
315
- args: Expression arguments to pass to the function
316
- kwargs: Keyword arguments for the function
317
- is_elementwise: Function operates element-wise
318
- changes_length: Function may change output length
319
- returns_scalar: Function returns a scalar value
320
- cast_to_supertype: Cast inputs to common supertype
321
- input_wildcard_expansion: Expand wildcard expressions
322
- pass_name_to_apply: Pass column name to function
323
- use_abs_path: Use absolute path for plugin resolution
324
325
Returns:
326
Expression that calls the plugin function
327
"""
328
```
329
330
## Usage Examples
331
332
### Configuration Management
333
334
```python
335
import polars as pl
336
337
# Temporary configuration changes
338
with pl.Config(set_tbl_cols=5, set_tbl_rows=10):
339
print(df) # Limited to 5 columns, 10 rows
340
341
# Permanent configuration changes
342
pl.Config.set_fmt_float("full")
343
pl.Config.set_tbl_formatting("ASCII_MARKDOWN")
344
345
# Save and load configuration
346
pl.Config.save("my_config.json")
347
pl.Config.load("my_config.json")
348
```
349
350
### String Cache Usage
351
352
```python
353
import polars as pl
354
355
# Context manager approach
356
with pl.StringCache():
357
df1 = pl.DataFrame({"cat": ["A", "B", "C"]}).with_columns(
358
pl.col("cat").cast(pl.Categorical)
359
)
360
df2 = pl.DataFrame({"cat": ["A", "B", "D"]}).with_columns(
361
pl.col("cat").cast(pl.Categorical)
362
)
363
# These can now be concatenated
364
result = pl.concat([df1, df2])
365
366
# Function approach
367
pl.enable_string_cache()
368
# ... create categorical columns ...
369
pl.disable_string_cache()
370
```
371
372
### API Extensions
373
374
```python
375
import polars as pl
376
377
@pl.register_dataframe_namespace("business")
378
class BusinessAccessor:
379
def __init__(self, df: pl.DataFrame):
380
self._df = df
381
382
def calculate_revenue(self) -> pl.DataFrame:
383
return self._df.with_columns(
384
(pl.col("price") * pl.col("quantity")).alias("revenue")
385
)
386
387
# Usage
388
df = pl.DataFrame({"price": [10, 20], "quantity": [5, 3]})
389
revenue_df = df.business.calculate_revenue()
390
```
391
392
### Plugin Usage
393
394
```python
395
import polars as pl
396
397
# Register and use a custom plugin function
398
expr = pl.register_plugin_function(
399
plugin_path="./my_plugin.so",
400
function_name="custom_transform",
401
args=[pl.col("data")],
402
is_elementwise=True
403
)
404
405
result = df.with_columns(expr.alias("transformed"))
406
```