pz-cli 5.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (399) hide show
  1. pz_cli-5.0.0.dist-info/METADATA +51 -0
  2. pz_cli-5.0.0.dist-info/RECORD +399 -0
  3. pz_cli-5.0.0.dist-info/WHEEL +4 -0
  4. pz_cli-5.0.0.dist-info/entry_points.txt +5 -0
  5. pz_core/__init__.py +64 -0
  6. pz_core/__main__.py +7 -0
  7. pz_core/app.py +45 -0
  8. pz_core/assembly/__init__.py +17 -0
  9. pz_core/assembly/app_discovery.py +1240 -0
  10. pz_core/assembly/apps/__init__.py +25 -0
  11. pz_core/assembly/apps/compiler.py +824 -0
  12. pz_core/assembly/apps/providers.py +188 -0
  13. pz_core/assembly/cli/__init__.py +9 -0
  14. pz_core/assembly/cli/compiler.py +166 -0
  15. pz_core/assembly/diagnostics/__init__.py +21 -0
  16. pz_core/assembly/diagnostics/checks.py +257 -0
  17. pz_core/assembly/diagnostics/dev_sources.py +569 -0
  18. pz_core/assembly/events/__init__.py +5 -0
  19. pz_core/assembly/events/compiler.py +219 -0
  20. pz_core/assembly/extensions/__init__.py +5 -0
  21. pz_core/assembly/extensions/compiler.py +696 -0
  22. pz_core/assembly/infra/__init__.py +6 -0
  23. pz_core/assembly/infra/compiler.py +272 -0
  24. pz_core/assembly/lifecycle/__init__.py +5 -0
  25. pz_core/assembly/lifecycle/compiler.py +95 -0
  26. pz_core/assembly/middlewares/__init__.py +19 -0
  27. pz_core/assembly/middlewares/compiler.py +508 -0
  28. pz_core/assembly/project/__init__.py +7 -0
  29. pz_core/assembly/project/compiler.py +9 -0
  30. pz_core/assembly/project/context.py +17 -0
  31. pz_core/assembly/project/discovery.py +227 -0
  32. pz_core/assembly/resources/__init__.py +19 -0
  33. pz_core/assembly/resources/compiler.py +310 -0
  34. pz_core/assembly/resources/settings.py +129 -0
  35. pz_core/assembly/routes/__init__.py +7 -0
  36. pz_core/assembly/routes/compiler.py +400 -0
  37. pz_core/assembly/runtime_manifests/__init__.py +13 -0
  38. pz_core/assembly/runtime_manifests/compiler.py +159 -0
  39. pz_core/assembly/settings/__init__.py +17 -0
  40. pz_core/assembly/settings/compiler.py +786 -0
  41. pz_core/assembly/settings/host_project_overrides.py +82 -0
  42. pz_core/assembly/settings/host_runtime_endpoint.py +207 -0
  43. pz_core/authoring/__init__.py +79 -0
  44. pz_core/authoring/app_init_service.py +946 -0
  45. pz_core/authoring/app_versions.py +814 -0
  46. pz_core/authoring/cli.py +192 -0
  47. pz_core/authoring/commands.py +1810 -0
  48. pz_core/authoring/conflicts.py +180 -0
  49. pz_core/authoring/dev_bindings.py +916 -0
  50. pz_core/authoring/dev_git.py +1087 -0
  51. pz_core/authoring/dev_import.py +1061 -0
  52. pz_core/authoring/dev_manifest.py +522 -0
  53. pz_core/authoring/dev_sources.py +1638 -0
  54. pz_core/authoring/env_cli.py +454 -0
  55. pz_core/authoring/files.py +109 -0
  56. pz_core/authoring/ide_projection.py +1129 -0
  57. pz_core/authoring/naming.py +58 -0
  58. pz_core/authoring/official_dev_sources.py +432 -0
  59. pz_core/authoring/official_sources.json +156 -0
  60. pz_core/authoring/orchestration_service.py +558 -0
  61. pz_core/authoring/project_default.jsonc +53 -0
  62. pz_core/authoring/project_defaults.py +88 -0
  63. pz_core/authoring/project_metadata_service.py +199 -0
  64. pz_core/authoring/project_settings_checks.py +51 -0
  65. pz_core/authoring/project_settings_cli.py +299 -0
  66. pz_core/authoring/project_settings_service.py +1700 -0
  67. pz_core/authoring/project_state.py +399 -0
  68. pz_core/authoring/publish_git.py +423 -0
  69. pz_core/authoring/publish_lock.py +188 -0
  70. pz_core/authoring/publish_source.py +195 -0
  71. pz_core/authoring/release.py +1382 -0
  72. pz_core/authoring/repo_keys.py +29 -0
  73. pz_core/authoring/root_cli.py +28 -0
  74. pz_core/authoring/scaffold_service.py +325 -0
  75. pz_core/authoring/sync_service.py +787 -0
  76. pz_core/authoring/templates/app/__init__.py +1 -0
  77. pz_core/authoring/templates/app/api.py +25 -0
  78. pz_core/authoring/templates/app/apps.py +31 -0
  79. pz_core/authoring/templates/app/auth_package_init.py +14 -0
  80. pz_core/authoring/templates/app/auth_readme.py +29 -0
  81. pz_core/authoring/templates/app/configs_package_init.py +14 -0
  82. pz_core/authoring/templates/app/default_env.py +18 -0
  83. pz_core/authoring/templates/app/default_jsonc.py +25 -0
  84. pz_core/authoring/templates/app/locales_readme.py +25 -0
  85. pz_core/authoring/templates/app/migrations_readme.py +19 -0
  86. pz_core/authoring/templates/app/models.py +14 -0
  87. pz_core/authoring/templates/app/package_init.py +8 -0
  88. pz_core/authoring/templates/app/pages_base.py +161 -0
  89. pz_core/authoring/templates/app/pages_readme.py +25 -0
  90. pz_core/authoring/templates/app/public.py +31 -0
  91. pz_core/authoring/templates/app/pyproject.py +77 -0
  92. pz_core/authoring/templates/app/readme.py +74 -0
  93. pz_core/authoring/templates/app/settings.py +46 -0
  94. pz_core/authoring/templates/app/static_app_js.py +24 -0
  95. pz_core/authoring/templates/app/static_readme.py +31 -0
  96. pz_core/authoring/templates/app/template_config_page.py +23 -0
  97. pz_core/authoring/templates/app/template_index_html.py +28 -0
  98. pz_core/authoring/templates/app/templates_readme.py +32 -0
  99. pz_core/authoring/templates/app/urls.py +36 -0
  100. pz_core/authoring/templates/app/views.py +36 -0
  101. pz_core/authoring/templates/project/__init__.py +1 -0
  102. pz_core/authoring/templates/project/agents.py +51 -0
  103. pz_core/authoring/templates/project/apps_container_readme.py +37 -0
  104. pz_core/authoring/templates/project/main_py.py +59 -0
  105. pz_core/authoring/templates/project/project_env.py +19 -0
  106. pz_core/authoring/templates/project/pyproject.py +26 -0
  107. pz_core/authoring/templates/project/pz_env_env.py +65 -0
  108. pz_core/authoring/templates/project/pz_env_jsonc.py +69 -0
  109. pz_core/authoring/templates/project/pz_jsonc.py +12 -0
  110. pz_core/authoring/templates/project/readme.py +94 -0
  111. pz_core/authoring/templates/project/root_gitkeep.py +8 -0
  112. pz_core/authoring/templates/shared/__init__.py +5 -0
  113. pz_core/authoring/templates/shared/text.py +10 -0
  114. pz_core/authoring/venv_service.py +87 -0
  115. pz_core/authoring/workspace.py +167 -0
  116. pz_core/cli.py +291 -0
  117. pz_core/cli_options.py +74 -0
  118. pz_core/core/__init__.py +3 -0
  119. pz_core/core/errors/__init__.py +5 -0
  120. pz_core/core/errors/models.py +117 -0
  121. pz_core/core/events/__init__.py +5 -0
  122. pz_core/core/events/registry.py +54 -0
  123. pz_core/core/extensions/__init__.py +51 -0
  124. pz_core/core/extensions/registry.py +790 -0
  125. pz_core/core/health/__init__.py +6 -0
  126. pz_core/core/health/contracts.py +10 -0
  127. pz_core/core/middlewares/__init__.py +6 -0
  128. pz_core/core/middlewares/models.py +24 -0
  129. pz_core/core/routing/__init__.py +5 -0
  130. pz_core/core/routing/models.py +21 -0
  131. pz_core/core/settings_contracts.py +25 -0
  132. pz_core/docs/README.md +20 -0
  133. pz_core/docs/distribution-README.md +438 -0
  134. pz_core/docs/pz/345/221/275/344/273/244/346/200/273/350/247/210.md +1011 -0
  135. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/00-pz/346/236/266/346/236/204/346/200/273/347/272/262.md +240 -0
  136. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/01-/347/233/256/345/275/225/344/270/216/345/210/206/345/261/202/350/247/204/350/214/203.md +216 -0
  137. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/02-/345/214/205/344/270/216/345/210/206/345/217/221/350/247/204/350/214/203.md +403 -0
  138. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/03-App/346/234/200/345/260/217/345/255/220/345/214/205/350/247/204/350/214/203.md +571 -0
  139. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/04-Settings/344/270/216/351/205/215/347/275/256/350/247/204/350/214/203.md +1177 -0
  140. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/05-/350/265/204/346/272/220/344/270/216/350/277/220/350/241/214/347/233/256/345/275/225/350/247/204/350/214/203.md +575 -0
  141. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/06-/346/225/260/346/215/256/345/272/223/344/270/216/345/217/257/351/200/211/345/237/272/347/241/200/350/256/276/346/226/275/350/247/204/350/214/203.md +499 -0
  142. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/07-App/346/233/277/346/215/242/350/247/204/350/214/203.md +206 -0
  143. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/08-/345/271/263/345/217/260/347/272/247App/344/270/216/350/277/220/350/241/214/346/227/266/345/215/225/344/276/213/350/247/204/350/214/203.md +445 -0
  144. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/09-CLI/344/270/216Worker/345/205/245/345/217/243/350/247/204/350/214/203.md +950 -0
  145. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/10-/346/265/213/350/257/225/344/270/216/345/245/221/347/272/246/350/247/204/350/214/203.md +1001 -0
  146. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/11-/344/273/223/345/272/223/347/234/237/347/233/270/346/272/220/345/234/260/345/233/276.md +102 -0
  147. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/12-/346/236/204/345/273/272/344/270/216/345/217/221/345/270/203/346/243/200/346/237/245/346/270/205/345/215/225.md +171 -0
  148. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/13-/346/255/243/345/274/217Facade/346/200/273/350/241/250.md +402 -0
  149. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/14-/345/210/206/345/261/202/344/270/216/346/211/251/345/261/225/350/247/204/350/214/203.md +550 -0
  150. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/15-/345/255/220/345/214/205/345/274/200/345/217/221/344/275/277/347/224/250/346/211/213/345/206/214.md +1004 -0
  151. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/16-/346/211/251/345/261/225/347/202/271/346/255/243/345/274/217/345/215/217/350/256/256/346/270/205/345/215/225.md +352 -0
  152. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/17-pz.protocols.v1/346/255/243/345/274/217/345/215/217/350/256/256.md +266 -0
  153. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/18-/346/211/251/345/261/225/347/202/271/345/206/262/347/252/201/350/243/201/345/206/263/346/200/273/350/241/250.md +131 -0
  154. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/19-/351/224/231/350/257/257/347/240/201/344/270/216/350/257/212/346/226/255/345/215/217/350/256/256.md +176 -0
  155. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/20-/347/247/201/346/234/211/345/214/205/344/273/223/344/270/216/347/273/237/344/270/200/350/256/244/350/257/201/351/203/250/347/275/262/350/247/204/350/214/203.md +243 -0
  156. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/21-contrib/347/272/246/345/256/232/344/270/216Provider/346/216/245/345/205/245/350/247/204/350/214/203.md +365 -0
  157. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/22-/345/244/232/345/233/275/350/257/255/350/250/200/350/265/204/346/272/220/346/262/273/347/220/206/344/270/216/346/214/211/351/234/200/345/212/240/350/275/275/350/247/204/350/214/203.md +912 -0
  158. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/23-/351/246/226/345/261/217/345/261/225/347/244/272/344/270/216/351/246/226/345/270/247/347/250/263/345/256/232/350/247/204/350/214/203.md +269 -0
  159. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/24-pz/345/220/257/345/212/250/344/270/216/350/277/220/350/241/214/346/227/266/347/274/226/350/257/221/346/265/201/347/250/213.md +245 -0
  160. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/25-/351/235/242/345/220/221/345/257/271/350/261/241/345/274/200/345/217/221/350/247/204/350/214/203.md +300 -0
  161. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/README.md +98 -0
  162. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/00-legacy_core/346/240/207/345/207/206pip/345/214/205/345/214/226/351/207/215/346/236/204/346/200/273/347/272/262.md +1073 -0
  163. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/01-/347/233/256/345/275/225/344/270/216/345/210/206/345/261/202/351/207/215/346/236/204/346/211/247/350/241/214/346/226/271/346/241/210.md +224 -0
  164. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/02-/345/214/205/344/270/216/345/210/206/345/217/221/350/247/204/350/214/203-/345/220/253/345/216/206/345/217/262/345/217/243/345/276/204.md +671 -0
  165. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/13-/344/270/200/346/254/241/346/200/247/345/256/236/346/226/275/346/270/205/345/215/225.md +387 -0
  166. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/14-/345/255/220/345/214/205/351/200/202/351/205/215/346/224/271/351/200/240/346/270/205/345/215/225.md +592 -0
  167. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/15-infra/350/243/201/345/211/252/344/270/216/350/220/275/344/275/215/346/270/205/345/215/225.md +81 -0
  168. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/19-core/345/215/225/344/270/200/346/255/243/345/274/217/346/226/271/346/241/210/346/224/266/346/225/233/346/211/247/350/241/214/346/270/205/345/215/225.md +161 -0
  169. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/25-/345/215/217/350/256/256/345/210/260/346/272/220/347/240/201/345/267/256/350/267/235/346/270/205/345/215/225.md +377 -0
  170. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/26-cutover/345/256/214/345/267/245/346/243/200/346/237/245/346/270/205/345/215/225.md +117 -0
  171. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/29-/345/244/232/345/233/275/350/257/255/350/250/200/350/265/204/346/272/220/346/262/273/347/220/206/344/270/216/346/214/211/351/234/200/345/212/240/350/275/275/350/247/204/350/214/203-/345/220/253/350/277/201/347/247/273/347/255/226/347/225/245.md +956 -0
  172. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/99-/350/265/204/346/272/220/346/224/266/345/217/243/345/220/216/347/273/255TODO.md +84 -0
  173. pz_core/docs//345/217/221/347/211/210/345/211/215/346/270/205/345/215/225-4.0.11.md +84 -0
  174. pz_core/docs//346/226/260/346/211/213/346/214/207/345/215/227.md +422 -0
  175. pz_core/infra/__init__.py +17 -0
  176. pz_core/infra/db/__init__.py +23 -0
  177. pz_core/infra/db/contracts.py +73 -0
  178. pz_core/infra/health/__init__.py +5 -0
  179. pz_core/infra/health/contracts.py +8 -0
  180. pz_core/infra/kv/__init__.py +5 -0
  181. pz_core/infra/kv/contracts.py +17 -0
  182. pz_core/infra/observability/__init__.py +23 -0
  183. pz_core/infra/observability/contracts.py +142 -0
  184. pz_core/infra/resilience/__init__.py +5 -0
  185. pz_core/infra/resilience/contracts.py +17 -0
  186. pz_core/infra/resources/__init__.py +5 -0
  187. pz_core/infra/resources/contracts.py +16 -0
  188. pz_core/infra/settings/__init__.py +17 -0
  189. pz_core/infra/settings/models.py +81 -0
  190. pz_core/infra/storage/__init__.py +5 -0
  191. pz_core/infra/storage/ports.py +27 -0
  192. pz_core/project_root_commands.py +282 -0
  193. pz_core/project_runtime_cli.py +344 -0
  194. pz_core/project_sources.py +253 -0
  195. pz_core/pz_launcher.py +209 -0
  196. pz_core/root_cli.py +70 -0
  197. pz_core/runtime/__init__.py +229 -0
  198. pz_core/runtime/access.py +86 -0
  199. pz_core/runtime/adapters/__init__.py +5 -0
  200. pz_core/runtime/adapters/base.py +18 -0
  201. pz_core/runtime/asyncio_bridge.py +18 -0
  202. pz_core/runtime/bindings/__init__.py +5 -0
  203. pz_core/runtime/bindings/container.py +50 -0
  204. pz_core/runtime/cli/__init__.py +5 -0
  205. pz_core/runtime/cli/_args.py +67 -0
  206. pz_core/runtime/cli/app_commands.py +417 -0
  207. pz_core/runtime/cli/check.py +214 -0
  208. pz_core/runtime/cli/db.py +297 -0
  209. pz_core/runtime/cli/main.py +89 -0
  210. pz_core/runtime/cli/resources.py +280 -0
  211. pz_core/runtime/discovery.py +23 -0
  212. pz_core/runtime/environment_integrity.py +157 -0
  213. pz_core/runtime/errors.py +5 -0
  214. pz_core/runtime/events.py +87 -0
  215. pz_core/runtime/facades/__init__.py +38 -0
  216. pz_core/runtime/facades/_capabilities.py +46 -0
  217. pz_core/runtime/facades/cache.py +103 -0
  218. pz_core/runtime/facades/database.py +71 -0
  219. pz_core/runtime/facades/events.py +380 -0
  220. pz_core/runtime/facades/health.py +101 -0
  221. pz_core/runtime/facades/mail.py +121 -0
  222. pz_core/runtime/facades/observability.py +102 -0
  223. pz_core/runtime/facades/providers.py +75 -0
  224. pz_core/runtime/facades/resources.py +52 -0
  225. pz_core/runtime/facades/storage.py +296 -0
  226. pz_core/runtime/health/__init__.py +5 -0
  227. pz_core/runtime/health/service.py +102 -0
  228. pz_core/runtime/host.py +188 -0
  229. pz_core/runtime/host_runner.py +282 -0
  230. pz_core/runtime/http/__init__.py +20 -0
  231. pz_core/runtime/http/app.py +576 -0
  232. pz_core/runtime/http_timing.py +173 -0
  233. pz_core/runtime/invocation.py +29 -0
  234. pz_core/runtime/json_safe.py +47 -0
  235. pz_core/runtime/lifecycle/__init__.py +25 -0
  236. pz_core/runtime/lifecycle/manager.py +533 -0
  237. pz_core/runtime/plan.py +214 -0
  238. pz_core/runtime/plan_context.py +33 -0
  239. pz_core/runtime/plan_snapshot.py +177 -0
  240. pz_core/runtime/registries/__init__.py +27 -0
  241. pz_core/runtime/registries/capabilities.py +101 -0
  242. pz_core/runtime/registries/providers.py +396 -0
  243. pz_core/runtime/resource_assets.py +344 -0
  244. pz_core/runtime/run_cli.py +211 -0
  245. pz_core/runtime/settings.py +888 -0
  246. pz_core/runtime/worker/__init__.py +21 -0
  247. pz_core/runtime/worker/engine.py +921 -0
  248. pz_core/runtime/worker/runtime.py +25 -0
  249. pz_core/testing/__init__.py +15 -0
  250. pz_core/testing/doc_route_contracts.py +305 -0
  251. pz_core/utils/__init__.py +44 -0
  252. pz_core/utils/env.py +65 -0
  253. pz_core/utils/project_jsonc/__init__.py +29 -0
  254. pz_core/utils/project_jsonc/document.py +420 -0
  255. pz_core/utils/project_settings.py +99 -0
  256. pz_foundation/__init__.py +50 -0
  257. pz_foundation/_contracts.py +81 -0
  258. pz_foundation/_errors.py +34 -0
  259. pz_foundation/api.py +14 -0
  260. pz_foundation/apps.py +127 -0
  261. pz_foundation/auth/__init__.py +1 -0
  262. pz_foundation/cache_control.py +233 -0
  263. pz_foundation/cli/__init__.py +2 -0
  264. pz_foundation/cli/workers.py +565 -0
  265. pz_foundation/configs/__init__.py +0 -0
  266. pz_foundation/configs/default.env +15 -0
  267. pz_foundation/configs/default.jsonc +452 -0
  268. pz_foundation/db/__init__.py +94 -0
  269. pz_foundation/db/aerich_executor.py +664 -0
  270. pz_foundation/db/config.py +358 -0
  271. pz_foundation/db/connection_manager.py +689 -0
  272. pz_foundation/db/connection_probe.py +204 -0
  273. pz_foundation/db/database.py +1291 -0
  274. pz_foundation/db/deps.py +47 -0
  275. pz_foundation/db/lifecycle_status.py +85 -0
  276. pz_foundation/db/migrations.py +477 -0
  277. pz_foundation/db/mysql.py +57 -0
  278. pz_foundation/db/postgresql.py +409 -0
  279. pz_foundation/db/production_pool_fallback.py +143 -0
  280. pz_foundation/db/public.py +45 -0
  281. pz_foundation/db/session.py +369 -0
  282. pz_foundation/db/sqlite.py +15 -0
  283. pz_foundation/db/tortoise_manager.py +724 -0
  284. pz_foundation/db/tortoise_psycopg.py +148 -0
  285. pz_foundation/docs/README.md +18 -0
  286. pz_foundation/docs/distribution-README.md +319 -0
  287. pz_foundation/docs/infra/350/243/201/345/211/252/344/270/216/350/220/275/344/275/215/350/257/264/346/230/216.md +39 -0
  288. pz_foundation/docs//345/205/254/345/274/200/345/205/215/350/264/271/346/216/245/345/217/243/351/230/262/346/273/245/347/224/250/344/270/216/344/272/272/346/234/272/346/240/241/351/252/214.md +680 -0
  289. pz_foundation/docs//350/256/276/350/256/241/346/226/207/346/241/243.md +288 -0
  290. pz_foundation/docs//350/267/257/347/224/261/344/270/216URL/345/244/204/347/220/206/350/247/204/350/214/203.md +119 -0
  291. pz_foundation/health.py +105 -0
  292. pz_foundation/host/__init__.py +11 -0
  293. pz_foundation/host/builder.py +34 -0
  294. pz_foundation/host/cache_runtime.py +44 -0
  295. pz_foundation/host/db/__init__.py +17 -0
  296. pz_foundation/host/db/aerich_config.py +36 -0
  297. pz_foundation/host/db/config.py +106 -0
  298. pz_foundation/host/db/connection_manager.py +48 -0
  299. pz_foundation/host/db/deps.py +5 -0
  300. pz_foundation/host/db/orm_retry_patch.py +566 -0
  301. pz_foundation/host/db/request_adapter.py +325 -0
  302. pz_foundation/host/db/router.py +28 -0
  303. pz_foundation/host/db/session.py +284 -0
  304. pz_foundation/host/db/tortoise_manager.py +10 -0
  305. pz_foundation/host/idempotency.py +132 -0
  306. pz_foundation/host/lifespan.py +247 -0
  307. pz_foundation/host/redis_runtime.py +100 -0
  308. pz_foundation/host/web.py +790 -0
  309. pz_foundation/infra_provider.py +236 -0
  310. pz_foundation/kv/__init__.py +25 -0
  311. pz_foundation/kv/cache.py +1166 -0
  312. pz_foundation/kv/deps.py +84 -0
  313. pz_foundation/kv/public.py +25 -0
  314. pz_foundation/kv/redis_manager.py +1531 -0
  315. pz_foundation/lazy_exports.py +43 -0
  316. pz_foundation/lazy_imports.py +124 -0
  317. pz_foundation/lifecycle.py +392 -0
  318. pz_foundation/managed_workers.py +1117 -0
  319. pz_foundation/middlewares/__init__.py +26 -0
  320. pz_foundation/middlewares/_settings.py +250 -0
  321. pz_foundation/middlewares/analytics.py +124 -0
  322. pz_foundation/middlewares/cache_control.py +156 -0
  323. pz_foundation/middlewares/compression.py +202 -0
  324. pz_foundation/middlewares/cors.py +62 -0
  325. pz_foundation/middlewares/geo_country.py +44 -0
  326. pz_foundation/middlewares/inner_router.py +50 -0
  327. pz_foundation/middlewares/rate_limited/__init__.py +3 -0
  328. pz_foundation/middlewares/rate_limited/key_limiter.py +115 -0
  329. pz_foundation/middlewares/request_logging.py +104 -0
  330. pz_foundation/middlewares/route_owner.py +309 -0
  331. pz_foundation/middlewares/security_csrf.py +44 -0
  332. pz_foundation/middlewares/security_headers/__init__.py +4 -0
  333. pz_foundation/middlewares/security_headers/conflicts.py +44 -0
  334. pz_foundation/middlewares/security_headers/csp_nonce.py +200 -0
  335. pz_foundation/middlewares/security_headers/security_headers.py +44 -0
  336. pz_foundation/migrations/__init__.py +1 -0
  337. pz_foundation/migrations/pz_foundation/__init__.py +1 -0
  338. pz_foundation/models.py +22 -0
  339. pz_foundation/notifications/__init__.py +23 -0
  340. pz_foundation/notifications/email.py +542 -0
  341. pz_foundation/notifications/public.py +31 -0
  342. pz_foundation/observability/__init__.py +71 -0
  343. pz_foundation/observability/http.py +34 -0
  344. pz_foundation/observability/logger/__init__.py +49 -0
  345. pz_foundation/observability/logger/_bot_settings.py +126 -0
  346. pz_foundation/observability/logger/bot_message.py +592 -0
  347. pz_foundation/observability/logger/core.py +385 -0
  348. pz_foundation/observability/logger/delivery_audit.py +84 -0
  349. pz_foundation/observability/logger/feishu_bot.py +199 -0
  350. pz_foundation/observability/logger/telegram_bot.py +194 -0
  351. pz_foundation/observability/metrics.py +365 -0
  352. pz_foundation/observability/runtime.py +68 -0
  353. pz_foundation/public.py +405 -0
  354. pz_foundation/resources/__init__.py +12 -0
  355. pz_foundation/resources/builder.py +900 -0
  356. pz_foundation/resources/images.py +363 -0
  357. pz_foundation/root_cli.py +20 -0
  358. pz_foundation/routing/__init__.py +203 -0
  359. pz_foundation/routing/canonical.py +486 -0
  360. pz_foundation/routing/convertors.py +82 -0
  361. pz_foundation/routing/declarations.py +843 -0
  362. pz_foundation/routing/exports.py +148 -0
  363. pz_foundation/routing/loaders.py +138 -0
  364. pz_foundation/routing/manifest.py +215 -0
  365. pz_foundation/routing/manifest_provider.py +47 -0
  366. pz_foundation/routing/mounts.py +101 -0
  367. pz_foundation/routing/ordering.py +172 -0
  368. pz_foundation/routing/registry.py +133 -0
  369. pz_foundation/routing/utils.py +28 -0
  370. pz_foundation/runtime.py +234 -0
  371. pz_foundation/settings.py +253 -0
  372. pz_foundation/settings_normalization.py +130 -0
  373. pz_foundation/storage/__init__.py +25 -0
  374. pz_foundation/storage/local.py +209 -0
  375. pz_foundation/storage/public.py +106 -0
  376. pz_foundation/storage/s3.py +116 -0
  377. pz_foundation/storage/service.py +234 -0
  378. pz_foundation/urls.py +19 -0
  379. pz_foundation/utils/__init__.py +6 -0
  380. pz_foundation/utils/merge.py +160 -0
  381. pz_foundation/worker_replicas.py +55 -0
  382. pz_settings_center/__init__.py +5 -0
  383. pz_settings_center/api/__init__.py +5 -0
  384. pz_settings_center/api/runtime_overrides.py +360 -0
  385. pz_settings_center/apps.py +28 -0
  386. pz_settings_center/configs/__init__.py +0 -0
  387. pz_settings_center/configs/default.env +2 -0
  388. pz_settings_center/configs/default.jsonc +1 -0
  389. pz_settings_center/docs/01-settings_center/350/203/275/345/212/233/350/276/271/347/225/214.md +124 -0
  390. pz_settings_center/docs/README.md +12 -0
  391. pz_settings_center/docs/distribution-README.md +150 -0
  392. pz_settings_center/docs//350/256/276/350/256/241/346/226/207/346/241/243.md +48 -0
  393. pz_settings_center/integration_payload.py +18 -0
  394. pz_settings_center/project_helpers.py +405 -0
  395. pz_settings_center/public.py +139 -0
  396. pz_settings_center/routing_helpers.py +73 -0
  397. pz_settings_center/runtime_override_provider.py +61 -0
  398. pz_settings_center/typed_settings.py +324 -0
  399. pz_settings_center/urls.py +9 -0
