confidantic 0.1.0__tar.gz

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 (215) hide show
  1. confidantic-0.1.0/.copier-answers.yml +23 -0
  2. confidantic-0.1.0/.editorconfig +11 -0
  3. confidantic-0.1.0/.gitattributes +1 -0
  4. confidantic-0.1.0/.github/dependabot.yaml +7 -0
  5. confidantic-0.1.0/.github/skills/agent-context-update/SKILL.md +50 -0
  6. confidantic-0.1.0/.github/skills/create-wiki/SKILL.md +48 -0
  7. confidantic-0.1.0/.github/skills/docstring-audit/SKILL.md +25 -0
  8. confidantic-0.1.0/.github/skills/fix-bugs/SKILL.md +24 -0
  9. confidantic-0.1.0/.github/skills/investigate/SKILL.md +21 -0
  10. confidantic-0.1.0/.github/skills/merge-to-master/SKILL.md +33 -0
  11. confidantic-0.1.0/.github/skills/release-package/SKILL.md +34 -0
  12. confidantic-0.1.0/.github/skills/test-audit/SKILL.md +25 -0
  13. confidantic-0.1.0/.github/skills/test-coverage-audit/SKILL.md +29 -0
  14. confidantic-0.1.0/.github/skills/tidy-code/SKILL.md +121 -0
  15. confidantic-0.1.0/.github/skills/update-wiki/SKILL.md +50 -0
  16. confidantic-0.1.0/.github/workflows/checks.yaml +106 -0
  17. confidantic-0.1.0/.github/workflows/ci.yaml +32 -0
  18. confidantic-0.1.0/.github/workflows/pages.yaml +58 -0
  19. confidantic-0.1.0/.github/workflows/release.yaml +130 -0
  20. confidantic-0.1.0/.gitignore +42 -0
  21. confidantic-0.1.0/.pre-commit-config.yaml +52 -0
  22. confidantic-0.1.0/.python-version +1 -0
  23. confidantic-0.1.0/AGENTS.md +130 -0
  24. confidantic-0.1.0/BUGS.md +61 -0
  25. confidantic-0.1.0/CHANGELOG.md +112 -0
  26. confidantic-0.1.0/LICENSE +21 -0
  27. confidantic-0.1.0/Makefile +96 -0
  28. confidantic-0.1.0/PKG-INFO +290 -0
  29. confidantic-0.1.0/README.md +248 -0
  30. confidantic-0.1.0/STYLE.md +29 -0
  31. confidantic-0.1.0/changelog.d/.gitkeep +0 -0
  32. confidantic-0.1.0/confidantic/__init__.py +20 -0
  33. confidantic-0.1.0/confidantic/_config/__init__.py +13 -0
  34. confidantic-0.1.0/confidantic/_config/_cli.py +192 -0
  35. confidantic-0.1.0/confidantic/_config/_docstring_backend.py +132 -0
  36. confidantic-0.1.0/confidantic/_config/_docstrings.py +283 -0
  37. confidantic-0.1.0/confidantic/_config/_factory_build.py +260 -0
  38. confidantic-0.1.0/confidantic/_config/_factory_resolution.py +344 -0
  39. confidantic-0.1.0/confidantic/_config/_formats.py +108 -0
  40. confidantic-0.1.0/confidantic/_config/_info.py +162 -0
  41. confidantic-0.1.0/confidantic/_config/_nested.py +269 -0
  42. confidantic-0.1.0/confidantic/_config/_options.py +145 -0
  43. confidantic-0.1.0/confidantic/_config/_settings.py +629 -0
  44. confidantic-0.1.0/confidantic/_config/base.py +1056 -0
  45. confidantic-0.1.0/confidantic/_config/factory.py +382 -0
  46. confidantic-0.1.0/confidantic/annotations.py +301 -0
  47. confidantic-0.1.0/confidantic/configurable.py +301 -0
  48. confidantic-0.1.0/confidantic/context.py +145 -0
  49. confidantic-0.1.0/confidantic/logging.py +182 -0
  50. confidantic-0.1.0/confidantic/paths.py +213 -0
  51. confidantic-0.1.0/confidantic/py.typed +0 -0
  52. confidantic-0.1.0/confidantic/types.py +53 -0
  53. confidantic-0.1.0/confidantic/utils.py +222 -0
  54. confidantic-0.1.0/docs/advanced/custom-sources.md +81 -0
  55. confidantic-0.1.0/docs/advanced/dynamic-template-clis.md +103 -0
  56. confidantic-0.1.0/docs/advanced/object-directives-and-portability.md +139 -0
  57. confidantic-0.1.0/docs/architecture/factory-lifecycle.md +59 -0
  58. confidantic-0.1.0/docs/architecture/overview.md +47 -0
  59. confidantic-0.1.0/docs/architecture/settings-lifecycle.md +59 -0
  60. confidantic-0.1.0/docs/changelog.md +5 -0
  61. confidantic-0.1.0/docs/concepts/configuration-and-objects.md +58 -0
  62. confidantic-0.1.0/docs/concepts/state-and-lifetimes.md +47 -0
  63. confidantic-0.1.0/docs/concepts/values-and-inheritance.md +74 -0
  64. confidantic-0.1.0/docs/getting-started/first-application.md +165 -0
  65. confidantic-0.1.0/docs/getting-started/installation.md +61 -0
  66. confidantic-0.1.0/docs/guide/cli.md +108 -0
  67. confidantic-0.1.0/docs/guide/descriptions-and-display.md +154 -0
  68. confidantic-0.1.0/docs/guide/factories.md +97 -0
  69. confidantic-0.1.0/docs/guide/files.md +146 -0
  70. confidantic-0.1.0/docs/guide/input-parsing.md +64 -0
  71. confidantic-0.1.0/docs/guide/nested-settings.md +88 -0
  72. confidantic-0.1.0/docs/guide/settings.md +112 -0
  73. confidantic-0.1.0/docs/guide/sources.md +128 -0
  74. confidantic-0.1.0/docs/index.md +81 -0
  75. confidantic-0.1.0/docs/license.md +7 -0
  76. confidantic-0.1.0/docs/recipes/configurable-objects.md +82 -0
  77. confidantic-0.1.0/docs/recipes/contexts.md +66 -0
  78. confidantic-0.1.0/docs/recipes/logging.md +67 -0
  79. confidantic-0.1.0/docs/recipes/paths.md +66 -0
  80. confidantic-0.1.0/docs/reference/annotations.md +57 -0
  81. confidantic-0.1.0/docs/reference/api.md +19 -0
  82. confidantic-0.1.0/docs/reference/index.md +16 -0
  83. confidantic-0.1.0/docs/reference/options.md +93 -0
  84. confidantic-0.1.0/docs/releasing.md +168 -0
  85. confidantic-0.1.0/examples/.env +2 -0
  86. confidantic-0.1.0/examples/basic.py +84 -0
  87. confidantic-0.1.0/examples/cli.py +38 -0
  88. confidantic-0.1.0/examples/config_updates.py +58 -0
  89. confidantic-0.1.0/examples/configurable.py +41 -0
  90. confidantic-0.1.0/examples/context.py +43 -0
  91. confidantic-0.1.0/examples/custom_sources.py +69 -0
  92. confidantic-0.1.0/examples/delimited.py +42 -0
  93. confidantic-0.1.0/examples/directive_annotations.py +165 -0
  94. confidantic-0.1.0/examples/env_files.py +77 -0
  95. confidantic-0.1.0/examples/factory.py +60 -0
  96. confidantic-0.1.0/examples/factory_dynamic_template.py +118 -0
  97. confidantic-0.1.0/examples/factory_template.py +62 -0
  98. confidantic-0.1.0/examples/formats.py +53 -0
  99. confidantic-0.1.0/examples/import_directive.py +21 -0
  100. confidantic-0.1.0/examples/logging_config.py +49 -0
  101. confidantic-0.1.0/examples/multilevel_cli.py +80 -0
  102. confidantic-0.1.0/examples/nested.py +46 -0
  103. confidantic-0.1.0/examples/paths.py +40 -0
  104. confidantic-0.1.0/examples/quickstart.py +31 -0
  105. confidantic-0.1.0/examples/serialization.py +75 -0
  106. confidantic-0.1.0/noxfile.py +128 -0
  107. confidantic-0.1.0/pyproject.toml +246 -0
  108. confidantic-0.1.0/scripts/__init__.py +1 -0
  109. confidantic-0.1.0/scripts/_repository.py +131 -0
  110. confidantic-0.1.0/scripts/check.py +64 -0
  111. confidantic-0.1.0/scripts/check_optional_dependencies.py +193 -0
  112. confidantic-0.1.0/scripts/commands.py +56 -0
  113. confidantic-0.1.0/scripts/distributions.py +168 -0
  114. confidantic-0.1.0/scripts/generate_coverage_badge.py +125 -0
  115. confidantic-0.1.0/scripts/merge.py +91 -0
  116. confidantic-0.1.0/scripts/publish.py +133 -0
  117. confidantic-0.1.0/scripts/release.py +149 -0
  118. confidantic-0.1.0/tests/README.md +43 -0
  119. confidantic-0.1.0/tests/__init__.py +1 -0
  120. confidantic-0.1.0/tests/_config/__init__.py +1 -0
  121. confidantic-0.1.0/tests/_config/factory_targets.py +136 -0
  122. confidantic-0.1.0/tests/_config/models.py +31 -0
  123. confidantic-0.1.0/tests/_config/test_base.py +518 -0
  124. confidantic-0.1.0/tests/_config/test_cli.py +229 -0
  125. confidantic-0.1.0/tests/_config/test_docstring_backend.py +42 -0
  126. confidantic-0.1.0/tests/_config/test_docstrings.py +503 -0
  127. confidantic-0.1.0/tests/_config/test_factory.py +356 -0
  128. confidantic-0.1.0/tests/_config/test_factory_build.py +550 -0
  129. confidantic-0.1.0/tests/_config/test_factory_resolution.py +494 -0
  130. confidantic-0.1.0/tests/_config/test_formats.py +130 -0
  131. confidantic-0.1.0/tests/_config/test_info.py +235 -0
  132. confidantic-0.1.0/tests/_config/test_nested.py +347 -0
  133. confidantic-0.1.0/tests/_config/test_options.py +85 -0
  134. confidantic-0.1.0/tests/_config/test_settings.py +895 -0
  135. confidantic-0.1.0/tests/helpers.py +34 -0
  136. confidantic-0.1.0/tests/integration/__init__.py +1 -0
  137. confidantic-0.1.0/tests/integration/test_examples.py +222 -0
  138. confidantic-0.1.0/tests/integration/test_import_defaults.py +43 -0
  139. confidantic-0.1.0/tests/integration/test_optional_dependencies.py +239 -0
  140. confidantic-0.1.0/tests/integration/test_serialization.py +345 -0
  141. confidantic-0.1.0/tests/scripts/__init__.py +1 -0
  142. confidantic-0.1.0/tests/scripts/conftest.py +53 -0
  143. confidantic-0.1.0/tests/scripts/test_check.py +37 -0
  144. confidantic-0.1.0/tests/scripts/test_distributions.py +130 -0
  145. confidantic-0.1.0/tests/scripts/test_generate_coverage_badge.py +85 -0
  146. confidantic-0.1.0/tests/scripts/test_merge.py +136 -0
  147. confidantic-0.1.0/tests/scripts/test_publish.py +184 -0
  148. confidantic-0.1.0/tests/scripts/test_release.py +179 -0
  149. confidantic-0.1.0/tests/test_annotations.py +389 -0
  150. confidantic-0.1.0/tests/test_configurable.py +273 -0
  151. confidantic-0.1.0/tests/test_context.py +273 -0
  152. confidantic-0.1.0/tests/test_init.py +11 -0
  153. confidantic-0.1.0/tests/test_logging.py +120 -0
  154. confidantic-0.1.0/tests/test_paths.py +258 -0
  155. confidantic-0.1.0/tests/test_types.py +57 -0
  156. confidantic-0.1.0/tests/test_utils.py +143 -0
  157. confidantic-0.1.0/uv.lock +2258 -0
  158. confidantic-0.1.0/wiki/README.md +48 -0
  159. confidantic-0.1.0/wiki/api/README.md +25 -0
  160. confidantic-0.1.0/wiki/api/__init__.md +32 -0
  161. confidantic-0.1.0/wiki/api/_config/README.md +27 -0
  162. confidantic-0.1.0/wiki/api/_config/__init__.md +25 -0
  163. confidantic-0.1.0/wiki/api/_config/_cli.md +42 -0
  164. confidantic-0.1.0/wiki/api/_config/_docstring_backend.md +32 -0
  165. confidantic-0.1.0/wiki/api/_config/_docstrings.md +43 -0
  166. confidantic-0.1.0/wiki/api/_config/_factory_build.md +48 -0
  167. confidantic-0.1.0/wiki/api/_config/_factory_resolution.md +53 -0
  168. confidantic-0.1.0/wiki/api/_config/_formats.md +36 -0
  169. confidantic-0.1.0/wiki/api/_config/_info.md +33 -0
  170. confidantic-0.1.0/wiki/api/_config/_nested.md +43 -0
  171. confidantic-0.1.0/wiki/api/_config/_options.md +35 -0
  172. confidantic-0.1.0/wiki/api/_config/_settings.md +73 -0
  173. confidantic-0.1.0/wiki/api/_config/base.md +69 -0
  174. confidantic-0.1.0/wiki/api/_config/factory.md +56 -0
  175. confidantic-0.1.0/wiki/api/annotations.md +46 -0
  176. confidantic-0.1.0/wiki/api/configurable.md +46 -0
  177. confidantic-0.1.0/wiki/api/context.md +36 -0
  178. confidantic-0.1.0/wiki/api/logging.md +36 -0
  179. confidantic-0.1.0/wiki/api/paths.md +39 -0
  180. confidantic-0.1.0/wiki/api/types.md +30 -0
  181. confidantic-0.1.0/wiki/api/utils.md +45 -0
  182. confidantic-0.1.0/wiki/architecture/README.md +16 -0
  183. confidantic-0.1.0/wiki/architecture/factory-lifecycle.md +70 -0
  184. confidantic-0.1.0/wiki/architecture/optional-integrations.md +45 -0
  185. confidantic-0.1.0/wiki/architecture/package-map.md +41 -0
  186. confidantic-0.1.0/wiki/architecture/settings-lifecycle.md +65 -0
  187. confidantic-0.1.0/wiki/architecture/state-and-isolation.md +61 -0
  188. confidantic-0.1.0/wiki/concepts/README.md +20 -0
  189. confidantic-0.1.0/wiki/concepts/clis.md +38 -0
  190. confidantic-0.1.0/wiki/concepts/configuration-models.md +48 -0
  191. confidantic-0.1.0/wiki/concepts/configured-objects.md +36 -0
  192. confidantic-0.1.0/wiki/concepts/contexts.md +37 -0
  193. confidantic-0.1.0/wiki/concepts/factories-and-templates.md +47 -0
  194. confidantic-0.1.0/wiki/concepts/input-annotations.md +41 -0
  195. confidantic-0.1.0/wiki/concepts/nested-configuration.md +41 -0
  196. confidantic-0.1.0/wiki/concepts/serialization.md +46 -0
  197. confidantic-0.1.0/wiki/concepts/sources-and-inheritance.md +46 -0
  198. confidantic-0.1.0/wiki/examples/README.md +36 -0
  199. confidantic-0.1.0/wiki/examples/advanced/README.md +15 -0
  200. confidantic-0.1.0/wiki/examples/advanced/custom-sources.md +48 -0
  201. confidantic-0.1.0/wiki/examples/advanced/dynamic-template-clis.md +44 -0
  202. confidantic-0.1.0/wiki/examples/advanced/portable-object-graphs.md +54 -0
  203. confidantic-0.1.0/wiki/examples/clis.md +50 -0
  204. confidantic-0.1.0/wiki/examples/configurable-objects.md +52 -0
  205. confidantic-0.1.0/wiki/examples/contexts.md +45 -0
  206. confidantic-0.1.0/wiki/examples/defining-config.md +64 -0
  207. confidantic-0.1.0/wiki/examples/environment-and-dotenv.md +51 -0
  208. confidantic-0.1.0/wiki/examples/factories.md +54 -0
  209. confidantic-0.1.0/wiki/examples/logging.md +44 -0
  210. confidantic-0.1.0/wiki/examples/nested-config.md +44 -0
  211. confidantic-0.1.0/wiki/examples/object-templates.md +50 -0
  212. confidantic-0.1.0/wiki/examples/paths.md +52 -0
  213. confidantic-0.1.0/wiki/examples/serialization.md +57 -0
  214. confidantic-0.1.0/wiki/examples/smart-annotations.md +53 -0
  215. confidantic-0.1.0/zensical.toml +149 -0
