0
# FastCore
1

2
A foundational Python library providing core utilities for the fastai ecosystem. FastCore offers a comprehensive collection of functional programming tools, enhanced data structures, testing utilities, and system integration helpers that serve as building blocks for modern Python development.
3

4
## Package Information
5

6
- **Package Name**: fastcore
7
- **Version**: 1.8.8
8
- **Language**: Python
9
- **Installation**: `pip install fastcore`
10
- **Repository**: https://github.com/fastai/fastcore
11

12
## Core Imports
13

14
```python { .api }
15
import fastcore
16
```
17

18
For accessing all public APIs:
19

20
```python { .api }
21
from fastcore.all import *
22
```
23

24
For specific functionality:
25

26
```python { .api }
27
from fastcore.basics import *      # Core utilities and data structures
28
from fastcore.foundation import *  # Collection classes (L) and config
29
from fastcore.test import *        # Testing framework
30
from fastcore.xtras import *       # Extended functionality
31
from fastcore.parallel import *    # Parallel processing
32
from fastcore.net import *         # Network utilities
33
from fastcore.meta import *        # Metaprogramming tools
34
from fastcore.xml import *         # HTML/XML generation
35
```
36

37
## Basic Usage
38

39
### Essential Utilities
40

41
```python { .api }
42
from fastcore.basics import ifnone, listify, AttrDict
43

44
# Null-safe operations
45
result = ifnone(None, "default")  # Returns "default"
46
result = ifnone("value", "default")  # Returns "value"
47

48
# Convert objects to lists
49
items = listify("single_item")  # Returns ["single_item"]
50
items = listify([1, 2, 3])      # Returns [1, 2, 3]
51

52
# Dictionary with attribute access
53
config = AttrDict({"model": "resnet", "lr": 0.01})
54
print(config.model)  # Access like attribute: "resnet"
55
config.batch_size = 32  # Set like attribute
56
```
57

58
### Enhanced Collections
59

60
```python { .api }
61
from fastcore.foundation import L
62

63
# Enhanced list with functional operations
64
data = L([1, 2, 3, 4, 5])
65
filtered = data.filter(lambda x: x > 2)  # L([3, 4, 5])
66
mapped = data.map(lambda x: x * 2)       # L([2, 4, 6, 8, 10])
67
first_item = data.first()                # 1
68

69
# Chaining operations
70
result = L(range(10)).filter(lambda x: x % 2 == 0).map(str)
71
# Result: L(['0', '2', '4', '6', '8'])
72
```
73

74
### Testing Framework
75

76
```python { .api }
77
from fastcore.test import test_eq, test_close, test_fail
78

79
# Equality testing with informative errors
80
test_eq([1, 2, 3], [1, 2, 3])  # Passes
81
test_close(3.14159, 3.14160, eps=1e-4)  # Passes
82

83
# Exception testing
84
test_fail(lambda: 1/0, contains="division")  # Tests ZeroDivisionError
85
```
86

87
## Architecture
88

89
FastCore is organized into focused modules that build upon each other:
90

91
### Core Foundation
92
- **basics.py**: Fundamental utilities, data structures, and functional helpers
93
- **foundation.py**: Enhanced collection classes and configuration management
94
- **imports.py**: Common imports and compatibility utilities
95

96
### Specialized Capabilities
97
- **test.py**: Comprehensive testing and assertion framework
98
- **xtras.py**: Extended functionality including caching, file operations, and async utilities
99
- **parallel.py**: Multi-threading and multi-processing utilities
100
- **meta.py**: Metaclasses and metaprogramming tools
101

102
### Integration Tools
103
- **net.py**: HTTP utilities and networking functions
104
- **xml.py**: HTML/XML generation and manipulation
105
- **script.py**: Command-line argument parsing
106
- **docments.py**: Documentation extraction and parsing
107

108
This modular design allows developers to import only needed functionality while providing a cohesive ecosystem of tools that work seamlessly together.
109

110
## Capabilities
111

112
### Core Utilities and Data Structures
113

114
Fundamental utilities including null-safe operations, enhanced dictionaries, attribute access helpers, and functional programming tools that form the foundation of the fastcore ecosystem.
115