@@ -0,0 +1,47 @@
1
+ from __future__ import annotations
2
+
3
+ from contextlib import asynccontextmanager
4
+ from typing import Any
5
+
6
+ from fastapi import Depends
7
+
8
+ from .config import build_foundation_tortoise_config
9
+ from .tortoise_manager import tortoise_manager
10
+
11
+ try:
12
+ from tortoise import Tortoise
13
+ except Exception: # pragma: no cover
14
+ Tortoise = Any # type: ignore[assignment]
15
+
16
+
17
+ def get_db_config(request: Any = None) -> dict[str, Any]:
18
+ del request
19
+ return build_foundation_tortoise_config()
20
+
21
+
22
+ async def ensure_db(request: Any = None):
23
+ del request
24
+ await tortoise_manager.ensure_initialized(
25
+ config_builder=build_foundation_tortoise_config,
26
+ cluster_factory=lambda: None,
27
+ )
28
+ return Tortoise
29
+
30
+
31
+ @asynccontextmanager
32
+ async def get_read_tx(_: Any = Depends(ensure_db)):
33
+ from .session import read_transaction
34
+
35
+ async with read_transaction() as tx:
36
+ yield tx
37
+
38
+
39
+ @asynccontextmanager
40
+ async def get_write_tx(_: Any = Depends(ensure_db)):
41
+ from .session import write_transaction
42
+
43
+ async with write_transaction() as tx:
44
+ yield tx
45
+
46
+
47
+ __all__ = ["ensure_db", "get_db_config", "get_read_tx", "get_write_tx"]
@@ -0,0 +1,85 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Any
5
+
6
+
7
+ @dataclass(frozen=True, slots=True)
8
+ class DBConnectionLifecycleStatus:
9
+ initialized: bool
10
+ loop_matches: bool
11
+ default_configured: bool
12
+ default_open: bool
13
+ read_only_configured: bool
14
+ read_only_open: bool
15
+
16
+ @property
17
+ def default_ready(self) -> bool:
18
+ return self.initialized and self.loop_matches and self.default_configured and self.default_open
19
+
20
+ @property
21
+ def read_only_ready(self) -> bool:
22
+ return self.initialized and self.loop_matches and self.read_only_configured and self.read_only_open
23
+
24
+ def alias_status(self, alias: str) -> str:
25
+ configured = self.default_configured if alias == "default" else self.read_only_configured
26
+ open_ = self.default_open if alias == "default" else self.read_only_open
27
+ if not self.initialized:
28
+ return "not_initialized"
29
+ if not configured:
30
+ return "not_configured"
31
+ if not self.loop_matches:
32
+ return "loop_mismatch"
33
+ if not open_:
34
+ return "closed"
35
+ return "ok"
36
+
37
+
38
+ def connection_lifecycle_status(tortoise_manager: Any) -> DBConnectionLifecycleStatus:
39
+ initialized = bool(getattr(tortoise_manager, "_initialized", False))
40
+ loop_matches = _loop_matches(tortoise_manager)
41
+ default_configured, default_open = _alias_status(tortoise_manager, "default")
42
+ read_only_configured, read_only_open = _alias_status(tortoise_manager, "read_only")
43
+ return DBConnectionLifecycleStatus(
44
+ initialized=initialized,
45
+ loop_matches=loop_matches,
46
+ default_configured=default_configured,
47
+ default_open=default_open,
48
+ read_only_configured=read_only_configured,
49
+ read_only_open=read_only_open,
50
+ )
51
+
52
+
53
+ def _loop_matches(tortoise_manager: Any) -> bool:
54
+ try:
55
+ current_loop_id_getter = getattr(tortoise_manager, "_current_loop_id", None)
56
+ current_loop_id = current_loop_id_getter() if callable(current_loop_id_getter) else None
57
+ manager_loop_id = getattr(tortoise_manager, "_loop_id", None)
58
+ return not (current_loop_id is not None and manager_loop_id is not None and current_loop_id != manager_loop_id)
59
+ except Exception:
60
+ return False
61
+
62
+
63
+ def _alias_status(tortoise_manager: Any, alias: str) -> tuple[bool, bool]:
64
+ try:
65
+ has_connection = getattr(tortoise_manager, "has_connection", None)
66
+ if callable(has_connection) and not bool(has_connection(alias)):
67
+ return False, False
68
+ conn = tortoise_manager.get_connection(alias)
69
+ except Exception:
70
+ return False, False
71
+ pool_ready = getattr(tortoise_manager, "_connection_pool_ready", None)
72
+ if callable(pool_ready):
73
+ try:
74
+ return True, bool(pool_ready(alias))
75
+ except Exception:
76
+ return True, False
77
+ return True, not _is_connection_closed(conn)
78
+
79
+
80
+ def _is_connection_closed(conn: Any) -> bool:
81
+ pool = getattr(conn, "_pool", None)
82
+ return bool(getattr(pool, "closed", False))
83
+
84
+
85
+ __all__ = ["DBConnectionLifecycleStatus", "connection_lifecycle_status"]
@@ -0,0 +1,477 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import asdict
4
+ from datetime import UTC, datetime
5
+ from importlib import import_module
6
+ from importlib.util import find_spec
7
+ import json
8
+ from pathlib import Path
9
+ import pkgutil
10
+ import shutil
11
+ from typing import Any, Protocol
12
+ from uuid import uuid4
13
+
14
+ from .._contracts import DatabaseMigrationSnapshot, DbOwner, MigrationSource
15
+ from .._errors import FoundationError
16
+
17
+
18
+ class DbExecutor(Protocol):
19
+ def __call__(
20
+ self,
21
+ *,
22
+ action: str,
23
+ plan: Any,
24
+ workspace_dir: Path,
25
+ manifest_path: Path,
26
+ orm_config_path: Path,
27
+ lock_path: Path,
28
+ migration_sources: tuple[MigrationSource, ...],
29
+ ) -> dict[str, Any] | None: ...
30
+
31
+
32
+ def _read_db_module_path(module_path: object, *, action: str) -> str:
33
+ if not isinstance(module_path, str) or not module_path.strip():
34
+ raise FoundationError(
35
+ code="PZ_DB_APP_MODULE_PATH_INVALID",
36
+ message="Database migration source must declare a non-empty string app module path.",
37
+ stage="db",
38
+ owner="infra.database",
39
+ action=action,
40
+ )
41
+ return module_path.strip()
42
+
43
+
44
+ def _read_executor_path(raw: object, *, action: str) -> str:
45
+ if not isinstance(raw, str) or not raw.strip():
46
+ raise FoundationError(
47
+ code="PZ_DB_EXECUTOR_INVALID",
48
+ message="database.migration_executor must declare a non-empty '<module>:<callable>' string.",
49
+ stage="db",
50
+ owner="infra.database",
51
+ action=action,
52
+ )
53
+ return raw.strip()
54
+
55
+
56
+ def db_workspace(plan: Any) -> Path:
57
+ return plan.project.cache_dir / "migrations"
58
+
59
+
60
+ def workspace_manifest_path(plan: Any) -> Path:
61
+ return db_workspace(plan) / "manifest.json"
62
+
63
+
64
+ def orm_config_path(plan: Any) -> Path:
65
+ return db_workspace(plan) / "orm_config.json"
66
+
67
+
68
+ def lock_path(plan: Any) -> Path:
69
+ return plan.project.runtime_dir / "locks" / "migrations.lock"
70
+
71
+
72
+ def execution_log_path(plan: Any) -> Path:
73
+ return db_workspace(plan) / "execution-log.json"
74
+
75
+
76
+ def migration_owners(plan: Any) -> tuple[DbOwner, ...]:
77
+ return tuple(
78
+ DbOwner(app_id=app.app_id, module_path=app.module_path, owner=app.app_id)
79
+ for app in plan.app_registry.apps
80
+ )
81
+
82
+
83
+ def module_root(module_path: str) -> Path:
84
+ module_name = _read_db_module_path(
85
+ module_path,
86
+ action="compile_migration_workspace",
87
+ ).split(":", 1)[0]
88
+ if module_name.endswith(".apps"):
89
+ module_name = module_name[:-5]
90
+ spec = find_spec(module_name)
91
+ if spec is None:
92
+ raise FoundationError(
93
+ code="PZ_DB_APP_PACKAGE_NOT_FOUND",
94
+ message=f"Cannot resolve app package '{module_name}' for migrations.",
95
+ stage="db",
96
+ owner=module_name or "db",
97
+ action="compile_migration_workspace",
98
+ )
99
+ if spec.submodule_search_locations:
100
+ return Path(next(iter(spec.submodule_search_locations))).resolve()
101
+ if spec.origin:
102
+ return Path(spec.origin).resolve().parent
103
+ raise FoundationError(
104
+ code="PZ_DB_APP_PACKAGE_NOT_FOUND",
105
+ message=f"Cannot resolve app package root '{module_name}' for migrations.",
106
+ stage="db",
107
+ owner=module_name or "db",
108
+ action="compile_migration_workspace",
109
+ )
110
+
111
+
112
+ def _models_module(module_path: str) -> str | None:
113
+ module_name = _read_db_module_path(
114
+ module_path,
115
+ action="compile_migration_workspace",
116
+ ).split(":", 1)[0]
117
+ candidate = f"{module_name}.models"
118
+ if find_spec(candidate) is None:
119
+ return None
120
+ if _module_declares_database_models(candidate):
121
+ return candidate
122
+ for discovered in _iter_model_submodules(candidate):
123
+ if _module_declares_database_models(discovered):
124
+ return discovered
125
+ return None
126
+
127
+
128
+ def _iter_model_submodules(module_name: str) -> tuple[str, ...]:
129
+ try:
130
+ module = import_module(module_name)
131
+ except Exception:
132
+ return ()
133
+ package_path = getattr(module, "__path__", None)
134
+ if package_path is None:
135
+ return ()
136
+ return tuple(child.name for child in pkgutil.walk_packages(package_path, prefix=f"{module_name}."))
137
+
138
+
139
+ def _module_declares_database_models(module_name: str) -> bool:
140
+ try:
141
+ module = import_module(module_name)
142
+ except Exception:
143
+ return False
144
+ try:
145
+ from tortoise.models import Model as TortoiseModel # type: ignore
146
+ except Exception:
147
+ TortoiseModel = None # type: ignore[assignment]
148
+ for name, obj in vars(module).items():
149
+ if not isinstance(obj, type):
150
+ continue
151
+ if getattr(obj, "__module__", "") != module_name:
152
+ continue
153
+ if TortoiseModel is not None:
154
+ try:
155
+ if issubclass(obj, TortoiseModel) and obj is not TortoiseModel:
156
+ meta = getattr(obj, "Meta", None)
157
+ if not getattr(meta, "abstract", False):
158
+ return True
159
+ except Exception:
160
+ pass
161
+ return False
162
+
163
+
164
+ def migration_sources(plan: Any) -> tuple[MigrationSource, ...]:
165
+ sources: list[MigrationSource] = []
166
+ for app in plan.app_registry.apps:
167
+ package_root = module_root(app.module_path)
168
+ migrations_root = package_root / "migrations"
169
+ owner_dir = migrations_root / app.app_id
170
+ models_module = _models_module(app.module_path)
171
+ files: tuple[str, ...] = ()
172
+ if owner_dir.is_dir():
173
+ files = tuple(
174
+ str(path.relative_to(owner_dir))
175
+ for path in sorted(owner_dir.rglob("*"))
176
+ if path.is_file()
177
+ and "__pycache__" not in path.relative_to(owner_dir).parts
178
+ and path.suffix != ".pyc"
179
+ )
180
+ if models_module is None and not owner_dir.is_dir():
181
+ continue
182
+ if models_module and not owner_dir.is_dir():
183
+ raise FoundationError(
184
+ code="PZ_DB_MIGRATIONS_MISSING",
185
+ message=(
186
+ f"App '{app.app_id}' exposes models via '{models_module}' but is missing "
187
+ f"migrations/{app.app_id}/."
188
+ ),
189
+ stage="db",
190
+ owner=app.app_id,
191
+ action="compile_migration_workspace",
192
+ )
193
+ if models_module is None and not tuple(item for item in files if item != "__init__.py"):
194
+ continue
195
+ sources.append(
196
+ MigrationSource(
197
+ app_id=app.app_id,
198
+ owner=app.app_id,
199
+ module_path=app.module_path,
200
+ version=app.version,
201
+ package_root=str(package_root),
202
+ migrations_dir=str(owner_dir),
203
+ models_module=models_module,
204
+ files=files,
205
+ )
206
+ )
207
+ return tuple(sources)
208
+
209
+
210
+ def history_entries(sources: tuple[MigrationSource, ...]) -> dict[str, tuple[str, ...]]:
211
+ return {source.owner: source.files for source in sources}
212
+
213
+
214
+ def write_migration_workspace(
215
+ plan: Any,
216
+ *,
217
+ action: str,
218
+ ) -> tuple[Path, Path, tuple[MigrationSource, ...]]:
219
+ workspace = db_workspace(plan)
220
+ workspace.mkdir(parents=True, exist_ok=True)
221
+ lock_path(plan).parent.mkdir(parents=True, exist_ok=True)
222
+ lock_path(plan).write_text(f"{action}\n", encoding="utf-8")
223
+ sources = migration_sources(plan)
224
+ staging_dir = workspace / f".staging-{uuid4().hex}"
225
+ if staging_dir.exists():
226
+ shutil.rmtree(staging_dir)
227
+ staging_dir.mkdir(parents=True, exist_ok=True)
228
+ owners_dir = staging_dir / "owners"
229
+ owners_dir.mkdir()
230
+ for source in sources:
231
+ source_dir = Path(source.migrations_dir)
232
+ target_dir = owners_dir / source.owner
233
+ if source_dir.is_dir():
234
+ shutil.copytree(source_dir, target_dir)
235
+ else:
236
+ target_dir.mkdir(parents=True, exist_ok=True)
237
+ final_owners_dir = workspace / "owners"
238
+ backup_dir = workspace / ".owners-backup"
239
+ if backup_dir.exists():
240
+ shutil.rmtree(backup_dir)
241
+ if final_owners_dir.exists():
242
+ final_owners_dir.replace(backup_dir)
243
+ owners_dir.replace(final_owners_dir)
244
+ shutil.rmtree(staging_dir, ignore_errors=True)
245
+ shutil.rmtree(backup_dir, ignore_errors=True)
246
+
247
+ orm_models = [source.models_module for source in sources if source.models_module]
248
+ orm_path = orm_config_path(plan)
249
+ orm_path.write_text(
250
+ json.dumps(
251
+ {
252
+ "generated_at": datetime.now(UTC).isoformat(),
253
+ "project_dir": str(plan.project.project_dir),
254
+ "database": {
255
+ "driver": plan.infra.database.get("driver", ""),
256
+ },
257
+ "apps": [source.app_id for source in sources],
258
+ "models": orm_models,
259
+ },
260
+ ensure_ascii=True,
261
+ indent=2,
262
+ sort_keys=True,
263
+ )
264
+ + "\n",
265
+ encoding="utf-8",
266
+ )
267
+ manifest_path = workspace_manifest_path(plan)
268
+ payload = {
269
+ "generated_at": datetime.now(UTC).isoformat(),
270
+ "project_dir": str(plan.project.project_dir),
271
+ "workspace_dir": str(workspace),
272
+ "action": action,
273
+ "lock_path": str(lock_path(plan)),
274
+ "orm_config_path": str(orm_path),
275
+ "database": {
276
+ "enabled": plan.infra.database.enabled,
277
+ "driver": plan.infra.database.get("driver", ""),
278
+ },
279
+ "migration_owners": [asdict(item) for item in migration_owners(plan)],
280
+ "migration_sources": [asdict(item) for item in sources],
281
+ "history_entries": history_entries(sources),
282
+ }
283
+ manifest_path.write_text(
284
+ json.dumps(payload, ensure_ascii=True, indent=2, sort_keys=True) + "\n",
285
+ encoding="utf-8",
286
+ )
287
+ return manifest_path, orm_path, sources
288
+
289
+
290
+ def require_database(plan: Any, *, action: str) -> None:
291
+ if not plan.infra.database.enabled:
292
+ raise FoundationError(
293
+ code="PZ_DB_DISABLED",
294
+ message="Database capability is disabled for the current project.",
295
+ stage="db",
296
+ owner="infra.database",
297
+ action=action,
298
+ )
299
+ if not str(plan.infra.database.get("driver", "") or "").strip():
300
+ raise FoundationError(
301
+ code="PZ_DB_DRIVER_MISSING",
302
+ message="Database capability is enabled but driver is empty.",
303
+ stage="db",
304
+ owner="infra.database",
305
+ action=action,
306
+ )
307
+
308
+
309
+ def load_migration_executor(plan: Any, *, action: str) -> DbExecutor:
310
+ migration_executor = plan.infra.database.get("migration_executor", "")
311
+ if migration_executor in (None, ""):
312
+ raise FoundationError(
313
+ code="PZ_DB_EXECUTOR_MISSING",
314
+ message=f"Database command '{action}' requires an explicit database.migration_executor.",
315
+ stage="db",
316
+ owner="infra.database",
317
+ action=action,
318
+ )
319
+ executor_path = _read_executor_path(
320
+ migration_executor,
321
+ action=action,
322
+ )
323
+ module_name, _, attr_name = executor_path.partition(":")
324
+ if not module_name or not attr_name:
325
+ raise FoundationError(
326
+ code="PZ_DB_EXECUTOR_INVALID",
327
+ message="database.migration_executor must use '<module>:<callable>' format.",
328
+ stage="db",
329
+ owner="infra.database",
330
+ action=action,
331
+ )
332
+ try:
333
+ module = import_module(module_name)
334
+ executor = getattr(module, attr_name)
335
+ except Exception as exc:
336
+ raise FoundationError(
337
+ code="PZ_DB_EXECUTOR_IMPORT_FAILED",
338
+ message=f"Failed to import migration executor '{executor_path}': {exc}",
339
+ stage="db",
340
+ owner="infra.database",
341
+ action=action,
342
+ ) from exc
343
+ if not callable(executor):
344
+ raise FoundationError(
345
+ code="PZ_DB_EXECUTOR_INVALID",
346
+ message=f"Migration executor '{executor_path}' is not callable.",
347
+ stage="db",
348
+ owner="infra.database",
349
+ action=action,
350
+ )
351
+ return executor
352
+
353
+
354
+ def write_execution_log(
355
+ plan: Any,
356
+ *,
357
+ action: str,
358
+ execution_result: dict[str, Any] | None,
359
+ ) -> Path:
360
+ path = execution_log_path(plan)
361
+ path.write_text(
362
+ json.dumps(
363
+ {
364
+ "action": action,
365
+ "generated_at": datetime.now(UTC).isoformat(),
366
+ "project_dir": str(plan.project.project_dir),
367
+ "executor": plan.infra.database.get("migration_executor", ""),
368
+ "result": execution_result,
369
+ },
370
+ ensure_ascii=True,
371
+ indent=2,
372
+ sort_keys=True,
373
+ )
374
+ + "\n",
375
+ encoding="utf-8",
376
+ )
377
+ return path
378
+
379
+
380
+ def run_migration_executor(
381
+ plan: Any,
382
+ *,
383
+ action: str,
384
+ sources: tuple[MigrationSource, ...],
385
+ ) -> dict[str, Any] | None:
386
+ executor = load_migration_executor(plan, action=action)
387
+ try:
388
+ result = executor(
389
+ action=action,
390
+ plan=plan,
391
+ workspace_dir=db_workspace(plan),
392
+ manifest_path=workspace_manifest_path(plan),
393
+ orm_config_path=orm_config_path(plan),
394
+ lock_path=lock_path(plan),
395
+ migration_sources=sources,
396
+ )
397
+ except FoundationError:
398
+ raise
399
+ except Exception as exc:
400
+ raise FoundationError(
401
+ code="PZ_DB_EXECUTOR_FAILED",
402
+ message=f"Database executor failed for '{action}': {exc}",
403
+ stage="db",
404
+ owner="infra.database",
405
+ action=action,
406
+ ) from exc
407
+ if result is not None and not isinstance(result, dict):
408
+ raise FoundationError(
409
+ code="PZ_DB_EXECUTOR_RESULT_INVALID",
410
+ message="Database executor must return a dict or None.",
411
+ stage="db",
412
+ owner="infra.database",
413
+ action=action,
414
+ )
415
+ write_execution_log(plan, action=action, execution_result=result)
416
+ return result
417
+
418
+
419
+ def _snapshot(plan: Any) -> DatabaseMigrationSnapshot:
420
+ sources = migration_sources(plan)
421
+ return DatabaseMigrationSnapshot(
422
+ workspace_dir=db_workspace(plan),
423
+ manifest_path=workspace_manifest_path(plan),
424
+ orm_config_path=orm_config_path(plan),
425
+ lock_path=lock_path(plan),
426
+ database_enabled=plan.infra.database.enabled,
427
+ database_driver=plan.infra.database.get("driver", ""),
428
+ migration_executor=plan.infra.database.get("migration_executor", "") or None,
429
+ migration_owners=migration_owners(plan),
430
+ migration_sources=sources,
431
+ history_entries=history_entries(sources),
432
+ )
433
+
434
+
435
+ class FoundationDatabaseMigrationRuntime:
436
+ def __init__(self, plan: Any) -> None:
437
+ self._plan = plan
438
+
439
+ def status(self) -> DatabaseMigrationSnapshot:
440
+ require_database(self._plan, action="status")
441
+ return _snapshot(self._plan)
442
+
443
+ def prepare(self, *, action: str) -> DatabaseMigrationSnapshot:
444
+ require_database(self._plan, action=action)
445
+ write_migration_workspace(self._plan, action=action)
446
+ return _snapshot(self._plan)
447
+
448
+ def execute(self, *, action: str) -> tuple[DatabaseMigrationSnapshot, dict[str, Any] | None]:
449
+ require_database(self._plan, action=action)
450
+ _, _, sources = write_migration_workspace(self._plan, action=action)
451
+ execution_result = run_migration_executor(self._plan, action=action, sources=sources)
452
+ return _snapshot(self._plan), execution_result
453
+
454
+
455
+ def build_migration_provider(context):
456
+ return FoundationDatabaseMigrationRuntime(context.plan)
457
+
458
+
459
+ __all__ = [
460
+ "DbExecutor",
461
+ "FoundationDatabaseMigrationRuntime",
462
+ "build_migration_provider",
463
+ "db_workspace",
464
+ "execution_log_path",
465
+ "history_entries",
466
+ "load_migration_executor",
467
+ "lock_path",
468
+ "migration_owners",
469
+ "migration_sources",
470
+ "module_root",
471
+ "orm_config_path",
472
+ "require_database",
473
+ "run_migration_executor",
474
+ "workspace_manifest_path",
475
+ "write_execution_log",
476
+ "write_migration_workspace",
477
+ ]
@@ -0,0 +1,57 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any
4
+
5
+
6
+ def _pool_credentials(settings) -> dict[str, Any]:
7
+ minsize = max(1, int(getattr(settings, "db_min_size", 2) or 1))
8
+ maxsize = max(minsize, int(getattr(settings, "db_max_size", 10) or minsize))
9
+ creds: dict[str, Any] = {"minsize": minsize, "maxsize": maxsize}
10
+ try:
11
+ timeout = float(getattr(settings, "db_connection_timeout", 0) or 0)
12
+ except Exception:
13
+ timeout = 0
14
+ if timeout > 0:
15
+ creds["connect_timeout"] = timeout
16
+ return creds
17
+
18
+
19
+ def _split_hosts_ports(settings) -> tuple[list[str], list[str]]:
20
+ hosts = [h.strip() for h in str(getattr(settings, "db_host", "") or "").split(",") if h.strip()]
21
+ ports = [p.strip() for p in str(getattr(settings, "db_port", "") or "").split(",") if p.strip()]
22
+ if not hosts:
23
+ raise ValueError("foundation mysql host is not configured")
24
+ if not ports:
25
+ ports = [str(getattr(settings, "db_port", 3306) or 3306)]
26
+ if len(ports) < len(hosts):
27
+ ports = [ports[0]] * len(hosts)
28
+ return hosts, ports
29
+
30
+
31
+ def build_mysql_connections(settings) -> dict[str, Any]:
32
+ hosts, ports = _split_hosts_ports(settings)
33
+ base = {
34
+ "engine": "tortoise.backends.mysql",
35
+ "credentials": {
36
+ "host": hosts[0],
37
+ "port": int(ports[0] or 3306),
38
+ "user": getattr(settings, "db_user", ""),
39
+ "password": getattr(settings, "db_password", ""),
40
+ "database": getattr(settings, "db_name", ""),
41
+ **_pool_credentials(settings),
42
+ },
43
+ }
44
+ out: dict[str, Any] = {"default": base}
45
+ if len(hosts) >= 2:
46
+ out["read_only"] = {
47
+ "engine": "tortoise.backends.mysql",
48
+ "credentials": {
49
+ **base["credentials"],
50
+ "host": hosts[1],
51
+ "port": int(ports[1] or ports[0] or 3306),
52
+ },
53
+ }
54
+ return out
55
+
56
+
57
+ __all__ = ["build_mysql_connections"]