Coverage for pygeodesy/lazily.py: 96%

1 

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

3 

4u'''Lazily import C{pygeodesy} modules and attributes, based on 

5U{lazy_import<https://modutil.ReadTheDocs.io/en/latest/#lazy_import>} 

6from I{Brett Cannon}'s U{modutil<https://PyPI.org/project/modutil>}. 

7 

8C{Lazy import} is I{supported only for }U{Python 3.7+ 

9<https://Snarky.Ca/lazy-importing-in-python-3-7>} and is I{enabled by 

10default} in U{PyGeodesy 18.11.10<https://PyPI.org/project/PyGeodesy>} 

11I{and newer}. 

12 

13To I{enable} C{lazy import}, set C{env} variable C{PYGEODESY_LAZY_IMPORT} 

14to C{1}, C{2}, C{3} or higher prior to C{import pygeodesy}. To I{disable} 

15C{lazy import}, set C{env} variable C{PYGEODESY_LAZY_IMPORT} to C{0} or 

16an empty string. Use C{2} or higher to print a message for each lazily 

17imported module and attribute, similar to C{env} variable C{PYTHONVERBOSE} 

18showing imports. Using C{3} or higher also shows the importing file name 

19and line number. 

20 

21@note: C{Lazy import} applies only to top-level modules of C{pygeodesy}. 

22 The C{lazy import} of a top-level module invariably loads all 

23 sub-modules imported by that top-level module. 

24 

25@note: C{Lazy import} raises a L{LazyAttributeError} or L{LazyImportError} 

26 depending on the cause of the error and such errors can occur late, 

27 after all initial imports. 

28''' 

29 

30from pygeodesy import internals as _internals, interns as _interns, \ 

31 _isfrozen # DON'T _lazy_import2 

32# from pygeodesy.errors import _error_init, _ImmutableError, _xkwds_item2 # _ALL_MODS 

33from pygeodesy.internals import _caller3, _envPYGEODESY, _headof, printf, _Property_RO, \ 

34 _tailof, typename, _versions # _getenv, _PYGEODESY_ENV, \ 

35# _MODS_Base, _MODS.sys_version_info2 

36from pygeodesy.interns import _attribute_, _by_, _COLONSPACE_, _COMMASPACE_, _DALL_, \ 

37 _DMAIN_, _doesn_t_exist_, _DOT_, _EQUALSPACED_, _from_, \ 

38 _HASH_, _line_, _module_, NN, _no_, _not_, _pygeodesy_, \ 

39 _pygeodesy_abspath_, _SPACE_, _SUB_PACKAGES, _or_, \ 

40 _UNDER_, _version_, _sys, _intern # function, _1_ 

41try: 

42 from importlib import import_module 

43except ImportError as x: # Python 2.6- 

44 raise ImportError(_COLONSPACE_(x, _versions())) 

45# import sys as _sys # from .interns 

46 

47_a0 = () # PYCHOK empty tuple 

48_asSPACED_ = ' as ' 

49_FOR_DOCS = _envPYGEODESY('FOR_DOCS') # for epydoc ... 

50_imported_ = 'imported' 

51_init__all__ = _FOR_DOCS or _envPYGEODESY('_init__all__', _DALL_) == _DALL_ # PYCHOK exported 

52_lazily_ = 'lazily' 

53_PYTHON_X_DEV = getattr(_sys.flags, 'dev_mode', False) # PYCHOK Python 3.2+ 

54_unlazy = _unLazy0 = _isfrozen or _internals._MODS.sys_version_info2 < (3, 7) # PYCHOK mod.__getattr__ 3.7+ 

55_WARNINGS_X_DEV = _envPYGEODESY('WARNINGS') and (_PYTHON_X_DEV or bool(_sys.warnoptions)) # PYCHOK .props 

56 

57# @module_property[_RO?] <https://GitHub.com/jtushman/proxy_tools/> <https://discuss.Python.org/t/47379> 

58isLazy = None # see @var isLazy in .__init__ 

59 

60 

61class LazyAttributeError(AttributeError): 

62 '''Raised if a C{lazily imported} attribute is missing or invalid. 

63 ''' 

64 def __init__(self, *args, **kwds): 

65 _ALL_MODS.errors._error_init(AttributeError, self, args, **kwds) 

66 

67 

68class LazyImportError(ImportError): 

69 '''Raised if C{lazy import} is not supported, disabled or failed. 

70 ''' 

71 def __init__(self, *args, **kwds): 

72 _ALL_MODS.errors._error_init(ImportError, self, args, **kwds) 

73 

74 

75class _Dict(dict): 

76 '''(INTERNAL) Imports C{dict}. 

77 ''' 

78 _name = NN 

79 

80 def __getattr__(self, attr): 

81 try: 

82 return self[attr] 

83 except KeyError: 

84 return dict.__getattr__(self, attr) 

85 

86# def __setattr__(self, attr, value): 

87# if attr in self: 

88# self[attr] = value 

89# else: 

90# dict.__setattr__(self, attr, value) 

91 

92 def add(self, name, mod_, *subs): 

93 '''Add a C{[name] = mod_} item. 

94 

95 @raise AssertionError: The B{C{name}} already exists 

96 with a different B{C{mod_}}. 

97 ''' 

98 try: 

99 sub = self[name] # duplicate OK 

100 if sub != mod_ and sub not in subs: 

101 t = _DOT_(self._name, name) 

102 t = _COLONSPACE_(t, repr(sub)) 

103 t = _COMMASPACE_(t, _not_(repr(mod_))) 

104 raise AssertionError(t) 

105 except KeyError: 

106 self[name] = mod_ 

107 

108 def _NAME(self, which): 

109 self._name = _intern(typename(which).upper()) 

110 

111 

112class _NamedEnum_RO(dict): 

113 '''(INTERNAL) C{Read_Only} enum-like C{dict} sub-class. 

114 ''' 

