Coverage for pygeodesy/lazily.py: 92%

204 statements  

« prev     ^ index     » next       coverage.py v7.2.2, created at 2023-12-24 11:18 -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 

41 

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

43from os.path import basename as _basename 

44import sys as _sys # in .basics._sizeof 

45try: 

46 from importlib import import_module 

47except ImportError: # Python 2.6- 

48 def import_module(name, *package): 

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

50 raise LazyImportError(t, txt=_doesn_t_exist_) 

51 

52_a_l_l_ = '__all__' # .__main__ 

53__as__ = ' as ' 

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

55_from_DOT__ = _SPACE_(NN, _from_, _DOT_) 

56_i0 = () # PYCHOK empty tuple 

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

58_lazily_ = 'lazily' 

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

60_p_a_c_k_a_g_e_ = '__package__' 

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

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

63_PYGEODESY_LAZY_IMPORT_ = 'PYGEODESY_LAZY_IMPORT' 

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

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

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

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

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

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

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

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

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

73 

74 

75class LazyAttributeError(AttributeError): 

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

77 ''' 

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

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

80 

81 

82class LazyImportError(ImportError): 

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

84 ''' 

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

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

87 

88 

89class _Dict(dict): 

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

91 ''' 

92 _name = NN 

93 

94 def __getattr__(self, attr): 

95 try: 

96 return self[attr] 

97 except KeyError: 

98 return dict.__getattr__(self, attr) 

99 

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

101# if attr in self: 

102# self[attr] = value 

103# else: 

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

105 

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

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

108 

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

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

111 ''' 

112 if name in self: 

113 sub = self[name] # duplicate OK 

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

115 t = _DOT_(self._name, name) 

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

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

118 raise AssertionError(t) 

119 else: 

120 self[name] = mod_ 

121 

122 def _NAME(self, which): 

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

124 

125 

126class _NamedEnum_RO(dict): 

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

128 ''' 

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

130 

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

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

133 

134 def __getattr__(self, attr): 

135 try: 

136 return self[attr] 

137 except KeyError: 

138 t = self._DOT_(attr) 

139 raise LazyAttributeError(t, txt=_doesn_t_exist_) 

140 

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

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

143 raise LazyAttributeError(t, txt=_immutable_) 

144 

145 def enums(self): 

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

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

148 n = m.replace(_UNDER_, _DOT_) 

149 if n != m: 

150 if m.startswith(_UNDER_): 

151 t = None # skip _name= ... 

152 else: 

153 u = m.rstrip(_UNDER_) 

154 if u != m: 

155 u = len(u) 

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

157 if isinstance(t, tuple): 

158 yield n, t 

159 

160 def fill_D(self, _D, which): 

161 # Fill C{_Dict _D}. 

162 _D._NAME(which) 

163 _a = _D.add 

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

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

166 for a in t: 

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

168 if as_: # import attr as attr_ 

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

170 else: 

171 _a(a, m) 

172 return _D 

173 

174 

175def _i(*names): 

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

177 ''' 

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

179 

180 

181def _ALL_ATTRS(*attrs): 

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

