Coverage for /home/runner/work/viur-core/viur-core/viur/src/viur/core/__init__.py: 14%

156 statements  

« prev     ^ index     » next       coverage.py v7.10.6, created at 2025-09-13 11:04 +0000

1""" 

2ViUR-core 

3Copyright © 2025 Mausbrand Informationssysteme GmbH 

4 

5https://core.docs.viur.dev 

6Licensed under the MIT license. See LICENSE for more information. 

7""" 

8 

9import os 

10import sys 

11 

12# Set a dummy project id to survive API Client initializations 

13if sys.argv[0].endswith("viur-migrate"): # FIXME: What a "kinda hackish" solution... 13 ↛ 14line 13 didn't jump to line 14 because the condition on line 13 was never true

14 os.environ["GOOGLE_CLOUD_PROJECT"] = "dummy" 

15 

16from google.appengine.api import wrap_wsgi_app 

17from types import ModuleType 

18from viur.core import i18n, request, utils 

19from viur.core.config import conf 

20from viur.core.decorators import access, exposed, force_post, force_ssl, internal_exposed, skey 

21from viur.core.i18n import translate 

22from viur.core.module import Method, Module 

23import inspect 

24import typing as t 

25import warnings 

26from .tasks import ( 

27 callDeferred, 

28 CallDeferred, 

29 DeleteEntitiesIter, 

30 PeriodicTask, 

31 QueryIter, 

32 retry_n_times, 

33 runStartupTasks, 

34 StartupTask, 

35 TaskHandler, 

36) 

37 

38if not sys.argv[0].endswith("viur-migrate"): # FIXME: What a "kinda hackish" solution... 38 ↛ 42line 38 didn't jump to line 42 because the condition on line 38 was always true

39 # noinspection PyUnresolvedReferences 

40 from viur.core import logging as viurLogging # unused import, must exist, initializes request logging 

41 

42import logging # this import has to stay here, see #571 

43from deprecated.sphinx import deprecated 

44 

45__all__ = [ 

46 # basics from this __init__ 

47 "setDefaultLanguage", 

48 "setDefaultDomainLanguage", 

49 "setup", 

50 # prototypes 

51 "Module", 

52 "Method", 

53 # tasks 

54 "DeleteEntitiesIter", 

55 "QueryIter", 

56 "retry_n_times", 

57 "callDeferred", 

58 "CallDeferred", 

59 "StartupTask", 

60 "PeriodicTask", 

61 # Decorators 

62 "access", 

63 "exposed", 

64 "force_post", 

65 "force_ssl", 

66 "internal_exposed", 

67 "skey", 

68 # others 

69 "conf", 

70 "translate", 

71] 

72 

73# Show DeprecationWarning from the viur-core 

74warnings.filterwarnings("once", category=DeprecationWarning) 

75warnings.filterwarnings("ignore", category=DeprecationWarning, module=r"viur\.datastore.*", 

76 message="'clonedBoneMap' was renamed into 'bone_map'") 

77 

78 

79@deprecated( 

80 version="3.8.0", 

81 reason="Simply set `conf.i18n.default_language` to the desired language." 

82) 

83def setDefaultLanguage(lang: str): 

84 """ 

85 Sets the default language used by ViUR to *lang*. 

86 

87 :param lang: Name of the language module to use by default. 

88 """ 

89 msg = f"`setDefaultLanguage(\"{lang}\")` is deprecated; " \ 

90 f"Replace the call by `conf.i18n.default_language = \"{lang.lower()}\"`" 

91 warnings.warn(msg, DeprecationWarning, stacklevel=2) 

92 logging.warning(msg) 

93 

94 conf.i18n.default_language = lang.lower() 

95 

96 

97def setDefaultDomainLanguage(domain: str, lang: str): 

98 """ 

99 If conf.i18n.language_method is set to "domain", this function allows setting the map of which domain 

100 should use which language. 

101 :param domain: The domain for which the language should be set 

102 :param lang: The language to use (in ISO2 format, e.g. "DE") 

103 """ 

104 host = domain.lower().strip(" /") 

