Coverage for pygeodesy/deprecated/functions.py: 94%

68 statements  

« prev     ^ index     » next       coverage.py v7.2.2, created at 2023-09-15 09:43 -0400

1 

2# -*- coding: utf-8 -*- 

3 

4u'''DEPRECATED functions for export and backward compatibility. 

5''' 

6 

7from pygeodesy.constants import EPS, R_M, float0_ 

8from pygeodesy.deprecated.classes import ClipCS3Tuple, TriAngle4Tuple, _TriAngle5Tuple 

9from pygeodesy.interns import NN, _area_, _COMMASPACE_, _DEPRECATED_, _negative_, \ 

10 _scalar_, _sep_, _SPACE_, _UNDER_, _value_ 

11from pygeodesy.lazily import _ALL_MODS as _MODS, _ALL_OTHER 

12from pygeodesy.props import deprecated_function 

13# from pygeodesy.resections import TriAngle5Tuple as _TriAngle5Tuple # from .classes 

14from pygeodesy.units import Number_, Scalar_ 

15 

16__all__ = () 

17__version__ = '23.09.12' 

18 

19_WGS84 = _UTM = object() 

20 

21 

22@deprecated_function 

23def anStr(name, OKd='._-', sub=_UNDER_): # PYCHOK no cover 

24 '''DEPRECATED, use function L{pygeodesy.anstr}.''' 

25 return _MODS.streprs.anstr(name, OKd=OKd, sub=sub) 

26 

27 

28@deprecated_function 

29def areaof(points, adjust=True, radius=R_M, wrap=True): # PYCHOK no cover 

30 '''DEPRECATED, use function L{pygeodesy.areaOf}.''' 

31 return _MODS.points.areaOf(points, adjust=adjust, radius=radius, wrap=wrap) 

32 

33 

34@deprecated_function 

35def bounds(points, wrap=True, LatLon=None): # PYCHOK no cover 

36 '''DEPRECATED, use function L{pygeodesy.boundsOf}. 

37 

38 @return: 2-Tuple C{(latlonSW, latlonNE)} as B{C{LatLon}} 

39 or 4-Tuple C{(latS, lonW, latN, lonE)} if 

40 B{C{LatLon}} is C{None}. 

41 ''' 

42 return tuple(_MODS.points.boundsOf(points, wrap=wrap, LatLon=LatLon)) 

43 

44 

45@deprecated_function 

46def clipCS3(points, lowerleft, upperright, closed=False, inull=False): # PYCHOK no cover 

47 '''DEPRECATED, use function L{pygeodesy.clipCS4}. 

48 

49 @return: Yield a L{ClipCS3Tuple}C{(start, end, index)} for each 

50 edge of the I{clipped} path. 

51 ''' 

52 for p1, p2, _, j in _MODS.clipy.clipCS4(points, lowerleft, upperright, 

53 closed=closed, inull=inull): 

54 yield ClipCS3Tuple(p1, p2, j) 

55 

56 

57@deprecated_function 

58def clipDMS(deg, limit): # PYCHOK no cover 

59 '''DEPRECATED, use function L{pygeodesy.clipDegrees}.''' 

60 return _MODS.dms.clipDegrees(deg, limit) 

61 

62 

63@deprecated_function 

64def clipStr(bstr, limit=50, white=NN): # PYCHOK no cover 

65 '''DEPRECATED, use function L{pygeodesy.clips}.''' 

66 return _MODS.basics.clips(bstr, limit=limit, white=white) 

67 

68 

69@deprecated_function 

70def collins(pointA, pointB, pointC, alpha, beta, **useZ_Clas_and_kwds): 

71 '''DEPRECATED, use function L{pygeodesy.collins5}.''' 

72 return _MODS.resections.collins5(pointA, pointB, pointC, alpha, beta, 

73 **useZ_Clas_and_kwds) 

74 

75 

76@deprecated_function 

77def copysign(x, y): # PYCHOK no cover 

78 '''DEPRECATED, use function L{pygeodesy.copysign0}.''' 

79 return _MODS.basics.copysign0(x, y) 

80 

81 

82@deprecated_function 

83def decodeEPSG2(arg): # PYCHOK no cover 

84 '''DEPRECATED, use function L{epsg.decode2}. 

85 

86 @return: 2-Tuple C{(zone, hemipole)} 

87 ''' 

88 return tuple(_MODS.epsg.decode2(arg)) 

89 

90 

91@deprecated_function 

92def encodeEPSG(zone, hemipole=NN, band=NN): # PYCHOK no cover 