183 ''' 

184 t = () 

185 for attr in attrs: 

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

187 return t 

188 

189 

190_ALL_INIT = _i(_pygeodesy_abspath_, _version_) 

191 

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

193_ALL_LAZY = _NamedEnum_RO(_name='_ALL_LAZY', 

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

195 'AlbersEqualAreaCylindrical', 'AlbersEqualAreaNorth', 'AlbersEqualAreaSouth', 

196 'AlbersError', 'Albers7Tuple'), 

197 auxilats=_i(), # module only 

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

199 'Equidistant', 'EquidistantExact', 'EquidistantGeodSolve', 'EquidistantKarney', 

200 'Gnomonic', 'GnomonicExact', 'GnomonicGeodSolve', 'GnomonicKarney', 

201 'LambertEqualArea', 'Orthographic', 'Stereographic', 

202 'equidistant', 'gnomonic'), 

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

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

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

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

207 'len2', 'map1', 'map2', 'neg', 'neg_', 

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

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

210 'isBoolean'), 

211 cartesianBase=_i(), # module only 

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

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

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

215 'EasNorAziRk4Tuple', 'EasNorAziRkEqu6Tuple', 'LatLonAziRk4Tuple'), 

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

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

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

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

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

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

222 'remainder'), 

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

224# deprecated=_i(), # module only 

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

226 '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 'S_DEG', 'S_MIN', 'S_SEC', 'S_DMS', 'S_RAD', 'S_SEP', 

229 'bearingDMS', 'clipDegrees', 'clipRadians', 'compassDMS', 'compassPoint', 

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

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

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

233 'EcefSudano', 'Ecef9Tuple', 'EcefVeness', 'EcefYou'), 

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

235 'elevation2', 'geoidHeight2'), 

236 ellipsoidalBase=_i(), # module only 

237 ellipsoidalBaseDI=_i(), # module only 

238 ellipsoidalExact=_i(), # module only 

239 ellipsoidalGeodSolve=_i(), # module only 

240 ellipsoidalKarney=_i(), # module only 

241 ellipsoidalNvector=_i(), # module only 

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

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

244 'Ellipsoid', 'Ellipsoid2', 'Ellipsoids', 

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

246 'a_f2b', 'a_f_2b', 'b_f2a', 'b_f_2a', 

247 'e2f', 'e22f', 

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

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

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

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

252 'NumPyError', 'LenError', 'LimitError', 'MGRSError', 

253 'ParseError', 'PointsError', 'RangeError', 'RhumbError', 

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

255 'crosserrors', 'exception_chaining', 'isError', 'itemsorted', 

256 'limiterrors', 'rangerrors'), 

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

258 'parseETM5', 'toEtm8'), 

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

260 'bqrt', 'cbrt', 'cbrt2', 'euclid', 'euclid_', 

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

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

263 'fpowers', 'fprod', 'frange', 'freduce', 'fremainder', 

264 'hypot', 'hypot_', 'hypot1', 'hypot2', 'hypot2_', 

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

266 formy=_i('Radical2Tuple', 

267 'antipode', 'antipode_', 'bearing', 'bearing_', 

268 'compassAngle', 'cosineForsytheAndoyerLambert', 'cosineForsytheAndoyerLambert_', 

269 'cosineAndoyerLambert', 'cosineAndoyerLambert_', 'cosineLaw', 'cosineLaw_', 

270 'equirectangular', 'equirectangular_', 'euclidean', 'euclidean_', 

271 'excessAbc_', 'excessCagnoli_', 'excessGirard_', 'excessLHuilier_', 

272 'excessKarney', 'excessKarney_', 'excessQuad', 'excessQuad_', 

273 'flatLocal', 'flatLocal_', 'flatPolar', 'flatPolar_', 

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

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

276 'latlon2n_xyz', 'normal', 'normal_', 'n_xyz2latlon', 'n_xyz2philam', 

277 'opposing', 'opposing_', 'philam2n_xyz', 'radical2', 'rtp2xyz', 'rtp2xyz_', 

278 'thomas', 'thomas_', 'vincentys', 'vincentys_', 'xyz2rtp', 'xyz2rtp_'), 

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

280 'FrechetCosineAndoyerLambert', 'FrechetCosineForsytheAndoyerLambert', 

281 'FrechetCosineLaw', 'FrechetDistanceTo', 'FrechetEquirectangular', 

282 'FrechetEuclidean', 'FrechetExact', 'FrechetFlatLocal', 'FrechetFlatPolar', 

283 'FrechetHaversine', 'FrechetHubeny', 'FrechetKarney', 'FrechetThomas', 

284 'FrechetVincentys', 'Frechet6Tuple', 

285 'frechet_'), 

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

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

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

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

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

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

292 'GeodesicAreaExact', 'GeodesicExact', 'GeodesicLineExact', 'PolygonArea'), 

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

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

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

296 'PGMError', 'GeoidHeight5Tuple'), 

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

298 'HausdorffCosineAndoyerLambert', 'HausdorffCosineForsytheAndoyerLambert', 

299 'HausdorffCosineLaw', 'HausdorffDistanceTo', 'HausdorffEquirectangular', 

300 'HausdorffEuclidean', 'HausdorffExact', 'HausdorffFlatLocal', 'HausdorffFlatPolar', 

301 'HausdorffHaversine', 'HausdorffHubeny', 'HausdorffKarney', 'HausdorffThomas', 

302 'HausdorffVincentys', 'Hausdorff6Tuple', 

303 'hausdorff_', 'randomrangenerator'), 

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

305 'HeightIDWcosineAndoyerLambert', 'HeightIDWcosineForsytheAndoyerLambert', 

306 'HeightIDWcosineLaw', 'HeightIDWdistanceTo', 'HeightIDWequirectangular', 

307 'HeightIDWeuclidean', 'HeightIDWexact', 'HeightIDWflatLocal', 'HeightIDWflatPolar', 

308 'HeightIDWhaversine', 'HeightIDWhubeny', 'HeightIDWkarney', 'HeightIDWthomas', 

309 'HeightIDWvincentys', 'HeightLinear', 'HeightLSQBiSpline', 'HeightSmoothBiSpline'), 

310 interns=_interns__all__, 

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

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

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

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

315 latlonBase=_i(), # module only 

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

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

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

319 'LocalCartesian', 'LocalError', 'Ltp', 'tyr3d'), 

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

321 'ChLVEN2Tuple', 'ChLV9Tuple', 'ChLVYX2Tuple', 'ChLVyx2Tuple', 

322 'Enu', 'Enu4Tuple', 'Footprint5Tuple', 'Local9Tuple', 'Los', 

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

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

325 named=_i('callername', 'classname', 'classnaming', 'modulename', 

326 'nameof', 'notImplemented', 'notOverloaded'), 

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

328 'Destination2Tuple', 'Destination3Tuple', 

329 'Distance2Tuple', 'Distance3Tuple', 'Distance4Tuple', 

330 'EasNor2Tuple', 'EasNor3Tuple', 'Forward4Tuple', 'Intersection3Tuple', 

331 'LatLon2Tuple', 'LatLon3Tuple', 'LatLon4Tuple', 

332 'LatLonDatum3Tuple', 'LatLonDatum5Tuple', 

333 'LatLonPrec3Tuple', 'LatLonPrec5Tuple', 

334 'NearestOn2Tuple', 'NearestOn3Tuple', 'NearestOn6Tuple', 'NearestOn8Tuple', 

335 'PhiLam2Tuple', 'PhiLam3Tuple', 'PhiLam4Tuple', 'Point3Tuple', 'Points2Tuple', 

336 'Reverse4Tuple', 'Triangle7Tuple', 'Triangle8Tuple', 'Trilaterate5Tuple', 

337 'UtmUps2Tuple', 'UtmUps5Tuple', 'UtmUps8Tuple', 'UtmUpsLatLon5Tuple', 

338 'Vector2Tuple', 'Vector3Tuple', 'Vector4Tuple'), 

339 nvectorBase=_i(_NorthPole_, _SouthPole_), 

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

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

342 _areaOf_, 'boundsOf', 'centroidOf', 'fractional', 

343 _isclockwise_, 'isconvex', 'isconvex_', 'isenclosedBy', _ispolar_, 

344 'luneOf', 'nearestOn5', 'perimeterOf', 'quadOf'), 

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

346 'deprecated_class', 'deprecated_function', 'deprecated_method', 

347 'deprecated_Property_RO', 'deprecated_property_RO', 'DeprecationWarnings'), 

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

349 'TriAngle5Tuple', 'TriSide2Tuple', 'TriSide4Tuple', 

350 'cassini', 'collins5', 'pierlot', 'pierlotx', 'tienstra7', 

351 'snellius3', 'wildberger3', 

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

353 rhumb=_i(), # module only 

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

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

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

357 sphericalBase=_i(), # module only 

358 sphericalNvector=_i(), # module only 

359 sphericalTrigonometry=_i(), # module only 

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

361 solveBase=_i(), # module only 

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

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

364 trf=_i('Helmert7Tuple', 'RefFrame', 'RefFrames', 

365 'date2epoch', 'epoch2date', 'trfXform'), 

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

367 'JacobiConformal', 'JacobiConformalSpherical', 

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

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

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

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

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

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

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

375 'Radius_', 'Scalar', 'Scalar_', 'Zone'), 

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

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

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

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

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

381# 'degrees2grades as degrees2gons', 

382 'fathom2m', 'ft2m', 'furlong2m', 

383 'grades', 'grades400', 'grades2degrees', 'grades2radians', 

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

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

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

387 'radians', 'radiansPI', 'radiansPI2', 'radiansPI_2', 'radians2m', 

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

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

390 'unroll180', 'unrollPI', 

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

392 'yard2m'), 

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

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

395 'utmupsValidate', 'utmupsValidateOK', 'utmupsZoneBand5'), 

396 utmupsBase=_i(), # module only 

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

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

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

400 'trilaterate2d2', 'trilaterate3d2'), 

401 vector3dBase=_i(), # module only 

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

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

404 

405_ALL_DEPRECATED = _NamedEnum_RO(_name='_ALL_DEPRECATED', 

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

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

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

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

410 'HeightIDW', 'HeightIDW2', 'HeightIDW3', 

411 'LatLonExact4Tuple', 'NearestOn4Tuple', 'Ned3Tuple', 

412 'RefFrameError', 'Rhumb7Tuple', 'RhumbOrder2Tuple', 

413 'Transform7Tuple', 'TriAngle4Tuple', 'UtmUps4Tuple'), 

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

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

416 'Datums', 'Ellipsoids', 'Transforms', 

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

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

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

420 'decodeEPSG2', 'encodeEPSG', 'enStr2', 'equirectangular3', 

421 'excessAbc', 'excessGirard', 'excessLHuilier', 

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

423 'inStr', 'isenclosedby', 'istuplist', 

424 'joined', 'joined_', 'nearestOn3', 'nearestOn4', 

425 'parseUTM', 'perimeterof', 'polygon', 'scalar', 'simplify2', 

426 'tienstra', 'toUtm', 'triAngle4', 'unsign0', 'unStr', 'utmZoneBand2'), 

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

428 

429 

430class _ALL_MODS(object): 

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

432 ''' 

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

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