115# _name = NN # also first kwd, __init__(_name=...) 

116 

117 def _DOT_(self, attr): # PYCHOK no cover 

118 return _DOT_(self._name, attr) # PYCHOK _name 

119 

120 def __getattr__(self, attr): 

121 try: 

122 return self[attr] 

123 except KeyError: 

124 t = self._DOT_(attr) 

125 raise LazyAttributeError(t, txt=_doesn_t_exist_) 

126 

127 def __setattr__(self, attr, value): # PYCHOK no cover 

128 e = _ALL_MODS.errors 

129 raise e._ImmutableError(self, attr, value, 

130 Error=LazyAttributeError) 

131 

132 def enums(self): 

133 # Yield all C{(mod_, tuple)} pairs 

134 for m, t in dict.items(self): 

135 n = m.replace(_UNDER_, _DOT_) 

136 if n != m: 

137 if m.startswith(_UNDER_): 

138 continue # skip _name= ... 

139 u = m.rstrip(_UNDER_) 

140 if u != m: 

141 u = len(u) 

142 n = n[:u] + m[u:] 

143 yield n, t 

144 

145 def fill_D(self, _D, which): 

146 # Fill C{_Dict _D}. 

147 _D._NAME(which) 

148 _a = _D.add 

149 for m, t in self.enums(): 

150 _a(m, _DOT_(m, NN, NN)) # import module 

151 for a in t: 

152 a, _, as_ = a.partition(_asSPACED_) 

153 if as_: # import attr as attr_ 

154 _a(as_, _DOT_(m, a, NN), *_SUB_PACKAGES) 

155 else: 

156 _a(a, m) 

157 return _D 

158 

159 

160def _a(*names): 

161 '''(INTERNAL) Intern all C{names}. 

162 ''' 

163 return tuple(map(_intern, names)) if names else _a0 

164 

165 

166def _ALL_ATTRS(*attrs): 

167 '''(INTERNAL) Unravel all exported module attributes. 

168 ''' 

169 t = () 

170 for attr in attrs: 

171 t += tuple(map(_getattras, attr)) 

172 return t 

173 

174 

175_ALL_INIT = _a(_pygeodesy_abspath_, _version_) 

176 

177# __all__ value for most modules, accessible as _ALL_LAZY.<module> 

