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,486 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Callable, Iterable, Mapping
4
+ import posixpath
5
+ from typing import Any
6
+ from urllib.parse import urlencode, urlsplit, urlunsplit
7
+
8
+
9
+ DEFAULT_SKIP_PREFIXES: tuple[str, ...] = (
10
+ "/api/",
11
+ "/core/",
12
+ "/static/",
13
+ "/uploads/",
14
+ "/docs",
15
+ "/redoc",
16
+ "/openapi.json",
17
+ "/.well-known/",
18
+ "/robots.txt",
19
+ "/sitemap.xml",
20
+ "/favicon.ico",
21
+ "/health",
22
+ "/live",
23
+ "/livez",
24
+ "/liveness",
25
+ "/ready",
26
+ "/readiness",
27
+ "/admin",
28
+ "/user/",
29
+ )
30
+
31
+ PublicRouteCanonicalResolver = Callable[[str], str | None]
32
+
33
+ _PUBLIC_ROUTE_CANONICAL_RESOLVERS: dict[str, tuple[int, PublicRouteCanonicalResolver]] = {}
34
+
35
+
36
+ def _normalize_language_aliases(
37
+ aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
38
+ ) -> dict[str, str]:
39
+ if aliases is None:
40
+ return {}
41
+ try:
42
+ items = aliases.items() if isinstance(aliases, Mapping) else aliases
43
+ except Exception:
44
+ return {}
45
+ normalized: dict[str, str] = {}
46
+ for raw_alias, raw_target in items:
47
+ alias = str(raw_alias or "").strip().strip("/")
48
+ target = str(raw_target or "").strip().strip("/")
49
+ if alias and target:
50
+ normalized[alias.casefold()] = target
51
+ return normalized
52
+
53
+
54
+ def normalize_language_code(
55
+ value: str | None,
56
+ languages: Iterable[str] | None = None,
57
+ aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
58
+ ) -> str:
59
+ raw = str(value or "").strip().strip("/")
60
+ if not raw:
61
+ return ""
62
+ alias_target = _normalize_language_aliases(aliases).get(raw.casefold(), "")
63
+ candidate = alias_target or raw
64
+ for item in languages or ():
65
+ current = str(item or "").strip()
66
+ if current and current.casefold() == candidate.casefold():
67
+ return current
68
+ return candidate
69
+
70
+
71
+ def resolve_supported_language_code(
72
+ value: str | None,
73
+ languages: Iterable[str] | None = None,
74
+ aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
75
+ ) -> str:
76
+ normalized = normalize_language_code(value, languages, aliases)
77
+ if not normalized:
78
+ return ""
79
+ for item in languages or ():
80
+ current = str(item or "").strip()
81
+ if current and current.casefold() == normalized.casefold():
82
+ return current
83
+ return ""
84
+
85
+
86
+ def language_url_segment(
87
+ value: str | None,
88
+ languages: Iterable[str] | None = None,
89
+ aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
90
+ ) -> str:
91
+ resolved = resolve_supported_language_code(value, languages, aliases)
92
+ return resolved if resolved else ""
93
+
94
+
95
+ def normalize_public_path(value: str | None) -> str:
96
+ raw = str(value or "").strip()
97
+ if not raw:
98
+ return "/"
99
+ parts = [part for part in raw.replace("\\", "/").split("/") if part]
100
+ if not parts:
101
+ return "/"
102
+ return "/" + "/".join(parts)
103
+
104
+
105
+ def _join_public_path_segments(*segments: Any) -> str:
106
+ parts: list[str] = []
107
+ for segment in segments:
108
+ value = str(segment or "").strip().replace("\\", "/").strip("/")
109
+ if value:
110
+ parts.append(value)
111
+ if not parts:
112
+ return "/"
113
+ return normalize_public_path(posixpath.join(*parts))
114
+
115
+
116
+ def normalize_directory_path(value: str | None) -> str:
117
+ normalized = normalize_public_path(value)
118
+ if normalized == "/":
119
+ return normalized
120
+ return normalized + "/"
121
+
122
+
123
+ def is_file_like_path(path: str) -> bool:
124
+ try:
125
+ return "." in (str(path or "/").rsplit("/", 1)[-1])
126
+ except Exception:
127
+ return False
128
+
129
+
130
+ def should_skip_public_route_path(
131
+ path: str,
132
+ *,
133
+ extra_prefixes: Iterable[str] | None = None,
134
+ check_file_like: bool = False,
135
+ ) -> bool:
136
+ prefixes = list(DEFAULT_SKIP_PREFIXES)
137
+ if extra_prefixes is not None:
138
+ prefixes.extend(str(item) for item in extra_prefixes if str(item).strip())
139
+ try:
140
+ current = str(path or "")
141
+ if any(current.startswith(prefix) for prefix in prefixes):
142
+ return True
143
+ if check_file_like and is_file_like_path(current or "/"):
144
+ return True
145
+ except Exception:
146
+ return False
147
+ return False
148
+
149
+
150
+ def register_public_route_canonical_resolver(
151
+ owner: str,
152
+ resolver: PublicRouteCanonicalResolver,
153
+ *,
154
+ priority: int = 50,
155
+ ) -> None:
156
+ """Register an owner-provided alias-to-canonical public path resolver.
157
+
158
+ Foundation owns the public href normalization pipeline. Page owners may
159
+ contribute already compiled route facts here without Foundation importing
160
+ their private runtime.
161
+ """
162
+
163
+ owner_key = str(owner or "").strip()
164
+ if not owner_key:
165
+ raise ValueError("public route canonical resolver owner is required.")
166
+ if not callable(resolver):
167
+ raise TypeError("public route canonical resolver must be callable.")
168
+ _PUBLIC_ROUTE_CANONICAL_RESOLVERS[owner_key] = (int(priority), resolver)
169
+
170
+
171
+ def unregister_public_route_canonical_resolver(owner: str) -> None:
172
+ owner_key = str(owner or "").strip()
173
+ if not owner_key:
174
+ return
175
+ _PUBLIC_ROUTE_CANONICAL_RESOLVERS.pop(owner_key, None)
176
+
177
+
178
+ def resolve_public_route_canonical_path(path: str) -> str:
179
+ normalized = normalize_directory_path(path) if not is_file_like_path(str(path or "")) else normalize_public_path(path)
180
+ for _owner, (_priority, resolver) in sorted(
181
+ _PUBLIC_ROUTE_CANONICAL_RESOLVERS.items(),
182
+ key=lambda item: (-item[1][0], item[0]),
183
+ ):
184
+ try:
185
+ resolved = str(resolver(normalized) or "").strip()
186
+ except Exception:
187
+ continue
188
+ if not resolved:
189
+ continue
190
+ canonical = normalize_directory_path(resolved) if not is_file_like_path(resolved) else normalize_public_path(resolved)
191
+ if canonical and canonical != normalized:
192
+ return canonical
193
+ return normalized
194
+
195
+
196
+ def strip_default_language_prefix(
197
+ path: str,
198
+ *,
199
+ default_language: str,
200
+ supported_languages: Iterable[str] | None = None,
201
+ language_aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
202
+ ) -> str | None:
203
+ raw = str(path or "").strip()
204
+ normalized = normalize_public_path(raw)
205
+ default_lang = normalize_language_code(default_language, supported_languages, language_aliases)
206
+ if not default_lang:
207
+ return None
208
+ parts = [part for part in normalized.split("/") if part]
209
+ if not parts:
210
+ return None
211
+ head = normalize_language_code(parts[0], supported_languages, language_aliases)
212
+ if head.casefold() != default_lang.casefold():
213
+ return None
214
+ if len(parts) == 1:
215
+ return "/"
216
+ stripped = normalize_public_path("/" + "/".join(parts[1:]))
217
+ if raw.endswith("/") and stripped != "/" and not is_file_like_path(stripped):
218
+ return normalize_directory_path(stripped)
219
+ return stripped
220
+
221
+
222
+ def canonicalize_default_language_path(
223
+ path: str,
224
+ *,
225
+ default_language: str,
226
+ supported_languages: Iterable[str] | None = None,
227
+ language_aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
228
+ directory: bool = True,
229
+ ) -> str:
230
+ stripped = strip_default_language_prefix(
231
+ path,
232
+ default_language=default_language,
233
+ supported_languages=supported_languages,
234
+ language_aliases=language_aliases,
235
+ )
236
+ target = stripped if stripped is not None else normalize_public_path(path)
237
+ if directory and not is_file_like_path(target):
238
+ return normalize_directory_path(target)
239
+ return target
240
+
241
+
242
+ def add_directory_slash(path: str) -> str | None:
243
+ normalized = normalize_public_path(path)
244
+ if normalized == "/" or normalized.endswith("/") or is_file_like_path(normalized):
245
+ return None
246
+ return normalized + "/"
247
+
248
+
249
+ def canonical_redirect_target(
250
+ path: str,
251
+ *,
252
+ default_language: str,
253
+ supported_languages: Iterable[str] | None = None,
254
+ language_aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
255
+ ) -> str | None:
256
+ if should_skip_public_route_path(path, check_file_like=True):
257
+ return None
258
+ raw = str(path or "").strip()
259
+ normalized = normalize_directory_path(raw) if raw.endswith("/") and not is_file_like_path(raw) else normalize_public_path(raw)
260
+ parts = [part for part in normalized.split("/") if part]
261
+ if parts:
262
+ head_segment = language_url_segment(parts[0], supported_languages, language_aliases)
263
+ if head_segment and head_segment != parts[0]:
264
+ normalized_head_path = "/" + "/".join((head_segment, *parts[1:]))
265
+ if normalized_head_path != "/" and not is_file_like_path(normalized_head_path):
266
+ normalized_head_path = normalize_directory_path(normalized_head_path)
267
+ return normalized_head_path
268
+ canonical = canonicalize_default_language_path(
269
+ normalized,
270
+ default_language=default_language,
271
+ supported_languages=supported_languages,
272
+ language_aliases=language_aliases,
273
+ directory=True,
274
+ )
275
+ if canonical != normalized:
276
+ return canonical
277
+ slash_target = add_directory_slash(normalized)
278
+ if slash_target and slash_target != normalized:
279
+ return slash_target
280
+ return None
281
+
282
+
283
+ def public_canonical_path(
284
+ path: str,
285
+ *,
286
+ default_language: str,
287
+ supported_languages: Iterable[str] | None = None,
288
+ language_aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
289
+ directory: bool = True,
290
+ ) -> str:
291
+ """Return the public canonical path owned by the routing layer.
292
+
293
+ This is the single projection used by redirects, SEO, and UI consumers:
294
+ default-language prefixes are removed, supported language casing is
295
+ normalized, and directory-style public URLs receive a trailing slash.
296
+ """
297
+
298
+ target = canonical_redirect_target(
299
+ path,
300
+ default_language=default_language,
301
+ supported_languages=supported_languages,
302
+ language_aliases=language_aliases,
303
+ )
304
+ if target:
305
+ return target
306
+ return canonicalize_default_language_path(
307
+ path,
308
+ default_language=default_language,
309
+ supported_languages=supported_languages,
310
+ language_aliases=language_aliases,
311
+ directory=directory,
312
+ )
313
+
314
+
315
+ def _is_absolute_or_special_href(value: str) -> bool:
316
+ if value.startswith(("#", "?")):
317
+ return True
318
+ parts = urlsplit(value)
319
+ if parts.scheme or parts.netloc:
320
+ return True
321
+ if value.startswith("//"):
322
+ return True
323
+ return False
324
+
325
+
326
+ def _normalize_href_query(value: Any) -> str:
327
+ if value is None:
328
+ return ""
329
+ if isinstance(value, str):
330
+ return value.lstrip("?")
331
+ if isinstance(value, Mapping):
332
+ return urlencode(value, doseq=True)
333
+ return urlencode(value, doseq=True)
334
+
335
+
336
+ def public_canonical_href(
337
+ href: Any = None,
338
+ *path_segments: Any,
339
+ language: str | None = None,
340
+ default_language: str,
341
+ supported_languages: Iterable[str] | None = None,
342
+ language_aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
343
+ directory: bool = True,
344
+ query: Any = None,
345
+ fragment: Any = None,
346
+ replace_language: bool = False,
347
+ ) -> str:
348
+ """Return a canonical public href for UI links.
349
+
350
+ Unlike :func:`public_canonical_path`, this helper accepts href-shaped input:
351
+ it preserves query strings and fragments, leaves external/special links
352
+ untouched, and only applies public route canonicalization to local paths.
353
+ Callers may pass path segments instead of assembling slash-delimited strings.
354
+ """
355
+
356
+ raw = str(href or "").strip()
357
+ if path_segments:
358
+ path = _join_public_path_segments(raw, *path_segments)
359
+ raw = path
360
+ if not raw:
361
+ raw = "/"
362
+ if not path_segments and _is_absolute_or_special_href(raw):
363
+ return raw
364
+
365
+ parts = urlsplit(raw)
366
+ pathname = parts.path or "/"
367
+ normalized_query = _normalize_href_query(query) if query is not None else parts.query
368
+ normalized_fragment = str(fragment).lstrip("#") if fragment is not None else parts.fragment
369
+
370
+ if should_skip_public_route_path(pathname, check_file_like=True):
371
+ return urlunsplit(("", "", pathname, normalized_query, normalized_fragment))
372
+
373
+ supported = tuple(supported_languages or ())
374
+ aliases = language_aliases
375
+ _tail, path_language = split_public_language_path(
376
+ pathname,
377
+ supported_languages=supported,
378
+ language_aliases=aliases,
379
+ )
380
+ if path_language and replace_language:
381
+ selected_language = normalize_language_code(language, supported, aliases)
382
+ default_lang = normalize_language_code(default_language, supported, aliases)
383
+ canonical_input = _tail
384
+ if selected_language and selected_language.casefold() != default_lang.casefold():
385
+ canonical_input = _join_public_path_segments(selected_language, _tail)
386
+ canonical_path = public_canonical_path(
387
+ canonical_input,
388
+ default_language=default_language,
389
+ supported_languages=supported,
390
+ language_aliases=aliases,
391
+ directory=directory,
392
+ )
393
+ elif path_language or not language:
394
+ canonical_path = public_canonical_path(
395
+ pathname,
396
+ default_language=default_language,
397
+ supported_languages=supported,
398
+ language_aliases=aliases,
399
+ directory=directory,
400
+ )
401
+ else:
402
+ selected_language = normalize_language_code(language, supported, aliases)
403
+ default_lang = normalize_language_code(default_language, supported, aliases)
404
+ canonical_input = normalize_public_path(pathname)
405
+ if selected_language and selected_language.casefold() != default_lang.casefold():
406
+ canonical_input = _join_public_path_segments(selected_language, canonical_input)
407
+ canonical_path = public_canonical_path(
408
+ canonical_input,
409
+ default_language=default_language,
410
+ supported_languages=supported,
411
+ language_aliases=aliases,
412
+ directory=directory,
413
+ )
414
+
415
+ canonical_path = resolve_public_route_canonical_path(canonical_path)
416
+
417
+ return urlunsplit(("", "", canonical_path, normalized_query, normalized_fragment))
418
+
419
+
420
+ def split_public_language_path(
421
+ path: str,
422
+ *,
423
+ supported_languages: Iterable[str] | None = None,
424
+ language_aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
425
+ ) -> tuple[str, str]:
426
+ normalized = normalize_public_path(path)
427
+ parts = [part for part in normalized.split("/") if part]
428
+ if not parts:
429
+ return "/", ""
430
+ language = resolve_supported_language_code(parts[0], supported_languages, language_aliases)
431
+ if not language:
432
+ return normalized, ""
433
+ tail = "/" + "/".join(parts[1:])
434
+ return normalize_public_path(tail), language
435
+
436
+
437
+ def rewrite_prefixless_default_language_path(
438
+ path: str,
439
+ *,
440
+ default_language: str,
441
+ supported_languages: Iterable[str] | None = None,
442
+ language_aliases: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
443
+ ) -> str | None:
444
+ if should_skip_public_route_path(path, check_file_like=True):
445
+ return None
446
+ normalized = normalize_directory_path(path)
447
+ default_lang = str(default_language or "").strip().strip("/")
448
+ if not default_lang:
449
+ return None
450
+ if normalized == "/":
451
+ return normalize_directory_path(f"/{default_lang}")
452
+ parts = [part for part in normalized.split("/") if part]
453
+ if not parts:
454
+ return None
455
+ head = normalize_language_code(parts[0], supported_languages, language_aliases)
456
+ supported = {
457
+ str(item or "").strip().casefold()
458
+ for item in supported_languages or ()
459
+ if str(item or "").strip()
460
+ }
461
+ if head.casefold() == default_lang.casefold() or (supported and head.casefold() in supported):
462
+ return None
463
+ return normalize_directory_path("/" + "/".join((default_lang, *parts)))
464
+
465
+
466
+ __all__ = [
467
+ "DEFAULT_SKIP_PREFIXES",
468
+ "add_directory_slash",
469
+ "canonical_redirect_target",
470
+ "canonicalize_default_language_path",
471
+ "is_file_like_path",
472
+ "language_url_segment",
473
+ "normalize_directory_path",
474
+ "normalize_language_code",
475
+ "normalize_public_path",
476
+ "public_canonical_href",
477
+ "public_canonical_path",
478
+ "register_public_route_canonical_resolver",
479
+ "resolve_public_route_canonical_path",
480
+ "resolve_supported_language_code",
481
+ "rewrite_prefixless_default_language_path",
482
+ "should_skip_public_route_path",
483
+ "split_public_language_path",
484
+ "strip_default_language_prefix",
485
+ "unregister_public_route_canonical_resolver",
486
+ ]
@@ -0,0 +1,82 @@
1
+ from __future__ import annotations
2
+
3
+ from contextlib import contextmanager
4
+ import hashlib
5
+ import re
6
+ import secrets
7
+
8
+ from starlette.convertors import CONVERTOR_TYPES, Convertor, register_url_convertor
9
+
10
+
11
+ _ENUM_PATH_CONVERTOR_CACHE: dict[tuple[str, tuple[str, ...]], str] = {}
12
+
13
+
14
+ class _EnumeratedSegmentConvertor(Convertor[str]):
15
+ regex: str
16
+
17
+ def __init__(self, values: tuple[str, ...]) -> None:
18
+ escaped = sorted({re.escape(item) for item in values if item}, key=len, reverse=True)
19
+ if not escaped:
20
+ raise ValueError("enumerated path convertor requires at least one value")
21
+ self.regex = "(?:" + "|".join(escaped) + ")"
22
+
23
+ def convert(self, value: str) -> str:
24
+ return value
25
+
26
+ def to_string(self, value: str) -> str:
27
+ return value
28
+
29
+
30
+ def register_enumerated_path_convertor(*, values: list[str] | tuple[str, ...], namespace: str = "pz_enum") -> str:
31
+ normalized_values = tuple(sorted({str(item).strip() for item in values if str(item).strip()}))
32
+ if not normalized_values:
33
+ raise ValueError("enumerated path convertor requires at least one non-empty value")
34
+ normalized_namespace = re.sub(r"[^a-zA-Z0-9_]+", "_", str(namespace or "pz_enum")).strip("_") or "pz_enum"
35
+ cache_key = (normalized_namespace, normalized_values)
36
+ cached = _ENUM_PATH_CONVERTOR_CACHE.get(cache_key)
37
+ if cached is not None:
38
+ return cached
39
+ digest = hashlib.sha1("\x00".join(normalized_values).encode("utf-8")).hexdigest()[:12]
40
+ convertor_name = f"{normalized_namespace}_{digest}"
41
+ if convertor_name not in CONVERTOR_TYPES:
42
+ register_url_convertor(convertor_name, _EnumeratedSegmentConvertor(normalized_values))
43
+ _ENUM_PATH_CONVERTOR_CACHE[cache_key] = convertor_name
44
+ return convertor_name
45
+
46
+
47
+ def unregister_path_convertor(name: str) -> None:
48
+ normalized = str(name or "").strip()
49
+ if not normalized:
50
+ return
51
+ CONVERTOR_TYPES.pop(normalized, None)
52
+
53
+
54
+ def create_temporary_enumerated_path_convertor(
55
+ *,
56
+ values: list[str] | tuple[str, ...],
57
+ namespace: str = "pz_enum",
58
+ ) -> tuple[str, callable]:
59
+ normalized_values = tuple(sorted({str(item).strip() for item in values if str(item).strip()}))
60
+ if not normalized_values:
61
+ raise ValueError("enumerated path convertor requires at least one non-empty value")
62
+ normalized_namespace = re.sub(r"[^a-zA-Z0-9_]+", "_", str(namespace or "pz_enum")).strip("_") or "pz_enum"
63
+ digest = hashlib.sha1("\x00".join(normalized_values).encode("utf-8")).hexdigest()[:12]
64
+ convertor_name = f"{normalized_namespace}_{digest}_{secrets.token_hex(4)}"
65
+ register_url_convertor(convertor_name, _EnumeratedSegmentConvertor(normalized_values))
66
+ return convertor_name, (lambda: unregister_path_convertor(convertor_name))
67
+
68
+
69
+ @contextmanager
70
+ def temporary_enumerated_path_convertor(
71
+ *,
72
+ values: list[str] | tuple[str, ...],
73
+ namespace: str = "pz_enum",
74
+ ):
75
+ convertor_name, cleanup = create_temporary_enumerated_path_convertor(
76
+ values=values,
77
+ namespace=namespace,
78
+ )
79
+ try:
80
+ yield convertor_name
81
+ finally:
82
+ cleanup()