435 

436 def __getattr__(self, name): 

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

438 

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

440 

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

442 

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

444 ''' 

445 m = self.getmodule(name) 

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

447 getattr(m, _tailof(name)) 

448 

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

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

451 raise AttributeError(_COLONSPACE_(t, _immutable_)) 

452 

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

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

455 

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

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

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

459 

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

461 

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

463 

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

465 ''' 

466 v = self.getmodule(mod) 

467 if attr_dflt: 

468 v = getattr(v, *attr_dflt) 

469 return v 

470 

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

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

473 

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

475 

476 @return: The C{pygeodesy} module. 

477 

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

479 ''' 

480 if _headof(name) != parent: 

481 name = _DOT_(parent, name) 

482 try: 

483 return _sys.modules[name] 

484 except KeyError: 

485 return import_module(name, parent) 

486 

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

488 '''Yield the modules imported so far. 

489 ''' 

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

491 yield n, m 

492 

493_ALL_MODS = _ALL_MODS() # PYCHOK singleton 

494 

495__all__ = _ALL_LAZY.lazily 

496__version__ = '23.12.08' 

497 

498 

499def _ALL_OTHER(*objs): 

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

501 ''' 

502 _interns = _ALL_MODS.interns # from pygeodesy import interns 

503 

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

505 n = _tailof(_dunder_nameof(o)) 

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