105 if host.startswith("www."): 

106 host = host[4:] 

107 conf.i18n.domain_language_mapping[host] = lang.lower() 

108 

109 

110def __build_app(modules: ModuleType | object, renderers: ModuleType | object, default: str = None) -> Module: 

111 """ 

112 Creates the application-context for the current instance. 

113 

114 This function converts the classes found in the *modules*-module, 

115 and the given renders into the object found at ``conf.main_app``. 

116 

117 Every class found in *modules* becomes 

118 

119 - instanced 

120 - get the corresponding renderer attached 

121 - will be attached to ``conf.main_app`` 

122 

123 :param modules: Usually the module provided as *modules* directory within the application. 

124 :param renderers: Usually the module *viur.core.renders*, or a dictionary renderName => renderClass. 

125 :param default: Name of the renderer, which will form the root of the application. 

126 This will be the renderer, which wont get a prefix, usually html. 

127 (=> /user instead of /html/user) 

128 """ 

129 if not isinstance(renderers, dict): 

130 # build up the dict from viur.core.render 

131 renderers, mod = {}, renderers 

132 

133 from viur.core.render.abstract import AbstractRenderer 

134 

135 for render_name, render_mod in vars(mod).items(): 

136 if inspect.ismodule(render_mod): 

137 for render_clsname, render_cls in vars(render_mod).items(): 

138 # this is "kinda hackish..." because ViUR 3's current renderer concept is pure bulls*t... 

139 if render_clsname == "DefaultRender": 

140 continue 

141 

142 if ( 

143 # test for a renderer 

144 (inspect.isclass(render_cls) and issubclass(render_cls, AbstractRenderer)) 

145 # bullsh*t, this must be entirely reworked! 

146 or render_clsname == "_postProcessAppObj" 

147 ): 

148 renderers.setdefault(render_name, {}) 

149 renderers[render_name][render_clsname] = render_cls 

150 

151 # assign ViUR system modules 

152 from viur.core.modules.moduleconf import ModuleConf # noqa: E402 # import works only here because circular imports 

153 from viur.core.modules.script import Script # noqa: E402 # import works only here because circular imports 

154 from viur.core.modules.translation import Translation # noqa: E402 # import works only here because circular imports 

155 from viur.core.prototypes.instanced_module import InstancedModule # noqa: E402 # import works only here because circular imports 

156 

157 for name, cls in { 

158 "_tasks": TaskHandler, 

159 "_moduleconf": ModuleConf, 

160 "_translation": Translation, 

161 "script": Script, 

162 }.items(): 

163 # Check whether name is contained in modules so that it can be overwritten 

164 if name not in vars(modules): 

165 setattr(modules, name, cls) 

166 

167 assert issubclass(getattr(modules, name), cls) 

168 

169 # Resolver defines the URL mapping 

170 resolver = {} 

171 

172 # Index is mapping all module instances for global access 

173 index = (modules.index if hasattr(modules, "index") else Module)("index", "") 

174 index.register(resolver, renderers[default]["default"](parent=index)) 

175 

176 for module_name, module_cls in vars(modules).items(): # iterate over all modules 

177 if module_name == "index": 

178 continue # ignore index, as it has been processed before! 

179 

180 if module_name in renderers: 

181 raise NameError(f"Cannot name module {module_name!r}, as it is a reserved render's name") 

182 

183 if not ( # we define the cases we want to use and then negate them all 

184 (inspect.isclass(module_cls) and issubclass(module_cls, Module) # is a normal Module class 

185 and not issubclass(module_cls, InstancedModule)) # but not a "instantiable" Module 

186 or isinstance(module_cls, InstancedModule) # is an already instanced Module 

187 ): 

188 continue 

189 

190 # remember module_instance for default renderer. 

191 module_instance = default_module_instance = None 

192 

193 for render_name, render in renderers.items(): # look, if a particular renderer should be built 

194 # Only continue when module_cls is configured for this render 

195 # todo: VIUR4 this is for legacy reasons, can be done better! 

196 if not getattr(module_cls, render_name, False): 

197 continue 

198 

199 # Create a new module instance 