178_ALL_LAZY = _NamedEnum_RO(_name='_ALL_LAZY', 

179 albers=_a('AlbersEqualArea', 'AlbersEqualArea2', 'AlbersEqualArea4', 

180 'AlbersEqualAreaCylindrical', 'AlbersEqualAreaNorth', 'AlbersEqualAreaSouth', 

181 'AlbersError', 'Albers7Tuple'), 

182 angles=_a('Ang', 'Deg', 'Lambertian', 'Rad', 'isAng'), 

183 auxilats=_a(), # module only 

184 azimuthal=_a('AzimuthalError', 'Azimuthal7Tuple', 

185 'Equidistant', 'EquidistantExact', 'EquidistantGeodSolve', 'EquidistantKarney', 

186 'Gnomonic', 'GnomonicExact', 'GnomonicGeodSolve', 'GnomonicKarney', 

187 'LambertEqualArea', 'Orthographic', 'Stereographic', 

188 'equidistant', 'gnomonic'), 

189 basics=_a('clips', 'copysign0', 'copytype', 'halfs2', 

190 'int1s', 'isbool', 'isCartesian', 'isclass', 'iscomplex', 'isDEPRECATED', 'isfloat', 

191 'isidentifier', 'isinstanceof', 'isint', 'isiterable', 'isiterablen', 'isiterabletype', 

192 'iskeyword', 'isLatLon', 'islistuple', 'isNvector', 'isodd', 

193 'isscalar', 'issequence', 'isstr', 'issubclassof', 'itemsorted', 

194 'len2', 'map1', 'map2', 'max2', 'min2', 'neg', 'neg_', 

195 'signBit', 'signOf', 'splice', 'str2ub', 'ub2str', 'unsigned0'), 

196 booleans=_a('BooleanFHP', 'BooleanGH', 'LatLonFHP', 'LatLonGH', 

197 'isBoolean'), 

198 cartesianBase=_a('RadiusThetaPhi3Tuple', 'rtp2xyz', 'rtp2xyz_', 'xyz2rtp', 'xyz2rtp_'), 

199 clipy=_a('ClipCS4Tuple', 'ClipFHP4Tuple', 'ClipGH4Tuple', 'ClipLB6Tuple', 'ClipSH3Tuple', 

200 'clipCS4', 'clipFHP4', 'clipGH4', 'clipLB6', 'clipSH', 'clipSH3'), 

201 css=_a('CassiniSoldner', 'Css', 'CSSError', 'toCss', 

202 'EasNorAziRk4Tuple', 'EasNorAziRkEqu6Tuple', 'LatLonAziRk4Tuple'), 

203 constants=_a('DIG', 'EPS', 'EPS0', 'EPS02', 'EPS1', 'EPS2', 'EPS4', 'EPS8', 'EPS_2', 

204 'INF', 'INT0', 'MANT_DIG', 'MAX', 'MAX_EXP', 'MIN', 'MIN_EXP', 'NAN', 'NEG0', 'NINF', 

205 'OVERFLOW', 'PI', 'PI2', 'PI_2', 'PI3', 'PI_3', 'PI3_2', 'PI4', 'PI_4', 'PI_6', 

206 'R_FM', 'R_GM', 'R_KM', 'R_M', 'R_MA', 'R_MB', 'R_NM', 'R_QM', 'R_SM', 'R_VM', 

207 'float_', 'float0_', 'floats_', 'isclose', 'isfinite', 'isinf', 'isint0', 

208 'isnan', 'isnear0', 'isnear1', 'isnear90', 'isneg', 'isneg0', 'isninf', 'isnon0', 

209 'remainder'), 

210 datums=_a('Datum', 'Datums', 'Transform', 'Transforms'), 

211# deprecated=_a(), # module only 

212 dms=_a('F_D', 'F_DM', 'F_DMS', 'F_DEG', 'F_MIN', 'F_SEC', 'F_D60', 'F__E', 'F__F', 'F__G', 'F_RAD', 

213 'F_D_', 'F_DM_', 'F_DMS_', 'F_DEG_', 'F_MIN_', 'F_SEC_', 'F_D60_', 'F__E_', 'F__F_', 'F__G_', 'F_RAD_', 

214 'F_D__', 'F_DM__', 'F_DMS__', 'F_DEG__', 'F_MIN__', 'F_SEC__', 'F_D60__', 'F__E__', 'F__F__', 'F__G__', 'F_RAD__', 

215 'S_DEG', 'S_MIN', 'S_SEC', 'S_DMS', 'S_RAD', 'S_SEP', 

216 'bearingDMS', 'clipDegrees', 'clipRadians', 'compassDMS', 'compassPoint', 

217 'degDMS', 'latDMS', 'latlonDMS', 'latlonDMS_', 'lonDMS', 'normDMS', 

218 'parseDDDMMSS', 'parseDMS', 'parseDMS2', 'parse3llh', 'parseRad', 'precision', 'toDMS'), 

219 ecef=_a('EcefFarrell21', 'EcefFarrell22', 'EcefKarney', 'EcefSudano', 'EcefUPC', 'EcefVeness', 'EcefYou', 

220 'EcefError', 'EcefMatrix', 'Ecef9Tuple'), 

221 ecefLocals=_a(), # module only 

222 elevations=_a('Elevation2Tuple', 'GeoidHeight2Tuple', 

223 'elevation2', 'geoidHeight2'), 

224 ellipses=_a('Ellipse', 'EllipseError'), 

225 ellipsoidalBase=_a(), # module only 

226 ellipsoidalBaseDI=_a(), # module only 

227 ellipsoidalExact=_a(), # module only 

228 ellipsoidalGeodSolve=_a(), # module only 

229 ellipsoidalKarney=_a(), # module only 

230 ellipsoidalNvector=_a(), # module only 

231 ellipsoidalVincenty=_a('VincentyError',), # nothing else 

232 ellipsoids=_a('a_f2Tuple', 'Curvature2Tuple', 

233 'Ellipsoid', 'Ellipsoid2', 'Ellipsoids', 

234 'a_b2e', 'a_b2e2', 'a_b2e22', 'a_b2e32', 'a_b2f', 'a_b2f_', 'a_b2f2', 'a_b2n', 

235 'a_f2b', 'a_f_2b', 'b_f2a', 'b_f_2a', 

236 'e2f', 'e22f', 

237 'f2e2', 'f2e22', 'f2e32', 'f_2f', 'f2f_', 'f2f2', 'f2n', 'n2e2', 'n2f', 'n2f_'), 

238 elliptic=_a('Elliptic', 'EllipticError', 'Elliptic3Tuple'), 

239 epsg=_a('Epsg', 'EPSGError'), 

240 errors=_a('AuxError', 'ClipError', 'CrossError', 'GeodesicError', 'IntersectionError', 

241 'NumPyError', 'LenError', 'LimitError', 'MGRSError', 

242 'ParseError', 'PointsError', 'RangeError', 'RhumbError', 

243 'SciPyError', 'SciPyWarning', 'TRFError', 'TriangleError', 'UnitError', 'VectorError', 

244 'crosserrors', 'exception_chaining', 'isError', 'limiterrors', 'rangerrors'), 

245 etm=_a('Etm', 'ETMError', 'ExactTransverseMercator', 

246 'parseETM5', 'toEtm8'), 

247 fmath=_a('Fdot', 'Fdot_', 'Fhorner', 'Fhypot', 'Fpolynomial', 'Fpowers', 'Fcbrt', 'Froot', 'Fsqrt', 

248 'bqrt', 'cbrt', 'cbrt2', 'euclid', 'euclid_', 

249 'facos1', 'fasin1', 'fatan', 'fatan1', 'fatan2', 'favg', 

250 'fdot', 'fdot_', 'fdot3', 'fma', 'fmean', 'fmean_', 'fhorner', 'fidw', 'f2mul_', 

251 'fpolynomial', 'fpowers', 'fprod', 'frandoms', 'frange', 'freduce', 'fremainder', 

252 'hypot', 'hypot_', 'hypot1', 'hypot2', 'hypot2_', 

253 'norm2', 'norm_', 'polar2', 'polar2d', 

254 'sqrt0', 'sqrt3', 'sqrt_a', 'zcrt', 'zqrt'), 

255 formy=_a('Radical2Tuple', 

256 'angle2chord', 'antipode', 'antipode_', 'bearing', 'bearing_', 

257 'chord2angle', 'compassAngle', 'cosineLaw', 'cosineLaw_', 

258 'equirectangular', 'equirectangular4', 'euclidean', 'euclidean_', 

259 'excessAbc_', 'excessCagnoli_', 'excessGirard_', 'excessLHuilier_', 

260 'excessKarney', 'excessKarney_', 'excessQuad', 'excessQuad_', 

261 'flatLocal', 'flatLocal_', 'flatPolar', 'flatPolar_', 

262 'hartzell', 'haversine', 'haversine_', 'heightOf', 'heightOrthometric', 'horizon', 'hubeny', 'hubeny_', 

263 'intersection2', 'intersections2', 'isantipode', 'isantipode_', 'isnormal', 'isnormal_', 

264 'normal', 'normal_', 'opposing', 'opposing_', 'radical2', 

265 'thomas', 'thomas_', 'vincentys', 'vincentys_'), 

266 frechet=_a('Frechet', 'FrechetDegrees', 'FrechetError', 'FrechetRadians', 'FrechetCosineLaw', 

267 'FrechetDistanceTo', 'FrechetEquirectangular', 'FrechetEuclidean', 'FrechetExact', 

268 'FrechetFlatLocal', 'FrechetFlatPolar', 'FrechetHaversine', 'FrechetHubeny', 'FrechetKarney', 

269 'FrechetThomas', 'FrechetVincentys', 'Frechet6Tuple', 

270 'frechet_'), 

271 fstats=_a('Fcook', 'Flinear', 'Fwelford'), 

272 fsums=_a('Fsum', 'DivMod2Tuple', 'Fsum2Tuple', 'ResidualError', 

273 'f2product', 'fsum', 'fsum_', 'fsumf_', 'fsum1', 'fsum1_', 'fsum1f_', 'nonfiniterrors'), 

274 gars=_a('Garef', 'GARSError'), 

275 geodesici=_a('Intersectool', 'Intersectool5Tuple', 'Intersect7Tuple', 

276 'Intersector', 'Intersector5Tuple', 'Middle5Tuple', 'XDict'), 

277 geodesicw=_a('Geodesic', 'GeodesicLine', 'Geodesic_WGS84'), 

278 geodesicx=_a('gx', 'gxarea', 'gxbases', 'gxline', # modules 

279 'GeodesicAreaExact', 'GeodesicExact', 'GeodesicLineExact', 'PolygonArea'), 

280 geodsolve=_a('GeodesicSolve', 'GeodesicLineSolve', 'GeodSolve12Tuple'), 

281 geod3solve=_a('Geodesic3Solve', 'GeodesicLine3Solve', 'Geod3Solve8Tuple', 'Geodesic3Error'), 

282 geohash=_a('Geohash', 'Geohashed', 'GeohashError', 'Neighbors8Dict', 'Resolutions2Tuple', 'Sizes3Tuple'), 

283 geoids=_a('GeoidError', 'GeoidEGM96', 'GeoidG2012B', 'GeoidKarney', 'GeoidPGM', 'egmGeoidHeights', 

284 'PGMError', 'GeoidHeight5Tuple'), 

285 hausdorff=_a('Hausdorff', 'HausdorffDegrees', 'HausdorffError', 'HausdorffRadians', 'HausdorffCosineLaw', 

286 'HausdorffDistanceTo', 'HausdorffEquirectangular', 'HausdorffEuclidean', 'HausdorffExact', 

287 'HausdorffFlatLocal', 'HausdorffFlatPolar', 'HausdorffHaversine', 'HausdorffHubeny', 

288 'HausdorffKarney', 'HausdorffThomas', 'HausdorffVincentys', 'Hausdorff6Tuple', 

289 'hausdorff_', 'randomrangenerator'), 

290 heights=_a('HeightCubic', 'HeightError', 'HeightIDWcosineLaw', 'HeightIDWdistanceTo', 

291 'HeightIDWequirectangular', 'HeightIDWeuclidean', 'HeightIDWexact', 'HeightIDWflatLocal', 

292 'HeightIDWflatPolar', 'HeightIDWhaversine', 'HeightIDWhubeny', 'HeightIDWkarney', 'HeightIDWthomas', 

293 'HeightIDWvincentys', 'HeightLinear', 'HeightLSQBiSpline', 'HeightSmoothBiSpline'), 

294 internals=_internals.__all__, 

295 interns=_interns.__all__, 

296 iters=_a('LatLon2PsxyIter', 'PointsIter', 'points2', 

297 'isNumpy2', 'isPoints2', 'isTuple2', 'iterNumpy2', 'iterNumpy2over'), 

298 karney=_a('Area3Tuple', 'Caps', 'Direct9Tuple', 'GDict', 'Inverse10Tuple'), 

299 ktm=_a('KTMError', 'KTransverseMercator'), 

300 latlonBase=_a('latlon2n_xyz', 'philam2n_xyz'), 

301 lazily=_a('LazyAttributeError', 'LazyImportError', 'isLazy'), 

302 lcc=_a('Conic', 'Conics', 'Lcc', 'LCCError', 'toLcc'), 

303 ltp=_a('Attitude', 'AttitudeError', 'ChLV', 'ChLVa', 'ChLVe', 'Frustum', 

304 'LocalCartesian', 'LocalError', 'Ltp', 'tyr3d'), 

305 ltpTuples=_a('Aer', 'Aer4Tuple', 'Attitude4Tuple', 

306 'ChLVEN2Tuple', 'ChLV9Tuple', 'ChLVYX2Tuple', 'ChLVyx2Tuple', 

307 'Enu', 'Enu4Tuple', 'Footprint5Tuple', 'Local9Tuple', 'Los', 

308 'Ned', 'Ned4Tuple', 'Uvw', 'Uvw3Tuple', 'XyzLocal', 'Xyz4Tuple'), 

309 mgrs=_a('Mgrs', 'parseMGRS', 'toMgrs', 'Mgrs4Tuple', 'Mgrs6Tuple'), 

310 named=_a('ADict', 

311 'callername', 'classname', 'classnaming', 'modulename', 

312 'nameof', 'notImplemented', 'notOverloaded'), 

313 namedTuples=_a('Bearing2Tuple', 'Bounds2Tuple', 'Bounds4Tuple', 

314 'Circle4Tuple', 'Destination2Tuple', 'Destination3Tuple', 

315 'Distance2Tuple', 'Distance3Tuple', 'Distance4Tuple', 

316 'EasNor2Tuple', 'EasNor3Tuple', 'Ellipse5Tuple', 

317 'Forward4Tuple', 'Intersection3Tuple', 

318 'LatLon2Tuple', 'LatLon3Tuple', 'LatLon4Tuple', 

319 'LatLonDatum3Tuple', 'LatLonDatum5Tuple', 

320 'LatLonPrec3Tuple', 'LatLonPrec5Tuple', 

321 'NearestOn2Tuple', 'NearestOn3Tuple', 'NearestOn6Tuple', 'NearestOn8Tuple', 

322 'PhiLam2Tuple', 'PhiLam3Tuple', 'PhiLam4Tuple', 'Point3Tuple', 'Points2Tuple', 

323 'Reverse4Tuple', 'Triangle7Tuple', 'Triangle8Tuple', 'Trilaterate5Tuple', 

324 'UtmUps2Tuple', 'UtmUps5Tuple', 'UtmUps8Tuple', 'UtmUpsLatLon5Tuple', 

325 'Vector2Tuple', 'Vector3Tuple', 'Vector4Tuple'), 

326 nvectorBase=_a('NorthPole', 'SouthPole', 'n_xyz2latlon', 'n_xyz2philam'), 

327 osgr=_a('Osgr', 'OSGRError', 'parseOSGR', 'toOsgr'), 

328 points=_a('LatLon_', 'LatLon2psxy', 'Numpy2LatLon', 'Shape2Tuple', 'Tuple2LatLon', 

329 'areaOf', 'boundsOf', 'centroidOf', 'fractional', 

330 'isclockwise', 'isconvex', 'isconvex_', 'isenclosedBy', 'ispolar', 

331 'luneOf', 'nearestOn5', 'perimeterOf', 'quadOf'), 

332 props=_a('Property', 'Property_RO', 'property_doc_', 

333 'property_RO', 'property_ROnce', 'property_ROver', 

334 'deprecated_class', 'deprecated_function', 'deprecated_method', 

335 'deprecated_Property_RO', 'deprecated_property_RO', 'DeprecationWarnings'), 

336 resections=_a('Collins5Tuple', 'ResectionError', 'Survey3Tuple', 'Tienstra7Tuple', 

337 'TriAngle5Tuple', 'TriSide2Tuple', 'TriSide4Tuple', 

338 'cassini', 'collins5', 'pierlot', 'pierlotx', 'tienstra7', 

339 'snellius3', 'wildberger3', 

340 'triAngle', 'triAngle5', 'triArea', 'triSide', 'triSide2', 'triSide4'), 

341 rhumb=_a(), # module only 

342 rhumb_aux_=_a('RhumbAux', 'RhumbLineAux'), 

343 rhumb_ekx=_a('Rhumb', 'RhumbLine'), 

344 rhumb_solve=_a('RhumbSolve', 'RhumbLineSolve', 'RhumbSolve7Tuple', 'Rhumb8Tuple'), # in .karney 

345 sphericalBase=_a(), # module only 

346 sphericalNvector=_a(), # module only 

347 sphericalTrigonometry=_a(), # module only 

348 simplify=_a('simplify1', 'simplifyRDP', 'simplifyRW', 'simplifyVW'), 

349 solveBase=_a(), # module only 

350 streprs=_a('anstr', 'attrs', 'enstr2', 'fstr', 'fstrzs', 'hstr', 'instr', 

351 'lrstrip', 'pairs', 'reprs', 'strs', 'unstr'), 

352 trf=_a('RefFrame', 'RefFrames', 'TransformXform', 'TRFXform', 'TRFXform7Tuple', 

353 'date2epoch', 'epoch2date', 'trfTransform0', 'trfTransforms', 'trfXform'), 

354 triaxials=_a(), # module only 

355 triaxials_bases=_a('LLK', 'TriaxialError'), 

356 triaxials_conformal3=_a('BetOmgGam5Tuple', 

357 'Conformal3', 'Conformal3B', 'Conformal3Sphere', 'Conformal5Tuple'), 

358 triaxials_triaxial3=_a('BetOmgAlp5Tuple', 'Cartesian5Tuple', 'PhiLamZet5Tuple', 

359 'Triaxial3', 'Triaxial3B', 'Triaxial3s'), 

360 triaxials_triaxial5=_a('BetaOmega2Tuple', 'BetaOmega3Tuple', 

361 'Conformal', 'ConformalSphere', 'Conformal2Tuple', 

362 'Triaxial', 'Triaxial_', 'Triaxials', 'hartzell4', 'height4'), 

363 units=_a('Azimuth', 'Band', 'Bearing', 'Bearing_', 'Bool', 

364 'Degrees', 'Degrees_', 'Degrees2', 'Distance', 'Distance_', 'Easting', 'Epoch', 

365 'Feet', 'FIx', 'Float_', 'Height', 'Height_', 'HeightX', 'Int_', 

366 'Lam', 'Lamd', 'Lat', 'Lat_', 'Lon', 'Lon_', 

367 'Meter', 'Meter_', 'Meter2', 'Meter3', 'Northing', 'Number_', 

368 'Phi', 'Phid', 'Precision_', 'Radians', 'Radians_', 'Radians2', 

369 'Radius_', 'Scalar', 'Scalar_', 'Zone'), 

370 unitsBase=_a('Float', 'Int', 'Radius', 'Str'), 

371 ups=_a('Ups', 'UPSError', 'parseUPS5', 'toUps8', 'upsZoneBand5'), 

372 utily=_a('acos1', 'acre2ha', 'acre2m2', 'agdf', 'asin1', 

373 'atan1', 'atan1d', 'atan2', 'atan2b', 'atan2d', 'atan2p', 

374 'chain2m', 'circle4', 'cot', 'cot_', 'cotd', 'cotd_', 

375 'degrees', 'degrees90', 'degrees180', 'degrees360', 'degrees2grades', 'degrees2m', 

376 'fathom2m', 'ft2m', 'furlong2m', # 'degrees2grades as degrees2gons', 

377 'gdf', 'grades', 'grades400', 'grades2degrees', 'grades2radians', 

378# 'grades as gons', 'grades400 as gons400', 'grades2degrees as gons2degrees', 'grades2radians as gons2radians', 

379 'ha2acre', 'ha2m2', 'hav', 'km2m', 

380 'm2acre', 'm2chain', 'm2degrees', 'm2fathom', 'm2ft', 'm2furlong', 

381 'm2ha', 'm2km', 'm2NM', 'm2radians', 'm2SM', 'm2toise', 'm2yard', 

382 'NM2m', 'radians', 'radiansPI', 'radiansPI2', 'radiansPI_2', 'radians2m', 

383 'sincos2', 'SinCos2', 'sincos2_', 'sincos2d', 'sincos2d_', 'sincostan3', 'sincostan3d', 'SM2m', 

384 'tan', 'tan_', 'tand', 'tand_', 'tan_2', 'tanPI_2_2', 'toise2m', 'truncate', 

385 'unroll180', 'unrollPI', 

386 'wrap90', 'wrap180', 'wrap360', 'wrapPI_2', 'wrapPI', 'wrapPI2', 'wrap_normal', 

387 'yard2m'), 

388 utm=_a('Utm', 'UTMError', 'parseUTM5', 'toUtm8', 'utmZoneBand5'), 

389 utmups=_a('UtmUps', 'UTMUPSError', 'parseUTMUPS5', 'toUtmUps8', 

390 'utmupsValidate', 'utmupsValidateOK', 'utmupsZoneBand5'), 

391 utmupsBase=_a(), # module only 

392 vector2d=_a('Circin6Tuple', 'Circum3Tuple', 'Circum4Tuple', 'Meeus2Tuple', 'Radii11Tuple', 'Soddy4Tuple', 'Triaxum5Tuple', 

393 'circin6', 'circum3', 'circum4', 'circum4_', 'meeus2', 'radii11', 'soddy4', 'triaxum5', 'trilaterate2d2'), 

394 vector3d=_a('Vector3d', 'intersection3d3', 'iscolinearWith', 'nearestOn', 'nearestOn6', 'parse3d', 

395 'trilaterate3d2'), 

396 vector3dBase=_a(), # module only 

397 webmercator=_a('Wm', 'WebMercatorError', 'parseWM', 'toWm', 'EasNorRadius3Tuple'), 

398 wgrs=_a('Georef', 'WGRSError'),) 

