periplus-map 0.2.1__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.
- periplus/__init__.py +70 -0
- periplus/checkmap.py +80 -0
- periplus/cli.py +658 -0
- periplus/contract/schema/map.schema.json +138 -0
- periplus/contract/schema/navigation.schema.json +200 -0
- periplus/contract/schema/pack-file.schema.json +1405 -0
- periplus/contract/schema/pack-manifest.schema.json +245 -0
- periplus/contract/schema/project-settings.schema.json +85 -0
- periplus/contract/spec/engine.md +151 -0
- periplus/contract/spec/rules.md +352 -0
- periplus/detect.py +228 -0
- periplus/engine/__init__.py +5 -0
- periplus/engine/check.py +481 -0
- periplus/engine/emit.py +368 -0
- periplus/engine/packload.py +2321 -0
- periplus/engine/pattern.py +27 -0
- periplus/engine/rules.py +1946 -0
- periplus/engine/select.py +491 -0
- periplus/engine/source.py +172 -0
- periplus/engine/tree.py +424 -0
- periplus/errors.py +332 -0
- periplus/init.py +358 -0
- periplus/layout.py +28 -0
- periplus/manifest.py +498 -0
- periplus/map.py +364 -0
- periplus/navigate/__init__.py +1 -0
- periplus/navigate/find.py +143 -0
- periplus/navigate/ids.py +30 -0
- periplus/navigate/listing.py +42 -0
- periplus/navigate/mapfile.py +189 -0
- periplus/navigate/path.py +175 -0
- periplus/navigate/show.py +175 -0
- periplus/navigate/types.py +83 -0
- periplus/navigate/walk.py +138 -0
- periplus/packs/advancedqueue_basic@0.0.1/pack.yaml +14 -0
- periplus/packs/advancedqueue_basic@0.0.1/queue_job_type/queue_job_type.yaml +9 -0
- periplus/packs/advancedqueue_basic@0.0.1/queue_job_type/queue_job_type_annotation.yaml +43 -0
- periplus/packs/advancedqueue_basic@0.0.1/queue_job_type/queue_job_type_attribute.yaml +43 -0
- periplus/packs/ai_basic@0.0.1/ai_agent/ai_agent.yaml +8 -0
- periplus/packs/ai_basic@0.0.1/ai_agent/ai_agent_attribute.yaml +43 -0
- periplus/packs/ai_basic@0.0.1/ai_function_call/ai_function_call.yaml +8 -0
- periplus/packs/ai_basic@0.0.1/ai_function_call/ai_function_call_attribute.yaml +43 -0
- periplus/packs/ai_basic@0.0.1/pack.yaml +15 -0
- periplus/packs/config_pages_basic@0.0.1/bundle/config_pages_bundle_config.yaml +54 -0
- periplus/packs/config_pages_basic@0.0.1/pack.yaml +11 -0
- periplus/packs/crop_basic@0.0.1/bundle/crop_bundle_config.yaml +54 -0
- periplus/packs/crop_basic@0.0.1/pack.yaml +11 -0
- periplus/packs/drupal@0.1.0/block/block_placement.yaml +25 -0
- periplus/packs/drupal@0.1.0/block/block_placement_code.yaml +58 -0
- periplus/packs/drupal@0.1.0/block/block_placement_config.yaml +53 -0
- periplus/packs/drupal@0.1.0/block/block_plugin.yaml +52 -0
- periplus/packs/drupal@0.1.0/block/block_plugin_altered.yaml +61 -0
- periplus/packs/drupal@0.1.0/block/block_plugin_annotation.yaml +69 -0
- periplus/packs/drupal@0.1.0/block/block_plugin_attribute.yaml +56 -0
- periplus/packs/drupal@0.1.0/block/block_plugin_content.yaml +46 -0
- periplus/packs/drupal@0.1.0/block/block_plugin_derived.yaml +110 -0
- periplus/packs/drupal@0.1.0/block/block_plugin_deriver.yaml +30 -0
- periplus/packs/drupal@0.1.0/block/block_type.yaml +14 -0
- periplus/packs/drupal@0.1.0/block/block_type_code.yaml +43 -0
- periplus/packs/drupal@0.1.0/block/block_type_config.yaml +45 -0
- periplus/packs/drupal@0.1.0/cache/cache.yaml +18 -0
- periplus/packs/drupal@0.1.0/cache/cache_backend.yaml +31 -0
- periplus/packs/drupal@0.1.0/component/sdc.yaml +19 -0
- periplus/packs/drupal@0.1.0/component/sdc_definition.yaml +25 -0
- periplus/packs/drupal@0.1.0/component/sdc_use.yaml +25 -0
- periplus/packs/drupal@0.1.0/config/config_object.yaml +65 -0
- periplus/packs/drupal@0.1.0/display/display.yaml +32 -0
- periplus/packs/drupal@0.1.0/display/display_code.yaml +53 -0
- periplus/packs/drupal@0.1.0/display/display_config.yaml +95 -0
- periplus/packs/drupal@0.1.0/entity/entity.yaml +33 -0
- periplus/packs/drupal@0.1.0/entity/entity_class.yaml +60 -0
- periplus/packs/drupal@0.1.0/entity/entity_save.yaml +27 -0
- periplus/packs/drupal@0.1.0/entity/entity_type_annotation.yaml +85 -0
- periplus/packs/drupal@0.1.0/entity/entity_type_attribute.yaml +76 -0
- periplus/packs/drupal@0.1.0/field/field_instance_code.yaml +40 -0
- periplus/packs/drupal@0.1.0/field/field_instance_config.yaml +58 -0
- periplus/packs/drupal@0.1.0/field/field_storage.yaml +37 -0
- periplus/packs/drupal@0.1.0/field/field_storage_code.yaml +39 -0
- periplus/packs/drupal@0.1.0/field/field_storage_config.yaml +24 -0
- periplus/packs/drupal@0.1.0/form/form.yaml +48 -0
- periplus/packs/drupal@0.1.0/form/form_class.yaml +50 -0
- periplus/packs/drupal@0.1.0/form/form_id.yaml +48 -0
- periplus/packs/drupal@0.1.0/form/form_methods.yaml +39 -0
- periplus/packs/drupal@0.1.0/hook/hook.yaml +8 -0
- periplus/packs/drupal@0.1.0/hook/hook_attribute.yaml +28 -0
- periplus/packs/drupal@0.1.0/module/module.yaml +8 -0
- periplus/packs/drupal@0.1.0/module/module_info.yaml +50 -0
- periplus/packs/drupal@0.1.0/pack.yaml +184 -0
- periplus/packs/drupal@0.1.0/plugin/plugin.yaml +17 -0
- periplus/packs/drupal@0.1.0/plugin/plugin_annotation.yaml +120 -0
- periplus/packs/drupal@0.1.0/recommendations/recommendations.yaml +14 -0
- periplus/packs/drupal@0.1.0/service/service.yaml +19 -0
- periplus/packs/drupal@0.1.0/service/service_autowire.yaml +28 -0
- periplus/packs/drupal@0.1.0/service/service_definition.yaml +24 -0
- periplus/packs/drupal@0.1.0/service/service_use.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/action/action.yaml +9 -0
- periplus/packs/drupal_basic@0.3.0/action/action_annotation.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/action/action_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/block/block_placement.yaml +16 -0
- periplus/packs/drupal_basic@0.3.0/block/block_placement_config.yaml +51 -0
- periplus/packs/drupal_basic@0.3.0/block_plugin/block_plugin.yaml +14 -0
- periplus/packs/drupal_basic@0.3.0/block_plugin/block_plugin_annotation.yaml +47 -0
- periplus/packs/drupal_basic@0.3.0/block_plugin/block_plugin_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/block_type/block_type.yaml +8 -0
- periplus/packs/drupal_basic@0.3.0/block_type/block_type_config.yaml +54 -0
- periplus/packs/drupal_basic@0.3.0/boundary/boundary_types.yaml +19 -0
- periplus/packs/drupal_basic@0.3.0/bundle/bundle.yaml +20 -0
- periplus/packs/drupal_basic@0.3.0/bundle/bundle_config.yaml +393 -0
- periplus/packs/drupal_basic@0.3.0/call/call.yaml +349 -0
- periplus/packs/drupal_basic@0.3.0/component/component.yaml +30 -0
- periplus/packs/drupal_basic@0.3.0/config/config_object.yaml +119 -0
- periplus/packs/drupal_basic@0.3.0/constraint/constraint.yaml +8 -0
- periplus/packs/drupal_basic@0.3.0/constraint/constraint_annotation.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/constraint/constraint_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/display/display.yaml +30 -0
- periplus/packs/drupal_basic@0.3.0/display/display_config.yaml +203 -0
- periplus/packs/drupal_basic@0.3.0/display/display_mode_config.yaml +60 -0
- periplus/packs/drupal_basic@0.3.0/entity_type/config_entity_type_annotation.yaml +46 -0
- periplus/packs/drupal_basic@0.3.0/entity_type/config_entity_type_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/entity_type/content_entity_type_annotation.yaml +46 -0
- periplus/packs/drupal_basic@0.3.0/entity_type/content_entity_type_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/entity_type/entity_type.yaml +16 -0
- periplus/packs/drupal_basic@0.3.0/field/field_instance_config.yaml +116 -0
- periplus/packs/drupal_basic@0.3.0/field/field_storage.yaml +21 -0
- periplus/packs/drupal_basic@0.3.0/field/field_storage_config.yaml +45 -0
- periplus/packs/drupal_basic@0.3.0/field_formatter/field_formatter.yaml +8 -0
- periplus/packs/drupal_basic@0.3.0/field_formatter/field_formatter_annotation.yaml +46 -0
- periplus/packs/drupal_basic@0.3.0/field_formatter/field_formatter_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/field_type/field_type_annotation.yaml +46 -0
- periplus/packs/drupal_basic@0.3.0/field_type/field_type_attribute.yaml +50 -0
- periplus/packs/drupal_basic@0.3.0/field_widget/field_widget_annotation.yaml +46 -0
- periplus/packs/drupal_basic@0.3.0/field_widget/field_widget_attribute.yaml +50 -0
- periplus/packs/drupal_basic@0.3.0/form/form_id.yaml +80 -0
- periplus/packs/drupal_basic@0.3.0/hook/hook.yaml +100 -0
- periplus/packs/drupal_basic@0.3.0/hook/hook_attribute.yaml +64 -0
- periplus/packs/drupal_basic@0.3.0/hook/hook_theme_include.yaml +34 -0
- periplus/packs/drupal_basic@0.3.0/library/library.yaml +12 -0
- periplus/packs/drupal_basic@0.3.0/library/library_definition.yaml +58 -0
- periplus/packs/drupal_basic@0.3.0/local_action/local_action.yaml +12 -0
- periplus/packs/drupal_basic@0.3.0/local_action/local_action_definition.yaml +49 -0
- periplus/packs/drupal_basic@0.3.0/mail/mail.yaml +8 -0
- periplus/packs/drupal_basic@0.3.0/mail/mail_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/media_source/media_source.yaml +8 -0
- periplus/packs/drupal_basic@0.3.0/media_source/media_source_annotation.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/media_source/media_source_attribute.yaml +79 -0
- periplus/packs/drupal_basic@0.3.0/menu_link/menu_link.yaml +18 -0
- periplus/packs/drupal_basic@0.3.0/menu_link/menu_link_definition.yaml +48 -0
- periplus/packs/drupal_basic@0.3.0/module/module.yaml +7 -0
- periplus/packs/drupal_basic@0.3.0/module/module_info.yaml +58 -0
- periplus/packs/drupal_basic@0.3.0/pack.yaml +528 -0
- periplus/packs/drupal_basic@0.3.0/permission/permission.yaml +7 -0
- periplus/packs/drupal_basic@0.3.0/permission/permission_definition.yaml +27 -0
- periplus/packs/drupal_basic@0.3.0/queue_worker/queue_worker.yaml +9 -0
- periplus/packs/drupal_basic@0.3.0/queue_worker/queue_worker_annotation.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/queue_worker/queue_worker_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/rest_resource/rest_resource.yaml +8 -0
- periplus/packs/drupal_basic@0.3.0/rest_resource/rest_resource_annotation.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/rest_resource/rest_resource_attribute.yaml +43 -0
- periplus/packs/drupal_basic@0.3.0/role/role.yaml +14 -0
- periplus/packs/drupal_basic@0.3.0/role/role_config.yaml +44 -0
- periplus/packs/drupal_basic@0.3.0/route/route.yaml +42 -0
- periplus/packs/drupal_basic@0.3.0/route/route_definition.yaml +113 -0
- periplus/packs/drupal_basic@0.3.0/route/route_options.yaml +55 -0
- periplus/packs/drupal_basic@0.3.0/route/route_requirements.yaml +108 -0
- periplus/packs/drupal_basic@0.3.0/service/service.yaml +56 -0
- periplus/packs/drupal_basic@0.3.0/service/service_definition.yaml +181 -0
- periplus/packs/drupal_basic@0.3.0/template/template.yaml +86 -0
- periplus/packs/drupal_basic@0.3.0/template/template_route_link.yaml +30 -0
- periplus/packs/drupal_basic@0.3.0/theme/theme.yaml +15 -0
- periplus/packs/drupal_basic@0.3.0/theme/theme_info.yaml +61 -0
- periplus/packs/drupal_basic@0.3.0/theme_hook/template_suggestion.yaml +29 -0
- periplus/packs/drupal_basic@0.3.0/theme_hook/theme_hook.yaml +87 -0
- periplus/packs/drupal_basic@0.3.0/theme_hook/theme_hook_render.yaml +20 -0
- periplus/packs/drupal_basic@0.3.0/url/url.yaml +88 -0
- periplus/packs/drupal_basic@0.3.0/views_plugin/views_field_attribute.yaml +80 -0
- periplus/packs/drupal_basic@0.3.0/views_plugin/views_filter_attribute.yaml +80 -0
- periplus/packs/drupal_basic@0.3.0/views_plugin/views_plugin.yaml +15 -0
- periplus/packs/drupal_basic@0.3.0/views_plugin/views_style_attribute.yaml +80 -0
- periplus/packs/drupal_js_basic@0.0.1/attachment/attachment.yaml +12 -0
- periplus/packs/drupal_js_basic@0.0.1/attachment/attachment_in_php.yaml +15 -0
- periplus/packs/drupal_js_basic@0.0.1/attachment/attachment_in_php_array.yaml +52 -0
- periplus/packs/drupal_js_basic@0.0.1/attachment/attachment_in_twig.yaml +26 -0
- periplus/packs/drupal_js_basic@0.0.1/attachment/php_function_holder.yaml +13 -0
- periplus/packs/drupal_js_basic@0.0.1/behavior/behavior.yaml +198 -0
- periplus/packs/drupal_js_basic@0.0.1/pack.yaml +153 -0
- periplus/packs/drupal_js_basic@0.0.1/setting/setting.yaml +13 -0
- periplus/packs/drupal_js_basic@0.0.1/setting/setting_in_js.yaml +15 -0
- periplus/packs/drupal_js_basic@0.0.1/setting/setting_in_php.yaml +92 -0
- periplus/packs/drush_basic@0.0.1/command/command.yaml +15 -0
- periplus/packs/drush_basic@0.0.1/command/command_annotation.yaml +60 -0
- periplus/packs/drush_basic@0.0.1/command/command_attribute.yaml +88 -0
- periplus/packs/drush_basic@0.0.1/pack.yaml +29 -0
- periplus/packs/eck_basic@0.0.1/bundle/eck_bundle_config.yaml +56 -0
- periplus/packs/eck_basic@0.0.1/entity_type/eck_entity_type_config.yaml +26 -0
- periplus/packs/eck_basic@0.0.1/pack.yaml +28 -0
- periplus/packs/go@0.0.2/interfaces/satisfies.yaml +47 -0
- periplus/packs/go@0.0.2/pack.yaml +51 -0
- periplus/packs/go@0.0.2/types/find_declarations.yaml +137 -0
- periplus/packs/go@0.0.2/types/node_types.yaml +36 -0
- periplus/packs/go_basic@0.0.3/pack.yaml +104 -0
- periplus/packs/go_basic@0.0.3/rules/calls.yaml +25 -0
- periplus/packs/go_basic@0.0.3/rules/declarations.yaml +40 -0
- periplus/packs/go_basic@0.0.3/rules/imports.yaml +16 -0
- periplus/packs/go_basic@0.0.3/types/node_types.yaml +15 -0
- periplus/packs/js_basic@0.0.1/function/function.yaml +68 -0
- periplus/packs/js_basic@0.0.1/pack.yaml +50 -0
- periplus/packs/laravel_basic@0.0.5/pack.yaml +313 -0
- periplus/packs/laravel_basic@0.0.5/rules/classes.yaml +42 -0
- periplus/packs/laravel_basic@0.0.5/rules/config.yaml +229 -0
- periplus/packs/laravel_basic@0.0.5/rules/routes.yaml +210 -0
- periplus/packs/laravel_basic@0.0.5/rules/types.yaml +50 -0
- periplus/packs/laravel_basic@0.0.5/rules/views.yaml +100 -0
- periplus/packs/paragraphs_basic@0.0.1/bundle/paragraph_bundle_config.yaml +54 -0
- periplus/packs/paragraphs_basic@0.0.1/pack.yaml +12 -0
- periplus/packs/php@0.1.0/edges/edge_kinds.yaml +64 -0
- periplus/packs/php@0.1.0/edges/find_calls.yaml +34 -0
- periplus/packs/php@0.1.0/edges/find_imports.yaml +18 -0
- periplus/packs/php@0.1.0/edges/find_member_access.yaml +22 -0
- periplus/packs/php@0.1.0/edges/find_structure.yaml +38 -0
- periplus/packs/php@0.1.0/embedded/embedded_regions.yaml +19 -0
- periplus/packs/php@0.1.0/imports/imports.yaml +20 -0
- periplus/packs/php@0.1.0/pack.yaml +117 -0
- periplus/packs/php@0.1.0/resolution/excluded_tokens.yaml +23 -0
- periplus/packs/php@0.1.0/resolution/resolution.yaml +35 -0
- periplus/packs/php@0.1.0/types/find_declarations.yaml +102 -0
- periplus/packs/php@0.1.0/types/node_types.yaml +55 -0
- periplus/packs/php_basic@0.2.0/edges/edge_kinds.yaml +48 -0
- periplus/packs/php_basic@0.2.0/edges/find_structure.yaml +750 -0
- periplus/packs/php_basic@0.2.0/imports/imports.yaml +19 -0
- periplus/packs/php_basic@0.2.0/pack.yaml +94 -0
- periplus/packs/php_basic@0.2.0/types/find_declarations.yaml +267 -0
- periplus/packs/php_basic@0.2.0/types/node_types.yaml +55 -0
- periplus/packs/profile_basic@0.0.1/bundle/profile_bundle_config.yaml +54 -0
- periplus/packs/profile_basic@0.0.1/pack.yaml +12 -0
- periplus/packs/salesforce_basic@0.0.1/event/salesforce_event.yaml +36 -0
- periplus/packs/salesforce_basic@0.0.1/pack.yaml +31 -0
- periplus/packs/salesforce_basic@0.0.1/salesforce_mapping/salesforce_mapping.yaml +19 -0
- periplus/packs/salesforce_basic@0.0.1/salesforce_mapping/salesforce_mapping_config.yaml +83 -0
- periplus/packs/salesforce_basic@0.0.1/salesforce_mapping_field/salesforce_mapping_field.yaml +8 -0
- periplus/packs/salesforce_basic@0.0.1/salesforce_mapping_field/salesforce_mapping_field_annotation.yaml +43 -0
- periplus/packs/twig@0.0.1/pack.yaml +26 -0
- periplus/packs/twig@0.0.1/types/template.yaml +57 -0
- periplus/packs/twig_basic@0.1.0/pack.yaml +11 -0
- periplus/packs/twig_tweak_basic@0.0.1/pack.yaml +27 -0
- periplus/packs/twig_tweak_basic@0.0.1/rules/block.yaml +20 -0
- periplus/packs/twig_tweak_basic@0.0.1/rules/entity.yaml +35 -0
- periplus/packs/twig_tweak_basic@0.0.1/rules/field.yaml +21 -0
- periplus/packs/twig_tweak_basic@0.0.1/rules/menu.yaml +21 -0
- periplus/packs/webform_basic@0.0.1/bundle/webform_submission_bundle_config.yaml +54 -0
- periplus/packs/webform_basic@0.0.1/pack.yaml +20 -0
- periplus/packs/webform_basic@0.0.1/webform_handler/webform_handler.yaml +8 -0
- periplus/packs/webform_basic@0.0.1/webform_handler/webform_handler_annotation.yaml +43 -0
- periplus/packs/yaml@0.0.1/pack.yaml +72 -0
- periplus/packs/yaml@0.0.1/types/find_mapping_entry.yaml +21 -0
- periplus/packs/yaml@0.0.1/types/yaml_types.yaml +44 -0
- periplus/packs/yaml_basic@0.1.0/pack.yaml +10 -0
- periplus/packs.py +447 -0
- periplus/preflight.py +102 -0
- periplus/py.typed +0 -0
- periplus/report.py +596 -0
- periplus/resolution.py +355 -0
- periplus/settings.py +617 -0
- periplus/settings.stub.yml +99 -0
- periplus/spec.py +774 -0
- periplus/update.py +197 -0
- periplus/validate.py +655 -0
- periplus_map-0.2.1.dist-info/METADATA +566 -0
- periplus_map-0.2.1.dist-info/RECORD +272 -0
- periplus_map-0.2.1.dist-info/WHEEL +4 -0
- periplus_map-0.2.1.dist-info/entry_points.txt +2 -0
- periplus_map-0.2.1.dist-info/licenses/LICENSE +202 -0
- periplus_map-0.2.1.dist-info/licenses/NOTICE +2 -0
periplus/settings.py
ADDED
|
@@ -0,0 +1,617 @@
|
|
|
1
|
+
"""Settings resolution: finding the two files, reading one, and merging them key by key.
|
|
2
|
+
|
|
3
|
+
Three separable questions, and they are three functions because they fail independently.
|
|
4
|
+
``locate_settings`` decides *which files apply* and opens nothing, so a file that exists and will
|
|
5
|
+
not parse can be reported as skipped rather than silently becoming absent.
|
|
6
|
+
``load_settings_document`` decides *what is in one file* and knows nothing about layers.
|
|
7
|
+
``resolve_settings`` decides *what wins* and reads no filesystem — it takes documents and
|
|
8
|
+
sources as arguments, which is what lets the whole cascade be tested against constructed values.
|
|
9
|
+
|
|
10
|
+
This is the first module in the package to import a runtime distribution. ``ruamel.yaml`` and
|
|
11
|
+
``platformdirs`` are both imported at module level here, deliberately and visibly: nothing on
|
|
12
|
+
``cli``'s module-level import path may reach this file, which is the property
|
|
13
|
+
``tests/test_console_script.py`` asserts by importing ``periplus.cli`` with both distributions
|
|
14
|
+
blocked. Before this module existed that test could only fail if somebody imported a distribution
|
|
15
|
+
for no reason. From here on it protects something real, because ``cli`` importing ``settings`` at
|
|
16
|
+
module level would break the startup check that names a missing dependency.
|
|
17
|
+
|
|
18
|
+
What this module does not do, because a later component does it:
|
|
19
|
+
|
|
20
|
+
* It does not substitute a brace in a folder value, join a folder to a root, or check that any path
|
|
21
|
+
exists. A ``folders`` value leaves here as written: one template string, or a tuple of them
|
|
22
|
+
for a list. That is the input of a later folder resolver, which is not built yet.
|
|
23
|
+
* It does not parse a ``packs:`` pin into a name and a version, list a directory, or decide whether
|
|
24
|
+
a pack root exists. Pins leave here as the strings the file wrote. That is ``packs.py``.
|
|
25
|
+
* It does not decide whether a failure ends the run, and it does not catch its own exception.
|
|
26
|
+
``resolution.py`` catches ``SettingsUnreadable`` and turns it into a ``Problem`` and a skipped
|
|
27
|
+
source; the "neither file exists" condition is invisible here, because this module is handed
|
|
28
|
+
documents rather than finding them.
|
|
29
|
+
* It validates nothing, by design. What it does do is refuse to *lie*
|
|
30
|
+
about a type: a value whose shape does not match the key's declared type is dropped rather than
|
|
31
|
+
coerced into a tuple of characters. See ``MERGE_RULES``.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
from __future__ import annotations
|
|
35
|
+
|
|
36
|
+
import os
|
|
37
|
+
from collections.abc import Callable, Mapping, Sequence
|
|
38
|
+
from dataclasses import dataclass
|
|
39
|
+
from pathlib import Path
|
|
40
|
+
from typing import Any, Generic, Literal, TypeVar
|
|
41
|
+
|
|
42
|
+
import platformdirs
|
|
43
|
+
from ruamel.yaml import YAML
|
|
44
|
+
from ruamel.yaml.error import YAMLError
|
|
45
|
+
|
|
46
|
+
from periplus.errors import ExitCode, HarnessError
|
|
47
|
+
|
|
48
|
+
# Re-exported, so every caller that imported these from here still can. The redundant alias is
|
|
49
|
+
# the explicit re-export form, and it is what tells the linter the names are deliberate.
|
|
50
|
+
from periplus.layout import PACKS_DIRECTORY as PACKS_DIRECTORY
|
|
51
|
+
from periplus.layout import PROJECT_MARKER as PROJECT_MARKER
|
|
52
|
+
from periplus.layout import SETTINGS_FILENAME as SETTINGS_FILENAME
|
|
53
|
+
|
|
54
|
+
__all__ = [
|
|
55
|
+
"MERGE_RULES",
|
|
56
|
+
"FirstParty",
|
|
57
|
+
"ResolvedSetting",
|
|
58
|
+
"ResolvedSettings",
|
|
59
|
+
"SettingsSource",
|
|
60
|
+
"SettingsUnreadable",
|
|
61
|
+
"SourceRef",
|
|
62
|
+
"find_project_root",
|
|
63
|
+
"load_settings_document",
|
|
64
|
+
"locate_settings",
|
|
65
|
+
"resolve_settings",
|
|
66
|
+
"user_config_dir",
|
|
67
|
+
]
|
|
68
|
+
|
|
69
|
+
T = TypeVar("T")
|
|
70
|
+
|
|
71
|
+
# Three vocabularies are written out at every annotation rather than named once as a module-level
|
|
72
|
+
# alias, which is not the arrangement anyone would choose. A `Literal` alias cannot be verified in
|
|
73
|
+
# an inline-typed package: mypy normalises `Literal["user", "project"]` into a union of two
|
|
74
|
+
# literals, the runtime object is one `_LiteralGenericAlias` and not a union, so a tool that
|
|
75
|
+
# compares the declared types against the imported module reports `SourceKind is not a Union` on a
|
|
76
|
+
# module that is correct. Measured with `mypy.stubtest` on 2026-08-30 — that run was the evidence
|
|
77
|
+
# for this shape, not a check holding it in place; nothing in this project runs stubtest. A leading
|
|
78
|
+
# underscore does not exempt the alias.
|
|
79
|
+
#
|
|
80
|
+
# the two layers that are settings files Literal["user", "project"]
|
|
81
|
+
# A third — a `folders` block inside a pack manifest — would arrive as one more member.
|
|
82
|
+
# what happened to one layer's file Literal["used", "absent", "skipped"]
|
|
83
|
+
# `skipped` is set by the caller that catches a parse failure, never here: the difference
|
|
84
|
+
# between "there is no file" and "there is a file I could not read" is the whole reason
|
|
85
|
+
# locating and loading are two functions.
|
|
86
|
+
# how one settings key merges Literal["replace", "union", "accumulate", "per_key",
|
|
87
|
+
# "paired"]
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
#: The environment variable that replaces the user configuration directory outright.
|
|
91
|
+
CONFIG_DIR_VARIABLE = "PERIPLUS_CONFIG_DIR"
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@dataclass(frozen=True, slots=True)
|
|
95
|
+
class SourceRef:
|
|
96
|
+
"""Which settings file an effective value came from, as it is printed beside that value."""
|
|
97
|
+
|
|
98
|
+
kind: Literal["user", "project"]
|
|
99
|
+
name: str
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
@dataclass(frozen=True, slots=True)
|
|
103
|
+
class SettingsSource:
|
|
104
|
+
"""One layer's file: where it is, what a relative path in it means, and what happened to it.
|
|
105
|
+
|
|
106
|
+
``root`` carries the anchor rather than leaving it to be derived, which is what makes "a
|
|
107
|
+
relative path resolves against the root of the file that declared it" structural instead of a
|
|
108
|
+
rule the merge has to remember. The two layers do not derive it the same way — the project
|
|
109
|
+
file's root is its grandparent, because the file is ``<root>/.periplus/settings.yml``, and the
|
|
110
|
+
user file's root is its parent — and an explicit ``--settings PATH`` breaks both derivations.
|
|
111
|
+
Computing it once where the file is located removes the question from every later reader.
|
|
112
|
+
"""
|
|
113
|
+
|
|
114
|
+
kind: Literal["user", "project"]
|
|
115
|
+
path: Path
|
|
116
|
+
root: Path
|
|
117
|
+
status: Literal["used", "absent", "skipped"]
|
|
118
|
+
reason: str | None
|
|
119
|
+
|
|
120
|
+
def ref(self) -> SourceRef:
|
|
121
|
+
"""This source as the reference an effective value carries.
|
|
122
|
+
|
|
123
|
+
The one place a ``SourceRef.name`` is built from a path, so the two cannot drift.
|
|
124
|
+
"""
|
|
125
|
+
return SourceRef(kind=self.kind, name=str(self.path))
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@dataclass(frozen=True, slots=True)
|
|
129
|
+
class ResolvedSetting(Generic[T]):
|
|
130
|
+
"""An effective value and every file that had a say in it.
|
|
131
|
+
|
|
132
|
+
There is no way to hold a value without holding where it came from, which is what makes
|
|
133
|
+
research's visibility requirement structural rather than a convention.
|
|
134
|
+
|
|
135
|
+
``sources`` is in cascade order — user first, then project. A key merged by replacement carries
|
|
136
|
+
exactly one entry, the file that won. A key merged by accumulation carries one entry per file
|
|
137
|
+
that declared it, including a file that declared it empty: presence is what makes a file a
|
|
138
|
+
source, not whether its contribution changed the answer.
|
|
139
|
+
|
|
140
|
+
``sources`` attributes the *key* and not the *entries in it*, and for a key that accumulates
|
|
141
|
+
those are different facts. Given a ``pack_paths`` of ``(pathA, pathB)`` and a ``sources`` of
|
|
142
|
+
``(user, project)``, nothing says which file added which path — so ``packs.py``'s
|
|
143
|
+
``PackRoot.source``, "which settings file added a configured root", would have to guess, and
|
|
144
|
+
would guess plausibly and silently. ``entry_sources`` is that missing fact: one ``SourceRef``
|
|
145
|
+
per element of ``value``, in the same order, for the keys that accumulate. It is ``None`` for
|
|
146
|
+
every other key, which says "there is nothing per-entry to say here" rather than repeating one
|
|
147
|
+
file N times — a replace key's entries all came from the one file ``sources`` already names.
|
|
148
|
+
|
|
149
|
+
One reference per entry, in the same order, holds by construction rather than by a check.
|
|
150
|
+
``_merge_sequence`` is the only code that builds a non-``None`` ``entry_sources``, and it
|
|
151
|
+
appends to ``values`` and to ``entry_sources`` in one loop body, so the two cannot come out of
|
|
152
|
+
step. A later builder that does not append in lockstep carries that check itself: the defect is
|
|
153
|
+
an ``entry_sources`` short by one, which type-checks, reads correctly, and reaches a report as
|
|
154
|
+
a misattribution rather than as a crash.
|
|
155
|
+
|
|
156
|
+
One gap this does not close, stated so it is not mistaken for closed: ``first_party``
|
|
157
|
+
accumulates two lists inside one ``FirstParty`` value, so a flat tuple of the same length as
|
|
158
|
+
``value`` cannot describe it. Its ``entry_sources`` is ``None``, and per-entry attribution for
|
|
159
|
+
its two lists is unavailable. ``pack_paths`` is the key that needs it.
|
|
160
|
+
"""
|
|
161
|
+
|
|
162
|
+
value: T
|
|
163
|
+
sources: tuple[SourceRef, ...]
|
|
164
|
+
entry_sources: tuple[SourceRef, ...] | None = None
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
@dataclass(frozen=True, slots=True)
|
|
168
|
+
class FirstParty:
|
|
169
|
+
"""The two path-pattern lists that decide where the codebase ends and its dependencies begin.
|
|
170
|
+
|
|
171
|
+
Both accumulate across layers, so this is one setting holding two lists rather than two
|
|
172
|
+
settings — ``ResolvedSetting[FirstParty]`` — and it means the sources are the files that
|
|
173
|
+
contributed to either list.
|
|
174
|
+
"""
|
|
175
|
+
|
|
176
|
+
include: tuple[str, ...]
|
|
177
|
+
exclude: tuple[str, ...]
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
@dataclass(frozen=True, slots=True)
|
|
181
|
+
class ResolvedSettings:
|
|
182
|
+
"""Every settings key, merged, with its sources. A key no file declared is ``None``.
|
|
183
|
+
|
|
184
|
+
``None`` rather than an empty tuple or a machine default, because a key that fell through to
|
|
185
|
+
nothing is exactly the case the output has to make visible: the cascade deliberately does not
|
|
186
|
+
forbid it, and a fabricated default would print as though somebody had chosen it.
|
|
187
|
+
|
|
188
|
+
``folders`` and ``extensions`` are mappings rather than optionals for the same reason in the
|
|
189
|
+
opposite direction — an empty mapping already says "no folder was declared anywhere", and
|
|
190
|
+
wrapping it in an optional would give two ways to write the same fact.
|
|
191
|
+
"""
|
|
192
|
+
|
|
193
|
+
periplus_version: ResolvedSetting[int] | None
|
|
194
|
+
packs: ResolvedSetting[tuple[str, ...]] | None
|
|
195
|
+
pack_paths: ResolvedSetting[tuple[Path, ...]] | None
|
|
196
|
+
folders: Mapping[str, ResolvedSetting[str | tuple[str, ...]]]
|
|
197
|
+
extensions: Mapping[str, ResolvedSetting[str]]
|
|
198
|
+
first_party: ResolvedSetting[FirstParty] | None
|
|
199
|
+
exclude: ResolvedSetting[tuple[str, ...]] | None
|
|
200
|
+
re_include: ResolvedSetting[tuple[str, ...]] | None
|
|
201
|
+
accepted_unknowns: ResolvedSetting[tuple[Mapping[str, object], ...]] | None
|
|
202
|
+
#: The named text values every template of every pack may name, merged as ``extensions`` is.
|
|
203
|
+
values: Mapping[str, ResolvedSetting[str]]
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
class SettingsUnreadable(HarnessError):
|
|
207
|
+
"""A settings file exists and could not be turned into a mapping.
|
|
208
|
+
|
|
209
|
+
One class for four causes — the bytes could not be read, they could not be decoded, the parser
|
|
210
|
+
refused them, or the document parsed into something that is not a mapping — because they are one
|
|
211
|
+
thing to do about it: open the file and fix it. ``detail`` names which one it was.
|
|
212
|
+
|
|
213
|
+
This is the only ``HarnessError`` subclass this module ships. There is deliberately no
|
|
214
|
+
``SettingsNotFound``: this module never sees the "neither file exists" condition, because it
|
|
215
|
+
takes documents and sources as arguments. That detection belongs to ``resolution.py``.
|
|
216
|
+
"""
|
|
217
|
+
|
|
218
|
+
code = ExitCode.UNREADABLE_SETTINGS
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def find_project_root(start: Path) -> Path | None:
|
|
222
|
+
"""The nearest directory at or above ``start`` that holds a ``.periplus/`` directory.
|
|
223
|
+
|
|
224
|
+
Lexical, and never ``resolve()``d. Following a symlink here would report a project root the
|
|
225
|
+
person never wrote and never navigated through, and the walk would leave the tree it was asked
|
|
226
|
+
about. ``Path.parents`` is a lexical sequence, so a symlinked parent cannot send the walk
|
|
227
|
+
somewhere unrelated; it stops at the filesystem root and returns ``None``.
|
|
228
|
+
|
|
229
|
+
The marker is a directory, not a file, for the reason ``git`` looks for ``.git`` — the same
|
|
230
|
+
directory holds the settings file and the project's own packs, so one marker answers both.
|
|
231
|
+
"""
|
|
232
|
+
for directory in (start, *start.parents):
|
|
233
|
+
if (directory / PROJECT_MARKER).is_dir():
|
|
234
|
+
return directory
|
|
235
|
+
return None
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def user_config_dir(env: Mapping[str, str]) -> Path:
|
|
239
|
+
"""Periplus' own configuration directory — ``~/.config/periplus`` on Linux, not ``~/.config``.
|
|
240
|
+
|
|
241
|
+
One function returns one level whichever branch produced it, which is what
|
|
242
|
+
``PERIPLUS_CONFIG_DIR`` forces: a variable named for this tool cannot sensibly point at the
|
|
243
|
+
directory holding every tool's configuration. So the user settings file is
|
|
244
|
+
``<user config dir>/settings.yml`` and the user pack root is ``<user config dir>/packs/``, with
|
|
245
|
+
no ``periplus`` segment appended by us.
|
|
246
|
+
|
|
247
|
+
The environment is an argument rather than something this function reads, so a test moves the
|
|
248
|
+
user layer without monkeypatching a module — and what it reads out of that argument is
|
|
249
|
+
``PERIPLUS_CONFIG_DIR`` alone. Everything else is ``platformdirs``, which reads the process
|
|
250
|
+
environment itself: ``XDG_CONFIG_HOME`` on POSIX, ``%APPDATA%`` on Windows,
|
|
251
|
+
``~/Library/Application Support`` on macOS. Verified 2026-08-30 against platformdirs 4.11.5 that
|
|
252
|
+
``user_config_dir()`` accepts no environment argument and reads ``os.environ`` at
|
|
253
|
+
``unix.py:326``, so an ``XDG_CONFIG_HOME`` passed through this mapping would be read by nothing
|
|
254
|
+
and offering it would be a decoration on the one variable that matters.
|
|
255
|
+
|
|
256
|
+
``appauthor=False`` is load-bearing on Windows and inert everywhere else: left at ``None``,
|
|
257
|
+
platformdirs uses the app name as the author directory and returns
|
|
258
|
+
``%APPDATA%\\periplus\\periplus``.
|
|
259
|
+
"""
|
|
260
|
+
override = env.get(CONFIG_DIR_VARIABLE)
|
|
261
|
+
if override:
|
|
262
|
+
return Path(override)
|
|
263
|
+
return Path(platformdirs.user_config_dir("periplus", appauthor=False))
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def locate_settings(
|
|
267
|
+
project_root: Path | None,
|
|
268
|
+
user_config_dir: Path | None,
|
|
269
|
+
settings_path: Path | None = None,
|
|
270
|
+
) -> tuple[SettingsSource, ...]:
|
|
271
|
+
"""One record per layer whose file location is knowable, in cascade order: user, then project.
|
|
272
|
+
|
|
273
|
+
Opens nothing. A layer whose file is not there comes back ``absent`` rather than being left out,
|
|
274
|
+
because the report has to name the file it did not find.
|
|
275
|
+
|
|
276
|
+
A layer appears at all only when its location can be named. ``user_config_dir=None`` means the
|
|
277
|
+
user layer was not consulted, and a project layer with neither a root nor an explicit file has
|
|
278
|
+
no path to report as absent.
|
|
279
|
+
|
|
280
|
+
The project source's root is ``project_root`` when one is given, and otherwise derived from
|
|
281
|
+
``settings_path`` by one rule: a file at ``X/.periplus/settings.yml`` anchors to ``X``,
|
|
282
|
+
and any other file anchors to its own directory. So the contract for the caller is one line —
|
|
283
|
+
pass the root when something decided it, and pass ``settings_path`` with ``project_root=None``
|
|
284
|
+
to get the ``--settings`` rule. Deciding between ``--project-root``, ``--settings`` and the walk
|
|
285
|
+
is the caller's, because only it knows which flag the person typed.
|
|
286
|
+
"""
|
|
287
|
+
sources: list[SettingsSource] = []
|
|
288
|
+
|
|
289
|
+
if user_config_dir is not None:
|
|
290
|
+
sources.append(_source("user", user_config_dir / SETTINGS_FILENAME, user_config_dir))
|
|
291
|
+
|
|
292
|
+
if settings_path is not None:
|
|
293
|
+
sources.append(_source("project", settings_path, project_root or _anchor_of(settings_path)))
|
|
294
|
+
elif project_root is not None:
|
|
295
|
+
path = project_root / PROJECT_MARKER / SETTINGS_FILENAME
|
|
296
|
+
sources.append(_source("project", path, project_root))
|
|
297
|
+
|
|
298
|
+
return tuple(sources)
|
|
299
|
+
|
|
300
|
+
|
|
301
|
+
def _anchor_of(settings_path: Path) -> Path:
|
|
302
|
+
"""The project root an explicitly named settings file implies.
|
|
303
|
+
|
|
304
|
+
A file at ``X/.periplus/settings.yml`` fixes the root at ``X``, so a person pointing
|
|
305
|
+
at a real project's file gets that project's root and the two can never disagree. Any other file
|
|
306
|
+
anchors to its own directory, which is the only answer available and the one that keeps a
|
|
307
|
+
relative ``pack_paths`` entry beside the file that wrote it.
|
|
308
|
+
"""
|
|
309
|
+
parent = settings_path.parent
|
|
310
|
+
return parent.parent if parent.name == PROJECT_MARKER else parent
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def _source(kind: Literal["user", "project"], path: Path, root: Path) -> SettingsSource:
|
|
314
|
+
"""One located layer. ``is_file()`` is the only filesystem call; the file is not opened."""
|
|
315
|
+
return SettingsSource(
|
|
316
|
+
kind=kind,
|
|
317
|
+
path=path,
|
|
318
|
+
root=root,
|
|
319
|
+
status="used" if path.is_file() else "absent",
|
|
320
|
+
reason=None,
|
|
321
|
+
)
|
|
322
|
+
|
|
323
|
+
|
|
324
|
+
def load_settings_document(path: Path) -> Mapping[str, object]:
|
|
325
|
+
"""Read one settings file into a mapping, or raise ``SettingsUnreadable``.
|
|
326
|
+
|
|
327
|
+
``YAML(typ='safe', pure=True)``. ``safe`` refuses arbitrary object construction and is YAML 1.2,
|
|
328
|
+
which is the whole reason ruamel is here rather than PyYAML: verified 2026-08-30 on 0.19.1, a
|
|
329
|
+
duplicate key raises where PyYAML keeps the last value silently, and ``12:30``, ``on``, ``yes``
|
|
330
|
+
and ``no`` stay the strings they were written as, where PyYAML makes the first of those the
|
|
331
|
+
integer 750. ``pure`` pins the pure-Python parser, which ruamel would otherwise swap for the C
|
|
332
|
+
one whenever the optional ``ruamel.yaml.clib`` extension happens to be importable — an
|
|
333
|
+
environment-dependent branch in a tool that promises output that is byte-identical
|
|
334
|
+
across machines.
|
|
335
|
+
|
|
336
|
+
One ``except`` covers every parser refusal, because ``DuplicateKeyError``, ``ParserError`` and
|
|
337
|
+
``ScannerError`` all subclass ``YAMLError``; the parser's own message, marks and all, goes into
|
|
338
|
+
``detail`` rather than into the one line a person reads.
|
|
339
|
+
|
|
340
|
+
``OSError`` and ``UnicodeDecodeError`` are caught for the same exit code, because exit 4
|
|
341
|
+
means "a settings file could not be read **or** parsed", and a person gets a named
|
|
342
|
+
failure rather than a traceback. A settings file that is a directory, or unreadable, or holds
|
|
343
|
+
bytes that are not UTF-8, reaches a person as a line naming the file.
|
|
344
|
+
|
|
345
|
+
An empty file loads as ``None`` and a scalar or a list document loads as a ``str`` or a
|
|
346
|
+
``list``. All three are valid YAML that is not a settings file, and all three are exit 4 — the
|
|
347
|
+
check is here rather than in the parser because no parser has an opinion about it.
|
|
348
|
+
|
|
349
|
+
Keys are not checked. A key the settings schema does not name is ignored by the merge without
|
|
350
|
+
comment, whatever its type, because this module validates nothing.
|
|
351
|
+
"""
|
|
352
|
+
yaml = YAML(typ="safe", pure=True)
|
|
353
|
+
try:
|
|
354
|
+
with path.open("r", encoding="utf-8") as stream:
|
|
355
|
+
document = yaml.load(stream)
|
|
356
|
+
except YAMLError as error:
|
|
357
|
+
raise SettingsUnreadable(
|
|
358
|
+
f"the settings file could not be parsed: {path}",
|
|
359
|
+
{"path": str(path), "cause": "parser", "detail": str(error)},
|
|
360
|
+
) from error
|
|
361
|
+
except UnicodeDecodeError as error:
|
|
362
|
+
raise SettingsUnreadable(
|
|
363
|
+
f"the settings file is not valid UTF-8: {path}",
|
|
364
|
+
{"path": str(path), "cause": "encoding", "detail": str(error)},
|
|
365
|
+
) from error
|
|
366
|
+
except OSError as error:
|
|
367
|
+
raise SettingsUnreadable(
|
|
368
|
+
f"the settings file could not be read: {path}",
|
|
369
|
+
{"path": str(path), "cause": "read", "detail": str(error)},
|
|
370
|
+
) from error
|
|
371
|
+
|
|
372
|
+
if not isinstance(document, Mapping):
|
|
373
|
+
raise SettingsUnreadable(
|
|
374
|
+
f"the settings file is not a mapping: {path}",
|
|
375
|
+
{"path": str(path), "cause": "shape", "detail": type(document).__name__},
|
|
376
|
+
)
|
|
377
|
+
return document
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
def _as_int(value: object) -> int | None:
|
|
381
|
+
"""An integer, and not a ``bool`` wearing one. ``periplus_version: true`` is not version 1."""
|
|
382
|
+
if isinstance(value, bool):
|
|
383
|
+
return None
|
|
384
|
+
return value if isinstance(value, int) else None
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
def _as_strings(value: object) -> tuple[str, ...] | None:
|
|
388
|
+
"""A list of strings, all of them, or nothing at all."""
|
|
389
|
+
if isinstance(value, list | tuple) and all(isinstance(item, str) for item in value):
|
|
390
|
+
return tuple(value)
|
|
391
|
+
return None
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def _as_string_mapping(value: object) -> Mapping[str, str] | None:
|
|
395
|
+
"""A mapping of string to string, all of them, or nothing at all."""
|
|
396
|
+
if isinstance(value, Mapping) and all(
|
|
397
|
+
isinstance(key, str) and isinstance(item, str) for key, item in value.items()
|
|
398
|
+
):
|
|
399
|
+
return dict(value)
|
|
400
|
+
return None
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
def _as_folder_mapping(value: object) -> Mapping[str, str | tuple[str, ...]] | None:
|
|
404
|
+
"""A mapping of string to a string or a non-empty list of strings, all of them, or nothing."""
|
|
405
|
+
if isinstance(value, Mapping) and all(
|
|
406
|
+
isinstance(key, str)
|
|
407
|
+
and (
|
|
408
|
+
isinstance(item, str)
|
|
409
|
+
or (isinstance(item, list) and item and _as_strings(item) is not None)
|
|
410
|
+
)
|
|
411
|
+
for key, item in value.items()
|
|
412
|
+
):
|
|
413
|
+
return {key: item if isinstance(item, str) else tuple(item) for key, item in value.items()}
|
|
414
|
+
return None
|
|
415
|
+
|
|
416
|
+
|
|
417
|
+
def _as_mappings(value: object) -> tuple[Mapping[str, object], ...] | None:
|
|
418
|
+
"""A list of string-keyed mappings, whatever their values are.
|
|
419
|
+
|
|
420
|
+
The values are deliberately not required to be strings. An ``accepted_unknowns`` entry's
|
|
421
|
+
``accepted_on`` is a date, and an unquoted ``2026-08-28`` loads as a ``datetime.date`` under
|
|
422
|
+
``typ='safe'`` — measured, not assumed. Requiring ``str`` here would silently delete a
|
|
423
|
+
legitimate entry from a person's file to satisfy a type annotation.
|
|
424
|
+
"""
|
|
425
|
+
if isinstance(value, list | tuple) and all(
|
|
426
|
+
isinstance(item, Mapping) and all(isinstance(key, str) for key in item) for item in value
|
|
427
|
+
):
|
|
428
|
+
return tuple(dict(item) for item in value)
|
|
429
|
+
return None
|
|
430
|
+
|
|
431
|
+
|
|
432
|
+
def _as_first_party(value: object) -> FirstParty | None:
|
|
433
|
+
"""A ``first_party`` block. A missing or malformed half is an empty list, not a refusal."""
|
|
434
|
+
if not isinstance(value, Mapping):
|
|
435
|
+
return None
|
|
436
|
+
return FirstParty(
|
|
437
|
+
include=_as_strings(value.get("include", [])) or (),
|
|
438
|
+
exclude=_as_strings(value.get("exclude", [])) or (),
|
|
439
|
+
)
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
@dataclass(frozen=True, slots=True)
|
|
443
|
+
class _Rule:
|
|
444
|
+
"""How one settings key merges across layers, and what shape its value has to be.
|
|
445
|
+
|
|
446
|
+
``coerce`` is part of the rule rather than a step beside it, because the two are one decision:
|
|
447
|
+
the behaviour says which contributions combine and the coercion says which ones count. A
|
|
448
|
+
contribution the coercion rejects is dropped exactly like a key the schema does not name.
|
|
449
|
+
"""
|
|
450
|
+
|
|
451
|
+
behaviour: Literal["replace", "union", "accumulate", "per_key", "paired"]
|
|
452
|
+
coerce: Callable[[object], Any]
|
|
453
|
+
anchor: bool = False
|
|
454
|
+
|
|
455
|
+
|
|
456
|
+
#: The merge rule for every key the settings schema names, keyed by the name. Data, not branches:
|
|
457
|
+
#: a new key in the settings schema is a row here and a field on ``ResolvedSettings``, never a
|
|
458
|
+
#: condition inside the merge.
|
|
459
|
+
#:
|
|
460
|
+
#: "Scalars — last wins" and "``packs`` — replace" are
|
|
461
|
+
#: one operation: take the last file that declared the key. One row kind, two names in prose.
|
|
462
|
+
#:
|
|
463
|
+
#: Only ``pack_paths`` sets ``anchor``, which turns each relative string into a path under the root
|
|
464
|
+
#: of the file that declared it. ``folders`` values are templates that a later folder resolver will
|
|
465
|
+
#: join to the project root, so they are stored exactly as written, braces intact.
|
|
466
|
+
MERGE_RULES: Mapping[str, _Rule] = {
|
|
467
|
+
"periplus_version": _Rule("replace", _as_int),
|
|
468
|
+
"packs": _Rule("replace", _as_strings),
|
|
469
|
+
"pack_paths": _Rule("union", _as_strings, anchor=True),
|
|
470
|
+
"folders": _Rule("per_key", _as_folder_mapping),
|
|
471
|
+
"extensions": _Rule("per_key", _as_string_mapping),
|
|
472
|
+
"first_party": _Rule("paired", _as_first_party),
|
|
473
|
+
"exclude": _Rule("accumulate", _as_strings),
|
|
474
|
+
"re_include": _Rule("accumulate", _as_strings),
|
|
475
|
+
"accepted_unknowns": _Rule("accumulate", _as_mappings),
|
|
476
|
+
"values": _Rule("per_key", _as_string_mapping),
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
|
|
480
|
+
def _anchor_path(root: Path, value: str) -> Path:
|
|
481
|
+
"""``value`` as an absolute path under ``root``, normalised lexically and never resolved.
|
|
482
|
+
|
|
483
|
+
An absolute entry is kept exactly as written. A relative one is joined and normalised with
|
|
484
|
+
``os.path.normpath``, which collapses ``..`` textually; ``Path.resolve()`` would follow a
|
|
485
|
+
symlink and print a directory the person never named.
|
|
486
|
+
"""
|
|
487
|
+
candidate = Path(value)
|
|
488
|
+
if candidate.is_absolute():
|
|
489
|
+
return candidate
|
|
490
|
+
return Path(os.path.normpath(root / candidate))
|
|
491
|
+
|
|
492
|
+
|
|
493
|
+
def _merge_key(
|
|
494
|
+
name: str, rule: _Rule, layers: Sequence[tuple[SettingsSource, Mapping[str, object]]]
|
|
495
|
+
) -> Any: # noqa: ANN401 - the return type is the field's, and the field declares it
|
|
496
|
+
"""Merge one key across every layer that declared it, in cascade order.
|
|
497
|
+
|
|
498
|
+
Returns ``None`` for a key no layer declared, except under ``per_key``, where the empty mapping
|
|
499
|
+
already says it.
|
|
500
|
+
"""
|
|
501
|
+
contributions = [
|
|
502
|
+
(source, coerced)
|
|
503
|
+
for source, document in layers
|
|
504
|
+
if name in document and (coerced := rule.coerce(document[name])) is not None
|
|
505
|
+
]
|
|
506
|
+
|
|
507
|
+
if rule.behaviour == "per_key":
|
|
508
|
+
return _merge_per_key(contributions)
|
|
509
|
+
if not contributions:
|
|
510
|
+
return None
|
|
511
|
+
if rule.behaviour == "replace":
|
|
512
|
+
source, value = contributions[-1]
|
|
513
|
+
return ResolvedSetting(value=value, sources=(source.ref(),))
|
|
514
|
+
if rule.behaviour == "paired":
|
|
515
|
+
return ResolvedSetting(
|
|
516
|
+
value=FirstParty(
|
|
517
|
+
include=tuple(item for _, value in contributions for item in value.include),
|
|
518
|
+
exclude=tuple(item for _, value in contributions for item in value.exclude),
|
|
519
|
+
),
|
|
520
|
+
sources=tuple(source.ref() for source, _ in contributions),
|
|
521
|
+
)
|
|
522
|
+
return _merge_sequence(contributions, rule)
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
def _merge_per_key(
|
|
526
|
+
contributions: Sequence[tuple[SettingsSource, Mapping[str, str]]],
|
|
527
|
+
) -> Mapping[str, ResolvedSetting[str]]:
|
|
528
|
+
"""A mapping merged entry by entry: for each name, the last layer that declared *that name*.
|
|
529
|
+
|
|
530
|
+
Each entry carries the one file that won it, which is what makes the fell-through case visible —
|
|
531
|
+
a name only the user file declares survives into the result carrying the user file as its
|
|
532
|
+
source, beside a name the project file overrode carrying the project file.
|
|
533
|
+
|
|
534
|
+
Sorted by name. ``report.py`` sorts everything it prints, but this mapping is a value a second
|
|
535
|
+
consumer can hold, and a mapping that reaches anyone in the order a YAML file happened to be
|
|
536
|
+
written in is a determinism defect waiting for a consumer that does not sort.
|
|
537
|
+
"""
|
|
538
|
+
merged: dict[str, ResolvedSetting[str]] = {}
|
|
539
|
+
for source, mapping in contributions:
|
|
540
|
+
for name, value in mapping.items():
|
|
541
|
+
merged[name] = ResolvedSetting(value=value, sources=(source.ref(),))
|
|
542
|
+
return dict(sorted(merged.items()))
|
|
543
|
+
|
|
544
|
+
|
|
545
|
+
def _merge_sequence(
|
|
546
|
+
contributions: Sequence[tuple[SettingsSource, tuple[Any, ...]]], rule: _Rule
|
|
547
|
+
) -> ResolvedSetting[tuple[Any, ...]]:
|
|
548
|
+
"""Concatenate every layer's list in cascade order.
|
|
549
|
+
|
|
550
|
+
``union`` drops a repeat and ``accumulate`` keeps it, and the difference is not cosmetic.
|
|
551
|
+
``pack_paths`` names directories to search: the same directory reached from two files is one
|
|
552
|
+
place to look, and listing it twice would make one pack directory match a pin under two roots
|
|
553
|
+
and fail the run at exit 6 for a duplicate that does not exist. ``exclude`` and ``re_include``
|
|
554
|
+
are ordered patterns where a repeat costs nothing and removing one would quietly reorder the
|
|
555
|
+
rest.
|
|
556
|
+
|
|
557
|
+
De-duplication keeps the first occurrence, so the earliest layer that named a path fixes its
|
|
558
|
+
position, and every layer that named it stays in ``sources``. It is also the layer the surviving
|
|
559
|
+
entry is attributed to: a directory both files name was added by the earlier one, and the later
|
|
560
|
+
one changed nothing about where it sits in the search order.
|
|
561
|
+
|
|
562
|
+
``entry_sources`` is built here, in the loop, and not derived afterwards. The declaring source
|
|
563
|
+
is in hand at the moment each item is appended and nowhere else; once the values are
|
|
564
|
+
concatenated the fact is gone. That is why per-entry attribution cannot be added to a merge
|
|
565
|
+
that did not collect it.
|
|
566
|
+
"""
|
|
567
|
+
values: list[Any] = []
|
|
568
|
+
entry_sources: list[SourceRef] = []
|
|
569
|
+
for source, value in contributions:
|
|
570
|
+
for item in value:
|
|
571
|
+
item = _anchor_path(source.root, item) if rule.anchor else item
|
|
572
|
+
if rule.behaviour == "union" and item in values:
|
|
573
|
+
continue
|
|
574
|
+
values.append(item)
|
|
575
|
+
entry_sources.append(source.ref())
|
|
576
|
+
return ResolvedSetting(
|
|
577
|
+
value=tuple(values),
|
|
578
|
+
sources=tuple(source.ref() for source, _ in contributions),
|
|
579
|
+
entry_sources=tuple(entry_sources),
|
|
580
|
+
)
|
|
581
|
+
|
|
582
|
+
|
|
583
|
+
def resolve_settings(
|
|
584
|
+
user: Mapping[str, object] | None,
|
|
585
|
+
project: Mapping[str, object] | None,
|
|
586
|
+
sources: Sequence[SettingsSource],
|
|
587
|
+
) -> ResolvedSettings:
|
|
588
|
+
"""Merge the layers into one record where every effective value names the files behind it.
|
|
589
|
+
|
|
590
|
+
The cascade is ``sources``' own order rather than a hardcoded user-then-project, so the order
|
|
591
|
+
``locate_settings`` returns is the order that applies and can be tested by reordering it.
|
|
592
|
+
|
|
593
|
+
A document is paired with the source of its own ``kind``, which is where a relative path in it
|
|
594
|
+
gets its anchor from. A layer contributes only when both halves are present: a ``used`` source
|
|
595
|
+
with no document, and a document for a layer that has no ``used`` source, are each skipped.
|
|
596
|
+
Neither can come from a person's input — only from wiring — and ``resolution.py``, the one
|
|
597
|
+
caller, builds this mapping from the same ``sources`` tuple it passes in.
|
|
598
|
+
"""
|
|
599
|
+
documents: dict[str, Mapping[str, object] | None] = {"user": user, "project": project}
|
|
600
|
+
layers = [
|
|
601
|
+
(source, document)
|
|
602
|
+
for source in sources
|
|
603
|
+
if source.status == "used" and (document := documents[source.kind]) is not None
|
|
604
|
+
]
|
|
605
|
+
merged = {name: _merge_key(name, rule, layers) for name, rule in MERGE_RULES.items()}
|
|
606
|
+
return ResolvedSettings(
|
|
607
|
+
periplus_version=merged["periplus_version"],
|
|
608
|
+
packs=merged["packs"],
|
|
609
|
+
pack_paths=merged["pack_paths"],
|
|
610
|
+
folders=merged["folders"],
|
|
611
|
+
extensions=merged["extensions"],
|
|
612
|
+
first_party=merged["first_party"],
|
|
613
|
+
exclude=merged["exclude"],
|
|
614
|
+
re_include=merged["re_include"],
|
|
615
|
+
accepted_unknowns=merged["accepted_unknowns"],
|
|
616
|
+
values=merged["values"],
|
|
617
|
+
)
|