200 module_instance = module_cls( 

201 module_name, ("/" + render_name if render_name != default else "") + "/" + module_name 

202 ) 

203 

204 # Attach the module-specific or the default render 

205 if render_name == default: # default or render (sub)namespace? 

206 default_module_instance = module_instance 

207 target = resolver 

208 else: 

209 if getattr(index, render_name, True) is True: 

210 # Render is not build yet, or it is just the simple marker that a given render should be build 

211 setattr(index, render_name, Module(render_name, "/" + render_name)) 

212 

213 # Attach the module to the given renderer node 

214 setattr(getattr(index, render_name), module_name, module_instance) 

215 target = resolver.setdefault(render_name, {}) 

216 

217 module_instance.register(target, render.get(module_name, render["default"])(parent=module_instance)) 

218 

219 # Apply Renderers postProcess Filters 

220 if "_postProcessAppObj" in render: # todo: This is ugly! 

221 render["_postProcessAppObj"](target) 

222 

223 # Ugly solution, but there is no better way to do it in ViUR 3: 

224 # Allow that any module can be accessed by `conf.main_app.<modulename>`, 

225 # either with default render or the last created render. 

226 # This behavior does NOT influence the routing. 

227 if default_module_instance or module_instance: 

228 setattr(index, module_name, default_module_instance or module_instance) 

229 

230 # fixme: Below is also ugly... 

231 if default in renderers and hasattr(renderers[default]["default"], "renderEmail"): 

232 conf.emailRenderer = renderers[default]["default"]().renderEmail 

233 elif "html" in renderers: 

234 conf.emailRenderer = renderers["html"]["default"]().renderEmail 

235 

236 # This might be useful for debugging, please keep it for now. 

237 if conf.debug.trace: 

238 import pprint 

239 logging.debug(pprint.pformat(resolver)) 

240 

241 conf.main_resolver = resolver 

242 conf.main_app = index 

243 

244 

245def setup(modules: ModuleType | object, render: ModuleType | object = None, default: str = "html"): 

246 """ 

247 Define whats going to be served by this instance. 

248 

249 :param modules: Usually the module provided as *modules* directory within the application. 

250 :param render: Usually the module *viur.core.renders*, or a dictionary renderName => renderClass. 

251 :param default: Name of the renderer, which will form the root of the application.\ 

252 This will be the renderer, which wont get a prefix, usually html. \ 

253 (=> /user instead of /html/user) 

254 """ 

255 from viur.core.bones.base import setSystemInitialized 

256 # noinspection PyUnresolvedReferences 

257 import skeletons # This import is not used here but _must_ remain to ensure that the 

258 # application's data models are explicitly imported at some place! 

259 if conf.instance.project_id not in conf.valid_application_ids: 

260 raise RuntimeError( 

261 f"""Refusing to start, {conf.instance.project_id=} is not in {conf.valid_application_ids=}""") 

262 if not render: 

263 import viur.core.render 

264 render = viur.core.render 

265 

266 __build_app(modules, render, default) 

267 

268 # Send warning email in case trace is activated in a cloud environment 

269 if ((conf.debug.trace 

270 or conf.debug.trace_external_call_routing 

271 or conf.debug.trace_internal_call_routing) 

272 and (not conf.instance.is_dev_server or conf.debug.dev_server_cloud_logging)): 

273 from viur.core import email 

274 try: 

275 email.send_email_to_admins( 

276 "Debug mode enabled", 

277 "ViUR just started a new Instance with call tracing enabled! This might log sensitive information!" 

278 ) 

279 except Exception as exc: # OverQuota, whatever 

280 logging.exception(exc) 

281 # Ensure that our Content Security Policy Header Cache gets build 

282 from viur.core import securityheaders 

283 securityheaders._rebuildCspHeaderCache() 

284 securityheaders._rebuildPermissionHeaderCache() 

285 setSystemInitialized() 

286 # Assert that all security related headers are in a sane state 

287 if conf.security.content_security_policy and conf.security.content_security_policy["_headerCache"]: 

288 for k in conf.security.content_security_policy["_headerCache"]: 