399 

400_ALL_DEPRECATED = _NamedEnum_RO(_name='_ALL_DEPRECATED', 

401 deprecated=_a('bases', 'datum', 'nvector', # DEPRECATED modules and ... 

402 'rhumbaux', 'rhumbBase', 'rhumbsolve', 'rhumbx'), # ... names 

403 deprecated_bases=_a('LatLonHeightBase', 'points2'), 

404 deprecated_classes=_a('ClipCS3Tuple', 'EasNorExact4Tuple', 'EcefCartesian', 'Fn_rt', 

405 'FrechetCosineAndoyerLambert', 'FrechetCosineForsytheAndoyerLambert', 

406 'HausdorffCosineAndoyerLambert', 'HausdorffCosineForsytheAndoyerLambert', 

407 'HeightIDW', 'HeightIDW2', 'HeightIDW3', 'HeightIDWcosineAndoyerLambert', 

408 'HeightIDWcosineForsytheAndoyerLambert', 'Helmert7Tuple', 

409 'JacobiConformal', 'JacobiConformalSpherical', 'Jacobi2Tuple', 

410 'Lam_', 'LatLonExact4Tuple', 'NearestOn4Tuple', 'Ned3Tuple', 

411 'Phi_', 'RefFrameError', 'Rhumb7Tuple', 'RhumbOrder2Tuple', 

412 'Transform7Tuple', 'TriAngle4Tuple', 'UtmUps4Tuple', 'XDist'), 

413 deprecated_consterns=_a('Elliperim', 'EPS1_2', 'MANTIS', 'OK'), 

414 deprecated_datum=_a('Curvature2Tuple', 'Datum', 'Ellipsoid', 'Transform', # assert 

415 'Datums', 'Ellipsoids', 'Transforms', 

416 'R_FM', 'R_KM', 'R_M', 'R_MA', 'R_MB', 'R_NM', 'R_SM', 'R_VM'), 

417 deprecated_functions=_a('anStr', 'areaof', 'atand', 'bounds', # most of the DEPRECATED functions, except ellipsoidal ... 

418 'clipCS3', 'clipDMS', 'clipStr', 'collins', 'copysign', # ... and spherical flavors 

419 'cosineAndoyerLambert', 'cosineAndoyerLambert_', 

420 'cosineForsytheAndoyerLambert', 'cosineForsytheAndoyerLambert_', 

421 'decodeEPSG2', 

422 'elliperim', 'elliperim_', 'encodeEPSG', 'enStr2', 'equirectangular_', 'equirectangular3', 

423 'excessAbc', 'excessGirard', 'excessLHuilier', 

424 'false2f', 'falsed2f', 'float0', 'fStr', 'fStrzs', 'Fsum2product', 

425 'hypot3', 'inStr', 'isenclosedby', 'istuplist', 

426 'joined', 'joined_', 'nearestOn3', 'nearestOn4', 

427 'parseUTM', 'perimeterof', 'polygon', 

428 'scalar', 'simplify2', 'simplifyRDPm', 'simplifyVWm', 

429 'tienstra', 'toUtm', 'triAngle4', 

430 'unsign0', 'unStr', 'utmZoneBand2'), 

431 deprecated_nvector=_a('LatLonNvectorBase', 'Nvector', 'sumOf', 'NorthPole', 'SouthPole'),) 

