Debian Codegraph @

django/contrib/gis/gdal/datasource.py

raw
1 """
2 DataSource is a wrapper for the OGR Data Source object, which provides
3 an interface for reading vector geometry data from many different file
4 formats (including ESRI shapefiles).
5
6 When instantiating a DataSource object, use the filename of a
7 GDAL-supported data source. For example, a SHP file or a
8 TIGER/Line file from the government.
9
10 The ds_driver keyword is used internally when a ctypes pointer
11 is passed in directly.
12
13 Example:
14 ds = DataSource('/home/foo/bar.shp')
15 for layer in ds:
16 for feature in layer:
17 # Getting the geometry for the feature.
18 g = feature.geom
19
20 # Getting the 'description' field for the feature.
21 desc = feature['description']
22
23 # We can also increment through all of the fields
24 # attached to this feature.
25 for field in feature:
26 # Get the name of the field (e.g. 'description')
27 nm = field.name
28
29 # Get the type (integer) of the field, e.g. 0 => OFTInteger
30 t = field.type
31
32 # Returns the value the field; OFTIntegers return ints,
33 # OFTReal returns floats, all else returns string.
34 val = field.value
35 """
36
37 from pathlib import Path
38
39 from django.contrib.gis.gdal.base import GDALBase
40 from django.contrib.gis.gdal.driver import Driver
41 from django.contrib.gis.gdal.error import GDALException
42 from django.contrib.gis.gdal.layer import Layer
43 from django.contrib.gis.gdal.prototypes import ds as capi
44 from django.utils.encoding import force_bytes, force_str
45
46
47 # For more information, see the OGR C API documentation:
48 # https://gdal.org/api/vector_c_api.html
49 #
50 # The OGR_DS_* routines are relevant here.
51 class DataSource(GDALBase):
52 "Wraps an OGR Data Source object."
53
54 destructor = capi.destroy_ds
55
56 def __init__(self, ds_input, ds_driver=False, write=False, encoding="utf-8"):
57 # The write flag.
58 self._write = capi.GDAL_OF_UPDATE if write else capi.GDAL_OF_READONLY
59 # See also https://gdal.org/development/rfc/rfc23_ogr_unicode.html
60 self.encoding = encoding
61
62 Driver.ensure_registered()
63
64 if isinstance(ds_input, (str, Path)):
65 try:
66 # GDALOpenEx will auto-detect the data source type.
67 ds = capi.open_ds(
68 force_bytes(ds_input),
69 self._write | capi.GDAL_OF_VECTOR,
70 None,
71 None,
72 None,
73 )
74 except GDALException:
75 # Making the error message more clear rather than something
76 # like "Invalid pointer returned from OGROpen".
77 raise GDALException('Could not open the datasource at "%s"' % ds_input)
78 elif isinstance(ds_input, self.ptr_type) and isinstance(
79 ds_driver, Driver.ptr_type
80 ):
81 ds = ds_input
82 else:
83 raise GDALException("Invalid data source input type: %s" % type(ds_input))
84
85 if ds:
86 self.ptr = ds
87 driver = capi.get_dataset_driver(ds)
88 self.driver = Driver(driver)
89 else:
90 # Raise an exception if the returned pointer is NULL
91 raise GDALException('Invalid data source file "%s"' % ds_input)
92
93 def __getitem__(self, index):
94 "Allows use of the index [] operator to get a layer at the index."
95 if isinstance(index, str):
96 try:
97 layer = capi.get_layer_by_name(self.ptr, force_bytes(index))
98 except GDALException:
99 raise IndexError("Invalid OGR layer name given: %s." % index)
100 elif isinstance(index, int):
101 if 0 <= index < self.layer_count:
102 layer = capi.get_layer(self._ptr, index)
103 else:
104 raise IndexError(
105 "Index out of range when accessing layers in a datasource: %s."
106 % index
107 )
108 else:
109 raise TypeError("Invalid index type: %s" % type(index))
110 return Layer(layer, self)
111
112 def __len__(self):
113 "Return the number of layers within the data source."
114 return self.layer_count
115
116 def __str__(self):
117 "Return OGR GetName and Driver for the Data Source."
118 return "%s (%s)" % (self.name, self.driver)
119
120 @property
121 def layer_count(self):
122 "Return the number of layers in the data source."
123 return capi.get_layer_count(self._ptr)
124
125 @property
126 def name(self):
127 "Return the name of the data source."
128 name = capi.get_ds_name(self._ptr)
129 return force_str(name, self.encoding, strings_only=True)