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/errors.py
ADDED
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
"""The error vocabulary: the exit-code table, the record a failure renders into, and the base
|
|
2
|
+
class every failing module raises.
|
|
3
|
+
|
|
4
|
+
Every module in the package imports this one, and ``cli`` imports it at module level — before the
|
|
5
|
+
dependency check has run. That places one constraint on this file, and the constraint is its whole
|
|
6
|
+
shape:
|
|
7
|
+
|
|
8
|
+
``errors`` and ``preflight`` import only the standard library, and nothing on ``cli``'s
|
|
9
|
+
module-level import path imports ``ruamel.yaml``, ``platformdirs`` or ``jsonschema``.
|
|
10
|
+
|
|
11
|
+
Two clauses, because they are two different properties. The first is about this file and can be
|
|
12
|
+
read off the header below. The second is about a graph, and it is the one a missing dependency
|
|
13
|
+
reported by name actually needs: a first-party ``from periplus.settings import ...``
|
|
14
|
+
here would satisfy "standard library only" while pulling ``ruamel.yaml`` onto the very path the
|
|
15
|
+
dependency check exists to keep clear. ``jsonschema`` is the third name in that clause since
|
|
16
|
+
``periplus validate`` grew a reference validator, and it is why ``cli`` imports that module inside
|
|
17
|
+
``main()`` rather than at module level. The file would look clean and the startup check would be
|
|
18
|
+
broken. Declaring ``Problem`` in ``resolution.py`` would have exactly that defect.
|
|
19
|
+
|
|
20
|
+
An earlier wording of this constraint said this module "imports nothing". That is literally false
|
|
21
|
+
and cannot be satisfied — ``ExitCode`` needs ``enum``, ``Problem`` needs ``dataclasses``,
|
|
22
|
+
``ClassVar`` needs ``typing`` and ``Mapping`` needs ``collections.abc``. The two-clause form above
|
|
23
|
+
replaced it.
|
|
24
|
+
|
|
25
|
+
``tests/test_console_script.py`` asserts the graph property directly: it imports ``periplus.cli`` in
|
|
26
|
+
a subprocess with every runtime distribution blocked at ``sys.meta_path``, having first confirmed in
|
|
27
|
+
that same subprocess that the block works.
|
|
28
|
+
|
|
29
|
+
What this module costs, recorded because it is paid on every invocation and the trade is
|
|
30
|
+
deliberate rather than overlooked. ``dataclasses`` is about 8.6 ms of import subtree on this
|
|
31
|
+
project's interpreter, against ``argparse`` at about 1.6 ms, because it pulls ``inspect``, ``ast``,
|
|
32
|
+
``dis`` and ``tokenize``. ``Problem`` is a frozen dataclass anyway: nothing in this package crosses
|
|
33
|
+
a boundary as a dictionary with implied keys, which is what lets a JSON renderer be a mechanical
|
|
34
|
+
walk rather than a place where the record's shape is re-decided. Startup time is not a
|
|
35
|
+
measured requirement.
|
|
36
|
+
|
|
37
|
+
The distribution name is not here. It is in ``__init__.py``, which needs it to resolve
|
|
38
|
+
``__version__`` and which imports nothing at all; taking it from here would pull ``enum`` and
|
|
39
|
+
``dataclasses`` into every ``import periplus``, and the reverse edge would be a cycle. It was never
|
|
40
|
+
error vocabulary — it sat in the design here only because this was to be the module importing
|
|
41
|
+
nothing, and ``__init__.py`` is now that module.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
from __future__ import annotations
|
|
45
|
+
|
|
46
|
+
from collections.abc import Mapping
|
|
47
|
+
from dataclasses import dataclass
|
|
48
|
+
from enum import IntEnum
|
|
49
|
+
from types import MappingProxyType
|
|
50
|
+
from typing import ClassVar
|
|
51
|
+
|
|
52
|
+
__all__ = ["ExitCode", "HarnessError", "Problem"]
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
class ExitCode(IntEnum):
|
|
56
|
+
"""Every status the process can return, one per class of failure.
|
|
57
|
+
|
|
58
|
+
One code per class, and each is a different thing for a person to do about it: install
|
|
59
|
+
something, fix a pin, delete a copy, fix a name, break a cycle. There is no code for a pin
|
|
60
|
+
disagreeing with a manifest, because that check belongs to the validator: ``packs.py`` assigns
|
|
61
|
+
it there by name, and ``manifest.py`` — which does open a ``pack.yaml`` — deliberately declines
|
|
62
|
+
it, carrying the directory's name and the manifest's own ``pack`` side by side rather than
|
|
63
|
+
choosing between them. Pin matching itself opens nothing inside a pack directory and could not
|
|
64
|
+
make the check; the reader that could is not its owner.
|
|
65
|
+
|
|
66
|
+
All of them are declared here although nothing in this package raises ``INTERNAL`` and nothing
|
|
67
|
+
returns ``USAGE`` as a value — both are statuses the process produces anyway, an uncaught
|
|
68
|
+
exception through the interpreter and a usage error through ``parser.error``. A code table
|
|
69
|
+
costs nothing to declare and withholding members would mean editing this enum in five later
|
|
70
|
+
components — which is the edit the open-closed principle says should never be needed. What
|
|
71
|
+
each member traces to is written beside it.
|
|
72
|
+
|
|
73
|
+
7 and 8 are absent rather than free. They were declared for a folder component, forecasting
|
|
74
|
+
``FOLDER_UNKNOWN`` and ``FOLDER_CYCLE``, and were deleted because nothing
|
|
75
|
+
folder-shaped was ever built and this file's own rule is that a failure class arrives with the
|
|
76
|
+
module that raises it. Neither number is reused: renumbering would change a status a person
|
|
77
|
+
may already have scripted against.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
#: Resolved. Implied by every command that produces a report.
|
|
81
|
+
OK = 0
|
|
82
|
+
|
|
83
|
+
#: An exception that is not a ``HarnessError``. Nothing raises it:
|
|
84
|
+
#: an uncaught Python exception already exits 1, so a top-level handler here would only
|
|
85
|
+
#: swallow the traceback that makes an internal error diagnosable. The member documents what
|
|
86
|
+
#: the status means. Adding the handler is a separate decision.
|
|
87
|
+
INTERNAL = 1
|
|
88
|
+
|
|
89
|
+
#: A usage error — argparse's own status, and the one ``cli`` already returned as a literal
|
|
90
|
+
#: before this enum existed.
|
|
91
|
+
USAGE = 2
|
|
92
|
+
|
|
93
|
+
#: A settings file that was **asked for** is not there. Raised by
|
|
94
|
+
#: ``resolution._refuse_a_named_file_that_is_not_there``, and by nothing else.
|
|
95
|
+
#:
|
|
96
|
+
#: It used to mean "no settings file at either level", which ``_merge`` raised on every
|
|
97
|
+
#: unconfigured run — so a fresh install exited 3 and printed a ``Problems`` section, reporting
|
|
98
|
+
#: its own normal starting condition as a fault. That is gone: for a command whose job is to
|
|
99
|
+
#: describe a state, an empty one is the state. What is left is the narrower case with the
|
|
100
|
+
#: opposite remedy — a path a person typed that does not exist, where exit 0 would tell them a
|
|
101
|
+
#: file was read that never was.
|
|
102
|
+
#:
|
|
103
|
+
#: The number is unchanged through both, which is the point of declaring the table up front.
|
|
104
|
+
NO_SETTINGS = 3
|
|
105
|
+
|
|
106
|
+
#: A settings file could not be read or parsed. It follows
|
|
107
|
+
#: from the decision to parse with ``ruamel.yaml`` at ``typ='safe'``, which raises on a
|
|
108
|
+
#: duplicate key where PyYAML silently keeps the last value. That refusal has to surface.
|
|
109
|
+
UNREADABLE_SETTINGS = 4
|
|
110
|
+
|
|
111
|
+
#: A pin matched no directory name. The *report* is required — "a named pin with no
|
|
112
|
+
#: matching directory is reported missing"; that the status is non-zero, and that it is 5, is a
|
|
113
|
+
#: design decision.
|
|
114
|
+
PIN_UNMATCHED = 5
|
|
115
|
+
|
|
116
|
+
#: One pin matched a directory name under two roots. Same split as above: "reported twice
|
|
117
|
+
#: rather than resolved" is the requirement, the status is the decision.
|
|
118
|
+
PIN_DUPLICATED = 6
|
|
119
|
+
|
|
120
|
+
#: A required distribution is absent. A non-zero status naming which one is required; the
|
|
121
|
+
#: number 9 is design.
|
|
122
|
+
MISSING_DEPENDENCY = 9
|
|
123
|
+
|
|
124
|
+
#: A path a command had to create is already there, and nothing was overwritten. Raised by
|
|
125
|
+
#: ``init.TargetExists``, which enumerates its causes: a settings file that already exists, a
|
|
126
|
+
#: regular file where either directory belongs, or a symlink where either belongs, refused
|
|
127
|
+
#: rather than followed. All are one thing to do about it: look at the named path. The number
|
|
128
|
+
#: 10 is design; it is the first member added after the original table.
|
|
129
|
+
TARGET_EXISTS = 10
|
|
130
|
+
|
|
131
|
+
#: A pack manifest exists as a path and could not be turned into a mapping. Raised by
|
|
132
|
+
#: ``manifest.ManifestUnreadable``, whose ``detail`` names which of the five causes it was.
|
|
133
|
+
#: The same shape as ``UNREADABLE_SETTINGS`` and a separate number, because the two name
|
|
134
|
+
#: different files with different owners: a person edits their own settings file, and a pack
|
|
135
|
+
#: manifest is shipped by whoever wrote the pack.
|
|
136
|
+
UNREADABLE_MANIFEST = 11
|
|
137
|
+
|
|
138
|
+
#: A ``depends`` entry names a pack no directory on the search path carries. One thing to do
|
|
139
|
+
#: about it: install that pack, or fix the name. The number 12 is design.
|
|
140
|
+
#:
|
|
141
|
+
#: ``DEPENDS_`` and not ``DEPENDENCY_``, throughout: ``MISSING_DEPENDENCY`` above already
|
|
142
|
+
#: means a runtime *distribution*, and so does ``preflight.DependencyStatus``. The three
|
|
143
|
+
#: members below are named for the manifest key they read, which is the one word that cannot
|
|
144
|
+
#: be confused with the other meaning.
|
|
145
|
+
DEPENDS_UNMATCHED = 12
|
|
146
|
+
|
|
147
|
+
#: A ``depends`` entry names a pack two directories on the search path both carry — ``php``
|
|
148
|
+
#: with a ``php@0.1.0`` and a ``php@0.2.0`` beside it. The same split as ``PIN_DUPLICATED``:
|
|
149
|
+
#: it is reported rather than resolved, because a ``depends`` entry carries no version and
|
|
150
|
+
#: nothing in the manifest says which of the two the author meant.
|
|
151
|
+
DEPENDS_DUPLICATED = 13
|
|
152
|
+
|
|
153
|
+
#: A pack's ``depends`` chain reaches back to a pack already on the path being walked, itself
|
|
154
|
+
#: included. One thing to do about it: break the cycle. The manifest schema does not forbid
|
|
155
|
+
#: it — ``depends`` items are matched against a name pattern and nothing compares them to the
|
|
156
|
+
#: declaring pack — so it is detected here rather than assumed away.
|
|
157
|
+
DEPENDS_CYCLE = 14
|
|
158
|
+
|
|
159
|
+
#: A pack named on the command line is not on the pack search path. Returned by
|
|
160
|
+
#: ``spec._unknown_pack``, and reachable the first time somebody types ``periplus spec`` and
|
|
161
|
+
#: misspells a pack.
|
|
162
|
+
#:
|
|
163
|
+
#: Its own number, and not ``DEPENDS_UNMATCHED``, although the remedy is the same sentence —
|
|
164
|
+
#: install that pack, or fix the name. That member says a *manifest* names a pack nothing
|
|
165
|
+
#: carries, which is a fault in a file somebody wrote and shipped; this one says an *argument*
|
|
166
|
+
#: does, which is a typo at a prompt. Different file, different owner, and a report printing
|
|
167
|
+
#: one number for both would tell a reader less than it knows.
|
|
168
|
+
#:
|
|
169
|
+
#: **It is a code in the report first, and on the process status it is often not there at
|
|
170
|
+
#: all.** Two facts about where it can appear, both read off the code rather than argued:
|
|
171
|
+
#:
|
|
172
|
+
#: * It never co-occurs with a ``DEPENDS_*`` code. ``spec._describe_pack`` appends this
|
|
173
|
+
#: problem and returns *before* ``resolve_pack_order`` is called, so a run that produced 15
|
|
174
|
+
#: walked no dependency graph, and a run that walked one found the pack. The two are
|
|
175
|
+
#: mutually exclusive by construction, and an earlier version of this docblock justified the
|
|
176
|
+
#: member with a run — a misspelled ``drupal`` whose ``yaml`` dependency is also missing —
|
|
177
|
+
#: that cannot happen.
|
|
178
|
+
#: * It does co-occur with a settings or pin fault, because ``spec`` resolves the search path
|
|
179
|
+
#: exactly as ``status`` does and inherits every problem resolution found. A report's status
|
|
180
|
+
#: is the *lowest* code among its problems and 15 is the highest number any report reaches
|
|
181
|
+
#: this way, so any such fault takes the status and this one is masked: ``periplus spec
|
|
182
|
+
#: twigg`` exits 5 in a project pinning a pack that is not installed, and 15 in a directory
|
|
183
|
+
#: that is not a project. Measured, both. (16 below is higher still and is never reached by
|
|
184
|
+
#: ``min()`` at all; that is the whole of its own note.)
|
|
185
|
+
#:
|
|
186
|
+
#: So the process status of a project that has any other fault does not tell a broken pack
|
|
187
|
+
#: name from a broken invocation, and a script that needs to must read the report rather than
|
|
188
|
+
#: ``$?``. That is where the two stay distinguishable: the problem is carried in
|
|
189
|
+
#: ``SpecReport.problems`` under this code with a ``detail`` naming the pack asked for and
|
|
190
|
+
#: every pack that is there, printed beside its number in the text form and under ``problems``
|
|
191
|
+
#: in ``--format json``. The status says a run had a fault; the report says which faults.
|
|
192
|
+
PACK_UNKNOWN = 15
|
|
193
|
+
|
|
194
|
+
#: A file inside a pack disagrees with the schema that pack file is written against. Returned
|
|
195
|
+
#: by ``validate.ValidationReport.exit_code``, and by nothing else.
|
|
196
|
+
#:
|
|
197
|
+
#: Its own number, and not one of the ``UNREADABLE_`` codes: those say a file could not be
|
|
198
|
+
#: turned into a mapping at all, and this one says the mapping is there and says the wrong
|
|
199
|
+
#: thing. One remedy either way — open the named file — but a different fault, and the report
|
|
200
|
+
#: names a key and a pointer inside the document for this one and cannot for those.
|
|
201
|
+
#:
|
|
202
|
+
#: **It is the one code with its own aggregation rule, and it needs one.** Every other report
|
|
203
|
+
#: takes ``min()`` over its problems, for the reason ``ResolutionReport.exit_code`` gives: the
|
|
204
|
+
#: status must not depend on the order the stages appended in. 16 is the highest number in this
|
|
205
|
+
#: table, so under ``min()`` it would be masked by every existing code — a ``validate`` run in a
|
|
206
|
+
#: project that also pins a pack nobody installed would exit 5, answering a question about a
|
|
207
|
+
#: pack with a fault in a settings file. So ``validate`` departs: **any schema error yields 16,
|
|
208
|
+
#: and with none the resolution problems aggregate by ``min()`` exactly as they do elsewhere.**
|
|
209
|
+
#: That departure is a property of one report and not of this table, which is why it is stated
|
|
210
|
+
#: here beside the member and asserted by a pair of tests — one run with both faults at once,
|
|
211
|
+
#: one with only the resolution fault — because either alone is satisfied by the wrong rule.
|
|
212
|
+
#:
|
|
213
|
+
#: A schema error is never dropped from the report to make the status say something. Both
|
|
214
|
+
#: kinds are carried side by side: ``ValidationReport.errors`` and ``ValidationReport.problems``
|
|
215
|
+
#: are separate fields because they are faults in different files with different owners.
|
|
216
|
+
SCHEMA_INVALID = 16
|
|
217
|
+
|
|
218
|
+
#: ``periplus map`` built a document its own schema refuses, an engine defect; or the project
|
|
219
|
+
#: pins no rutter, which stops the run before anything is built. Nothing is written.
|
|
220
|
+
MAP_INVALID = 17
|
|
221
|
+
|
|
222
|
+
#: A folder name is unknown, cyclic, in conflict between packs, or leaves the project root.
|
|
223
|
+
FOLDER_UNRESOLVED = 18
|
|
224
|
+
|
|
225
|
+
#: A pack's rule file cannot be read, or its types or rules disagree.
|
|
226
|
+
PACK_RULES_UNREADABLE = 19
|
|
227
|
+
|
|
228
|
+
#: A source file cannot be read as data: a parse error, bytes that are not UTF-8, a root that
|
|
229
|
+
#: is not a mapping, a tag outside the core set, or a key written twice in one mapping.
|
|
230
|
+
SOURCE_UNREADABLE = 20
|
|
231
|
+
|
|
232
|
+
#: Rules found types for one id that do not lie on one ancestor chain.
|
|
233
|
+
TYPE_COLLISION = 21
|
|
234
|
+
|
|
235
|
+
#: An edge's end has a type the edge kind does not allow there.
|
|
236
|
+
EDGE_ILLEGAL = 22
|
|
237
|
+
|
|
238
|
+
#: A pack names a type that neither it nor a pack it depends on declares.
|
|
239
|
+
UNDECLARED_TYPE = 23
|
|
240
|
+
|
|
241
|
+
#: An edge rule names a kind that neither its pack nor a pack it depends on declares.
|
|
242
|
+
UNDECLARED_EDGE_KIND = 24
|
|
243
|
+
|
|
244
|
+
#: Two rules of one pack carry one name.
|
|
245
|
+
RULE_DUPLICATED = 25
|
|
246
|
+
|
|
247
|
+
#: A rule has a shape the engine cannot execute, so the run is refused rather than partial.
|
|
248
|
+
RULE_NOT_EXECUTABLE = 26
|
|
249
|
+
|
|
250
|
+
#: The map could not be written to the path asked for.
|
|
251
|
+
OUTPUT_UNWRITABLE = 27
|
|
252
|
+
|
|
253
|
+
#: A pack's grammar pins a parser runtime or a grammar version other than the one installed,
|
|
254
|
+
#: or one that is not installed at all. Found before any source file is opened.
|
|
255
|
+
GRAMMAR_MISMATCH = 28
|
|
256
|
+
|
|
257
|
+
#: A navigation command found no map to read: no project above the working directory, or no
|
|
258
|
+
#: file at the default path or at the ``--map`` path. Remedy: run ``periplus map``.
|
|
259
|
+
MAP_NOT_FOUND = 29
|
|
260
|
+
|
|
261
|
+
#: The file a navigation command read is not JSON, or fails the map schema.
|
|
262
|
+
NOT_A_MAP = 30
|
|
263
|
+
|
|
264
|
+
#: An id given to a navigation command names no node in the map.
|
|
265
|
+
NODE_NOT_FOUND = 31
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
@dataclass(frozen=True, slots=True)
|
|
269
|
+
class Problem:
|
|
270
|
+
"""One failure, as a record rather than as a formatted string.
|
|
271
|
+
|
|
272
|
+
``message`` is the one line a person reads. ``detail`` is the same failure as named facts, so a
|
|
273
|
+
consumer of ``--format json`` reads keys rather than parsing prose. Both are populated at the
|
|
274
|
+
point the failure is found, where the facts are still in scope.
|
|
275
|
+
|
|
276
|
+
Frozen and slotted so that a report is assembled from records that cannot be edited after the
|
|
277
|
+
stage that produced them has returned, and so that a renderer walking a report cannot silently
|
|
278
|
+
depend on a key nobody declared.
|
|
279
|
+
"""
|
|
280
|
+
|
|
281
|
+
code: ExitCode
|
|
282
|
+
message: str
|
|
283
|
+
detail: Mapping[str, str]
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
class HarnessError(Exception):
|
|
287
|
+
"""The base of every failure the harness raises, carrying its own exit code.
|
|
288
|
+
|
|
289
|
+
``code`` is declared and deliberately not assigned. A subclass sets it, so the exit-code table
|
|
290
|
+
is a property of the class hierarchy rather than a branch inside ``main`` — adding a failure
|
|
291
|
+
class is a new exception class and a new enum member, never an edit to the console script.
|
|
292
|
+
|
|
293
|
+
Nothing enforces that a subclass remembered. A subclass that forgets raises ``AttributeError``
|
|
294
|
+
from ``problem()`` rather than reporting some default code, which is the better of the two
|
|
295
|
+
failure modes: a missing code is loud, and a wrong code is a report that lies.
|
|
296
|
+
|
|
297
|
+
No subclass ships in this file. Each one arrives with the module that raises it —
|
|
298
|
+
``SettingsUnreadable`` with ``settings.py``. A subclass
|
|
299
|
+
with no raiser and no test exercising it is work pulled forward, and shipping them here would
|
|
300
|
+
let the claim above be asserted once instead of exercised five times. The test for
|
|
301
|
+
``problem()`` defines its own subclass, which tests the mechanism rather than one instance of
|
|
302
|
+
it.
|
|
303
|
+
|
|
304
|
+
``packs.py`` ships no subclass at all. It returns ``Problem`` records directly, because one
|
|
305
|
+
call has to report every unmatched pin and an exception carries one.
|
|
306
|
+
"""
|
|
307
|
+
|
|
308
|
+
code: ClassVar[ExitCode]
|
|
309
|
+
|
|
310
|
+
def __init__(self, message: str, detail: Mapping[str, str] | None = None) -> None:
|
|
311
|
+
"""Take the one-line message and the named facts that go with it.
|
|
312
|
+
|
|
313
|
+
``detail`` is accepted here, rather than left for a subclass to add later, because without
|
|
314
|
+
it ``problem()`` could only ever return an empty mapping and ``Problem.detail`` would be a
|
|
315
|
+
dead field until some component reopened this file to fix that. Reopening this file is the
|
|
316
|
+
thing the class is arranged to avoid.
|
|
317
|
+
|
|
318
|
+
The mapping is copied and wrapped, so the record ``problem()`` returns cannot be edited
|
|
319
|
+
through the exception that produced it. A frozen dataclass stops the field being rebound;
|
|
320
|
+
it does not stop the mapping inside it being mutated, and this is where that is closed.
|
|
321
|
+
``types`` is already resident before user code runs, so the wrap costs nothing measurable.
|
|
322
|
+
"""
|
|
323
|
+
super().__init__(message)
|
|
324
|
+
self.detail: Mapping[str, str] = MappingProxyType(dict(detail or {}))
|
|
325
|
+
|
|
326
|
+
def problem(self) -> Problem:
|
|
327
|
+
"""This failure as a ``Problem``, carrying the raising subclass's own code.
|
|
328
|
+
|
|
329
|
+
``type(self).code`` rather than a literal, which is the whole arrangement: the code
|
|
330
|
+
travels with the class, so this method never learns about a new failure class.
|
|
331
|
+
"""
|
|
332
|
+
return Problem(code=type(self).code, message=str(self), detail=self.detail)
|