432 

433 

434class _ALL_MODS(_internals._MODS_Base): 

435 '''(INTERNAL) Memoized import of any L{pygeodesy} module. 

436 ''' 

437 def __getattr__(self, name): 

438 '''Get a C{pygeodesy} module or attribute by B{C{name}}. 

439 

440 @arg name: Un/qualified module or qualified attribute name (C{str}). 

441 

442 @raise ImportError: Importing module B{C{name}} failed. 

443 

444 @raise AttributeError: No attribute named B{C{name}}. 

445 ''' 

446 try: 

447 v = _lazy_dict[name] # package.__dict__ 

448 except KeyError: 

449 v = _lazy_module(name) # package.__getattr__ 

450 if _tailof(typename(v)) != name: 

451 try: 

452 v = getattr(v, _tailof(name)) 

453 except AttributeError: 

454 pass # XXX LazyAttributeError? 

455 return v 

456 

457 def getattr(self, name, *attr_dflt): # , parent=_pygeodesy_ 

458 '''Get an attribute of/or a C{pygeodesy} module. 

459 

460 @arg name: Un/qualified module name (C{str}). 

461 @arg attr_dflt: Optional attribute name (C{str}) and 

462 optional default value (any C{type}). 

463 

464 @return: The C{pygeodesy} module's attribute value. 

465 

466 @raise ImportError: Importing module B{C{name}} failed. 

467 

468 @raise AttributeError: No attribute named B{C{attr}}. 

469 ''' 