116
```python { .api }
117
def ifnone(a, b): ...
118
def listify(o): ...
119
def tuplify(o): ...
120
class AttrDict(dict): ...
121
class AttrDictDefault(AttrDict): ...
122
def store_attr(names=None, self=None, but='', cast=False, **attrs): ...
123
```
124

125
[Core Utilities](./core-utilities.md)
126

127
### Enhanced Collections
128

129
Powerful collection classes with functional programming methods, lazy evaluation support, and advanced indexing capabilities built on top of standard Python collections.
130

131
```python { .api }
132
class L(CollBase): ...
133
def mask2idxs(mask): ...
134
def is_indexer(idx): ...
135
class CollBase: ...
136
```
137

138
[Enhanced Collections](./collections.md)
139

140
### Testing Framework
141

142
Comprehensive testing utilities with detailed error reporting, specialized assertion helpers for different data types, and utilities for testing exceptions and warnings.
143

144
```python { .api }
145
def test_eq(a, b): ...
146
def test_close(a, b, eps=1e-5): ...
147
def test_fail(f, msg='', contains='', exc=Exception): ...
148
def test_stdout(f, exp, regex=False): ...
149
class ExceptionExpected: ...
150
```
151

152
[Testing Framework](./testing.md)
153

154
### Extended Functionality
155

156
Advanced utilities including caching systems, file operations, async helpers, data serialization, and system integration tools for complex development scenarios.
157

158
```python { .api }
159
def walk(path, symlinks=True, file_type=None, file_exts=None, **kwargs): ...
160
def run(cmd, *rest, same_in_win=False, ignore_ex=False, **kwargs): ...
161
class CachedIter: ...
162
def flexicache(cache_dir=None, **kwargs): ...
163
```
164

165
[Extended Functionality](./extended.md)
166

167
### Parallel Processing
168

169
Multi-threading and multi-processing utilities with simplified APIs, progress tracking, and seamless integration with fastcore's functional programming patterns.
170

171
```python { .api }
172
def parallel(f, items, *args, n_workers=defaults.cpus, **kwargs): ...
173
def threaded(process=False): ...
174
class ThreadPoolExecutor: ...
175
def parallel_gen(cls, items, n_workers=defaults.cpus, **kwargs): ...
176
```
177

178
[Parallel Processing](./parallel.md)
179

180
### Networking Utilities
181

182
HTTP client functionality with comprehensive error handling, URL manipulation utilities, and socket programming helpers for network-based applications.
183

184
```python { .api }
185
def urlopen(url, data=None, **kwargs): ...
186
def urlread(url, decode=True, **kwargs): ...
187
def urljson(url, **kwargs): ...
188
def urlsave(url, dest=None, **kwargs): ...
189
```
190

191
[Networking Utilities](./networking.md)
192

193
### Metaprogramming Tools
194

195
Advanced metaclasses, function signature manipulation, delegation patterns, and dynamic code generation utilities for building flexible and extensible APIs.
196

197
```python { .api }
198
def delegates(to=None, keep=False, but=None): ...
199
class FixSigMeta: ...
200
class AutoInit: ...
201
def use_kwargs(f, **kwargs): ...
202
```
203

204
[Metaprogramming](./metaprogramming.md)
205

206
### HTML/XML Generation
207

208
Programmatic HTML and XML generation with a fluent API, supporting all standard HTML elements and providing safe string handling for web development.
209

210
```python { .api }
211
def ft(tag, *c, **kw): ...
212
class FT: ...
213
def Html(*c, **kwargs): ...
214
def to_xml(elm, lvl=0): ...
215
```
216

217
[HTML/XML Generation](./xml-html.md)
218

219
### System Integration
220

221
Command-line argument parsing, documentation tools, file system utilities, and development aids that bridge fastcore functionality with system-level operations.
222

223
```python { .api }
224
def call_parse(func=None, **kwargs): ...
225
class Param: ...
226
def docstring(sym): ...
227
def get_source(s): ...
228
```
229

230
[System Integration](./system-integration.md)
231

232
## Version Information
233

234
FastCore version 1.8.8 provides stable APIs with comprehensive backward compatibility. The library follows semantic versioning and maintains API stability across minor version updates.
235

236
```python { .api }
237
import fastcore
238
print(fastcore.__version__)  # "1.8.8"
239
```