Coverage for pygeodesy/lazily.py: 92%

208 statements  

« prev     ^ index     » next       coverage.py v7.2.2, created at 2024-02-07 13:12 -0500

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 

30# from pygeodesy.errors import _xError2 # _ALL_MODS 

31from pygeodesy.interns import MISSING, NN, __all__ as _interns__all__, _areaOf_, \ 

32 _attribute_, _by_, _COLONSPACE_, _COMMASPACE_, \ 

33 _doesn_t_exist_, _DOT_, _enabled_, _EQUALSPACED_, \ 

34 _from_, _HASH_, _immutable_, _isclockwise_, _ispolar_, \ 

35 _NL_, _no_, _NorthPole_, _not_, _or_, _pygeodesy_, \ 

36 _line_, _module_, _pygeodesy_abspath_, _Python_, _QUOTE1_, \ 

37 _QUOTE2_, _SouthPole_, _SPACE_, _sub_packages, _UNDER_, \ 

38 _version_, _dunder_nameof, _headof, _tailof # _DEPRECATED_ 

39from pygeodesy.interns import _intern # PYCHOK used! 

40# from pygeodesy.streprs import Fmt, pairs, unstr # _ALL_MODS 

41from pygeodesy import _isfrozen # handle as w/o lazy import 

42 

43from os import getenv as _getenv # in .errors, .geodsolve, .props, .units 

44from os.path import basename as _basename 

45import sys as _sys # in .basics._sizeof 

46try: 

47 from importlib import import_module 

48except ImportError: # Python 2.6- 

49 def import_module(name, *package): 

50 t = _ALL_MODS.streprs.unstr(import_module, name, *package) 

51 raise LazyImportError(t, txt=_doesn_t_exist_) 

52 

53_a_l_l_ = '__all__' # .__main__ 

54__as__ = ' as ' 

55_FOR_DOCS = _getenv('PYGEODESY_FOR_DOCS', NN) # for epydoc ... 

56_from_DOT__ = _SPACE_(NN, _from_, _DOT_) 

57_i0 = () # PYCHOK empty tuple 

58_init__all__ = _FOR_DOCS or _getenv('PYGEODESY_INIT__ALL__', _a_l_l_) == _a_l_l_ # PYCHOK expoted 

59_lazily_ = 'lazily' 

60_lazily_imported__ = _SPACE_(_HASH_, _lazily_, 'imported', NN) 

61_p_a_c_k_a_g_e_ = '__package__' 

62_PYGEODESY_GEOCONVERT_ = 'PYGEODESY_GEOCONVERT' # PYCHOK .mgrs, test.bases 

63_PYGEODESY_GEODSOLVE_ = 'PYGEODESY_GEODSOLVE' # PYCHOK .geodsolve, test.bases 

64_PYGEODESY_LAZY_IMPORT_ = 'PYGEODESY_LAZY_IMPORT' 

65_PYGEODESY_RHUMBSOLVE_ = 'PYGEODESY_RHUMBSOLVE' # PYCHOK .rhumb.solve, test.bases 

66_PYTHON_X_DEV = getattr(_sys, '_xoptions', {}).get('dev', # Python 3.2+ 

67 _getenv('PYTHONDEVMODE', NN)) # PYCHOK exported 

68_sys_version_info2 = _sys.version_info[:2] # in .basics, .fmath, ... 

69_unlazy = _unLazy0 = _isfrozen or _sys_version_info2 < (3, 7) # PYCHOK mod.__getattr__ 3.7+ 

70_WARNINGS_X_DEV = _getenv('PYGEODESY_WARNINGS', NN) and ( 

71 _PYTHON_X_DEV or bool(_sys.warnoptions)) # PYCHOK .props 

72# @module_property[_RO?] <https://GitHub.com/jtushman/proxy_tools/> 

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

74 

75 

76class LazyAttributeError(AttributeError): 

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

78 ''' 

79 def __init__(self, *name_value, **txt): 

80 _ALL_MODS.errors._error_init(AttributeError, self, name_value, **txt) 

81 

82 

83class LazyImportError(ImportError): 

84 '''Raised if C{lazy import} is not supported, disabled or failed some other way. 

85 ''' 

86 def __init__(self, *name_value, **txt): 

87 _ALL_MODS.errors._error_init(ImportError, self, name_value, **txt) 

88 

89 

90class _Dict(dict): 

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

92 ''' 

93 _name = NN 

94 

95 def __getattr__(self, attr): 

96 try: 

97 return self[attr] 

98 except KeyError: 

99 return dict.__getattr__(self, attr) 

100 

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

102# if attr in self: 

103# self[attr] = value 

104# else: 

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

106 

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

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

109 

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

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

112 ''' 

113 if name in self: 

114 sub = self[name] # duplicate OK 

115 if sub != mod_ and sub not in subs: # PYCHOK no cover 

116 t = _DOT_(self._name, name) 

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

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

119 raise AssertionError(t) 

120 else: 

121 self[name] = mod_ 

122 

123 def _NAME(self, which): 

124 self._name = _intern(which.__name__.upper()) 

125 

126 

127class _NamedEnum_RO(dict): 

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

129 ''' 

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

131 

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

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

134 

135 def __getattr__(self, attr): 

136 try: 

137 return self[attr] 

138 except KeyError: 

139 t = self._DOT_(attr) 

140 raise LazyAttributeError(t, txt=_doesn_t_exist_) 

141 

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

143 t = _EQUALSPACED_(self._DOT_(attr), value) 

144 raise LazyAttributeError(t, txt=_immutable_) 

145 

146 def enums(self): 

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

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

149 n = m.replace(_UNDER_, _DOT_) 

150 if n != m: 

151 if m.startswith(_UNDER_): 