470 v = self.getmodule(name) 

471 if attr_dflt: 

472 v = getattr(v, *attr_dflt) 

473 return v 

474 

475 def getmodule(self, name, parent=_pygeodesy_): 

476 '''Get a C{pygeodesy} module or the C{__main__}. 

477 

478 @arg name: Un/qualified module name (C{str}). 

479 

480 @return: The C{pygeodesy} module. 

481 

482 @raise ImportError: Importing module B{C{name}} failed. 

483 ''' 

484 if _headof(name) != parent and name != _DMAIN_: 

485 name = _DOT_(parent, name) 

486 try: 

487 return _sys.modules[name] 

488 except KeyError: 

489 return _getmodule(name, parent) 

490 

491 def imported(self, name): 

492 '''Return module or package C{name} if already imported. 

493 ''' 

494 return _sys.modules.get(name, None) 

495 

496 def into(self, **mod_DNAME): 

497 '''Deferred import of module C{mod} into module C{_DNAME_} 

498 and overwrite C{_DNAME_._mod} to module C{mod}, I{once} 

499 at the first access of an attribute of module C{mod}. 

500 ''' 

501 # assert len(mod_DNAME) == 1 

502 # mod, dun = mod_DNAME.popitem() 

503 

504 class _Into(object): 

505 

