Coverage for pygeodesy/deprecated/functions.py: 94%
68 statements
« prev ^ index » next coverage.py v7.2.2, created at 2023-09-20 13:43 -0400
« prev ^ index » next coverage.py v7.2.2, created at 2023-09-20 13:43 -0400
2# -*- coding: utf-8 -*-
4u'''DEPRECATED functions for export and backward compatibility.
5'''
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_
16__all__ = ()
17__version__ = '23.09.12'
19_WGS84 = _UTM = object()
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)
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)
34@deprecated_function
35def bounds(points, wrap=True, LatLon=None): # PYCHOK no cover
36 '''DEPRECATED, use function L{pygeodesy.boundsOf}.
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))
45@deprecated_function
46def clipCS3(points, lowerleft, upperright, closed=False, inull=False): # PYCHOK no cover
47 '''DEPRECATED, use function L{pygeodesy.clipCS4}.
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)
57@deprecated_function
58def clipDMS(deg, limit): # PYCHOK no cover
59 '''DEPRECATED, use function L{pygeodesy.clipDegrees}.'''
60 return _MODS.dms.clipDegrees(deg, limit)
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)
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)
76@deprecated_function
77def copysign(x, y): # PYCHOK no cover
78 '''DEPRECATED, use function L{pygeodesy.copysign0}.'''
79 return _MODS.basics.copysign0(x, y)
82@deprecated_function
83def decodeEPSG2(arg): # PYCHOK no cover
84 '''DEPRECATED, use function L{epsg.decode2}.
86 @return: 2-Tuple C{(zone, hemipole)}
87 '''
88 return tuple(_MODS.epsg.decode2(arg))
91@deprecated_function
92def encodeEPSG(zone, hemipole=NN, band=NN): # PYCHOK no cover
93 '''DEPRECATED, use function L{epsg.encode}.
95 @return: C{EPSG} code (C{int}).
96 '''
97 return int(_MODS.epsg.encode(zone, hemipole=hemipole, band=band))
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)
106@deprecated_function
107def equirectangular3(lat1, lon1, lat2, lon2, **options): # PYCHOK no cover
108 '''DEPRECATED, use function L{pygeodesy.equirectangular_}.
110 @return: 3-Tuple C{(distance2, delta_lat, delta_lon)}.
111 '''
112 return tuple(_MODS.formy.equirectangular_(lat1, lon1, lat2, lon2, **options)[:3])
115@deprecated_function
116def excessAbc(A, b, c):
117 '''DEPRECATED, use function L{pygeodesy.excessAbc_}.'''
118 return _MODS.formy.excessAbc_(A, b, c)
121@deprecated_function
122def excessGirard(A, B, C):
123 '''DEPRECATED, use function L{pygeodesy.excessGirard_}.'''
124 return _MODS.formy.excessGirard_(A, B, C)
127@deprecated_function
128def excessLHuilier(a, b, c):
129 '''DEPRECATED, use function L{pygeodesy.excessLHuilier_}.'''
130 return _MODS.formy.excessLHuilier_(a, b, c)
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})
139@deprecated_function
140def falsed2f(falsed=True, Error=ValueError, **name_value): # PYCHOK no cover
141 '''DEPRECATED, use class L{Easting} or L{Northing}.
143 Convert a falsed east-/northing to non-negative C{float}.
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.
149 @return: The value (C{float}).
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)
167@deprecated_function
168def float0(*xs):
169 '''DEPRECATED, use function L{pygeodesy.float0_}.'''
170 return float0_(*xs)
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)
179@deprecated_function
180def fStrzs(floatstr): # PYCHOK no cover
181 '''DEPRECATED, use function L{pygeodesy.fstrzs}.'''
182 return _MODS.streprs.fstrzs(floatstr)
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)
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)
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
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)
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)
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))
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))
231@deprecated_function
232def nearestOn3(point, points, closed=False, wrap=False, **options): # PYCHOK no cover
233 '''DEPRECATED, use function L{pygeodesy.nearestOn5}.
235 @return: 3-Tuple C{(lat, lon, distance)}
236 '''
237 return tuple(_MODS.points.nearestOn5(point, points, closed=closed, wrap=wrap, **options)[:3])
240@deprecated_function
241def nearestOn4(point, points, closed=False, wrap=False, **options): # PYCHOK no cover
242 '''DEPRECATED, use function L{pygeodesy.nearestOn5}.
244 @return: 4-Tuple C{(lat, lon, distance, angle)}
245 '''
246 return tuple(_MODS.points.nearestOn5(point, points, closed=closed, wrap=wrap, **options)[:4])
249@deprecated_function
250def parseUTM(strUTM, datum=_WGS84, Utm=_UTM, name=NN): # PYCHOK no cover
251 '''DEPRECATED, use function L{parseUTM5}.
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
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)
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)
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_}.
280 @return: New value (C{float} or C{int} for C{int} B{C{low}}).
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)
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)
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)
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}.
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
318@deprecated_function
319def triAngle4(a, b, c):
320 '''DEPRECATED, use function L{pygeodesy.triAngle5}.
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])
328@deprecated_function
329def unsign0(x): # PYCHOK no cover
330 '''DEPRECATED, use function L{pygeodesy.unsigned0}.'''
331 return _MODS.basics.unsigned0(x)
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)
340@deprecated_function
341def utmZoneBand2(lat, lon): # PYCHOK no cover
342 '''DEPRECATED, use function L{pygeodesy.utmZoneBand5}.
344 @return: 2-Tuple C{(zone, band)}.
345 '''
346 r = _MODS.utm.utmZoneBand5(lat, lon) # UtmUpsLatLon5Tuple
347 return r.zone, r.band
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)
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.