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,106 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Any
5
+
6
+ from fastapi import Request
7
+
8
+ from ..runtime import require_runtime_bindings
9
+
10
+
11
+ class StorageFacade:
12
+ pass
13
+
14
+
15
+ @dataclass(slots=True)
16
+ class RuntimePresignInfo:
17
+ method: str
18
+ url: str
19
+ expires: int | None = None
20
+ headers: dict[str, str] | None = None
21
+ fields: dict[str, str] | None = None
22
+
23
+
24
+ @dataclass(slots=True)
25
+ class RuntimeStoredObject:
26
+ path: str
27
+ size: int | None = None
28
+ content_type: str | None = None
29
+
30
+
31
+ class StorageClient:
32
+ def __init__(self, namespace: str | None = None, *, request: Any | None = None) -> None:
33
+ self.namespace = namespace
34
+ self._storage = require_runtime_bindings(request=request).storage
35
+
36
+ def open(self, key: str, *, mode: str = "rb"):
37
+ return self._storage.open(key, mode=mode)
38
+
39
+ def save(self, key: str, payload: Any, *, content_type: str | None = None) -> RuntimeStoredObject:
40
+ stored = self._storage.save(key, payload, content_type=content_type)
41
+ object_key = getattr(stored, "object_key", key)
42
+ return RuntimeStoredObject(
43
+ path=str(object_key),
44
+ size=getattr(stored, "size", None),
45
+ content_type=getattr(stored, "content_type", content_type),
46
+ )
47
+
48
+ def delete(self, key: str) -> None:
49
+ self._storage.delete(key)
50
+
51
+ def url(self, key: str, *, expires_in: int | None = None) -> str | None:
52
+ return self._storage.url(key, expires_in=expires_in)
53
+
54
+ def presign_upload(
55
+ self,
56
+ key: str,
57
+ *,
58
+ content_type: str | None = None,
59
+ expires_in: int = 300,
60
+ ) -> RuntimePresignInfo:
61
+ del content_type
62
+ presign = self._storage.presign(key, method="PUT", expires_in=expires_in)
63
+ return RuntimePresignInfo(
64
+ method=getattr(presign, "method", "PUT"),
65
+ url=getattr(presign, "url"),
66
+ expires=getattr(presign, "expires_in_seconds", expires_in),
67
+ headers={},
68
+ fields={},
69
+ )
70
+
71
+ def presign_download(self, key: str, *, expires_in: int = 300) -> RuntimePresignInfo:
72
+ presign = self._storage.presign(key, method="GET", expires_in=expires_in)
73
+ return RuntimePresignInfo(
74
+ method=getattr(presign, "method", "GET"),
75
+ url=getattr(presign, "url"),
76
+ expires=getattr(presign, "expires_in_seconds", expires_in),
77
+ headers={},
78
+ fields={},
79
+ )
80
+
81
+
82
+ def get_storage_facade(*, request: Any | None = None, project_dir: str | None = None):
83
+ return require_runtime_bindings(request=request, project_dir=project_dir).storage
84
+
85
+
86
+ def get_storage_client(namespace: str | None = None, *, request: Any | None = None):
87
+ return StorageClient(namespace=namespace, request=request)
88
+
89
+
90
+ def get_storage(namespace: str | None = None):
91
+ def _dependency(request: Request):
92
+ return get_storage_client(namespace=namespace, request=request)
93
+
94
+ return _dependency
95
+
96
+
97
+ STABLE_EXPORTS: tuple[str, ...] = (
98
+ "StorageFacade",
99
+ "get_storage",
100
+ "get_storage_client",
101
+ "get_storage_facade",
102
+ )
103
+
104
+ COMPAT_EXPORTS: tuple[str, ...] = ()
105
+
106
+ __all__ = [*STABLE_EXPORTS, *COMPAT_EXPORTS]
@@ -0,0 +1,116 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass, field
4
+ from typing import Any
5
+
6
+ from .._contracts import PresignInfo, StoredObject
7
+
8
+ try:
9
+ import boto3 # type: ignore
10
+ from botocore.client import Config as BotoConfig # type: ignore
11
+ except Exception: # pragma: no cover
12
+ boto3 = None # type: ignore
13
+ BotoConfig = None # type: ignore
14
+
15
+
16
+ def _normalize_key(object_key: str) -> str:
17
+ key = str(object_key or "").strip().lstrip("/")
18
+ if not key:
19
+ raise ValueError("object_key must be a non-empty string")
20
+ if any(part == ".." for part in key.replace("\\", "/").split("/")):
21
+ raise ValueError("path traversal detected in object key")
22
+ return key
23
+
24
+
25
+ @dataclass(slots=True)
26
+ class S3Storage:
27
+ bucket: str
28
+ region_name: str | None = None
29
+ endpoint_url: str | None = None
30
+ access_key_id: str | None = None
31
+ secret_access_key: str | None = None
32
+ force_path_style: bool = False
33
+ public_base_url: str | None = None
34
+ _client: Any = field(init=False, repr=False)
35
+
36
+ def __post_init__(self) -> None:
37
+ if boto3 is None:
38
+ raise RuntimeError("boto3 is required for S3Storage")
39
+ kwargs: dict[str, Any] = {"service_name": "s3"}
40
+ if self.region_name:
41
+ kwargs["region_name"] = self.region_name
42
+ if self.endpoint_url:
43
+ kwargs["endpoint_url"] = self.endpoint_url
44
+ if self.access_key_id and self.secret_access_key:
45
+ kwargs["aws_access_key_id"] = self.access_key_id
46
+ kwargs["aws_secret_access_key"] = self.secret_access_key
47
+ if BotoConfig is not None:
48
+ kwargs["config"] = BotoConfig(s3={"addressing_style": "path" if self.force_path_style else "auto"})
49
+ self._client = boto3.client(**kwargs)
50
+ if self.public_base_url:
51
+ self.public_base_url = self.public_base_url.rstrip("/")
52
+
53
+ def store_bytes(self, object_key: str, payload: bytes, *, content_type: str | None = None) -> StoredObject:
54
+ key = _normalize_key(object_key)
55
+ extra: dict[str, Any] = {}
56
+ if content_type:
57
+ extra["ContentType"] = content_type
58
+ self._client.put_object(Bucket=self.bucket, Key=key, Body=payload, **extra)
59
+ return StoredObject(object_key=key, size=len(payload), content_type=content_type)
60
+
61
+ def delete(self, object_key: str) -> None:
62
+ key = _normalize_key(object_key)
63
+ self._client.delete_object(Bucket=self.bucket, Key=key)
64
+
65
+ def presign_get(self, object_key: str, *, expires_in_seconds: int) -> PresignInfo:
66
+ key = _normalize_key(object_key)
67
+ return PresignInfo(
68
+ method="GET",
69
+ url=self._client.generate_presigned_url(
70
+ "get_object",
71
+ Params={"Bucket": self.bucket, "Key": key},
72
+ ExpiresIn=expires_in_seconds,
73
+ ),
74
+ expires_in_seconds=expires_in_seconds,
75
+ )
76
+
77
+ def presign(self, object_key: str, *, method: str = "GET", expires_in: int | None = None) -> PresignInfo:
78
+ key = _normalize_key(object_key)
79
+ normalized_method = str(method or "GET").strip().upper() or "GET"
80
+ ttl = int(expires_in) if expires_in is not None else 300
81
+ operation = {
82
+ "GET": "get_object",
83
+ "PUT": "put_object",
84
+ }.get(normalized_method)
85
+ if operation is None:
86
+ raise RuntimeError(f"unsupported S3 presign method: {normalized_method}")
87
+ return PresignInfo(
88
+ method=normalized_method,
89
+ url=self._client.generate_presigned_url(
90
+ operation,
91
+ Params={"Bucket": self.bucket, "Key": key},
92
+ ExpiresIn=ttl,
93
+ ),
94
+ expires_in_seconds=ttl,
95
+ )
96
+
97
+ def url(self, object_key: str, *, expires_in: int | None = None) -> str:
98
+ del expires_in
99
+ key = _normalize_key(object_key)
100
+ if self.public_base_url:
101
+ return f"{self.public_base_url}/{key}"
102
+ if self.endpoint_url and self.force_path_style:
103
+ return f"{self.endpoint_url.rstrip('/')}/{self.bucket}/{key}"
104
+ if self.region_name:
105
+ return f"https://{self.bucket}.s3.{self.region_name}.amazonaws.com/{key}"
106
+ return f"https://{self.bucket}.s3.amazonaws.com/{key}"
107
+
108
+ def check_ready(self) -> bool:
109
+ try:
110
+ self._client.head_bucket(Bucket=self.bucket)
111
+ except Exception:
112
+ return False
113
+ return True
114
+
115
+
116
+ __all__ = ["S3Storage"]
@@ -0,0 +1,234 @@
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ import pz_settings_center.public as settings_center
9
+ from pz_core.assembly.project import resolve_project_context
10
+ from .local import LocalStorage, LocalStorageSettings, get_local_storage, reset_local_storages
11
+ from .s3 import S3Storage
12
+
13
+
14
+ @dataclass(frozen=True, slots=True)
15
+ class FoundationStorageSettings:
16
+ enabled: bool = False
17
+ backend: str = "local"
18
+ base_dir: str = ""
19
+ base_url: str = ""
20
+ bucket: str = ""
21
+ region_name: str = ""
22
+ endpoint_url: str = ""
23
+ access_key_id: str = ""
24
+ secret_access_key: str = ""
25
+ force_path_style: bool = False
26
+ public_base_url: str = ""
27
+
28
+
29
+ _STORAGE_SINGLETONS: dict[str, object] = {}
30
+
31
+
32
+ def _resolved_settings(*, project_dir: str | os.PathLike[str] | None = None):
33
+ if project_dir is None:
34
+ return settings_center.settings
35
+ return settings_center.resolve_settings(project_dir=str(Path(project_dir).resolve()))
36
+
37
+
38
+ def _project_settings(*, project_dir: str | os.PathLike[str] | None = None):
39
+ try:
40
+ return _resolved_settings(project_dir=project_dir).project
41
+ except Exception:
42
+ return None
43
+
44
+
45
+ def _foundation_settings_section(
46
+ name: str,
47
+ *,
48
+ project_dir: str | os.PathLike[str] | None = None,
49
+ ):
50
+ try:
51
+ return getattr(getattr(_resolved_settings(project_dir=project_dir), "pz_foundation"), str(name or "").strip())
52
+ except Exception:
53
+ return {}
54
+
55
+
56
+ def load_foundation_storage_settings(
57
+ *,
58
+ project_dir: str | os.PathLike[str] | None = None,
59
+ ) -> FoundationStorageSettings:
60
+ return _resolve_foundation_storage_settings(project_dir=project_dir)
61
+
62
+
63
+ def _resolve_foundation_storage_settings(
64
+ *,
65
+ project_dir: str | os.PathLike[str] | None = None,
66
+ ) -> FoundationStorageSettings:
67
+ storage_cfg = _storage_snapshot(project_dir=project_dir)
68
+ return FoundationStorageSettings(
69
+ enabled=_read_bool_value(storage_cfg, "enabled", False),
70
+ backend=(_read_value(storage_cfg, "backend") or "local").lower(),
71
+ base_dir=_read_value(storage_cfg, "base_dir"),
72
+ base_url=_read_value(storage_cfg, "base_url") or _read_value(storage_cfg, "public_base_url"),
73
+ bucket=_read_value(storage_cfg, "bucket"),
74
+ region_name=_read_value(storage_cfg, "region_name"),
75
+ endpoint_url=_read_value(storage_cfg, "endpoint_url"),
76
+ access_key_id=_read_value(storage_cfg, "access_key_id"),
77
+ secret_access_key=_read_value(storage_cfg, "secret_access_key"),
78
+ force_path_style=_read_bool_value(storage_cfg, "force_path_style", False),
79
+ public_base_url=_read_value(storage_cfg, "public_base_url"),
80
+ )
81
+
82
+
83
+ def get_foundation_storage(
84
+ *,
85
+ project_dir: str | os.PathLike[str] | None = None,
86
+ settings: FoundationStorageSettings | None = None,
87
+ ):
88
+ resolved = settings or _resolve_foundation_storage_settings(project_dir=project_dir)
89
+ if not resolved.enabled:
90
+ raise RuntimeError("foundation storage is disabled")
91
+ if resolved.backend == "local":
92
+ storage = get_local_storage(
93
+ project_dir=project_dir,
94
+ settings=LocalStorageSettings(
95
+ enabled=resolved.enabled,
96
+ base_dir=Path(resolved.base_dir).expanduser() if resolved.base_dir else None,
97
+ base_url=resolved.base_url or None,
98
+ ),
99
+ )
100
+ return storage
101
+ if resolved.backend == "s3":
102
+ bucket = resolved.bucket.strip()
103
+ if not bucket:
104
+ raise RuntimeError("foundation storage bucket is not configured")
105
+ key = "|".join(
106
+ (
107
+ "s3",
108
+ bucket,
109
+ resolved.region_name,
110
+ resolved.endpoint_url,
111
+ resolved.access_key_id,
112
+ resolved.public_base_url or resolved.base_url,
113
+ str(int(bool(resolved.force_path_style))),
114
+ )
115
+ )
116
+ storage = _STORAGE_SINGLETONS.get(key)
117
+ if storage is None:
118
+ storage = S3Storage(
119
+ bucket=bucket,
120
+ region_name=resolved.region_name or None,
121
+ endpoint_url=resolved.endpoint_url or None,
122
+ access_key_id=resolved.access_key_id or None,
123
+ secret_access_key=resolved.secret_access_key or None,
124
+ force_path_style=resolved.force_path_style,
125
+ public_base_url=(resolved.public_base_url or resolved.base_url) or None,
126
+ )
127
+ _STORAGE_SINGLETONS[key] = storage
128
+ return storage
129
+ raise RuntimeError(f"unsupported foundation storage backend: {resolved.backend!r}")
130
+
131
+
132
+ def build_storage_provider(context):
133
+ project = getattr(getattr(context, "plan", None), "project", None)
134
+ project_dir = getattr(project, "project_dir", None)
135
+ settings = _resolve_foundation_storage_settings(project_dir=project_dir)
136
+ if not settings.enabled:
137
+ return None
138
+ return get_foundation_storage(project_dir=project_dir, settings=settings)
139
+
140
+
141
+ def probe_foundation_storage(
142
+ *,
143
+ project_dir: str | os.PathLike[str] | None = None,
144
+ settings: FoundationStorageSettings | None = None,
145
+ ) -> dict[str, Any]:
146
+ resolved = settings or _resolve_foundation_storage_settings(project_dir=project_dir)
147
+ status: dict[str, Any] = {
148
+ "enabled": bool(resolved.enabled),
149
+ "configured": False,
150
+ "backend": resolved.backend,
151
+ "ready": False,
152
+ "error": None,
153
+ }
154
+ if not resolved.enabled:
155
+ return status
156
+ if resolved.backend == "local":
157
+ project_root = _project_root(project_dir=project_dir)
158
+ base_dir = resolved.base_dir or str(_project_asset_dir(project_dir=project_dir) / "storage")
159
+ if not Path(base_dir).is_absolute():
160
+ base_dir = str((project_root / base_dir).resolve())
161
+ status.update({"configured": True, "base_dir": base_dir, "base_url": resolved.base_url or None})
162
+ elif resolved.backend == "s3":
163
+ status.update(
164
+ {
165
+ "configured": bool(resolved.bucket.strip()),
166
+ "bucket": resolved.bucket or None,
167
+ "endpoint_url": resolved.endpoint_url or None,
168
+ "region_name": resolved.region_name or None,
169
+ }
170
+ )
171
+ else:
172
+ status["error"] = f"unsupported backend: {resolved.backend}"
173
+ return status
174
+ if not status["configured"]:
175
+ return status
176
+ try:
177
+ storage = get_foundation_storage(project_dir=project_dir, settings=resolved)
178
+ checker = getattr(storage, "check_ready", None)
179
+ status["ready"] = bool(checker()) if callable(checker) else True
180
+ except Exception as exc:
181
+ status["error"] = f"{type(exc).__name__}: {exc}"
182
+ return status
183
+
184
+
185
+ def reset_foundation_storages() -> None:
186
+ _STORAGE_SINGLETONS.clear()
187
+ reset_local_storages()
188
+
189
+
190
+ def _project_root(*, project_dir: str | os.PathLike[str] | None = None) -> Path:
191
+ if project_dir is not None:
192
+ return resolve_project_context(project_dir).project_dir.resolve()
193
+ try:
194
+ project = _project_settings()
195
+ return resolve_project_context(str(getattr(project, "project_dir", ".") or ".")).project_dir.resolve()
196
+ except Exception:
197
+ return resolve_project_context().project_dir.resolve()
198
+
199
+
200
+ def _project_asset_dir(*, project_dir: str | os.PathLike[str] | None = None) -> Path:
201
+ project_root = _project_root(project_dir=project_dir)
202
+ project = _project_settings(project_dir=project_dir)
203
+ raw_asset_dir = str(getattr(project, "asset_dir", "") or "").strip() if project is not None else ""
204
+ asset_dir = Path(raw_asset_dir).expanduser() if raw_asset_dir else resolve_project_context(project_root).asset_dir
205
+ if not asset_dir.is_absolute():
206
+ asset_dir = project_root / asset_dir
207
+ return asset_dir.resolve()
208
+
209
+
210
+ def _storage_snapshot(*, project_dir: str | os.PathLike[str] | None = None):
211
+ payload = _foundation_settings_section("storage", project_dir=project_dir)
212
+ if hasattr(payload, "to_dict") and callable(payload.to_dict):
213
+ payload = payload.to_dict()
214
+ if isinstance(payload, dict):
215
+ return dict(payload)
216
+ return dict(getattr(payload, "__dict__", {}) or {})
217
+
218
+
219
+ def _read_value(payload: Any, key: str) -> str:
220
+ if isinstance(payload, dict):
221
+ return str(payload.get(key) or "").strip()
222
+ return str(getattr(payload, key, "") or "").strip()
223
+
224
+
225
+ def _read_bool_value(payload: Any, key: str, default: bool) -> bool:
226
+ if isinstance(payload, dict):
227
+ value = payload.get(key, default)
228
+ else:
229
+ value = getattr(payload, key, default)
230
+ if value is None:
231
+ return default
232
+ if isinstance(value, bool):
233
+ return value
234
+ return str(value).strip().lower() in {"1", "true", "yes", "on"}
pz_foundation/urls.py ADDED
@@ -0,0 +1,19 @@
1
+ from __future__ import annotations
2
+
3
+ from pz_foundation.observability.http import metrics_endpoint
4
+ from pz_foundation.routing import path
5
+
6
+ app_name = "pz_foundation"
7
+
8
+ urlpatterns = (
9
+ path(
10
+ "/metrics",
11
+ metrics_endpoint,
12
+ methods=("GET",),
13
+ name="pz-foundation:metrics",
14
+ include_in_schema=False,
15
+ ),
16
+ )
17
+
18
+
19
+ __all__ = ["app_name", "urlpatterns"]
@@ -0,0 +1,6 @@
1
+ from .merge import deep_merge_dict, merge_tree_overlay
2
+
3
+ __all__ = [
4
+ "deep_merge_dict",
5
+ "merge_tree_overlay",
6
+ ]
@@ -0,0 +1,160 @@
1
+ from __future__ import annotations
2
+
3
+ from copy import deepcopy
4
+ from pathlib import Path
5
+ import shutil
6
+ from typing import Any, Callable, Iterable, Literal, Mapping
7
+
8
+
9
+ def deep_merge_dict(
10
+ base: Mapping[str, Any],
11
+ override: Mapping[str, Any],
12
+ *,
13
+ stringify_keys: bool = False,
14
+ copy_values: bool = False,
15
+ sequence_merge_mode: Literal["replace", "append"] = "replace",
16
+ replace_paths: Iterable[str] | None = None,
17
+ deep_merge_paths: Iterable[str] | None = None,
18
+ ) -> dict[str, Any]:
19
+ replace_path_parts = _normalize_merge_paths(replace_paths)
20
+ deep_merge_path_parts = _normalize_merge_paths(deep_merge_paths)
21
+
22
+ def copy_value(value: Any) -> Any:
23
+ return deepcopy(value) if copy_values else value
24
+
25
+ def normalize_mapping(value: Mapping[str, Any]) -> dict[Any, Any]:
26
+ if stringify_keys:
27
+ return {str(key): item for key, item in dict(value or {}).items()}
28
+ return dict(value or {})
29
+
30
+ def copy_mapping(value: Mapping[str, Any]) -> dict[Any, Any]:
31
+ return {key: copy_value(item) for key, item in normalize_mapping(value).items()}
32
+
33
+ def matching_depth(path: tuple[str, ...], paths: tuple[tuple[str, ...], ...]) -> int:
34
+ depth = -1
35
+ for candidate in paths:
36
+ candidate_len = len(candidate)
37
+ if candidate_len <= len(path) and path[:candidate_len] == candidate:
38
+ depth = max(depth, candidate_len)
39
+ return depth
40
+
41
+ def is_replace_path(path: tuple[str, ...]) -> bool:
42
+ replace_depth = matching_depth(path, replace_path_parts)
43
+ deep_merge_depth = matching_depth(path, deep_merge_path_parts)
44
+ return replace_depth > deep_merge_depth
45
+
46
+ def has_deep_merge_descendant(path: tuple[str, ...]) -> bool:
47
+ path_len = len(path)
48
+ return any(
49
+ len(candidate) > path_len and candidate[:path_len] == path
50
+ for candidate in deep_merge_path_parts
51
+ )
52
+
53
+ def preserved_deep_merge_value(existing: Any, path: tuple[str, ...]) -> Any:
54
+ if path in deep_merge_path_parts:
55
+ return copy_value(existing)
56
+ if not isinstance(existing, Mapping) or not has_deep_merge_descendant(path):
57
+ return _MISSING
58
+ existing_normalized = normalize_mapping(existing)
59
+ preserved: dict[Any, Any] = {}
60
+ for key, item in existing_normalized.items():
61
+ key_path = (*path, str(key))
62
+ value = preserved_deep_merge_value(item, key_path)
63
+ if value is _MISSING:
64
+ continue
65
+ preserved[key] = value
66
+ if not preserved:
67
+ return _MISSING
68
+ return preserved
69
+
70
+ def merge_value(existing: Any, value: Any, path: tuple[str, ...]) -> Any:
71
+ replace_scope = is_replace_path(path)
72
+ if isinstance(existing, Mapping) and isinstance(value, Mapping):
73
+ if replace_scope and not has_deep_merge_descendant(path):
74
+ return copy_mapping(value)
75
+ return merge_mapping(existing, value, path=path, replace_scope=replace_scope)
76
+ if (
77
+ not replace_scope
78
+ and sequence_merge_mode == "append"
79
+ and isinstance(existing, (list, tuple))
80
+ and isinstance(value, (list, tuple))
81
+ ):
82
+ return [*list(existing), *list(value)]
83
+ return copy_value(value)
84
+
85
+ def merge_mapping(
86
+ existing_mapping: Mapping[str, Any],
87
+ incoming_mapping: Mapping[str, Any],
88
+ *,
89
+ path: tuple[str, ...],
90
+ replace_scope: bool,
91
+ ) -> dict[Any, Any]:
92
+ existing_normalized = normalize_mapping(existing_mapping)
93
+ incoming_normalized = normalize_mapping(incoming_mapping)
94
+ if replace_scope:
95
+ merged: dict[Any, Any] = {}
96
+ else:
97
+ merged = {key: copy_value(value) for key, value in existing_normalized.items()}
98
+
99
+ for key, value in incoming_normalized.items():
100
+ key_path = (*path, str(key))
101
+ existing = existing_normalized.get(key)
102
+ if key in existing_normalized:
103
+ merged[key] = merge_value(existing, value, key_path)
104
+ else:
105
+ merged[key] = copy_value(value)
106
+ if replace_scope:
107
+ for key, value in existing_normalized.items():
108
+ if key in incoming_normalized:
109
+ continue
110
+ preserved = preserved_deep_merge_value(value, (*path, str(key)))
111
+ if preserved is not _MISSING:
112
+ merged[key] = preserved
113
+ return merged
114
+
115
+ return merge_mapping(base, override, path=(), replace_scope=False)
116
+
117
+
118
+ _MISSING = object()
119
+
120
+
121
+ def _normalize_merge_path(value: Any) -> tuple[str, ...]:
122
+ if isinstance(value, str):
123
+ return tuple(part for part in (item.strip() for item in value.split(".")) if part)
124
+ if isinstance(value, (list, tuple)):
125
+ return tuple(str(item).strip() for item in value if str(item).strip())
126
+ return ()
127
+
128
+
129
+ def _normalize_merge_paths(values: Iterable[str] | None) -> tuple[tuple[str, ...], ...]:
130
+ if values is None:
131
+ return ()
132
+ if isinstance(values, str):
133
+ raw_values: Iterable[Any] = (values,)
134
+ else:
135
+ raw_values = values
136
+ seen: set[tuple[str, ...]] = set()
137
+ normalized: list[tuple[str, ...]] = []
138
+ for value in raw_values:
139
+ path = _normalize_merge_path(value)
140
+ if not path or path in seen:
141
+ continue
142
+ seen.add(path)
143
+ normalized.append(path)
144
+ return tuple(normalized)
145
+
146
+
147
+ def merge_tree_overlay(
148
+ source_dir: Path,
149
+ target_dir: Path,
150
+ *,
151
+ transform_file: Callable[[Path, Path], bool] | None = None,
152
+ ) -> None:
153
+ for file_path in sorted(source_dir.rglob("*")):
154
+ if not file_path.is_file():
155
+ continue
156
+ target_path = target_dir / file_path.relative_to(source_dir)
157
+ if transform_file is not None and transform_file(file_path, target_path):
158
+ continue
159
+ target_path.parent.mkdir(parents=True, exist_ok=True)
160
+ shutil.copy2(file_path, target_path)