506 def __getattr__(unused, name): 

507 m = _getmodinto(mod_DNAME, _Into) 

508 return getattr(m, name) 

509 

510 return _Into() 

511 

512# @_Property_RO 

513# def _isBoolean(self): 

514# '''(INTERNAL) Get function C(.booleans.isBoolean}, I{once}. 

515# ''' 

516# return self.booleans.isBoolean 

517 

518 def items(self): # no module named 'items' 

519 '''Yield the modules imported so far. 

520 ''' 

521 for n, m in _sys.modules.items(): 

522 if _headof(n) == _pygeodesy_: 

523 yield n, m 

524 

525 @_Property_RO 

526 def _triaxials_triaxial5(self): 

527 '''(INTERNAL) Get module C{triaxial.triaxials}. 

528 ''' 

529 return self.triaxials.triaxial5 

530 

531_internals._MODS = _ALL_MODS = _ALL_MODS() # PYCHOK singleton 

532 

533__all__ = _ALL_LAZY.lazily 

534__version__ = '26.03.20' 

535 

536 

537def _ALL_OTHER(*objs): 

538 '''(INTERNAL) Get class and function B{C{objs}} for __all__. 

539 ''' 

540 def _interned(o): # intern'd base name 

541 n = _tailof(typename(o)) 

542 i = NN(_UNDER_, n, _UNDER_) # intern'd 

543 return getattr(_interns, i, n) 

544 

545 return tuple(map(_interned, objs)) # map2 

546 

547 

548if _FOR_DOCS: # PYCHOK no cover 

549 _ALL_DOCS = _ALL_OTHER 

550 # (INTERNAL) Only export B{C{objs.__name__}} when making the 

551 # docs to force C{epydoc} to include certain classes, methods, 

552 # functions and other names in the documentation. Using the 

553 # C{epydoc --private ...} command line option tends to include 

554 # too much internal documentation. 

555else: 

556 def _ALL_DOCS(*unused): 

557 return () 

558 

559 

560def _all_deprecates(): 

561 '''(INTERNAL) Build C{dict} of all deprecated imports and attributes. 

562 ''' 

563 D = _ALL_DEPRECATES 

564 if not D: 

565 _ALL_DEPRECATED.fill_D(D, _all_deprecates) # see _all_imports() 

566 return D 

567 

568_ALL_DEPRECATES = _Dict() # PYCHOK _ALL_DEPRECATED.imports() 

569 

570 

571def _all_enums(): 

572 '''(INTERNAL) Yield all C{(mod_, tuple)} pairs for C{__init__._all}. 

573 ''' 

574 # assert _init__all__ 

575 for mod_t in _ALL_LAZY.enums(): 

576 yield mod_t 

577 if _FOR_DOCS: 

578 for mod_t in _ALL_DEPRECATED.enums(): 

579 yield mod_t 

580 

581 

582def _all_imports(): 

583 '''(INTERNAL) Build C{dict} of all lazy imports. 

584 ''' 

585 # imports naming conventions stored below - [<key>] = <from>: 

586 # import <module> - [<module>] = <module> 

587 # from <module> import <attr> - [<attr>] = <module> 

588 # from pygeodesy import <attr> - [<attr>] = <attr> 

589 # from <module> import <attr> as <name> - [<name>] = <module>.<attr>. 

590 D = _ALL_IMPORTS 

591 if not D: 

592 _ALL_LAZY.fill_D(D, _all_imports) # see _all_deprecates() 

593 return D 

594 

595_ALL_IMPORTS = _Dict() # PYCHOK _ALL_LAZY.imports() 

596 

597 

598def _all_missing2(_all_): 