507 return getattr(_interns, i, n) 

508 

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

510 

511 

512if _FOR_DOCS: 

513 _ALL_DOCS = _ALL_OTHER 

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

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

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

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

518 # too much internal documentation. 

519else: 

520 def _ALL_DOCS(*unused): 

521 return () 

522 

523 

524def _all_deprecates(): 

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

526 ''' 

527 _D = _ALL_DEPRECATES 

528 if not _D: 

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

530 return _D 

531 

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

533 

534 

535def _all_imports(): 

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

537 ''' 

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

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

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

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

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

543 _D = _ALL_IMPORTS 

544 if not _D: 

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

546 return _D 

547 

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

549 

550 

551def _all_missing2(_all_): 

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

553 ''' 

554 def _diff(one, two): 

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

556 

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

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

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

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

561 

562 

563def _attrof(attr_as): # .testDeprecated 

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

565 return as_ or a_.rstrip(_DOT_) 

566 

567 

568def _caller3(up): # in .named 

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

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

571 ''' 

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

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

574 f = _sys._getframe(up + 1) 

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

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

577 f.f_lineno) # line number 

578 

579 

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

581 pass 

582 

583 

584# def _lazy_attributes(_name_): 

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

586# on lazily imported modules and sub-modules. 

587# ''' 

