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 # in .rdnap._v_grid 

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(), # package 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', 'Similarity', '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', 'LqRD', '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(), # package 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(), # package 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 

534def _ALL_OTHER(*objs): 

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

536 ''' 

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

538 n = _tailof(typename(o)) 

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

540 return getattr(_interns, i, n) 

541 

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

543 

544 

545if _FOR_DOCS: # PYCHOK no cover 

546 _ALL_DOCS = _ALL_OTHER 

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

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

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

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

551 # too much internal documentation. 

552else: 

553 def _ALL_DOCS(*unused): 

554 return () 

555 

556 

557def _all_deprecates(): 

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

559 ''' 

560 D = _ALL_DEPRECATES 

561 if not D: 

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

563 return D 

564 

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

566 

567 

568def _all_enums(): 

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

570 ''' 

571 # assert _init__all__ 

572 for mod_t in _ALL_LAZY.enums(): 

573 yield mod_t 

574 if _FOR_DOCS: 

575 for mod_t in _ALL_DEPRECATED.enums(): 

576 yield mod_t 

577 

578 

579def _all_imports(): 

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

581 ''' 

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

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

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

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

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

587 D = _ALL_IMPORTS 

588 if not D: 

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

590 return D 

591 

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

593 

594 

595def _all_missing2(_all_): 

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

597 ''' 

598 def _diff(one, two): 

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

600 

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

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

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

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

605 

606 

607def _getattras(attr_as): # test/testDeprecated 

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

609 ''' 

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

611 return as_ or a_.rstrip(_DOT_) 

612 

613 

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

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

616 ''' 

617 try: 

618 return getattr(m, name) 

619 except AttributeError: 

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

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

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

623 

624 

625def _getmodinto(mod_DNAME, *Intos): 

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

627 ''' 

628 _MODS = _ALL_MODS 

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

630 _mod = _UNDER_(NN, mod) 

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

632 i = _getmodattr(d, _mod, dun) 

633 assert isinstance(i, Intos) 

634 m = _MODS.getmodule(mod) 

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

636 if isLazy and isLazy > 1: 

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

638 _hash_imported(t, _MODS.into.__name__) 

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

640 return m 

641 

642 

643def _getmodule(name, *parent): 

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

645 ''' 

646 try: 

647 return import_module(name, parent) 

648 except ImportError: 

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

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

651 

652 

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

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

655 ''' 

656 if isLazy and isLazy > 2: 

657 try: # see C{internals._caller3} 

658 _, f, s = _caller3(up) 

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

660 except ValueError: 

661 pass 

662 printf(t) # XXX print 

663 

664 

665# def _lazy_attributes(DUNDER_name): 

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

667# on lazily imported modules and sub-modules. 

668# ''' 

669# if _unlazy: 

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

671# 

672# def _getattr(attr, *dflt): 

673# try: # a module name 

674# return _ALL_MODS.getmodule(attr) 

675# except (AttributeError, ImportError): 

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

677# 

678# return _getattr 

679 

680 

681_lazy_dict = {} # PYCHOK overwritten by _lazy_import2 

682 

683 

684def _lazy_import2(pack): # MCCABE 14 

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

686 

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

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

689 

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

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

692 C{package.__getattr__}. 

693 

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

695 invalid or does not exist. 

696 

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

698 an import failed. 

699 

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

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

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

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

704 causing a C{ModuleNotFoundError}. 

705 

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

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

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

709 ''' 

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

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

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

713 

714 package, parent = _lazy_init2(pack) # _pygeodesy_ 

715 

716 _DPACKAGE_ = '__package__' 

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

718 

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

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

721 imports = _all_imports() 

722 deprecates = _all_deprecates() 

723 

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

725 # only called once for each undefined pygeodesy attribute 

726 mod = imports.get(name, NN) or deprecates.get(name, NN)