599 '''(INTERNAL) Get diffs between pygeodesy.__all__ and lazily._all_imports. 

600 ''' 

601 def _diff(one, two): 

602 return tuple(sorted(a for a in one if a not in two)) 

603 

604 _alzy = _Dict((a, a) for a in _ALL_INIT) 

605 _alzy.update(_all_imports()) # without _all_backups! 

606 return ((_DOT_(_lazily_, _all_imports.__name__), _diff(_all_, _alzy)), 

607 (_DOT_(_pygeodesy_, _DALL_), _diff(_alzy.keys(), _all_))) 

608 

609 

610def _getattras(attr_as): # test/testDeprecated 

611 '''(INTERNAL) Get the C{"as name"} or C{"name"} of a lazy entry. 

612 ''' 

613 a_, _, as_ = attr_as.partition(_asSPACED_) 

614 return as_ or a_.rstrip(_DOT_) 

615 

616 

617def _getmodattr(m, name, mod=_pygeodesy_): 

618 '''(INTERNAL) Get attr C{m.name}. 

619 ''' 

620 try: 

621 return getattr(m, name) 

622 except AttributeError: 

623 name = _DOT_(typename(m, mod), name) 

624 # <https://GitHub.com/mrJean1/PyGeodesy/issues/76> 

625 raise LazyAttributeError(_no_(_attribute_), txt=name) 

626 

627 

628def _getmodinto(mod_DNAME, *Intos): 

629 '''(INTERNAL) Core of C{_ALL_MODS.into}. 

630 ''' 

631 _MODS = _ALL_MODS 

632 mod, dun = _MODS.errors._xkwds_item2(mod_DNAME) 

633 _mod = _UNDER_(NN, mod) 

634 d = _MODS.getmodule(dun) # '__main__' OK 

635 i = _getmodattr(d, _mod, dun) 

636 assert isinstance(i, Intos) 

637 m = _MODS.getmodule(mod) 

638 setattr(d, _mod, m) # overwrite C{d._mod} 

639 if isLazy and isLazy > 1: 

640 t = _SPACE_(_HASH_, _imported_, m.__name__) # typename(m) 

641 _hash_imported(t, _MODS.into.__name__) 

642 assert getattr(d, _mod, None) is m 

643 return m 

644 

645 

646def _getmodule(name, *parent): 

647 '''(INTERNAL) Wrapper for C{import_module}. 

648 ''' 

649 try: 

650 return import_module(name, parent) 

651 except ImportError: 

652 # <https://GitHub.com/mrJean1/PyGeodesy/issues/76> 

653 raise LazyImportError(_no_(_module_), txt=name) 

654 

655 

656def _hash_imported(t, by_into, up=3): 

657 '''(INTERNAL) Helper for C{_lazy_import2} and C{_ALL_MODS.into}. 

658 ''' 

659 if isLazy and isLazy > 2: 

660 try: # see C{internals._caller3} 

661 _, f, s = _caller3(up) 

662 t = _SPACE_(t, by_into, f, _line_, s) 

663 except ValueError: 

664 pass 

665 printf(t) # XXX print 

666 

667 

668# def _lazy_attributes(DUNDER_name): 

669# '''(INTERNAL) Return a function to C{B{__name__}.__getattr__(attr)} 

670# on lazily imported modules and sub-modules. 

671# ''' 

672# if _unlazy: 

673# raise AssertionError(_COMMASPACE_(DUNDER_name, _not_(_DEPRECATED_))) 

674# 

675# def _getattr(attr, *dflt): 

676# try: # a module name 

677# return _ALL_MODS.getmodule(attr) 

678# except (AttributeError, ImportError): 

679# return _ALL_MODS.getattr(DUNDER_name, attr, *dflt) 

680# 

681# return _getattr 

682 

683 

684_lazy_dict = {} # PYCHOK overwritten by _lazy_import2 

685 

686 

687def _lazy_import2(pack): # MCCABE 14 

688 '''Check for and set up C{lazy import}. 

689 

690 @arg pack: The name of the package (C{str}) performing the imports, 

691 to help resolving relative imports, usually C{__package__}. 

692 

693 @return: 2-Tuple C{(package, getattr)} of the importing package for 

694 easy reference within itself and the callable to be set to 

695 C{package.__getattr__}. 

696 

697 @raise LazyAttributeError: The package, module or attribute name is 

698 invalid or does not exist. 

699 

700 @raise LazyImportError: Lazy import not supported or not enabled or 

701 an import failed. 

702 

703 @note: This is I{Brett Cannon}'s function U{modutil.lazy_import 

704 <https://GitHub.com/brettcannon/modutil/blob/master/modutil.py>} 

705 modified to handle the C{__all__} and C{__dir__} attributes and 

706 call C{importlib.import_module(<module>.<name>, ...)} without 

707 causing a C{ModuleNotFoundError}. 

708 

709 @see: The original U{modutil<https://PyPI.org/project/modutil>}, 

710 U{PEP 562<https://www.Python.org/dev/peps/pep-0562>} and the 

711 U{new way<https://Snarky.CA/lazy-importing-in-python-3-7/>}. 

712 ''' 

713 if pack != _pygeodesy_ or _unlazy: # Python 3.7+ # PYCHOK no cover 

714 t = _DOT_(pack, typename(_lazy_import2)) 

715 raise LazyImportError(_no_(t), txt=_versions()) 

716 

717 package, parent = _lazy_init2(pack) # _pygeodesy_ 

718 

719 _DPACKAGE_ = '__package__' 

720 _lazily_imported_ = _SPACE_(_HASH_, _lazily_, _imported_, parent) 

721 

722 sub_packages = set((parent, NN) + tuple( 

723 _DOT_(parent, s) for s in _SUB_PACKAGES)) 

724 imports = _all_imports() 

725 deprecates = _all_deprecates() 

726 

727 def __getattr__(name): # __getattr__ only for Python 3.7+