@@ -0,0 +1,23 @@
1
+ # Changes here will be overwritten by Copier. Do not edit manually.
2
+ _commit: 19792dc
3
+ _src_path: gh:sztal/python-package-template
4
+ code_of_conduct: false
5
+ doctest:
6
+ - docstrings
7
+ - docs
8
+ - readme
9
+ entry_points: []
10
+ features:
11
+ - tasks
12
+ - docs
13
+ - doctest
14
+ github_user: sztal
15
+ install: uv pip
16
+ license: MIT
17
+ package_layout: flat
18
+ project_description: Configuration and CLIs for Python projects based on Pydantic
19
+ and Pydantic Settings.
20
+ project_name: Confidantic
21
+ target_python: py314
22
+ user_email: stalaga@protonmail.com
23
+ user_name: Szymon Talaga
@@ -0,0 +1,11 @@
1
+ root = true
2
+
3
+ [*]
4
+ indent_style = space
5
+ end_of_line = lf
6
+ charset = utf-8
7
+ trim_trailing_whitespace = true
8
+ insert_final_newline = true
9
+
10
+ [*.{toml,yaml}]
11
+ indent_size = 2
@@ -0,0 +1 @@
1
+ * text=auto eol=lf
@@ -0,0 +1,7 @@
1
+ ---
2
+ version: 2
3
+ updates:
4
+ - package-ecosystem: github-actions
5
+ directory: /
6
+ schedule:
7
+ interval: monthly
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: agent-context-update
3
+ description: Audit the repository and update AGENTS.md and all generated skills to match the current project.
4
+ argument-hint: Optional focus area; default is AGENTS.md and every skill
5
+ ---
6
+
7
+ # Agent Context Update
8
+
9
+ Use this skill when the repository structure, architecture, tools, or workflows
10
+ have changed and agent guidance may be stale.
11
+
12
+ ## First run in a newly generated repository
13
+
14
+ 1. Inspect the complete repository tree and the selected package layout.
15
+ 1. Read `pyproject.toml`, `README.md`, `Makefile`, `noxfile.py`,
16
+ `zensical.toml`, `.python-version`, and tests.
17
+ `confidantic/` is the import package; `docs/`, `examples/`, and
18
+ `changelog.d/` are the documentation, runnable-guide, and release-note
19
+ surfaces. `tests/integration/test_examples.py` lists the scripts under
20
+ `examples/` that have smoke-test coverage.
21
+ 1. Replace every placeholder in `AGENTS.md` with verified project facts.
22
+ 1. Update every skill under `.github/skills/` with the actual paths, commands,
23
+ environment rules, and testing conventions.
24
+ 1. Keep confirmed unresolved source defects in root `BUGS.md` and remove any
25
+ bug-backlog content from `wiki/`.
26
+ 1. Remove assumptions that are not supported by the source tree.
27
+ 1. Run `uv run noxfile.py -s lint` before `uv run pytest`; pre-commit can
28
+ modify files. Use `make coverage` only when coverage statistics are
29
+ relevant.
30
+ 1. Re-read all agent files and confirm they agree with each other.
31
+
32
+ Never run `make test`, `nox -s tests`, or `uv run noxfile.py -s tests` as an
33
+ agent. The Nox `tests` session runs the full supported-Python matrix; that
34
+ multi-version run is reserved for a human contributor. Use the direct pytest
35
+ command for the repository test suite:
36
+
37
+ ```console
38
+ uv run pytest
39
+ ```
40
+
41
+ ## Later updates
42
+
43
+ Keep edits limited to agent guidance and project records such as `BUGS.md` or
44
+ wiki migrations. Verify claims against source code and current commands before
45
+ documenting them. Do not change runtime behavior.
46
+
47
+ The package supports Python 3.11 and later. The repository default is recorded
48
+ in `.python-version` and is currently Python 3.13. Use `uv sync --group dev`
49
+ to install the development toolchain and add `--group docs` for documentation
50
+ builds.
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: create-wiki
3
+ description: Create durable architecture, design, investigation, or technical reference pages under wiki/.
4
+ argument-hint: Topic and relevant source files, decisions, or validation results
5
+ ---
6
+
7
+ # Create Wiki Pages
8
+
9
+ Create brief, informative Markdown notes for this repository. Derive the page
10
+ topic and scope from the user's request; ask one focused question only when the
11
+ topic or intended audience is not clear enough to write a useful note.
12
+
13
+ Never create a wiki page to track a bug or task-session progress. Confirmed,
14
+ unresolved source defects belong only in `../../../BUGS.md`; use a testing or
15
+ bug-fixing workflow for those records.
16
+
17
+ The repository's durable code references are `confidantic/` for the package,
18
+ `tests/` for behavior, `docs/` for published documentation, and `examples/`
19
+ for runnable guides. Verify claims against those paths and `pyproject.toml`
20
+ rather than inferring them.
21
+
22
+ ## Workflow
23
+
24
+ 1. Read the existing wiki page closest to the topic, when one exists, and the
25
+ source files most directly relevant to the request.
26
+ 1. Identify the note's purpose, intended reader, key decisions or facts, and
27
+ any validation or follow-up work worth recording.
28
+ 1. Choose a concise, descriptive lowercase filename using hyphens. Create the
29
+ page only in `wiki/` or one of its subdirectories. Never create wiki content
30
+ elsewhere in the repository.
31
+ 1. Write a short GitHub-flavored Markdown page. Use `Goal`, `Decisions and findings`, `Validation`, and `Follow-up` when they fit. Omit empty sections
32
+ and add focused headings when the topic calls for them.
33
+ 1. Prefer plain prose and lists. Include links to relevant local files when
34
+ useful. Use tables, Mermaid diagrams, reference-style links, or math only
35
+ when they materially improve clarity; do not add them as decoration.
36
+ 1. Verify the file is valid Markdown, concise, factually supported by the
37
+ supplied context or inspected sources, and located under `wiki/`.
38
+
39
+ ## Quality Bar
40
+
41
+ - Capture the topic and the information a future contributor needs to act on.
42
+ - Distinguish confirmed facts from assumptions, open questions, and follow-up.
43
+ - Keep unresolved source defects in `BUGS.md`, never in wiki content.
44
+ - Avoid copying large source excerpts, changelog entries, or implementation
45
+ narration.
46
+ - Use ASCII unless the subject requires other characters.
47
+ - Do not modify production code, tests, or documentation outside `wiki/` as
48
+ part of this skill.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: docstring-audit
3
+ description: Audit public documentation and doctest examples for accuracy.
4
+ argument-hint: Optional module or documentation concern
5
+ ---
6
+
7
+ # Docstring Audit
8
+
9
+ Check public classes, functions, and properties for concise, accurate
10
+ NumPy-style docstrings. Review doctests in `confidantic/`, `docs/`, and
11
+ `README.md`, which pytest collects. After documentation changes, run
12
+ `uv run noxfile.py -s lint`, `uv run pytest`, and
13
+ `uv run noxfile.py -s docs`; lint precedes pytest because pre-commit may modify
14
+ files. Keep comments focused on non-obvious behavior and avoid documenting
15
+ implementation details as API contracts.
16
+
17
+ Use `pyproject.toml` and `zensical.toml` as the sources of truth for pytest
18
+ collection and API documentation. Public exports include the package root and
19
+ the modules listed in `docs/reference/api.md`.
20
+
21
+ Record any confirmed unresolved source defect in `../../../BUGS.md`, not in
22
+ `wiki/`, and leave its fix to a separate bug-fixing task. Never run `make test`,
23
+ `nox -s tests`, or `uv run noxfile.py -s tests`.
24
+
25
+ The repository's lint, pytest, typecheck, and docs sessions currently pass.
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: fix-bugs
3
+ description: Fix confirmed bugs with focused regression tests.
4
+ argument-hint: Optional bug or module to fix
5
+ ---
6
+
7
+ # Fix Bugs
8
+
9
+ Read `../../../BUGS.md` when fixing a tracked defect. Confirm the bug against
10
+ current source, make the smallest focused change, and add a regression test that
11
+ fails before the fix. Do not mix unrelated refactors or test-audit work into a
12
+ bug fix.
13
+
14
+ Source code lives under `confidantic/` and focused regression tests belong under
15
+ `tests/`. Release notes are consolidated when merging into `master`; do not
16
+ create Towncrier fragments during individual bug fixes.
17
+
18
+ Run `uv run noxfile.py -s lint` before `uv run pytest`; pre-commit can modify
19
+ files. Use `make coverage` only when coverage statistics are relevant. After
20
+ the fix and required checks pass, remove its entry from `../../../BUGS.md`; Git
21
+ history retains the resolved record. Never track bugs in `wiki/`.
22
+
23
+ Never run `make test`, `nox -s tests`, or `uv run noxfile.py -s tests`; the full
24
+ multi-version Nox matrix is reserved for a human contributor.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: investigate
3
+ description: Investigate a reported behavior without changing existing source files.
4
+ argument-hint: Describe the issue, command, failure, or behavior
5
+ ---
6
+
7
+ # Investigate
8
+
9
+ Start from the nearest failing test, command, symbol, or file. Reproduce the
10
+ behavior when possible, identify the controlling code path, and report facts,
11
+ hypotheses, evidence, and a minimal fix direction. Do not modify existing
12
+ source, tests, configuration, or documentation files during investigation.
13
+
14
+ Use `uv run pytest` for a focused reproduction. The test suite also collects
15
+ doctests from `confidantic/`, `docs/`, and `README.md`; examples are executable
16
+ scripts under `examples/`. Check `tests/integration/test_examples.py` for the
17
+ smoke-tested scripts.
18
+
19
+ Do not use `wiki/` as a bug tracker. Because this workflow is read-only, report
20
+ confirmed unresolved defects for a follow-up task to record in
21
+ `../../../BUGS.md`.
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: merge-to-master
3
+ description: Prepare or complete a local feature/development branch merge into master with consolidated Towncrier notes and validation. Use for merge requests, not ordinary development or individual bug fixes.
4
+ ---
5
+
6
+ # Merge to master
7
+
8
+ Read [the release guide](../../../docs/releasing.md). Use the existing Make
9
+ commands; do not implement an alternative Git merge procedure.
10
+
11
+ Inspect the source branch and current local and remote `master` before writing
12
+ notes. Summarize the final integrated user-visible behavior, including migrations,
13
+ using source, tests, and documentation as evidence. Account for changes already
14
+ on master; do not turn intermediate commits or abandoned APIs into release notes.
15
+ Resolve conflicts as a separate source-branch change before retrying preparation.
16
+
17
+ Write category files (`added.md`, `changed.md`, `fixed.md`, `removed.md`,
18
+ `deprecated.md`, `security.md`) in a temporary directory outside the repository.
19
+ Only include categories with relevant changes. For documentation-only or internal
20
+ work, use `NO_NOTES_REASON` with a concise explanation instead. Ordinary coding
21
+ work does not create fragments; the merge helper writes them during integration.
22
+
23
+ Start from a clean checkout on `master` that contains the current remote master.
24
+ Use `make merge-check BRANCH=feature NOTES=/path/to/notes` when the request is
25
+ only to prepare or review. When the user has requested the merge, run
26
+ `make merge BRANCH=feature NOTES=/path/to/notes`; it performs the checks itself,
27
+ so a separate rehearsal is unnecessary. Substitute `NO_NOTES_REASON='reason'`
28
+ for `NOTES` when applicable. Respect existing authorization; a review request
29
+ does not authorize merging. Neither command pushes or creates a release tag.
30
+
31
+ On failure, report the retained preparation checkout and the cause. Resolve the
32
+ cause before retrying; do not reset user work, force-update master, or bypass
33
+ validation. Report the resulting master commit and summaries after a merge.
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: release-package
3
+ description: Build, check, prepare, or explicitly publish Confidantic releases derived from annotated Git tags. Use for package release work; implementation and review requests do not authorize real tags, pushes, or uploads.
4
+ ---
5
+
6
+ # Release package
7
+
8
+ Read [the release guide](../../../docs/releasing.md). Git tags determine versions;
9
+ do not edit a static version field or set a version override. Ask for the desired
10
+ version if the request does not identify one; do not infer a release bump from
11
+ commit messages. Use `master`, and fully qualified refs when working with tags:
12
+ a branch named `v0.0.0` can coexist with a tag of the same name.
13
+
14
+ Use `make build`, `make check-dist`, and `make check` for validation. Ordinary
15
+ builds can have development versions, but release artifacts must match their tag.
16
+ `make release-notes VERSION=1.2.0` previews notes without modifying tracked files.
17
+
18
+ For an authorized local release preparation, run `make release VERSION=1.2.0`
19
+ on clean master. Candidate versions such as `1.2.0rc1` keep pending fragments;
20
+ final releases consume them into the changelog. Preparation creates only local
21
+ state and prints the explicit push command. Use
22
+ `uv run python -m scripts.release --dry-run 1.2.0` for a requested rehearsal.
23
+
24
+ Push only if the user requested pushing, using the exact atomic push command
25
+ reported by preparation. Tag pushes validate without publishing. Publish only
26
+ when requested, using `make publish TAG=v1.2.0`; candidates go to TestPyPI and
27
+ final releases go to PyPI. A successful Git push is not publication success.
28
+ The helper tracks its specific Actions dispatch and returns publication failures.
29
+
30
+ Do not recreate or move an existing tag after failure. Inspect the retained
31
+ checkout or workflow logs, explain partial completion, and follow the guide's
32
+ recovery procedure. Never retry uploads blindly after a timeout or partial upload.
33
+ Publisher configuration is an account setup step; inspect it when an
34
+ `invalid-publisher` error occurs. Report the exact tag, destination, and outcome.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: test-audit
3
+ description: Audit pytest coverage and quality against the package source.
4
+ argument-hint: Optional module or test concern
5
+ ---
6
+
7
+ # Test Audit
8
+
9
+ Review public behavior, error paths, and meaningful edge cases. Prefer shared
10
+ fixtures, factory helpers, parametrization, and short behavioral assertions.
11
+ Do not test trivial implementation details.
12
+
13
+ If the audit confirms an unresolved source bug, add a concise entry to
14
+ `../../../BUGS.md` with its symptom, reproduction or evidence, affected
15
+ behavior, and expected behavior. Do not fix source bugs during a test audit and
16
+ never track them in `wiki/`.
17
+
18
+ Package behavior is implemented under `confidantic/`, with tests under
19
+ `tests/`; runnable examples are under `examples/`. Check
20
+ `tests/integration/test_examples.py` for the smoke-tested scripts.
21
+
22
+ Run `uv run noxfile.py -s lint` before `uv run pytest` after test changes;
23
+ pre-commit can modify files. Use `make coverage` only when coverage statistics
24
+ are relevant. Pytest collects `confidantic/`, `tests/`, `docs/`, and `README.md`.
25
+ Never run `make test`, `nox -s tests`, or `uv run noxfile.py -s tests`.
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: test-coverage-audit
3
+ description: Find meaningful missing pytest coverage and add focused tests.
4
+ argument-hint: Optional module or coverage concern
5
+ ---
6
+
7
+ # Test Coverage Audit
8
+
9
+ Start with `uv run coverage erase && make coverage`, then inspect uncovered
10
+ behavior alongside its tests. The explicit erase is needed because the Make
11
+ target uses the persistent repository `.coverage` file; after package files
12
+ are moved or deleted, stale paths can make `coverage report` fail with
13
+ `No source for code`.
14
+ Prioritize branches, validation, error paths, and public behavior. Avoid adding
15
+ tests only to execute trivial lines.
16
+
17
+ Use `confidantic/` as the source package and `tests/` as the behavioral test
18
+ surface. Example scripts are under `examples/`; check `tests/integration/test_examples.py`
19
+ to see which are covered by smoke tests.
20
+
21
+ If the audit confirms an unresolved source bug, add a concise entry to
22
+ `../../../BUGS.md` with its symptom, reproduction or evidence, affected
23
+ behavior, and expected behavior. Do not fix it during a coverage audit and
24
+ never track it in `wiki/`.
25
+
26
+ Run `uv run noxfile.py -s lint` before `uv run pytest` after test changes;
27
+ pre-commit can modify files. Pytest collects `confidantic/`, `tests/`, `docs/`,
28
+ and `README.md`. Never run `make test`, `nox -s tests`, or
29
+ `uv run noxfile.py -s tests`.
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: tidy-code
3
+ description: Organize definitions and function or method bodies in code files, modules, or packages to make their structure legible and predictable. Use when tidying code, organizing class members, grouping related functions and classes, consolidating module globals, or arranging longer function bodies into logical blocks with informative comments. Preserve behavior and public APIs.
4
+ ---
5
+
6
+ # Tidy Code
7
+
8
+ Organize definitions and function or method bodies within the requested files
9
+ so readers can predict where to find declarations, constructors, public
10
+ operations, implementation details, and each stage of a computation. Apply the
11
+ rules below to Python code, using equivalent constructs where applicable in
12
+ other languages.
13
+
14
+ ## Scope
15
+
16
+ - Accept a file, module, or package as the target, together with optional
17
+ contextual requests about related concepts or preferred reading order.
18
+ - For a package, apply the ordering within its files; do not move definitions
19
+ between modules, split files, or change exports unless requested.
20
+ - Use the target established by the conversation. If none is identifiable,
21
+ ask for the target rather than reorganizing the entire repository.
22
+ - Keep this a structural edit. Preserve names, signatures, decorators,
23
+ docstrings, and implementation behavior. Move attached comments and
24
+ docstrings with their definitions or statements, updating section comments
25
+ only as needed to describe the reorganized blocks.
26
+
27
+ ## Class bodies
28
+
29
+ Keep the class docstring first, then use this order:
30
+
31
+ 1. **Class attributes and variables:** constants, annotated fields,
32
+ configuration declarations, and other class-level data.
33
+ 1. **Dunder methods:** `__init__` first, followed by the remaining special
34
+ methods, such as `__new__`, `__repr__`, and protocol implementations.
35
+ 1. **Properties:** regular and cached properties, with each getter, setter,
36
+ and deleter kept together in their required order. Include private
37
+ properties here; classify them by their property role.
38
+ 1. **Constructors:** alternative constructors such as `from_*` classmethods
39
+ and other methods whose purpose is to create instances. Classify by
40
+ behavior, not just by name or the presence of `@classmethod`.
41
+ 1. **Public methods:** remaining public instance, class, and static methods.
42
+ 1. **Private methods:** remaining implementation helpers at the very end,
43
+ including private classmethods and staticmethods. Dunders belong in the
44
+ dunder section, not here.
45
+
46
+ Within each category, keep related operations together and choose a natural
47
+ reading order, such as lifecycle or workflow order. Do not alphabetize
48
+ mechanically. Keep existing relative order when it is already coherent.
49
+
50
+ ## Function and method bodies
51
+
52
+ - Review function and method bodies as well as definition order, especially
53
+ longer bodies. Arrange related statements into cohesive logical blocks.
54
+ - Where dependencies and existing behavior permit, put input validation,
55
+ invariant checks, and guard clauses first, followed by input preparation,
56
+ step-by-step computations, and final state updates or result assembly.
57
+ Keep checks that depend on intermediate results beside those results.
58
+ - Keep each computation stage together and order stages by their data flow.
59
+ Avoid interleaving unrelated preparation, calculation, and output handling.
60
+ - Separate substantial logical blocks with blank lines and short, informative
61
+ comments describing their purpose, relevant invariant, or non-obvious
62
+ reasoning. Prefer domain-specific descriptions over generic labels such as
63
+ "Step 1" or comments that merely repeat the next statement.
64
+ - Do not add a comment for every statement or force headings into short,
65
+ self-explanatory bodies. Preserve useful existing comments and keep them
66
+ attached to the logic they explain.
67
+ - Reorder only when safe: preserve evaluation and exception order, short-circuit
68
+ behavior, mutation timing, resource lifetimes, and other side effects. Do not
69
+ move checks ahead of earlier operations if that changes observable behavior.
70
+ - Do not extract helpers, introduce abstractions, add checks, or change
71
+ algorithms merely to produce a tidier layout.
72
+
73
+ ## Module and file structure
74
+
75
+ - Keep the module docstring and imports at the beginning, respecting future
76
+ imports and existing import conventions.
77
+ - Place module-level variables and globals immediately after imports and
78
+ before function and class definitions. This includes constants, loggers,
79
+ sentinels, registries, type aliases, and `__all__`.
80
+ - Group function and class definitions by logically related responsibility.
81
+ Within each group, generally place functions first and classes second.
82
+ Prefer meaningful conceptual groups over collecting unrelated functions
83
+ together solely because they are functions.
84
+ - In a long file with clearly separated logical groups, a global specific to
85
+ one group may appear at the beginning of that group. Shared globals still
86
+ belong at the top. Do not create artificial groups to justify scattered
87
+ assignments, or bury globals between unrelated definitions.
88
+ - Use short section comments only when they clarify substantial groups;
89
+ small files do not need a heading for every category.
90
+
91
+ ## Preserve order-dependent behavior
92
+
93
+ Check definition-time dependencies before moving blocks. Base classes,
94
+ decorators, default argument expressions, evaluated annotations, aliases,
95
+ and instantiated globals may require earlier definitions. Preserve decorator
96
+ application and registration order, including dispatch implementations, and
97
+ keep overload declarations with their implementation.
98
+
99
+ Preserve field order where frameworks such as dataclasses, enums, or Pydantic
100
+ give it meaning. Keep executable initialization and entry-point code in an
101
+ order that preserves side effects. Do not convert instance state into class
102
+ attributes just to put declarations at the top.
103
+
104
+ When a dependency prevents the preferred layout, make the smallest necessary
105
+ exception and explain it in the completion report. Do not introduce lazy
106
+ initialization, wrappers, new imports, or other behavioral refactoring merely
107
+ to force an ordering rule.
108
+
109
+ ## Validation
110
+
111
+ Review the diff for unintended changes beyond moving complete definitions or
112
+ logical statement blocks and updating their section comments. Check that body
113
+ reordering preserves data dependencies and observable execution order. Follow
114
+ the project's applicable agent instructions and documented environment setup.
115
+ Run the project's required lint checks and tests relevant to the changed code,
116
+ including doctests or focused smoke checks where appropriate. For broad
117
+ reorganizations, consider a full test run if selective test tracking may miss
118
+ affected behavior. Report any checks that could not be run.
119
+
120
+ Report the files organized, any necessary ordering exceptions, and validation
121
+ results.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: update-wiki
3
+ description: Update durable architecture, design, investigation, or technical reference pages under wiki/.
4
+ argument-hint: Wiki page, requested update, and relevant source files or decisions
5
+ ---
6
+
7
+ # Update Wiki Pages
8
+
9
+ Update existing Markdown pages under `wiki/` from the user's input. Preserve
10
+ the page's useful structure and concise style while making the requested
11
+ information accurate, coherent, and actionable for future contributors.
12
+
13
+ Never add or retain bug-backlog entries in wiki pages. Confirmed, unresolved
14
+ source defects belong only in `../../../BUGS.md`; use a testing or bug-fixing
15
+ workflow for those records.
16
+
17
+ Use `confidantic/` as the package source, `tests/` as the behavioral reference,
18
+ `docs/` as the published documentation surface, and `examples/` for runnable
19
+ guides. Check `pyproject.toml`, `.python-version`, and `zensical.toml` for
20
+ supported Python versions and tool configuration.
21
+
22
+ ## Workflow
23
+
24
+ 1. Read the target wiki page and the project files most directly relevant to
25
+ the requested update.
26
+ 1. Determine whether the user request adds new facts, corrects stale facts,
27
+ clarifies intent, or changes a decision or follow-up item.
28
+ 1. Apply the smallest edit that fully reflects the request. Keep content brief,
29
+ retain useful existing context, and remove or revise statements contradicted
30
+ by verified project sources.
31
+ 1. When the request is ambiguous, prefer an update that keeps the page
32
+ sensible in the context of the codebase: verify names, paths, commands,
33
+ architecture, and behavior against the repository. Preserve uncertainty as
34
+ an open question rather than inventing an unsupported conclusion.
35
+ 1. Use GitHub-flavored Markdown. Prefer prose and lists; use local links,
36
+ tables, Mermaid diagrams, reference-style links, or math only when they
37
+ materially improve clarity.
38
+ 1. Verify the resulting page remains valid Markdown, concise, internally
39
+ consistent, supported by the relevant codebase context, and located under
40
+ `wiki/` or one of its subdirectories.
41
+
42
+ ## Quality Bar
43
+
44
+ - Honor the requested update without rewriting unrelated content.
45
+ - Do not leave obsolete paths, commands, APIs, or project claims in the page.
46
+ - Remove bug-backlog content after ensuring it is recorded in `BUGS.md`.
47
+ - Distinguish verified facts from assumptions, questions, and pending work.
48
+ - Do not add decorative advanced Markdown features or copy large source
49
+ excerpts.
50
+ - Do not modify files outside `wiki/` as part of this skill.
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: Shared validation
3
+
4
+ on:
5
+ workflow_call:
6
+ inputs:
7
+ ref:
8
+ required: true
9
+ type: string
10
+ tag:
11
+ default: ''
12
+ type: string
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ lint:
19
+ runs-on: ubuntu-latest
20
+ steps:
21
+ - uses: actions/checkout@v5
22
+ with:
23
+ fetch-depth: 0
24
+ ref: ${{ inputs.ref }}
25
+ - uses: astral-sh/setup-uv@v7
26
+ - run: uv run noxfile.py -s lint
27
+ - run: git diff --exit-code
28
+
29
+ checks:
30
+ needs: lint
31
+ runs-on: ubuntu-latest
32
+ steps:
33
+ - uses: actions/checkout@v5
34
+ with:
35
+ fetch-depth: 0
36
+ ref: ${{ inputs.ref }}
37
+ - uses: astral-sh/setup-uv@v7
38
+ - run: uv run noxfile.py -s typecheck docs
39
+ - run: git diff --exit-code
40
+
41
+ distributions:
42
+ needs: lint
43
+ runs-on: ubuntu-latest
44
+ steps:
45
+ - uses: actions/checkout@v5
46
+ with:
47
+ fetch-depth: 0
48
+ ref: ${{ inputs.ref }}
49
+ - uses: astral-sh/setup-uv@v7
50
+ - run: make build
51
+ - run: make check-dist
52
+ env:
53
+ TAG: ${{ inputs.tag }}
54
+ - uses: actions/upload-artifact@v4
55
+ with:
56
+ name: python-package-distributions
57
+ path: |
58
+ dist/*.whl
59
+ dist/*.tar.gz
60
+ if-no-files-found: error
61
+
62
+ tests:
63
+ needs: lint
64
+ runs-on: ubuntu-latest
65
+ strategy:
66
+ fail-fast: false
67
+ matrix:
68
+ python_version:
69
+ - '3.14'
70
+ - '3.13'
71
+ - '3.12'
72
+ - '3.11'
73
+ steps:
74
+ - uses: actions/checkout@v5
75
+ with:
76
+ fetch-depth: 0
77
+ ref: ${{ inputs.ref }}
78
+ - name: Install the latest version of uv
79
+ uses: astral-sh/setup-uv@v7
80
+ with:
81
+ enable-cache: true
82
+ github-token: ${{ secrets.GITHUB_TOKEN }}
83
+ - name: Install Nox
84
+ run: >-
85
+ uv tool install nox
86
+ --python-preference only-managed
87
+ --python 3.14
88
+ - name: Set up the test suite
89
+ run: >-
90
+ nox
91
+ --install-only
92
+ --error-on-missing-interpreters
93
+ --session tests-${{ matrix.python_version }}
94
+ - name: Run the test suite
95
+ run: >-
96
+ nox
97
+ --no-install
98
+ --session tests-${{ matrix.python_version }}
99
+ env:
100
+ COVERAGE_FILE: coverage-data
101
+ - name: Store coverage data
102
+ if: matrix.python_version == '3.13'
103
+ uses: actions/upload-artifact@v4
104
+ with:
105
+ name: coverage-data
106
+ path: coverage-data
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: CI
3
+
4
+ on:
5
+ push:
6
+ branches: [master]
7
+ pull_request: null
8
+ workflow_dispatch: null
9
+
10
+ concurrency:
11
+ group: ${{ github.workflow }}-${{ github.ref }}
12
+ cancel-in-progress: true
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ checks:
19
+ uses: ./.github/workflows/checks.yaml
20
+ with:
21
+ ref: ${{ github.sha }}
22
+
23
+ pages:
24
+ if: github.event_name == 'push' && github.ref == 'refs/heads/master'
25
+ needs: checks
26
+ uses: ./.github/workflows/pages.yaml
27
+ with:
28
+ ref: ${{ github.sha }}
29
+ permissions:
30
+ contents: read
31
+ pages: write
32
+ id-token: write