Coverage for pygeodesy/lazily.py: 92%

208 statements  

« prev     ^ index     » next       coverage.py v7.2.2, created at 2024-01-26 16:28 -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('callername', 'classname', 'classnaming', 'modulename', 

327 'nameof', 'notImplemented', 'notOverloaded'), 

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

329 'Destination2Tuple', 'Destination3Tuple', 

330 'Distance2Tuple', 'Distance3Tuple', 'Distance4Tuple', 

331 'EasNor2Tuple', 'EasNor3Tuple', 'Forward4Tuple', 'Intersection3Tuple', 

332 'LatLon2Tuple', 'LatLon3Tuple', 'LatLon4Tuple', 

333 'LatLonDatum3Tuple', 'LatLonDatum5Tuple', 

334 'LatLonPrec3Tuple', 'LatLonPrec5Tuple', 

335 'NearestOn2Tuple', 'NearestOn3Tuple', 'NearestOn6Tuple', 'NearestOn8Tuple', 

336 'PhiLam2Tuple', 'PhiLam3Tuple', 'PhiLam4Tuple', 'Point3Tuple', 'Points2Tuple', 

337 'Reverse4Tuple', 'Triangle7Tuple', 'Triangle8Tuple', 'Trilaterate5Tuple', 

338 'UtmUps2Tuple', 'UtmUps5Tuple', 'UtmUps8Tuple', 'UtmUpsLatLon5Tuple', 

339 'Vector2Tuple', 'Vector3Tuple', 'Vector4Tuple'), 

340 nvectorBase=_i(_NorthPole_, _SouthPole_), 

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

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

343 _areaOf_, 'boundsOf', 'centroidOf', 'fractional', 

344 _isclockwise_, 'isconvex', 'isconvex_', 'isenclosedBy', _ispolar_, 

345 'luneOf', 'nearestOn5', 'perimeterOf', 'quadOf'), 

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

347 'deprecated_class', 'deprecated_function', 'deprecated_method', 

348 'deprecated_Property_RO', 'deprecated_property_RO', 'DeprecationWarnings'), 

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

350 'TriAngle5Tuple', 'TriSide2Tuple', 'TriSide4Tuple', 

351 'cassini', 'collins5', 'pierlot', 'pierlotx', 'tienstra7', 

352 'snellius3', 'wildberger3', 

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

354 rhumb=_i(), # module only 

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

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

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

358 sphericalBase=_i(), # module only 

359 sphericalNvector=_i(), # module only 

360 sphericalTrigonometry=_i(), # module only 

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

362 solveBase=_i(), # module only 

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

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

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

366 'date2epoch', 'epoch2date', 'trfTransforms', 'trfXform'), 

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

368 'JacobiConformal', 'JacobiConformalSpherical', 

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

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

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

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

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

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

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

376 'Radius_', 'Scalar', 'Scalar_', 'Zone'), 

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

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

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

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

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

382# 'degrees2grades as degrees2gons', 

383 'fathom2m', 'ft2m', 'furlong2m', 

384 'grades', 'grades400', 'grades2degrees', 'grades2radians', 

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

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

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

388 'radians', 'radiansPI', 'radiansPI2', 'radiansPI_2', 'radians2m', 

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

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

391 'unroll180', 'unrollPI', 

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

393 'yard2m'), 

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

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

396 'utmupsValidate', 'utmupsValidateOK', 'utmupsZoneBand5'), 

397 utmupsBase=_i(), # module only 

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

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

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

401 'trilaterate2d2', 'trilaterate3d2'), 

402 vector3dBase=_i(), # module only 

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

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

405 

406_ALL_DEPRECATED = _NamedEnum_RO(_name='_ALL_DEPRECATED', 

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

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

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

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

411 'HeightIDW', 'HeightIDW2', 'HeightIDW3', 

412 'LatLonExact4Tuple', 'NearestOn4Tuple', 'Ned3Tuple', 

413 'RefFrameError', 'Rhumb7Tuple', 'RhumbOrder2Tuple', 

414 'Transform7Tuple', 'TriAngle4Tuple', 'UtmUps4Tuple'), 

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

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

417 'Datums', 'Ellipsoids', 'Transforms', 

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

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

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

421 'decodeEPSG2', 'encodeEPSG', 'enStr2', 'equirectangular3', 

422 'excessAbc', 'excessGirard', 'excessLHuilier', 

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

424 'inStr', 'isenclosedby', 'istuplist', 

425 'joined', 'joined_', 'nearestOn3', 'nearestOn4', 

426 'parseUTM', 'perimeterof', 'polygon', 'scalar', 'simplify2', 

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

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

429 