152 t = None # skip _name= ... 

153 else: 

154 u = m.rstrip(_UNDER_) 

155 if u != m: 

156 u = len(u) 

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

158 if isinstance(t, tuple): 

159 yield n, t 

160 

161 def fill_D(self, _D, which): 

162 # Fill C{_Dict _D}. 

163 _D._NAME(which) 

164 _a = _D.add 

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

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

167 for a in t: 

168 a, _, as_ = a.partition(__as__) 

169 if as_: # import attr as attr_ 

170 _a(as_, _DOT_(m, a, NN), *_sub_packages) 

171 else: 

172 _a(a, m) 

173 return _D 

174 

175 

176def _i(*names): 

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

178 ''' 

179 return tuple(map(_intern, names)) if names else _i0 

180 

181 

182def _ALL_ATTRS(*attrs): 

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

184 ''' 

185 t = () 

186 for attr in attrs: 

187 t += tuple(map(_attrof, attr)) 

188 return t 

189 

190 

191_ALL_INIT = _i(_pygeodesy_abspath_, _version_) 

192 

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

194_ALL_LAZY = _NamedEnum_RO(_name='_ALL_LAZY', 

195 albers=_i('AlbersEqualArea', 'AlbersEqualArea2', 'AlbersEqualArea4', 

196 'AlbersEqualAreaCylindrical', 'AlbersEqualAreaNorth', 'AlbersEqualAreaSouth', 

197 'AlbersError', 'Albers7Tuple'), 

198 auxilats=_i(), # module only 

199 azimuthal=_i('AzimuthalError', 'Azimuthal7Tuple', 

200 'Equidistant', 'EquidistantExact', 'EquidistantGeodSolve', 'EquidistantKarney', 

201 'Gnomonic', 'GnomonicExact', 'GnomonicGeodSolve', 'GnomonicKarney', 

202 'LambertEqualArea', 'Orthographic', 'Stereographic', 

203 'equidistant', 'gnomonic'), 

204 basics=_i('clips', 'copysign0', 'copytype', 'halfs2', 

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

206 'isidentifier', 'isinstanceof', 'isint', 'iskeyword', 'isLatLon', 'islistuple', 

207 'isNvector', 'isodd', 'isscalar', 'issequence', 'isstr', 'issubclassof', 

208 'len2', 'map1', 'map2', 'neg', 'neg_', 

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

210 booleans=_i('BooleanFHP', 'BooleanGH', 'LatLonFHP', 'LatLonGH', 

211 'isBoolean'), 

212 cartesianBase=_i('RadiusThetaPhi3Tuple', 'rtp2xyz', 'rtp2xyz_', 'xyz2rtp', 'xyz2rtp_'), 

213 clipy=_i('ClipCS4Tuple', 'ClipFHP4Tuple', 'ClipGH4Tuple', 'ClipLB6Tuple', 'ClipSH3Tuple', 

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

215 css=_i('CassiniSoldner', 'Css', 'CSSError', 'toCss', 

216 'EasNorAziRk4Tuple', 'EasNorAziRkEqu6Tuple', 'LatLonAziRk4Tuple'), 

217 constants=_i('DIG', 'EPS', 'EPS0', 'EPS02', 'EPS1', 'EPS2', 'EPS4', 'EPS_2', 

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

219 'PI', 'PI2', 'PI_2', 'PI3', 'PI_3', 'PI3_2', 'PI4', 'PI_4', 

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

221 'float_', 'float0_', 'isclose', 'isfinite', 'isinf', 'isint0', 

222 'isnan', 'isnear0', 'isnear1', 'isnear90', 'isneg0', 'isninf', 'isnon0', 

223 'remainder'), 

224 datums=_i('Datum', 'Datums', 'Transform', 'Transforms'), 

225# deprecated=_i(), # module only 

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

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

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

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

230 'bearingDMS', 'clipDegrees', 'clipRadians', 'compassDMS', 'compassPoint', 

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

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

233 ecef=_i('EcefError', 'EcefFarrell21', 'EcefFarrell22', 'EcefKarney', 'EcefMatrix', 

234 'EcefSudano', 'Ecef9Tuple', 'EcefVeness', 'EcefYou'), 

235 elevations=_i('Elevation2Tuple', 'GeoidHeight2Tuple', 

236 'elevation2', 'geoidHeight2'), 

237 ellipsoidalBase=_i(), # module only 

238 ellipsoidalBaseDI=_i(), # module only 

239 ellipsoidalExact=_i(), # module only 

240 ellipsoidalGeodSolve=_i(), # module only 

241 ellipsoidalKarney=_i(), # module only 

242 ellipsoidalNvector=_i(), # module only 

243 ellipsoidalVincenty=_i('VincentyError',), # nothing else 

244 ellipsoids=_i('a_f2Tuple', 'Circle4Tuple', 'Curvature2Tuple', 

245 'Ellipsoid', 'Ellipsoid2', 'Ellipsoids', 

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

247 'a_f2b', 'a_f_2b', 'b_f2a', 'b_f_2a', 

248 'e2f', 'e22f', 

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

250 elliptic=_i('Elliptic', 'EllipticError', 'Elliptic3Tuple'), 

251 epsg=_i('Epsg', 'EPSGError'), 

252 errors=_i('AuxError', 'ClipError', 'CrossError', 'GeodesicError', 'IntersectionError', 

253 'NumPyError', 'LenError', 'LimitError', 'MGRSError', 

254 'ParseError', 'PointsError', 'RangeError', 'RhumbError', 

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

256 'crosserrors', 'exception_chaining', 'isError', 'itemsorted', 

257 'limiterrors', 'rangerrors'), 

258 etm=_i('Etm', 'ETMError', 'ExactTransverseMercator', 

259 'parseETM5', 'toEtm8'), 

260 fmath=_i('Fdot', 'Fhorner', 'Fhypot', 'Fpolynomial', 'Fpowers', 'Fn_rt', 'Fcbrt', 'Fsqrt', 

261 'bqrt', 'cbrt', 'cbrt2', 'euclid', 'euclid_', 

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

263 'fdot', 'fdot3', 'fmean', 'fmean_', 'fhorner', 'fidw', 'fpolynomial', 

264 'fpowers', 'fprod', 'frange', 'freduce', 'fremainder', 

265 'hypot', 'hypot_', 'hypot1', 'hypot2', 'hypot2_', 

266 'norm2', 'norm_', 'sqrt0', 'sqrt3', 'sqrt_a', 'zcrt', 'zqrt'), 

267 formy=_i('Radical2Tuple', 

268 'antipode', 'antipode_', 'bearing', 'bearing_', 

269 'compassAngle', 'cosineForsytheAndoyerLambert', 'cosineForsytheAndoyerLambert_', 

270 'cosineAndoyerLambert', 'cosineAndoyerLambert_', 'cosineLaw', 'cosineLaw_', 

271 'equirectangular', 'equirectangular_', 'euclidean', 'euclidean_', 

272 'excessAbc_', 'excessCagnoli_', 'excessGirard_', 'excessLHuilier_', 

273 'excessKarney', 'excessKarney_', 'excessQuad', 'excessQuad_', 

274 'flatLocal', 'flatLocal_', 'flatPolar', 'flatPolar_', 

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

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

277 'latlon2n_xyz', 'normal', 'normal_', 'n_xyz2latlon', 'n_xyz2philam', 

278 'opposing', 'opposing_', 'philam2n_xyz', 'radical2', 

279 'thomas', 'thomas_', 'vincentys', 'vincentys_'), 

280 frechet=_i('Frechet', 'FrechetDegrees', 'FrechetError', 'FrechetRadians', 

281 'FrechetCosineAndoyerLambert', 'FrechetCosineForsytheAndoyerLambert', 

282 'FrechetCosineLaw', 'FrechetDistanceTo', 'FrechetEquirectangular', 

283 'FrechetEuclidean', 'FrechetExact', 'FrechetFlatLocal', 'FrechetFlatPolar', 

284 'FrechetHaversine', 'FrechetHubeny', 'FrechetKarney', 'FrechetThomas', 

285 'FrechetVincentys', 'Frechet6Tuple', 

286 'frechet_'), 

287 fstats=_i('Fcook', 'Flinear', 'Fwelford'), 

288 fsums=_i('Fsum', 'Fsum2Tuple', 'ResidualError', 

289 'fsum', 'fsum_', 'fsumf_', 'fsum1', 'fsum1_', 'fsum1f_'), 

290 gars=_i('Garef', 'GARSError'), 

291 geodesicw=_i('Geodesic', 'GeodesicLine', 'Geodesic_WGS84'), 

292 geodesicx=_i('gx', 'gxarea', 'gxbases', 'gxline', # modules, see _sub_packages 

293 'GeodesicAreaExact', 'GeodesicExact', 'GeodesicLineExact', 'PolygonArea'), 

294 geodsolve=_i('GeodesicSolve', 'GeodesicLineSolve', 'GeodSolve12Tuple'), 

295 geohash=_i('Geohash', 'GeohashError', 'Neighbors8Dict', 'Resolutions2Tuple'), 

296 geoids=_i('GeoidError', 'GeoidG2012B', 'GeoidKarney', 'GeoidPGM', 'egmGeoidHeights', 

297 'PGMError', 'GeoidHeight5Tuple'), 

298 hausdorff=_i('Hausdorff', 'HausdorffDegrees', 'HausdorffError', 'HausdorffRadians', 

299 'HausdorffCosineAndoyerLambert', 'HausdorffCosineForsytheAndoyerLambert', 

300 'HausdorffCosineLaw', 'HausdorffDistanceTo', 'HausdorffEquirectangular', 

301 'HausdorffEuclidean', 'HausdorffExact', 'HausdorffFlatLocal', 'HausdorffFlatPolar', 

302 'HausdorffHaversine', 'HausdorffHubeny', 'HausdorffKarney', 'HausdorffThomas', 

303 'HausdorffVincentys', 'Hausdorff6Tuple', 

304 'hausdorff_', 'randomrangenerator'), 

305 heights=_i('HeightCubic', 'HeightError', 

306 'HeightIDWcosineAndoyerLambert', 'HeightIDWcosineForsytheAndoyerLambert', 

307 'HeightIDWcosineLaw', 'HeightIDWdistanceTo', 'HeightIDWequirectangular', 

308 'HeightIDWeuclidean', 'HeightIDWexact', 'HeightIDWflatLocal', 'HeightIDWflatPolar', 

309 'HeightIDWhaversine', 'HeightIDWhubeny', 'HeightIDWkarney', 'HeightIDWthomas', 

310 'HeightIDWvincentys', 'HeightLinear', 'HeightLSQBiSpline', 'HeightSmoothBiSpline'), 

311 interns=_interns__all__, 

312 iters=_i('LatLon2PsxyIter', 'PointsIter', 'points2', 

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

314 karney=_i('Area3Tuple', 'Caps', 'Direct9Tuple', 'GDict', 'Inverse10Tuple', 'Rhumb8Tuple'), 

315 ktm=_i('KTMError', 'KTransverseMercator'), 

316 latlonBase=_i(), # module only 

317 lazily=_i('LazyAttributeError', 'LazyImportError', 'isLazy', 'print_', 'printf'), 

318 lcc=_i('Conic', 'Conics', 'Lcc', 'LCCError', 'toLcc'), 

319 ltp=_i('Attitude', 'AttitudeError', 'ChLV', 'ChLVa', 'ChLVe', 'Frustum', 

320 'LocalCartesian', 'LocalError', 'Ltp', 'tyr3d'), 

321 ltpTuples=_i('Aer', 'Aer4Tuple', 'Attitude4Tuple', 

322 'ChLVEN2Tuple', 'ChLV9Tuple', 'ChLVYX2Tuple', 'ChLVyx2Tuple', 

323 'Enu', 'Enu4Tuple', 'Footprint5Tuple', 'Local9Tuple', 'Los', 

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

325 mgrs=_i('Mgrs', 'parseMGRS', 'toMgrs', 'Mgrs4Tuple', 'Mgrs6Tuple'), 

326 named=_i('ADict', 

327 'callername', 'classname', 'classnaming', 'modulename', 

328 'nameof', 'notImplemented', 'notOverloaded'), 

329 namedTuples=_i('Bearing2Tuple', 'Bounds2Tuple', 'Bounds4Tuple', 

330 'Destination2Tuple', 'Destination3Tuple', 

331 'Distance2Tuple', 'Distance3Tuple', 'Distance4Tuple', 

332 'EasNor2Tuple', 'EasNor3Tuple', 'Forward4Tuple', 'Intersection3Tuple', 

333 'LatLon2Tuple', 'LatLon3Tuple', 'LatLon4Tuple', 

334 'LatLonDatum3Tuple', 'LatLonDatum5Tuple', 

335 'LatLonPrec3Tuple', 'LatLonPrec5Tuple', 

336 'NearestOn2Tuple', 'NearestOn3Tuple', 'NearestOn6Tuple', 'NearestOn8Tuple', 

337 'PhiLam2Tuple', 'PhiLam3Tuple', 'PhiLam4Tuple', 'Point3Tuple', 'Points2Tuple', 

338 'Reverse4Tuple', 'Triangle7Tuple', 'Triangle8Tuple', 'Trilaterate5Tuple', 

339 'UtmUps2Tuple', 'UtmUps5Tuple', 'UtmUps8Tuple', 'UtmUpsLatLon5Tuple', 

340 'Vector2Tuple', 'Vector3Tuple', 'Vector4Tuple'), 

341 nvectorBase=_i(_NorthPole_, _SouthPole_), 

342 osgr=_i('Osgr', 'OSGRError', 'parseOSGR', 'toOsgr'), 

343 points=_i('LatLon_', 'LatLon2psxy', 'Numpy2LatLon', 'Shape2Tuple', 'Tuple2LatLon', 

344 _areaOf_, 'boundsOf', 'centroidOf', 'fractional', 

345 _isclockwise_, 'isconvex', 'isconvex_', 'isenclosedBy', _ispolar_, 

346 'luneOf', 'nearestOn5', 'perimeterOf', 'quadOf'), 

347 props=_i('Property', 'Property_RO', 'property_RO', 'property_doc_', 

348 'deprecated_class', 'deprecated_function', 'deprecated_method', 

349 'deprecated_Property_RO', 'deprecated_property_RO', 'DeprecationWarnings'), 

350 resections=_i('Collins5Tuple', 'ResectionError', 'Survey3Tuple', 'Tienstra7Tuple', 

351 'TriAngle5Tuple', 'TriSide2Tuple', 'TriSide4Tuple', 

352 'cassini', 'collins5', 'pierlot', 'pierlotx', 'tienstra7', 

353 'snellius3', 'wildberger3', 

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

355 rhumb=_i(), # module only 

356 rhumb_aux_=_i('RhumbAux', 'RhumbLineAux'), 

357 rhumb_ekx=_i('Rhumb', 'RhumbLine'), 

358 rhumb_solve=_i('RhumbSolve', 'RhumbLineSolve', 'RhumbSolve7Tuple'), 

359 sphericalBase=_i(), # module only 

360 sphericalNvector=_i(), # module only 

361 sphericalTrigonometry=_i(), # module only 

362 simplify=_i('simplify1', 'simplifyRDP', 'simplifyRDPm', 'simplifyRW', 'simplifyVW', 'simplifyVWm'), 

363 solveBase=_i(), # module only 

364 streprs=_i('anstr', 'attrs', 'enstr2', 'fstr', 'fstrzs', 'hstr', 'instr', 

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

366 trf=_i('RefFrame', 'RefFrames', 'TransformXform', 'TRFXform', 'TRFXform7Tuple', 

367 'date2epoch', 'epoch2date', 'trfTransform0', 'trfXform'), 

368 triaxials=_i('BetaOmega2Tuple', 'BetaOmega3Tuple', 'Jacobi2Tuple', 

369 'JacobiConformal', 'JacobiConformalSpherical', 

370 'Triaxial', 'Triaxial_', 'TriaxialError', 'Triaxials', 'hartzell4'), 

371 units=_i('Band', 'Bearing', 'Bearing_', 'Bool', 

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

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

374 'Lam', 'Lam_', 'Lat', 'Lat_', 'Lon', 'Lon_', 

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

376 'Phi', 'Phi_', 'Precision_', 'Radians', 'Radians_', 'Radians2', 

377 'Radius_', 'Scalar', 'Scalar_', 'Zone'), 

378 unitsBase=_i('Float', 'Int', 'Radius', 'Str'), 

379 ups=_i('Ups', 'UPSError', 'parseUPS5', 'toUps8', 'upsZoneBand5'), 

380 utily=_i('acos1', 'acre2ha', 'acre2m2', 'asin1', 'atan1', 'atan1d', 'atan2b', 'atan2d', 

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

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

383# 'degrees2grades as degrees2gons', 

384 'fathom2m', 'ft2m', 'furlong2m', 

385 'grades', 'grades400', 'grades2degrees', 'grades2radians', 

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

387 'km2m', 'm2chain', 'm2degrees', 'm2fathom', 'm2ft', 'm2furlong', 

388 'm2km', 'm2NM', 'm2radians', 'm2SM', 'm2toise', 'm2yard', 'NM2m', 

389 'radians', 'radiansPI', 'radiansPI2', 'radiansPI_2', 'radians2m', 

390 'sincos2', 'SinCos2', 'sincos2_', 'sincos2d', 'sincos2d_', 'sincostan3', 'SM2m', 

391 'tand', 'tand_', 'tan_2', 'tanPI_2_2', 'toise2m', 'truncate', 

392 'unroll180', 'unrollPI', 

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

394 'yard2m'), 

395 utm=_i('Utm', 'UTMError', 'parseUTM5', 'toUtm8', 'utmZoneBand5'), 

396 utmups=_i('UtmUps', 'UTMUPSError', 'parseUTMUPS5', 'toUtmUps8', 

397 'utmupsValidate', 'utmupsValidateOK', 'utmupsZoneBand5'), 

398 utmupsBase=_i(), # module only 

399 vector2d=_i('Circin6Tuple', 'Circum3Tuple', 'Circum4Tuple', 'Meeus2Tuple', 'Radii11Tuple', 'Soddy4Tuple', 

400 'circin6', 'circum3', 'circum4_', 'meeus2', 'radii11', 'soddy4'), 

401 vector3d=_i('Vector3d', 'intersection3d3', 'iscolinearWith', 'nearestOn', 'nearestOn6', 'parse3d', 

402 'trilaterate2d2', 'trilaterate3d2'), 

403 vector3dBase=_i(), # module only 

404 webmercator=_i('Wm', 'WebMercatorError', 'parseWM', 'toWm', 'EasNorRadius3Tuple'), 

405 wgrs=_i('Georef', 'WGRSError'),) 

406 

407_ALL_DEPRECATED = _NamedEnum_RO(_name='_ALL_DEPRECATED', 

408 deprecated=_i('bases', 'datum', 'nvector', # DEPRECATED modules and ... 

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

410 deprecated_bases=_i('LatLonHeightBase', 'points2'), 

411 deprecated_classes=_i('ClipCS3Tuple', 'EasNorExact4Tuple', 'EcefCartesian', 

412 'HeightIDW', 'HeightIDW2', 'HeightIDW3', 'Helmert7Tuple', 

413 'LatLonExact4Tuple', 'NearestOn4Tuple', 'Ned3Tuple', 

414 'RefFrameError', 'Rhumb7Tuple', 'RhumbOrder2Tuple', 

415 'Transform7Tuple', 'TriAngle4Tuple', 'UtmUps4Tuple'), 

416 deprecated_consterns=_i('EPS1_2', 'MANTIS', 'OK'), 

417 deprecated_datum=_i('Curvature2Tuple', 'Datum', 'Ellipsoid', 'Transform', # assert 

418 'Datums', 'Ellipsoids', 'Transforms', 

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

420 deprecated_functions=_i('anStr', 'areaof', 'atand', 'bounds', # most of the DEPRECATED functions, except ... 

421 'clipCS3', 'clipDMS', 'clipStr', 'collins', 'copysign', # ... ellipsoidal, spherical flavors 

422 'decodeEPSG2', 'encodeEPSG', 'enStr2', 'equirectangular3', 

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

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

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

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

427 'parseUTM', 'perimeterof', 'polygon', 'scalar', 'simplify2', 

428 'tienstra', 'toUtm', 'trfTransforms', 'triAngle4', 

429 'unsign0', 'unStr', 'utmZoneBand2'), 

430 deprecated_nvector=_i('LatLonNvectorBase', 'Nvector', 'sumOf', 'NorthPole', 'SouthPole'),) 

431 

432 

433class _ALL_MODS(object): 

434 '''(INTERNAL) Memoize import of any L{pygeodesy} module. 

435 ''' 

436 def _DOT_(self, name): # PYCHOK no cover 

437 return _DOT_(self.__class__.__name__, name) 

438 

439 def __getattr__(self, name): 

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

441 

442 @arg name: Qualified module or attribute name (C{str}). 

443 

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

445 

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

447 ''' 

448 m = self.getmodule(name) 

449 return m if _tailof(m.__name__) == name else \ 

450 getattr(m, _tailof(name)) 

451 

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

453 t = _EQUALSPACED_(self._DOT_(attr), repr(value)) 

454 raise AttributeError(_COLONSPACE_(t, _immutable_)) 

455 

456 def getattr(self, mod, *attr_dflt): # , parent=_pygeodesy_ 

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

458 

459 @arg mod: Qualified module name (C{str}). 

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

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

462 

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

464 

465 @raise ImportError: Importing module B{C{mod}} failed. 

466 

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

468 ''' 

469 v = self.getmodule(mod) 

470 if attr_dflt: 

471 v = getattr(v, *attr_dflt) 

472 return v 

473 

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

475 '''Get a C{pygeodesy} module. 

476 

477 @arg name: Qualified module name (C{str}). 

478 

479 @return: The C{pygeodesy} module. 

480 

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

482 ''' 

483 if _headof(name) != parent: 

484 name = _DOT_(parent, name) 

485 try: 

486 return _sys.modules[name] 

487 except KeyError: 

488 return import_module(name, parent) 

489 

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

491 '''Yield the modules imported so far. 

492 ''' 

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

494 yield n, m 

495 

496 @property # property_RO 

497 def name(self): 

498 return self.__class__.__name__ 

499 

500_ALL_MODS = _ALL_MODS() # PYCHOK singleton 

501 

502__all__ = _ALL_LAZY.lazily 

503__version__ = '24.02.02' 

504 

505 

506def _ALL_OTHER(*objs): 

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

508 ''' 

509 _interns = _ALL_MODS.interns # from pygeodesy import interns 

510 

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

512 n = _tailof(_dunder_nameof(o)) 

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

514 return getattr(_interns, i, n) 

515 

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

517 

518 

519if _FOR_DOCS: 

520 _ALL_DOCS = _ALL_OTHER 

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

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

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

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

525 # too much internal documentation. 

526else: 

527 def _ALL_DOCS(*unused): 

528 return () 

529 

530 

531def _all_deprecates(): 

532 '''(INTERNAL) Build C{dict} of all deprecated imports. 

533 ''' 

534 _D = _ALL_DEPRECATES 

535 if not _D: 

536 _ALL_DEPRECATED.fill_D(_D, _all_deprecates) # see _all_imports() 

537 return _D 

538 

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

540 

541 

542def _all_imports(): 

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

544 ''' 

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

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

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

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

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

550 _D = _ALL_IMPORTS 

551 if not _D: 

552 _ALL_LAZY.fill_D(_D, _all_imports) # see _all_deprecates() 

553 return _D 

554 

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

556 

557 

558def _all_missing2(_all_): 

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

560 ''' 

561 def _diff(one, two): 

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

563 

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

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

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

567 (_DOT_(_pygeodesy_, _a_l_l_), _diff(_alzy.keys(), _all_))) 

568 

569 

570def _attrof(attr_as): # .testDeprecated 

571 a_, _, as_ = attr_as.partition(__as__) 

572 return as_ or a_.rstrip(_DOT_) 

573 

574 

575def _caller3(up): # in .named 

576 '''(INTERNAL) Get 3-tuple C{(caller name, file name, line number)} 

577 for the caller B{C{up}} stack frames in the Python call stack. 

578 ''' 

579 # sys._getframe(1) ... 'importlib._bootstrap' line 1032, 

580 # may throw a ValueError('call stack not deep enough') 

581 f = _sys._getframe(up + 1) 

582 return (f.f_code.co_name, # caller name 

583 _basename(f.f_code.co_filename), # file name 

584 f.f_lineno) # line number 

585 

586 

587def _lazy_attr(unused): # PYCHOK overwritten in _lazy_import 

588 pass 

589 

590 

591# def _lazy_attributes(_name_): 

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

593# on lazily imported modules and sub-modules. 

594# ''' 

595# if _unlazy: 

596# raise AssertionError(_COMMASPACE_(_name_, _not_(_DEPRECATED_))) 

597# 

598# def _getattr(attr, *dflt): 

599# try: # a module name 

600# return _ALL_MODS.getmodule(attr) 

601# except (AttributeError, ImportError): 

602# return _ALL_MODS.getattr(_name_, attr, *dflt) 

603# 

604# return _getattr 

605 

606 

607def _lazy_import2(pack): # MCCABE 14 

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

609 

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

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

612 

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

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

615 C{package.__getattr__}. 

616 

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

618 invalid or does not exist. 

619 

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

621 an import failed. 

622 

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

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

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

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

627 causing a C{ModuleNotFoundError}. 

628 

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

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

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

632 ''' 

633 if pack != _pygeodesy_ or _unlazy: # new in 3.7 

634 t = _no_(_DOT_(pack, _lazy_import2.__name__)) # PYCHOK no cover 

635 raise LazyImportError(t, txt=_Python_(_sys.version)) 

636 

637 package, parent = _lazy_init2(pack) # _pygeodesy_ 

638 

639 subpacks = set((parent, '__main__', NN) + tuple( 

640 _DOT_(parent, s) for s in _sub_packages)) 

641 imports = _all_imports() 

642 deprecates = _all_deprecates() 

643 

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

645 # only called once for each undefined pygeodesy attribute 

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

647 if mod: 

648 # importlib.import_module() implicitly sets sub-modules 

649 # on this module as appropriate for direct imports (see 

650 # note in the _lazy_import2.__doc__ above). 

651 if mod.endswith(_DOT_): # import mod[.attr] as name 

652 mod, _, attr = mod[:-1].rpartition(_DOT_) 

653 else: # from mod import name 

654 attr = name 

655 try: 

656 t = _DOT_(pack, mod) 

657 imported = import_module(t, parent) 

658 except ImportError: 

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

660 raise LazyImportError(_no_(_module_), txt=t) 

661 t = getattr(imported, _p_a_c_k_a_g_e_, None) 

662 if t not in subpacks: # invalid module package 

663 raise LazyImportError(_DOT_(mod, _p_a_c_k_a_g_e_), t) 

664 if attr: # get the attribute 

665 imported = getattr(imported, attr, MISSING) 

666 if imported is MISSING: # PYCHOK no cover 

667 t = _DOT_(mod, attr) 

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

669 raise LazyAttributeError(_no_(_attribute_), txt=t) 

670 

671 elif name in (_a_l_l_,): # XXX '_d_i_r_', '_m_e_m_b_e_r_s_'? 

672 imported = _ALL_INIT + tuple(imports.keys()) 

673 else: # PYCHOK no cover 

674 t = _no_(_module_, _or_, _attribute_) 

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

676 raise LazyAttributeError(t, txt=_DOT_(parent, name)) 

677 

678 setattr(package, name, imported) 

679 if isLazy > 1: 

680 t = NN(_lazily_imported__, _DOT_(parent, name)) 

681 if mod and _tailof(mod) != name: 

682 t = NN(t, _from_DOT__, mod) 

683 if isLazy > 2: 

684 try: # see C{_caller3} 

685 _, f, s = _caller3(2) 

686 t = _SPACE_(t, _by_, f, _line_, s) 

687 except ValueError: 

688 pass 

689 printf(t) # XXX print 

690 

691 return imported # __getattr__ 

692 

693 global _lazy_attr 

694 _lazy_attr = __getattr__ 

695 

696 return package, __getattr__ # _lazy_import2 

697 

698 

699# def _lazy_import_all(_name_): 

700# '''(INTERNAL) Return a function mimicking C{from B{__name__} import *}, 

701# of all items, see .deprecated.__init__ 

702# ''' 

703# if _unlazy: 

704# raise AssertionError(_COMMASPACE_(_name_, _not_(_DEPRECATED_))) 

705# 

706# _getattr = _lazy_attributes(_name_) # _name_.__getattr__ 

707# _import_start = _lazy_import_star(_name_, ALL_=_ALL_IMPORTS) 

708# 

709# def _import_all(attr, *dflt): 

710# return _import_star(_name_) if attr == _a_l_l_ else \ 

711# _getattr(attr, *dflt) 

712# 

713# return _import_all 

714 

715 

716def _lazy_import_as(_name_): 

717 '''(INTERNAL) Return a function to C{import B{__name__}.mod as mod} 

718 I{of modules only}, see .deprecated, .rhumb or get an attribute 

719 lazily exported by C{__name__}. 

720 ''' 

721 if _unlazy: 

722 return None 

723 

724 def _import_as(mod): 

725 try: 

726 return _ALL_MODS.getmodule(_DOT_(_name_, mod)) 

727 except ImportError: 

728 return _lazy_attr(mod) 

729 

730 return _import_as 

731 

732 

733# def _lazy_import_star(_name_, ALL_=_ALL_DEPRECATES): 

734# '''(INTERNAL) Return a function to mimick C{from B{__name__} import *}, 

735# of all DEPRECATED items, see .deprecated, .testDeprecated 

736# ''' 

737# if _unlazy: 

738# raise AssertionError(_COMMASPACE_(_name_, _not_(_DEPRECATED_))) 

739# 

740# def _import_star(_into_): 

741# '''Do C{from B{__name__} import *} inside module C{B{__into__}}. 

742# ''' 

743# d = dict() 

744# nm = _tailof(_name_) 

745# _g = _ALL_MODS.getattr # pygeodesy.__getattr__ 

746# _h = _headof 

747# for a, m in ALL_.items(): 

748# if _h(m) == nm: 

749# try: 

750# d[a] = _g(m, a) 

751# except (AttributeError, ImportError): 

752# pass 

753# _sys.modules[_into_].__dict__.update(d) 

754# return d.keys() # imported names 

755# 

756# return _import_star 

757 

758 

759# def _lazy_subs(_name_, force=_FOR_DOCS, over=False): 

760# '''(INTERNAL) Return the names of a package's sub-packages and 

761# update the package's C{__dict__} accordingly. 

762# ''' 

763# sm = dict() 

764# if force and _name_ != '__main__': 

765# nm = _tailof(_name_) 

766# _a = _ALL_MODS.getattr 

767# _m = _ALL_MODS.getmodule 

768# d = _a(_name_, '__dict__', {}) 

769# for n in _a(_name_, _a_l_l_, ()): 

770# try: # n is a class name, get its mod name 

771# m = _a(_name_, n).__module__ 

772# n, s = m.split(_DOT_)[-2:] 

773# if n == nm and s not in sm: 

774# # like import m as s 

775# m = _m(m) 

776# sm[s] = m if over else d.get(s, m) 

777# except (AttributeError, ImportError, ValueError) as x: 

778# pass 

779# d.update(sm) 

780# 

781# return _ALL_OTHER(*sm.values()) 

782 

783 

784def _lazy_init2(pack): 

785 '''(INTERNAL) Initialize lazy import and set globals C{isLazy} and C{_unLazy0}. 

786 

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

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

789 

790 @return: 2-Tuple C{(package, parent)} with the importing C{package} 

791 for easy reference within itself and its name aka the 

792 C{parent}, same as B{C{pack}}. 

793 

794 @raise LazyImportError: Lazy import not supported or not enabled, 

795 an import failed or the package name is 

796 invalid or does not exist. 

797 

798 @note: Global C{isLazy} is set accordingly. 

799 ''' 

800 global isLazy, _unLazy0 

801 

802 z = _getenv(_PYGEODESY_LAZY_IMPORT_, None) 

803 if z is None: # _PYGEODESY_LAZY_IMPORT_ not set 

804 isLazy = 1 # ... but only by default on 3.7 

805 else: 

806 z = z.strip() # like PYTHONVERBOSE et.al. 

807 isLazy = int(z) if z.isdigit() else (1 if z else 0) 

808 

809 _unLazy0 = _unlazy or not isLazy # pre-3.7 or w/o lazy import 

810 

811 if isLazy < 1: # not enabled 

812 raise LazyImportError(_PYGEODESY_LAZY_IMPORT_, repr(z), txt=_not_(_enabled_)) 

813 if _getenv('PYTHONVERBOSE', None): # PYCHOK no cover 

814 isLazy += 1 

815 

816 try: # to initialize in Python 3+ 

817 package = import_module(pack) 

818 parent = package.__spec__.parent # __spec__ only in Python 3.7+ 

819 if parent != pack: # assert 

820 t = _COMMASPACE_(parent, _not_(pack)) # PYCHOK no cover 

821 raise AttributeError(_EQUALSPACED_('parent', t)) 

822 

823 except (AttributeError, ImportError) as x: 

824 isLazy = False # failed 

825 raise LazyImportError(_lazy_init2.__name__, pack, cause=x) 

826 

827 return package, parent 

828 

829 

830def _pairs(*args, **kwds): # in .ktm 

831 # from pygeodesy.streprs import pairs 

832 return _ALL_MODS.streprs.pairs(*args, **kwds) 

833 

834 

835def print_(*args, **nl_nt_prefix_end_file_flush_sep): # PYCHOK no cover 

836 '''Python 3+ C{print}-like formatting and printing. 

837 

838 @arg args: Arguments to be converted to C{str} and joined by B{C{sep}} 

839 (any C{type}, all positional). 

840 @kwarg nl_nt_prefix_end_file_flush_sep: Keyword arguments C{B{nl}=0} 

841 for the number of leading blank lines (C{int}), C{B{nt}=0} 

842 the number of trailing blank lines (C{int}), C{B{prefix}=NN} 

843 to be inserted before the formatted text (C{str}) and Python 

844 3+ C{print} keyword arguments C{B{end}}, C{B{sep}}, C{B{file}} 

845 and C{B{flush}}. 

846 

847 @return: Number of bytes written. 

848 ''' 

849 return printf(NN, *args, **nl_nt_prefix_end_file_flush_sep) 

850 

851 

852def printf(fmt, *args, **nl_nt_prefix_end_file_flush_sep_kwds): 

853 '''C{Printf-style} and Python 3+ C{print}-like formatting and printing. 

854 

855 @arg fmt: U{Printf-style<https://Docs.Python.org/3/library/stdtypes.html# 

856 printf-style-string-formatting>} format specification (C{str}). 

857 @arg args: Arguments to be formatted (any C{type}, all positional). 

858 @kwarg nl_nt_prefix_end_file_flush_sep_kwds: Keyword arguments C{B{nl}=0} 

859 for the number of leading blank lines (C{int}), C{B{nt}=0} the 

860 number of trailing blank lines (C{int}), C{B{prefix}=NN} to 

861 be inserted before the formatted text (C{str}) and Python 3+ 

862 C{print} keyword arguments C{B{end}}, C{B{sep}}, C{B{file}} and 

863 C{B{flush}}. Any remaining C{B{kwds}} are U{printf-style 

864 <https://Docs.Python.org/3/library/stdtypes.html#printf-style-string-formatting>} 

865 keyword arguments to be formatted, I{iff no B{C{args}} are present}. 

866 

867 @return: Number of bytes written. 

868 ''' 

869 b, e, s, f, fl, p, kwds = _xprint7(**nl_nt_prefix_end_file_flush_sep_kwds) 

870 try: 

871 if args: 

872 t = (fmt % args) if fmt else s.join(map(str, args)) 

873 elif kwds: # PYCHOK no cover 

874 t = (fmt % kwds) if fmt else s.join(_pairs(kwds, prec=p)) 

875 else: # PYCHOK no cover 

876 t = fmt 

877 except Exception as x: 

878 _E, s = _ALL_MODS.errors._xError2(x) 

879 unstr = _ALL_MODS.streprs.unstr 

880 t = unstr(printf, fmt, *args, **nl_nt_prefix_end_file_flush_sep_kwds) 

881 raise _E(s, txt=t, cause=x) 

882 try: 

883 n = f.write(NN(b, t, e)) 

884 except UnicodeEncodeError: # XXX only Windows 

885 t = t.replace('\u2032', _QUOTE1_).replace('\u2033', _QUOTE2_) 

886 n = f.write(NN(b, t, e)) 

887 if fl: # PYCHOK no cover 

888 f.flush() 

889 return n 

890 

891 

892def _xprint7(nl=0, nt=0, prec=6, prefix=NN, sep=_SPACE_, file=_sys.stdout, 

893 end=_NL_, flush=False, **kwds): 

894 '''(INTERNAL) Unravel the C{printf} and remaining keyword arguments. 

895 ''' 

896 if nl > 0: 

897 prefix = NN(_NL_ * nl, prefix) 

898 if nt > 0: 

899 end = NN(end, _NL_ * nt) 

900 return prefix, end, sep, file, flush, prec, kwds 

901 

902 

903# del _i, _i0, _intern 

904 

905if __name__ == '__main__': 

906 

907 from timeit import timeit 

908 

909 def t1(): 

910 from pygeodesy.trf import RefFrame 

911 return RefFrame 

912 

913 def t2(): 

914 return _ALL_MODS.trf.RefFrame 

915 

916 assert t1() is t2() # prime each 

917 

918 t1 = timeit(t1, number=1000000) 

919 t2 = timeit(t2, number=1000000) 

920 v = _Python_(_sys.version) 

921 printf('%.8f import vs %.8f _ALL_MODS: %.3fX, %s', t1, t2, t2 / t1, v) 

922 del t1, t2, v 

923 

924# python3.12 -m pygeodesy.lazily 

925# 0.13352763 import vs 0.70804508 _ALL_MODS: 5.303X, Python 3.12.0 

926 

927# % python3.11 -W ignore -m pygeodesy.lazily 

928# 0.37998008 import vs 0.79537812 _ALL_MODS: 2.093X, Python 3.11.5 

929 

930# % python3.10 -W ignore -m pygeodesy.lazily 

931# 0.39046367 import vs 0.90492925 _ALL_MODS: 2.318X, Python 3.10.8 

932 

933# % python2 -m pygeodesy.lazily 

934# 1.17563510 import vs 2.02626395 _ALL_MODS: 1.724X, Python 2.7.18 

935 

936# **) MIT License 

937# 

938# Copyright (C) 2018-2024 -- mrJean1 at Gmail -- All Rights Reserved. 

939# 

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

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

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

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

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

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

946# 

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

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

949# 

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

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

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

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

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

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

956# OTHER DEALINGS IN THE SOFTWARE.