289 if not k.startswith("Content-Security-Policy"): 

290 raise AssertionError("Got unexpected header in " 

291 "conf.security.content_security_policy['_headerCache']") 

292 if conf.security.strict_transport_security: 

293 if not conf.security.strict_transport_security.startswith("max-age"): 

294 raise AssertionError("Got unexpected header in conf.security.strict_transport_security") 

295 crossDomainPolicies = {None, "none", "master-only", "by-content-type", "all"} 

296 if conf.security.x_permitted_cross_domain_policies not in crossDomainPolicies: 

297 raise AssertionError("conf.security.x_permitted_cross_domain_policies " 

298 f"must be one of {crossDomainPolicies!r}") 

299 if conf.security.x_frame_options is not None and isinstance(conf.security.x_frame_options, tuple): 

300 mode, uri = conf.security.x_frame_options 

301 assert mode in ["deny", "sameorigin", "allow-from"] 

302 if mode == "allow-from": 

303 assert uri is not None and (uri.lower().startswith("https://") or uri.lower().startswith("http://")) 

304 runStartupTasks() # Add a deferred call to run all queued startup tasks 

305 i18n.initializeTranslations() 

306 if conf.file_hmac_key is None: 

307 from viur.core import db 

308 key = db.Key("viur-conf", "viur-conf") 

309 if not (obj := db.get(key)): # create a new "viur-conf"? 

310 logging.info("Creating new viur-conf") 

311 obj = db.Entity(key) 

312 

313 if "hmacKey" not in obj: # create a new hmacKey 

314 logging.info("Creating new hmacKey") 

315 obj["hmacKey"] = utils.string.random(length=20) 

316 db.put(obj) 

317 

318 conf.file_hmac_key = bytes(obj["hmacKey"], "utf-8") 

319 

320 if conf.instance.is_dev_server: 

321 WIDTH = 80 # defines the standard width 

322 FILL = "#" # define sthe fill char (must be len(1)!) 

323 PYTHON_VERSION = (sys.version_info.major, sys.version_info.minor, sys.version_info.micro) 

324 

325 # define lines to show 

326 lines = ( 

327 " LOCAL DEVELOPMENT SERVER IS UP AND RUNNING ", # title line 

328 f"""project = \033[1;31m{conf.instance.project_id}\033[0m""", 

329 f"""python = \033[1;32m{".".join((str(i) for i in PYTHON_VERSION))}\033[0m""", 

330 f"""viur = \033[1;32m{".".join((str(i) for i in conf.version))}\033[0m""", 

331 "" # empty line 

332 ) 

333 

334 # first and last line are shown with a cool line made of FILL 

335 first_last = (0, len(lines) - 1) 

336 

337 # dump to console 

338 for i, line in enumerate(lines): 

339 print( 

340 f"""\033[0m{FILL}{line:{ 

341 FILL if i in first_last else " "}^{(WIDTH - 2) + (11 if i not in first_last else 0) 

342 }}{FILL}""" 

343 ) 

344 

345 return wrap_wsgi_app(app) 

346 

347 

348def app(environ: dict, start_response: t.Callable): 

349 return request.Router(environ).response(environ, start_response) 

350 

351 

352# DEPRECATED ATTRIBUTES HANDLING 

353 

354__DEPRECATED_DECORATORS = { 

355 # stuff prior viur-core < 3.5 

356 "forcePost": ("force_post", force_post), 

357 "forceSSL": ("force_ssl", force_ssl), 

358 "internalExposed": ("internal_exposed", internal_exposed) 

359} 

360 

361 

362def __getattr__(attr: str) -> object: 

363 if entry := __DEPRECATED_DECORATORS.get(attr): 363 ↛ 364line 363 didn't jump to line 364 because the condition on line 363 was never true

364 func = entry[1] 

365 msg = f"@{attr} was replaced by @{entry[0]}" 

366 warnings.warn(msg, DeprecationWarning, stacklevel=2) 

367 logging.warning(msg, stacklevel=2) 

368 return func 

369 

370 return super(__import__(__name__).__class__).__getattr__(attr)