430 

431class _ALL_MODS(object): 

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

433 ''' 

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

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

436 

437 def __getattr__(self, name): 

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

439 

440 @arg name: Qualified module or 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 m = self.getmodule(name) 

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

448 getattr(m, _tailof(name)) 

449 

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

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

452 raise AttributeError(_COLONSPACE_(t, _immutable_)) 

453 

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

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

456 

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

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

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

460 

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

462 

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

464 

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

466 ''' 

467 v = self.getmodule(mod) 

468 if attr_dflt: 

469 v = getattr(v, *attr_dflt) 

470 return v 

471 

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

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

474 

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

476 

477 @return: The C{pygeodesy} module. 

478 

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

480 ''' 

481 if _headof(name) != parent: 

482 name = _DOT_(parent, name) 

483 try: 

484 return _sys.modules[name] 

485 except KeyError: 

486 return import_module(name, parent) 

487 

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

489 '''Yield the modules imported so far. 

490 ''' 

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

492 yield n, m 

493 

494 @property # property_RO 

495 def name(self): 

496 return self.__class__.__name__ 

497 

498_ALL_MODS = _ALL_MODS() # PYCHOK singleton 

499 

500__all__ = _ALL_LAZY.lazily 

501__version__ = '24.01.24' 

502 

503 

504def _ALL_OTHER(*objs): 

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

506 ''' 

507 _interns = _ALL_MODS.interns # from pygeodesy import interns 

508 

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

510 n = _tailof(_dunder_nameof(o)) 

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

512 return getattr(_interns, i, n) 

513 

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

515 

516 

517if _FOR_DOCS: 

518 _ALL_DOCS = _ALL_OTHER 

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

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

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

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

523 # too much internal documentation. 

524else: 

525 def _ALL_DOCS(*unused): 

526 return () 

527 

528 

529def _all_deprecates(): 

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

531 ''' 

532 _D = _ALL_DEPRECATES 

533 if not _D: 

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

535 return _D 

536 

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

538 

539 

540def _all_imports(): 

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

542 ''' 

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

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

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

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

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

548 _D = _ALL_IMPORTS 

549 if not _D: 

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

551 return _D 

552 

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

554 

555 

556def _all_missing2(_all_): 

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

558 ''' 

559 def _diff(one, two): 

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

561 

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

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

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

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

566 

567 

568def _attrof(attr_as): # .testDeprecated 

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

570 return as_ or a_.rstrip(_DOT_) 

571 

572 

573def _caller3(up): # in .named 

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

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

576 ''' 

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

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

579 f = _sys._getframe(up + 1) 

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

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

582 f.f_lineno) # line number 

583 

584 

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

586 pass 

587 

588 

589# def _lazy_attributes(_name_): 

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

591# on lazily imported modules and sub-modules. 

592# ''' 

593# if _unlazy: 

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

595# 

596# def _getattr(attr, *dflt): 

597# try: # a module name 

598# return _ALL_MODS.getmodule(attr) 

599# except (AttributeError, ImportError): 

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

601# 

602# return _getattr 

603 

604 

605def _lazy_import2(pack): # MCCABE 14 

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

607 

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

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

610 

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

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

613 C{package.__getattr__}. 

614 

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

616 invalid or does not exist. 

617 

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

619 an import failed. 

620 

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

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

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

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

625 causing a C{ModuleNotFoundError}. 

626 

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

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

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

630 ''' 

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

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

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

634 

635 package, parent = _lazy_init2(pack) # _pygeodesy_ 

636 

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

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

639 imports = _all_imports() 

640 deprecates = _all_deprecates() 

641 

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

643 # only called once for each undefined pygeodesy attribute 

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

645 if mod: 

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

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

648 # note in the _lazy_import2.__doc__ above). 

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

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

651 else: # from mod import name 

652 attr = name 

653 try: 

654 t = _DOT_(pack, mod) 

655 imported = import_module(t, parent) 

656 except ImportError: 

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

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

659 t = getattr(imported, _p_a_c_k_a_g_e_, None) 

660 if t not in subpacks: # invalid module package 

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

662 if attr: # get the attribute 

663 imported = getattr(imported, attr, MISSING) 

664 if imported is MISSING: # PYCHOK no cover 

665 t = _DOT_(mod, attr) 

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

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

668 

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

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

671 else: # PYCHOK no cover 

672 t = _no_(_module_, _or_, _attribute_) 

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

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

675 

676 setattr(package, name, imported) 

677 if isLazy > 1: 

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

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

680 t = NN(t, _from_DOT__, mod) 

681 if isLazy > 2: 

682 try: # see C{_caller3} 

683 _, f, s = _caller3(2) 

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

685 except ValueError: 

686 pass 

687 printf(t) # XXX print 

688 

689 return imported # __getattr__ 

690 

691 global _lazy_attr 

692 _lazy_attr = __getattr__ 

693 

694 return package, __getattr__ # _lazy_import2 

695 

696 

697# def _lazy_import_all(_name_): 

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

699# of all items, see .deprecated.__init__ 

700# ''' 