588# if _unlazy: 

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

590# 

591# def _getattr(attr, *dflt): 

592# try: # a module name 

593# return _ALL_MODS.getmodule(attr) 

594# except (AttributeError, ImportError): 

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

596# 

597# return _getattr 

598 

599 

600def _lazy_import2(pack): # MCCABE 14 

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

602 

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

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

605 

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

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

608 C{package.__getattr__}. 

609 

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

611 invalid or does not exist. 

612 

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

614 an import failed. 

615 

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

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

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

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

620 causing a C{ModuleNotFoundError}. 

621 

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

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

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

625 ''' 

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

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

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

629 

630 package, parent = _lazy_init2(pack) # _pygeodesy_ 

631 

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

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

634 imports = _all_imports() 

635 deprecates = _all_deprecates() 

636 

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

638 # only called once for each undefined pygeodesy attribute 

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

640 if mod: 

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

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

643 # note in the _lazy_import2.__doc__ above). 

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

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

646 else: # from mod import name 

647 attr = name 

648 try: 

649 t = _DOT_(pack, mod) 

650 imported = import_module(t, parent) 

651 except ImportError: 

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

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

654 t = getattr(imported, _p_a_c_k_a_g_e_, None) 

655 if t not in subpacks: # invalid module package 

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

657 if attr: # get the attribute 

658 imported = getattr(imported, attr, MISSING) 

659 if imported is MISSING: # PYCHOK no cover 

660 t = _DOT_(mod, attr) 

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

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

663 

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

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

666 else: # PYCHOK no cover 

667 t = _no_(_module_, _or_, _attribute_) 

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

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

670 

671 setattr(package, name, imported) 

672 if isLazy > 1: 

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

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

675 t = NN(t, _from_DOT__, mod) 

676 if isLazy > 2: 

677 try: # see C{_caller3} 

678 _, f, s = _caller3(2) 

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

680 except ValueError: 

681 pass 

682 printf(t) # XXX print 

683 

684 return imported # __getattr__ 

685 

686 global _lazy_attr 

687 _lazy_attr = __getattr__ 

688 

689 return package, __getattr__ # _lazy_import2 

690 

691 

692# def _lazy_import_all(_name_): 

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

694# of all items, see .deprecated.__init__ 

695# ''' 

696# if _unlazy: 

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

698# 

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

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

701# 

702# def _import_all(attr, *dflt): 

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

704# _getattr(attr, *dflt) 

705# 

706# return _import_all 

707 

708 

709def _lazy_import_as(_name_): 

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

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

