0
# File I/O Operations
1

2
Core functionality for opening, reading, and writing geospatial vector data files. Fiona supports numerous formats through GDAL/OGR drivers including Shapefile, GeoJSON, GeoPackage, KML, and many others. The library provides both file-based and in-memory operations with support for virtual file systems and cloud storage.
3

4
## Capabilities
5

6
### Opening Collections
7

8
Opens a vector dataset collection for reading, writing, or appending. This is the primary entry point for working with geospatial data files.
9

10
```python { .api }
11
def open(
12
    fp,
13
    mode="r",
14
    driver=None,
15
    schema=None,
16
    crs=None,
17
    encoding=None,
18
    layer=None,
19
    vfs=None,
20
    enabled_drivers=None,
21
    crs_wkt=None,
22
    ignore_fields=None,
23
    ignore_geometry=False,
24
    include_fields=None,
25
    wkt_version=None,
26
    allow_unsupported_drivers=False,
27
    opener=None,
28
    **kwargs
29
):
30
    """
31
    Open a collection for read, append, or write.
32

33
    Parameters:
34
    - fp: str or Path, dataset resource identifier or file object
35
    - mode: str, one of 'r' (read), 'a' (append), or 'w' (write)
36
    - driver: str, format driver name (required for write mode)
37
    - schema: dict, required in write mode, defines geometry and properties
38
    - crs: str or dict, coordinate reference system (required for write mode)
39
    - encoding: str, name of encoding used to encode/decode dataset
40
    - layer: int or str, integer index or name of layer in multi-layer dataset
41
    - vfs: str, deprecated, use URI scheme instead
42
    - enabled_drivers: list, optional list of driver names to use
43
    - crs_wkt: str, optional WKT representation of CRS
44
    - ignore_fields: list[str], field names to ignore on load
45
    - include_fields: list[str], subset of field names to include on load
46
    - ignore_geometry: bool, ignore geometry on load
47
    - wkt_version: WktVersion or str, version for CRS WKT
48
    - allow_unsupported_drivers: bool, don't limit to known working drivers
49
    - opener: callable or obj, custom dataset opener for virtual filesystem
50
    - kwargs: dict, other driver-specific parameters
51

52
    Returns:
53
    Collection object
54

55
    Raises:
56
    DriverError: When selected driver cannot provide requested capabilities
57
    """
58
```
59

60
#### Usage Examples
61

62
```python
63
# Reading a shapefile
64
with fiona.open('data.shp', 'r') as collection:
65
    for feature in collection:
66
        print(feature['properties'])
67

68
# Writing GeoJSON with specific schema
69
schema = {
70
    'geometry': 'Point',
71
    'properties': {'name': 'str:50', 'population': 'int'}
72
}
73

74
with fiona.open('cities.geojson', 'w', driver='GeoJSON',
75
                schema=schema, crs='EPSG:4326') as collection:
76
    feature = {
77
        'geometry': {'type': 'Point', 'coordinates': [-122.5, 37.5]},
78
        'properties': {'name': 'San Francisco', 'population': 875000}
79
    }
80
    collection.write(feature)
81

82
# Reading specific layer from multi-layer file
83
with fiona.open('data.gpkg', 'r', layer='roads') as collection:
84
    print(f"Layer CRS: {collection.crs}")
85
    print(f"Feature count: {len(collection)}")
86

87
# Using custom field filtering
88
with fiona.open('large_dataset.shp', 'r', 
89
                include_fields=['name', 'category']) as collection:
90
    for feature in collection:
91
        # Only 'name' and 'category' fields are loaded
92
        print(feature['properties'])
93
```
94

95
### Listing Layers
96

97
Lists the layers (collections) in a multi-layer dataset such as GeoPackage, PostGIS database, or other formats that support multiple layers.
98

99
```python { .api }
100
def listlayers(fp, opener=None, vfs=None, **kwargs):
101
    """
102
    Lists the layers in a dataset.
103

104
    Parameters:
105
    - fp: str, Path, or file-like object, dataset identifier
106
    - opener: callable or obj, custom dataset opener
107
    - vfs: str, deprecated parameter
108
    - kwargs: dict, dataset opening options
109

110
    Returns:
111
    list[str]: List of layer name strings
112

113
    Raises:
114
    TypeError: If input is not str, Path, or file object
115
    """
116
```
117

118
#### Usage Examples
119

120
```python
121
# List layers in a GeoPackage
122
layers = fiona.listlayers('database.gpkg')
123
print(f"Available layers: {layers}")
124

125
# List layers in a PostGIS database
126
layers = fiona.listlayers('PG:host=localhost dbname=gis user=postgres')
127
for layer in layers:
128
    print(f"Layer: {layer}")
129

130
# List layers in a zip archive
131
layers = fiona.listlayers('zip://data.zip')
132
```
133

134
### Listing Directory Contents
135

136
Lists datasets in a directory or archive file, useful for discovering available data files in a location.
137