93 '''DEPRECATED, use function L{epsg.encode}. 

94 

95 @return: C{EPSG} code (C{int}). 

96 ''' 

97 return int(_MODS.epsg.encode(zone, hemipole=hemipole, band=band)) 

98 

99 

100@deprecated_function 

101def enStr2(easting, northing, prec, *extras): # PYCHOK no cover 

102 '''DEPRECATED, use function L{pygeodesy.enstr2}.''' 

103 return _MODS.streprs.enstr2(easting, northing, (int(prec) // 2 - 5), *extras) 

104 

105 

106@deprecated_function 

107def equirectangular3(lat1, lon1, lat2, lon2, **options): # PYCHOK no cover 

108 '''DEPRECATED, use function L{pygeodesy.equirectangular_}. 

109 

110 @return: 3-Tuple C{(distance2, delta_lat, delta_lon)}. 

111 ''' 

112 return tuple(_MODS.formy.equirectangular_(lat1, lon1, lat2, lon2, **options)[:3]) 

113 

114 

115@deprecated_function 

116def excessAbc(A, b, c): 

117 '''DEPRECATED, use function L{pygeodesy.excessAbc_}.''' 

118 return _MODS.formy.excessAbc_(A, b, c) 

119 

120 

121@deprecated_function 

122def excessGirard(A, B, C): 

123 '''DEPRECATED, use function L{pygeodesy.excessGirard_}.''' 

124 return _MODS.formy.excessGirard_(A, B, C) 

125 

126 

127@deprecated_function 

128def excessLHuilier(a, b, c): 

129 '''DEPRECATED, use function L{pygeodesy.excessLHuilier_}.''' 

130 return _MODS.formy.excessLHuilier_(a, b, c) 

131 

132 

133@deprecated_function 

134def false2f(value, name=_value_, false=True, Error=ValueError): # PYCHOK no cover 

135 '''DEPRECATED, use function L{pygeodesy.falsed2f}.''' 

136 return falsed2f(falsed=false, Error=Error, **{name: value}) 

137 

138 

139@deprecated_function 

140def falsed2f(falsed=True, Error=ValueError, **name_value): # PYCHOK no cover 

141 '''DEPRECATED, use class L{Easting} or L{Northing}. 

142 

143 Convert a falsed east-/northing to non-negative C{float}. 

144 

145 @kwarg falsed: Value includes false origin (C{bool}). 

146 @kwarg Error: Optional, overriding error (C{Exception}). 

147 @kwarg name_value: One C{B{name}=value} pair. 

148 

149 @return: The value (C{float}). 

150 

151 @raise Error: Invalid or negative C{B{name}=value}. 

152 ''' 

153 t = NN 

154 if len(name_value) == 1: 

155 try: 

156 for f in name_value.values(): 

157 f = float(f) 

158 if falsed and f < 0: 

159 break 

160 return f 

161 t = _COMMASPACE_('falsed', _negative_) 

162 except (TypeError, ValueError) as x: 

163 t = str(x) 

164 raise _MODS.errors._InvalidError(Error=Error, txt=t, **name_value) 

165 

166 

167@deprecated_function 

168def float0(*xs): 

169 '''DEPRECATED, use function L{pygeodesy.float0_}.''' 

170 return float0_(*xs) 

171 

172 

173@deprecated_function 

174def fStr(floats, prec=6, fmt=_MODS.streprs.Fmt.f, ints=False, sep=_COMMASPACE_): # PYCHOK no cover 

175 '''DEPRECATED, use function L{fstr}.''' 

176 return _MODS.streprs.fstr(floats, prec=prec, fmt=fmt, ints=ints, sep=sep) 

177 

178 

179@deprecated_function 

180def fStrzs(floatstr): # PYCHOK no cover 

181 '''DEPRECATED, use function L{pygeodesy.fstrzs}.''' 

182 return _MODS.streprs.fstrzs(floatstr) 

183 

184 

185@deprecated_function 

186def hypot3(x, y, z): # PYCHOK no cover 

187 '''DEPRECATED, use function L{pygeodesy.hypot_}.''' 

188 return _MODS.fmath.hypot_(x, y, z) 

189 

190 

191@deprecated_function 

192def inStr(inst, *args, **kwds): # PYCHOK no cover 

193 '''DEPRECATED, use function L{pygeodesy.instr}.''' 

194 return _MODS.streprs.instr(inst, *args, **kwds) 

195 

196 

197def isDEPRECATED(obj): 

198 '''Return C{True} if C{B{obj}} is a C{DEPRECATED} class, method 

199 or function, C{False} if not or C{None} if undetermined. 

200 ''' 

201 try: # XXX inspect.getdoc(obj) 

202 return bool(obj.__doc__.lstrip().startswith(_DEPRECATED_)) 

203 except AttributeError: 

204 return None 

205 

206 

207@deprecated_function 

208def isenclosedby(point, points, wrap=False): # PYCHOK no cover 

209 '''DEPRECATED, use function L{pygeodesy.isenclosedBy}.''' 

210 return _MODS.points.isenclosedBy(point, points, wrap=wrap) 

211 

212 

213@deprecated_function 

214def istuplist(obj, minum=0): # PYCHOK no cover 

215 '''DEPRECATED, use function L{pygeodesy.islistuple}.''' 

216 return _MODS.basics.islistuple(obj, minum=minum) 

217 

218 

219@deprecated_function 

220def joined(*words, **sep): # PYCHOK no cover 

221 '''DEPRECATED, use C{NN(...)}, C{NN.join_} or C{B{sep}.join}.''' 

222 return sep.get(_sep_, NN).join(map(str, words)) 

223 

224 

225@deprecated_function 

226def joined_(*words, **sep): # PYCHOK no cover 

227 '''DEPRECATED, use C{_SPACE_(...)}, C{_SPACE_.join_} or C{B{sep}.join}, sep=" ".''' 

228 return sep.get(_sep_, _SPACE_).join(map(str, words)) 

229 

230 

231@deprecated_function 

232def nearestOn3(point, points, closed=False, wrap=False, **options): # PYCHOK no cover 

233 '''DEPRECATED, use function L{pygeodesy.nearestOn5}. 

234 

235 @return: 3-Tuple C{(lat, lon, distance)} 

236 ''' 

237 return tuple(_MODS.points.nearestOn5(point, points, closed=closed, wrap=wrap, **options)[:3]) 

238 

239 

240@deprecated_function 

241def nearestOn4(point, points, closed=False, wrap=False, **options): # PYCHOK no cover 

242 '''DEPRECATED, use function L{pygeodesy.nearestOn5}. 

243 

244 @return: 4-Tuple C{(lat, lon, distance, angle)} 

245 ''' 

246 return tuple(_MODS.points.nearestOn5(point, points, closed=closed, wrap=wrap, **options)[:4]) 

247 

248 

249@deprecated_function 

250def parseUTM(strUTM, datum=_WGS84, Utm=_UTM, name=NN): # PYCHOK no cover 

251 '''DEPRECATED, use function L{parseUTM5}. 

252 

253 @return: The UTM coordinate (B{L{Utm}}) or 4-tuple C{(zone, 

254 hemisphere, easting, northing)} if B{C{Utm}} is C{None}. 

255 ''' 

256 d = _MODS.datums.Datums.WGS84 if datum is _WGS84 else datum # PYCHOK shadows? 

257 U = _MODS.utm.Utm if Utm is _UTM else Utm 

258 r = _MODS.utm.parseUTM5(strUTM, datum=d, Utm=U, name=name) 

259 if isinstance(r, tuple): # UtmUps5Tuple 

260 r = r.zone, r.hemipole, r.easting, r.northing # no band 

261 return r 

262 

263 

264@deprecated_function 

265def perimeterof(points, closed=False, adjust=True, radius=R_M, wrap=True): # PYCHOK no cover 

266 '''DEPRECATED, use function L{pygeodesy.perimeterOf}.''' 

267 return _MODS.points.perimeterOf(points, closed=closed, adjust=adjust, radius=radius, wrap=wrap) 

268 

269 

270@deprecated_function 

271def polygon(points, closed=True, base=None): # PYCHOK no cover 

272 '''DEPRECATED, use function L{pygeodesy.points2}.''' 

273 return _MODS.deprecated.bases.points2(points, closed=closed, base=base) 

274 

275 

276@deprecated_function 

277def scalar(value, low=EPS, high=1.0, name=_scalar_, Error=ValueError): # PYCHOK no cover 

278 '''DEPRECATED, use class L{Number_} or L{Scalar_}. 

279 

280 @return: New value (C{float} or C{int} for C{int} B{C{low}}). 

281 

282 @raise Error: Invalid B{C{value}}. 

283 ''' 

284 C_ = Number_ if _MODS.basics.isint(low) else Scalar_ 

285 return C_(value, name=name, Error=Error, low=low, high=high) 

286 

287 

288@deprecated_function 

289def simplify2(points, pipe, radius=R_M, shortest=False, indices=False, **options): # PYCHOK no cover 

290 '''DEPRECATED, use function L{pygeodesy.simplifyRW}. 

291 ''' 

292 return _MODS.simplify.simplifyRW(points, pipe, radius=radius, shortest=shortest, 

293 indices=indices, **options) 

294 

295 

296@deprecated_function 

297def tienstra(pointA, pointB, pointC, alpha, **beta_gamma_useZ_Clas_and_kwds): 

298 '''DEPRECATED, use function L{pygeodesy.tienstra7}.''' 

299 return _MODS.resections.tienstra7(pointA, pointB, pointC, alpha, **beta_gamma_useZ_Clas_and_kwds) 

300 

301 

302@deprecated_function 

303def toUtm(latlon, lon=None, datum=None, Utm=_UTM, cmoff=True, name=NN): # PYCHOK no cover 

304 '''DEPRECATED, use function L{pygeodesy.toUtm8}. 

305 

306 @return: The UTM coordinate (B{C{Utm}}) or a 6-tuple C{(zone, 

307 easting, northing, band, convergence, scale)} if 

308 B{C{Utm}} is C{None} or B{C{cmoff}} is C{False}. 

309 ''' 

310 U = _MODS.utm.Utm if Utm is _UTM else Utm 

311 r = _MODS.utm.toUtm8(latlon, lon=lon, datum=datum, Utm=U, name=name, falsed=cmoff) 

312 if isinstance(r, tuple): # UtmUps8Tuple 

313 # no hemisphere/pole and datum 

314 r = r.zone, r.easting, r.northing, r.band, r.gamma, r.scale 

315 return r 

316 

317 

318@deprecated_function 

319def triAngle4(a, b, c): 

320 '''DEPRECATED, use function L{pygeodesy.triAngle5}. 

321 

322 @return: A I{DEPRECATED} L{TriAngle4Tuple}C{(radA, radB, radC, rIn)}. 

323 ''' 

324 assert _TriAngle5Tuple._Names_.index(_area_) == 4 

325 return TriAngle4Tuple(_MODS.resections.triAngle5(a, b, c)[:4]) 

326 

327 

328@deprecated_function 

329def unsign0(x): # PYCHOK no cover 

330 '''DEPRECATED, use function L{pygeodesy.unsigned0}.''' 

331 return _MODS.basics.unsigned0(x) 

332 

333 

334@deprecated_function 

335def unStr(name, *args, **kwds): # PYCHOK no cover 

336 '''DEPRECATED, use function L{pygeodesy.unstr}.''' 

337 return _MODS.streprs.unstr(name, *args, **kwds) 

338 

339 

340@deprecated_function 

341def utmZoneBand2(lat, lon): # PYCHOK no cover 

342 '''DEPRECATED, use function L{pygeodesy.utmZoneBand5}. 

343 

344 @return: 2-Tuple C{(zone, band)}. 

345 ''' 

346 r = _MODS.utm.utmZoneBand5(lat, lon) # UtmUpsLatLon5Tuple 

347 return r.zone, r.band 

348 

349 

350__all__ += _ALL_OTHER(anStr, areaof, bounds, 

351 clipCS3, clipDMS, clipStr, collins, copysign, 

352 decodeEPSG2, enStr2, encodeEPSG, equirectangular3, 

353 excessAbc, excessGirard, excessLHuilier, 

354 false2f, falsed2f, float0, fStr, fStrzs, 

355 hypot3, inStr, isDEPRECATED, isenclosedby, istuplist, 

356 joined, joined_, nearestOn3, nearestOn4, 

357 parseUTM, perimeterof, polygon, scalar, simplify2, 

358 tienstra, toUtm, triAngle4, unsign0, unStr, utmZoneBand2) 

359 

360# **) MIT License 

361# 

362# Copyright (C) 2018-2023 -- mrJean1 at Gmail -- All Rights Reserved. 

363# 

364# Permission is hereby granted, free of charge, to any person obtaining a 

365# copy of this software and associated documentation files (the "Software"), 

366# to deal in the Software without restriction, including without limitation 

367# the rights to use, copy, modify, merge, publish, distribute, sublicense, 

368# and/or sell copies of the Software, and to permit persons to whom the 

369# Software is furnished to do so, subject to the following conditions: 

370# 

371# The above copyright notice and this permission notice shall be included 

372# in all copies or substantial portions of the Software. 

373# 

374# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 

375# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 

376# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 

377# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR 

378# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 

379# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 

380# OTHER DEALINGS IN THE SOFTWARE.