701# if _unlazy: 

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

703# 

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

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

706# 

707# def _import_all(attr, *dflt): 

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

709# _getattr(attr, *dflt) 

710# 

711# return _import_all 

712 

713 

714def _lazy_import_as(_name_): 

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

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

717 lazily exported by C{__name__}. 

718 ''' 

719 if _unlazy: 

720 return None 

721 

722 def _import_as(mod): 

723 try: 

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

725 except ImportError: 

726 return _lazy_attr(mod) 

727 

728 return _import_as 

729 

730 

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

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

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

734# ''' 

735# if _unlazy: 

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

737# 

738# def _import_star(_into_): 

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

740# ''' 

741# d = dict() 

742# nm = _tailof(_name_) 

743# _g = _ALL_MODS.getattr # pygeodesy.__getattr__ 

744# _h = _headof 

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

746# if _h(m) == nm: 

747# try: 

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

749# except (AttributeError, ImportError): 

750# pass 

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

752# return d.keys() # imported names 

753# 

754# return _import_star 

755 

756 

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

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

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

760# ''' 

761# sm = dict() 

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

763# nm = _tailof(_name_) 

764# _a = _ALL_MODS.getattr 

765# _m = _ALL_MODS.getmodule 

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

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

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

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

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

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

772# # like import m as s 

773# m = _m(m) 

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

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

776# pass 

777# d.update(sm) 

778# 

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

780 

781 

782def _lazy_init2(pack): 

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

784 

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

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

787 

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

789 for easy reference within itself and its name aka the 

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

791 

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

793 an import failed or the package name is 

794 invalid or does not exist. 

795 

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

797 ''' 

798 global isLazy, _unLazy0 

799 

800 z = _getenv(_PYGEODESY_LAZY_IMPORT_, None) 

801 if z is None: # _PYGEODESY_LAZY_IMPORT_ not set 

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

803 else: 

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

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

806 

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

808 

809 if isLazy < 1: # not enabled 

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

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

812 isLazy += 1 

813 

814 try: # to initialize in Python 3+ 

815 package = import_module(pack) 

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

817 if parent != pack: # assert 

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

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

820 

821 except (AttributeError, ImportError) as x: 

822 isLazy = False # failed 

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

824 

825 return package, parent 

826 

827 

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

829 # from pygeodesy.streprs import pairs 

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

831 

832 

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

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

835 

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

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

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

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

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

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

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

843 and C{B{flush}}. 

844 

845 @return: Number of bytes written. 

846 ''' 

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

848 

849 

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

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

852 

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

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

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

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

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

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

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

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

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

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

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

864 

865 @return: Number of bytes written. 

866 ''' 

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

868 try: 

869 if args: 

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

871 elif kwds: # PYCHOK no cover 

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

873 else: # PYCHOK no cover 

874 t = fmt 

875 except Exception as x: 

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

877 unstr = _ALL_MODS.streprs.unstr 

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

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

880 try: 

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

882 except UnicodeEncodeError: # XXX only Windows 

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

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

885 if fl: # PYCHOK no cover 

886 f.flush() 

887 return n 

888 

889 

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

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

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

893 ''' 

894 if nl > 0: 

895 prefix = NN(_NL_ * nl, prefix) 

896 if nt > 0: 

897 end = NN(end, _NL_ * nt) 

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

899 

900 

901# del _i, _i0, _intern 

902 

903if __name__ == '__main__': 

904 

905 from timeit import timeit 

906 

907 def t1(): 

908 from pygeodesy.trf import RefFrame 

909 return RefFrame 

910 

911 def t2(): 

912 return _ALL_MODS.trf.RefFrame 

913 

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

915 

916 t1 = timeit(t1, number=1000000) 

917 t2 = timeit(t2, number=1000000) 

918 v = _Python_(_sys.version) 

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

920 del t1, t2, v 

921 

922# python3.12 -m pygeodesy.lazily 

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

924 

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

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

927 

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

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

930 

931# % python2 -m pygeodesy.lazily 

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

933 

934# **) MIT License 

935# 

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

937# 

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

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

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

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

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

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

944# 

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

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

947# 

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

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

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

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

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

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

954# OTHER DEALINGS IN THE SOFTWARE.