712 lazily exported by C{__name__}. 

713 ''' 

714 if _unlazy: 

715 return None 

716 

717 def _import_as(mod): 

718 try: 

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

720 except ImportError: 

721 return _lazy_attr(mod) 

722 

723 return _import_as 

724 

725 

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

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

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

729# ''' 

730# if _unlazy: 

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

732# 

733# def _import_star(_into_): 

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

735# ''' 

736# d = dict() 

737# nm = _tailof(_name_) 

738# _g = _ALL_MODS.getattr # pygeodesy.__getattr__ 

739# _h = _headof 

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

741# if _h(m) == nm: 

742# try: 

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

744# except (AttributeError, ImportError): 

745# pass 

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

747# return d.keys() # imported names 

748# 

749# return _import_star 

750 

751 

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

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

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

755# ''' 

756# sm = dict() 

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

758# nm = _tailof(_name_) 

759# _a = _ALL_MODS.getattr 

760# _m = _ALL_MODS.getmodule 

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

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

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

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

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

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

767# # like import m as s 

768# m = _m(m) 

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

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

771# pass 

772# d.update(sm) 

773# 

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

775 

776 

777def _lazy_init2(pack): 

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

779 

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

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

782 

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

784 for easy reference within itself and its name aka the 

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

786 

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

788 an import failed or the package name is 

789 invalid or does not exist. 

790 

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

792 ''' 

793 global isLazy, _unLazy0 

794 

795 z = _getenv(_PYGEODESY_LAZY_IMPORT_, None) 

796 if z is None: # _PYGEODESY_LAZY_IMPORT_ not set 

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

798 else: 

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

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

801 

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

803 

804 if isLazy < 1: # not enabled 

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

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

807 isLazy += 1 

808 

809 try: # to initialize in Python 3+ 

810 package = import_module(pack) 

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

812 if parent != pack: # assert 

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

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

815 

816 except (AttributeError, ImportError) as x: 

817 isLazy = False # failed 

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

819 

820 return package, parent 

821 

822 

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

824 # from pygeodesy.streprs import pairs 

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

826 

827 

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

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

830 

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

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

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

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

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

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

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

838 and C{B{flush}}. 

839 

840 @return: Number of bytes written. 

841 ''' 

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

843 

844 

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

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

847 

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

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

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

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

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

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

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

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

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

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

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

859 

860 @return: Number of bytes written. 

861 ''' 

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

863 try: 

864 if args: 

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

866 elif kwds: # PYCHOK no cover 

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

868 else: # PYCHOK no cover 

869 t = fmt 

870 except Exception as x: 

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

872 unstr = _ALL_MODS.streprs.unstr 

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

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

875 try: 

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

877 except UnicodeEncodeError: # XXX only Windows 

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

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

880 if fl: # PYCHOK no cover 

881 f.flush() 

882 return n 

883 

884 

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

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

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

888 ''' 

889 if nl > 0: 

890 prefix = NN(_NL_ * nl, prefix) 

891 if nt > 0: 

892 end = NN(end, _NL_ * nt) 

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

894 

895 

896# del _i, _i0, _intern 

897 

898if __name__ == '__main__': 

899 

900 from timeit import timeit 

901 

902 def t1(): 

903 from pygeodesy.trf import RefFrame 

904 return RefFrame 

905 

906 def t2(): 

907 return _ALL_MODS.trf.RefFrame 

908 

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

910 

911 t1 = timeit(t1, number=1000000) 

912 t2 = timeit(t2, number=1000000) 

913 v = _Python_(_sys.version) 

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

915 del t1, t2, v 

916 

917# python3.12 -m pygeodesy.lazily 

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

919 

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

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

922 

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

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

925 

926# % python2 -m pygeodesy.lazily 

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

928 

929# **) MIT License 

930# 

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

932# 

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

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

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

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

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

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

939# 

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

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

942# 

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

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

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

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

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

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

949# OTHER DEALINGS IN THE SOFTWARE.