138
```python { .api }
139
def listdir(fp, opener=None):
140
    """
141
    Lists datasets in a directory or archive file.
142

143
    Parameters:
144
    - fp: str or Path, directory or archive path
145
    - opener: callable or obj, custom dataset opener
146

147
    Returns:
148
    list[str]: List of dataset paths
149

150
    Raises:
151
    TypeError: If input is not str or Path
152
    """
153
```
154

155
#### Usage Examples
156

157
```python
158
# List datasets in a directory
159
datasets = fiona.listdir('/path/to/gis/data')
160
for dataset in datasets:
161
    print(f"Found dataset: {dataset}")
162

163
# List datasets in a zip archive
164
datasets = fiona.listdir('zip://archive.zip')
165

166
# List datasets in a tar archive
167
datasets = fiona.listdir('tar://archive.tar.gz')
168
```
169

170
### Removing Datasets
171

172
Deletes an OGR data source or one of its layers, including associated sidecar files.
173

174
```python { .api }
175
def remove(path_or_collection, driver=None, layer=None, opener=None):
176
    """
177
    Delete an OGR data source or layer.
178

179
    Parameters:
180
    - path_or_collection: str, Path, or Collection, target to delete
181
    - driver: str, name of driver for deletion (usually auto-detected)
182
    - layer: str or int, name or index of specific layer to delete
183
    - opener: callable or obj, custom dataset opener
184

185
    Returns:
186
    None
187

188
    Raises:
189
    DatasetDeleteError: If data source cannot be deleted
190
    """
191
```
192

193
#### Usage Examples
194

195
```python
196
# Remove entire dataset
197
fiona.remove('unwanted_data.shp')
198

199
# Remove specific layer from multi-layer dataset
200
fiona.remove('database.gpkg', layer='temporary_layer')
201

202
# Remove using Collection object
203
with fiona.open('data.shp', 'r') as collection:
204
    # Process data...
205
    pass
206
# Remove the dataset after processing
207
fiona.remove(collection)
208
```
209

210
### Memory Files
211

212
In-memory operations for working with geospatial data without disk I/O, useful for temporary processing and testing.
213

214
```python { .api }
215
class MemoryFile:
216
    def __init__(self, file_or_bytes=None, filename=None, ext=""):
217
        """
218
        BytesIO-like object backed by in-memory file.
219

220
        Parameters:
221
        - file_or_bytes: bytes or file-like object, initial content
222
        - filename: str, optional filename for format detection
223
        - ext: str, file extension for format detection
224
        """
225
    
226
    def open(self, mode=None, driver=None, schema=None, crs=None, **kwargs):
227
        """
228
        Open and return Collection for the memory file.
229

230
        Returns:
231
        Collection object
232
        """
233
```
234

235
#### Usage Examples
236

237
```python
238
from fiona.io import MemoryFile
239

240
# Create in-memory GeoJSON
241
schema = {'geometry': 'Point', 'properties': {'name': 'str'}}
242

243
with MemoryFile() as memfile:
244
    with memfile.open(driver='GeoJSON', mode='w', 
245
                      schema=schema, crs='EPSG:4326') as collection:
246
        feature = {
247
            'geometry': {'type': 'Point', 'coordinates': [0, 0]},
248
            'properties': {'name': 'Origin'}
249
        }
250
        collection.write(feature)
251
    
252
    # Read back from memory
253
    memfile.seek(0)
254
    with memfile.open('r') as collection:
255
        for feature in collection:
256
            print(feature)
257

258
# Work with existing bytes data
259
geojson_bytes = b'{"type": "FeatureCollection", "features": []}'
260
with MemoryFile(geojson_bytes) as memfile:
261
    with memfile.open('r') as collection:
262
        print(f"Driver: {collection.driver}")
263
```
264

265
## Driver Support
266

267
Fiona supports numerous geospatial data formats through GDAL/OGR drivers:
268

269
### Common Formats
270
- **Shapefile** (`ESRI Shapefile`): Traditional GIS format with .shp, .shx, .dbf files
271
- **GeoJSON** (`GeoJSON`): Web-friendly JSON format for geospatial data
272
- **GeoPackage** (`GPKG`): Modern SQLite-based format supporting multiple layers
273
- **KML** (`KML`, `LIBKML`): Google Earth format
274
- **CSV** (`CSV`): Comma-separated values with geometry columns
275
- **PostGIS** (`PostgreSQL`): PostgreSQL spatial database
276

277
### Archive Support
278
- **ZIP files**: Access datasets within zip archives using `zip://` prefix
279
- **TAR files**: Access datasets within tar archives using `tar://` prefix
280

281
### Cloud Storage
282
- **AWS S3**: Access via `/vsis3/bucket/path` virtual file system
283
- **Google Cloud**: Access via `/vsigs/bucket/path` virtual file system
284
- **Azure**: Access via `/vsiaz/container/path` virtual file system
285

286
## Error Handling
287

288
File I/O operations can raise several specific exceptions:
289

290
- **DriverError**: Unsupported driver or mode combinations
291
- **DataIOError**: General I/O errors with driver registration
292
- **DriverIOError**: Format-specific driver errors
293
- **DatasetDeleteError**: Dataset deletion failures
294
- **PathError**: Invalid dataset path errors
295
- **FieldNameEncodeError**: Field name encoding issues