def purpose(self) -> DescriptionWithSubSections: tp = TextParser({ 'cd_concept': formatting.concept(self.singular_name()), 'CD': self.acronym(), 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'sds_concept': formatting.concept_(concepts.SDS_CONCEPT_INFO), 'act_sub_dir': SUB_DIRECTORY__ACT + '/', 'path_type': formatting.symbol_type_(types.PATH_TYPE_INFO), 'act_phase': phase_names.ACT.emphasis, 'rel_cd_option': formatting.cli_option(path.REL_CWD_OPTION), 'cd_instruction': InstructionName(instruction_names.CHANGE_DIR_INSTRUCTION_NAME), 'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME), 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name, 'os_process': misc_texts.OS_PROCESS_NAME, }) return DescriptionWithSubSections( self.single_line_description(), SectionContents( tp.fnap(_INITIAL_PARAGRAPHS), [ docs.section( tp.text(_USING_THE_CD_HEADER), tp.fnap(_USING_THE_CD) ), docs.section( tp.text(_DESCRIPTION_DEF_INSTRUCTION_HEADER), cd_instruction_section_on_def_instruction() ), ] ))
def _what_outcome_depends_on(tp: TextParser) -> ParagraphItem: items = [ list_item(tp.text(_OUTCOME_DEPENDENCE__STATUS), tp.fnap(_OUTCOME_DEFAULT_STATUS)), list_item(tp.text(_OUTCOME_DEPENDENCE__ASSERT_PHASE)), ] return lists.HeaderContentList(items, lists.Format(lists.ListType.ORDERED_LIST, custom_separations=SEPARATION_OF_HEADER_AND_CONTENTS))
def _what_outcome_depends_on(tp: TextParser) -> ParagraphItem: items = [ list_item(tp.text(_OUTCOME_DEPENDENCE__STATUS), tp.fnap(_OUTCOME_DEFAULT_STATUS)), list_item(tp.text(_OUTCOME_DEPENDENCE__ASSERT_PHASE)), ] return lists.HeaderContentList( items, lists.Format(lists.ListType.ORDERED_LIST, custom_separations=SEPARATION_OF_HEADER_AND_CONTENTS))
class ConfigurationSectionDocumentation(TestSuiteSectionDocumentationForSectionWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'conf_phase': phase_names.CONFIGURATION, }) def instructions_section_header(self) -> docs.Text: return docs.text('Additional instructions') def instruction_purpose_description(self) -> List[ParagraphItem]: return [] def contents_description(self) -> docs.SectionContents: return self._tp.section_contents(_CONTENTS_DESCRIPTION) def purpose(self) -> Description: paragraphs = self._tp.fnap(_PURPOSE_REST_TEXT) paragraphs += test_case_phase_sections.insertion_position_description(self.section_info.name, True) return Description(self._tp.text(_PURPOSE_SINGLE_LINE_DESCRIPTION_TEXT), paragraphs) @property def see_also_targets(self) -> List[SeeAlsoTarget]: return [ phase_infos.CONFIGURATION.cross_reference_target ]
class _TypeConcept(ConceptDocumentation): def __init__(self): super().__init__(concepts.TYPE_CONCEPT_INFO) self._parser = TextParser({ 'type': concepts.TYPE_CONCEPT_INFO.name, 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'string_type': types.STRING_TYPE_INFO.name, 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name, }) def purpose(self) -> DescriptionWithSubSections: rest_paragraphs = self._parser.fnap(_REST__BEFORE_CATEGORY_LIST) rest_paragraphs.append(_types_categories_list(self._parser)) rest_paragraphs += (self._parser.fnap(_REST__AFTER_CATEGORY_LIST)) sub_sections = [ docs.section(self._parser.text('Summary of {type:s}'), [_types_list()]) ] return DescriptionWithSubSections( self.single_line_description(), SectionContents(rest_paragraphs, sub_sections)) def see_also_targets(self) -> List[SeeAlsoTarget]: return list( map(lambda type_doc: type_doc.cross_reference_target(), all_types.all_types()))
class ConfigurationSectionDocumentation( TestSuiteSectionDocumentationForSectionWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'conf_phase': phase_names.CONFIGURATION, }) def instructions_section_header(self) -> docs.Text: return docs.text('Additional instructions') def instruction_purpose_description(self) -> List[ParagraphItem]: return [] def contents_description(self) -> docs.SectionContents: return self._tp.section_contents(_CONTENTS_DESCRIPTION) def purpose(self) -> Description: paragraphs = self._tp.fnap(_PURPOSE_REST_TEXT) paragraphs += test_case_phase_sections.insertion_position_description( self.section_info.name, True) return Description( self._tp.text(_PURPOSE_SINGLE_LINE_DESCRIPTION_TEXT), paragraphs) @property def see_also_targets(self) -> List[SeeAlsoTarget]: return [phase_infos.CONFIGURATION.cross_reference_target]
class _SectionThatIsIdenticalToTestCasePhase(TestSuiteSectionDocumentationBaseForSectionWithoutInstructions): def __init__(self, phase_name: str, contents_is_inserted_before_case_contents: bool): super().__init__(phase_name) self._contents_is_inserted_before_case_contents = contents_is_inserted_before_case_contents self._tp = TextParser({ 'phase': self.section_info.name, }) def contents_description(self) -> SectionContents: return self._tp.section_contents(_CONTENTS_DESCRIPTION) def purpose(self) -> Description: paragraphs = self._tp.fnap(_CORRESPONDENCE_DESCRIPTION) paragraphs += insertion_position_description(self.section_info.name, self._contents_is_inserted_before_case_contents) return Description(self._tp.text(_SINGLE_LINE_DESCRIPTION), paragraphs) @property def see_also_targets(self) -> List[SeeAlsoTarget]: return [ TestCasePhaseCrossReference(self.name.plain) ]
class _EnvironmentVariableConcept(ConceptDocumentation): def __init__(self): super().__init__(ENVIRONMENT_VARIABLE_CONCEPT_INFO) self._tp = TextParser({ 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'env_vars__plain': self.name().plural, 'env_instruction': InstructionName(instruction_names.ENV_VAR_INSTRUCTION_NAME), 'tcds_concept': formatting.concept_(concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO), }) def purpose(self) -> DescriptionWithSubSections: return DescriptionWithSubSections( self.single_line_description(), docs.section_contents( self._tp.fnap(_INITIAL_PARAGRAPHS), [ docs.section(self._tp.text('Environment variables set by {program_name}'), self._tp.fnap(_E_SETS_EXTRA_ENV_VARS), [ self._variables_from_setup(), self._variables_from_before_assert(), ]) ])) def see_also_targets(self) -> List[SeeAlsoTarget]: ret_val = name_and_cross_ref.cross_reference_id_list([ concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO, conf_params.HOME_CASE_DIRECTORY_CONF_PARAM_INFO, conf_params.HOME_ACT_DIRECTORY_CONF_PARAM_INFO, ]) ret_val += [ phase_infos.SETUP.instruction_cross_reference_target(instruction_names.ENV_VAR_INSTRUCTION_NAME) ] return ret_val def _variables_from_setup(self) -> docs.Section: return _variables_section(phase_names.SETUP, _variables_list_paragraphs([ self._item(var_name) for var_name in map(operator.itemgetter(0), environment_variables.ENVIRONMENT_VARIABLES_SET_BEFORE_ACT) ])) def _variables_from_before_assert(self) -> docs.Section: return _variables_section(phase_names.BEFORE_ASSERT, _variables_list_paragraphs([ self._item(var_name) for var_name in map(operator.itemgetter(0), environment_variables.ENVIRONMENT_VARIABLES_SET_AFTER_ACT) ])) def _item(self, var_name: str) -> lists.HeaderContentListItem: return docs.list_item(directory_variable_name_text(var_name), environment_variables.ENVIRONMENT_VARIABLE_DESCRIPTION.as_description_paragraphs( var_name))
def path_type_path_rendering() -> SectionItem: tp = TextParser({ 'current_directory_concept': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), 'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME), 'symbol_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.singular_name), 'rel_cd_option': formatting.cli_option(file_ref.REL_CWD_OPTION), 'path_type': formatting.keyword(types.PATH_TYPE_INFO.name.singular), }) return Section(tp.text(_PATH_TYPE_PATH_RENDERING_DESCRIPTION_HEADER), tp.section_contents(_PATH_TYPE_PATH_RENDERING_DESCRIPTION))
class CleanupPhaseDocumentation( TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'SKIP': NAME_SKIP, 'execution_mode': formatting.conf_param_( conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO), 'ATC': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo( self._tp.fnap(_SEQUENCE_INFO__PRECEDING_PHASE), self._tp.fnap(_SEQUENCE_INFO__SUCCEEDING_PHASE), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def instruction_purpose_description(self) -> List[ParagraphItem]: return self._tp.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( cwd_at_start_of_phase_for_non_first_phases(), environment_variables_prologue= env_vars_prologue_for_inherited_from_previous_phase(), timeout_prologue=timeout_prologue_for_inherited_from_previous_phase( ), ) @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.SDS_CONCEPT_INFO.cross_reference_target, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO. cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, concepts.TIMEOUT_CONCEPT_INFO.cross_reference_target, conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO. cross_reference_target, phase_infos.ASSERT.cross_reference_target, phase_infos.CONFIGURATION.instruction_cross_reference_target( TEST_CASE_STATUS_INSTRUCTION_NAME), ]
def path_type_path_rendering() -> SectionItem: tp = TextParser({ 'current_directory_concept': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), 'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME), 'symbol_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.singular_name), 'rel_cd_option': formatting.cli_option(path.REL_CWD_OPTION), 'path_type': types.PATH_TYPE_INFO.name, 'external_program': misc_texts.EXTERNAL_PROGRAM, 'os_process': misc_texts.OS_PROCESS_NAME, 'Note': headers.NOTE_LINE_HEADER, }) return Section(tp.text(_PATH_TYPE_PATH_RENDERING_DESCRIPTION_HEADER), tp.section_contents(_PATH_TYPE_PATH_RENDERING_DESCRIPTION))
def purpose(self) -> DescriptionWithSubSections: tp = TextParser({ 'cd_concept': formatting.concept(self.singular_name()), 'CD': self.acronym(), 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'sds_concept': formatting.concept_(concepts.SANDBOX_CONCEPT_INFO), 'act_sub_dir': SUB_DIRECTORY__ACT + '/', 'path_type': formatting.symbol_type_(types.PATH_TYPE_INFO), 'act_phase': phase_names.ACT.syntax, 'rel_cd_option': formatting.cli_option(file_ref.REL_CWD_OPTION), 'cd_instruction': InstructionName(instruction_names.CHANGE_DIR_INSTRUCTION_NAME), 'run_instruction': InstructionName(instruction_names.RUN_INSTRUCTION_NAME), 'shell_instruction': InstructionName(instruction_names.SHELL_INSTRUCTION_NAME), 'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME), 'os_process': misc_texts.OS_PROCESS_NAME, }) return DescriptionWithSubSections( self.single_line_description(), SectionContents( tp.fnap(_INITIAL_PARAGRAPHS), [ docs.section( tp.text(_USING_THE_CD_HEADER), tp.fnap(_USING_THE_CD) ), docs.section( tp.text(_DESCRIPTION_DEF_INSTRUCTION_HEADER), cd_instruction_section_on_def_instruction() ), ] ))
class BeforeAssertPhaseDocumentation( TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'CWD': formatting.concept_( concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo( sequence_info__preceding_phase(phase_names.ACT), sequence_info__succeeding_phase(phase_names.ASSERT), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def instruction_purpose_description(self) -> List[ParagraphItem]: return self._tp.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) def execution_environment_info(self) -> ExecutionEnvironmentInfo: previous = '{setup} phase'.format(setup=phase_names.SETUP.emphasis) return ExecutionEnvironmentInfo( cwd_at_start_of_phase_is_same_as_at_end_of_the(previous), prologue=execution_environment_prologue_for_post_act_phase(), environment_variables_prologue= env_vars_prologue_for_inherited_from_previous_phase(), timeout_prologue=timeout_prologue_for_inherited_from_previous_phase( ), ) @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.SDS_CONCEPT_INFO.cross_reference_target, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO. cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, concepts.TIMEOUT_CONCEPT_INFO.cross_reference_target, phase_infos.ACT.cross_reference_target, phase_infos.ASSERT.cross_reference_target, ]
class ConfigurationPhaseDocumentation( TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._parser = TextParser({ 'configuration_parameters': formatting.concept( concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name), 'execution_mode': formatting.conf_param_( conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO), 'SKIP': NAME_SKIP, 'setup': phase_names.SETUP, }) def purpose(self) -> Description: first_line = self._parser.text(ONE_LINE_DESCRIPTION) remaining_lines = [] return Description(first_line, remaining_lines) def sequence_info(self) -> PhaseSequenceInfo: preceding_phase = self._parser.fnap(SEQUENCE_INFO__PRECEDING_PHASE) succeeding_phase = self._parser.fnap(SEQUENCE_INFO__SUCCEEDING_PHASE) return PhaseSequenceInfo(preceding_phase, succeeding_phase) def instruction_purpose_description(self) -> List[ParagraphItem]: return self._parser.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( cwd_at_start_of_phase_for_configuration_phase()) @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO. cross_reference_target, conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO. cross_reference_target, self.section_info.instruction_cross_reference_target( TEST_CASE_STATUS_INSTRUCTION_NAME), phase_infos.SETUP.cross_reference_target, ]
class SetupPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'ATC': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO), 'env_var': concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.name, 'env_vars_default': concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.default, 'timeout_default': concepts.TIMEOUT_CONCEPT_INFO.default, 'stdin': misc_texts.STDIN, 'SDS': concepts.SDS_CONCEPT_INFO.name, }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(self._tp.fnap(SEQUENCE_INFO__PRECEDING_PHASE), sequence_info__succeeding_phase(phase_names.ACT), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def instruction_purpose_description(self) -> List[ParagraphItem]: return self._tp.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo(cwd_at_start_of_phase_first_phase_executed_in_the_sandbox(), environment_variables_prologue=self._tp.fnap(ENV_VARS_PROLOGUE), timeout_prologue=self._tp.fnap(TIMEOUT_PROLOGUE)) @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.SDS_CONCEPT_INFO.cross_reference_target, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, concepts.TIMEOUT_CONCEPT_INFO.cross_reference_target, phase_infos.CONFIGURATION.cross_reference_target, phase_infos.ACT.cross_reference_target, ]
class CleanupPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'SKIP': NAME_SKIP, 'execution_mode': formatting.conf_param_(conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO), 'ATC': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(self._tp.fnap(_SEQUENCE_INFO__PRECEDING_PHASE), self._tp.fnap(_SEQUENCE_INFO__SUCCEEDING_PHASE), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def instruction_purpose_description(self) -> List[ParagraphItem]: return self._tp.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( cwd_at_start_of_phase_for_non_first_phases(), EXISTS_AT_BEFORE_ASSERT_MAIN, environment_variables_prologue=env_vars_prologue_for_inherited_from_previous_phase()) @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.SANDBOX_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO.cross_reference_target, phase_infos.ASSERT.cross_reference_target, phase_infos.CONFIGURATION.instruction_cross_reference_target(TEST_CASE_STATUS_INSTRUCTION_NAME), ]
class ConfigurationPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._parser = TextParser({ 'configuration_parameters': formatting.concept(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name), 'execution_mode': formatting.conf_param_(conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO), 'SKIP': NAME_SKIP, 'setup': phase_names.SETUP, }) def purpose(self) -> Description: first_line = self._parser.text(ONE_LINE_DESCRIPTION) remaining_lines = [] return Description(first_line, remaining_lines) def sequence_info(self) -> PhaseSequenceInfo: preceding_phase = self._parser.fnap(SEQUENCE_INFO__PRECEDING_PHASE) succeeding_phase = self._parser.fnap(SEQUENCE_INFO__SUCCEEDING_PHASE) return PhaseSequenceInfo(preceding_phase, succeeding_phase) def instruction_purpose_description(self) -> List[ParagraphItem]: return self._parser.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo(cwd_at_start_of_phase_for_configuration_phase(), env_vars_for_configuration_phase()) @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.cross_reference_target, conf_params.TEST_CASE_STATUS_CONF_PARAM_INFO.cross_reference_target, self.section_info.instruction_cross_reference_target(TEST_CASE_STATUS_INSTRUCTION_NAME), phase_infos.SETUP.cross_reference_target, ]
class BeforeAssertPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'CWD': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(sequence_info__preceding_phase(phase_names.ACT), sequence_info__succeeding_phase(phase_names.ASSERT), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def instruction_purpose_description(self) -> List[ParagraphItem]: return self._tp.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) def execution_environment_info(self) -> ExecutionEnvironmentInfo: previous = '{setup} phase'.format(setup=phase_names.SETUP.emphasis) return ExecutionEnvironmentInfo( cwd_at_start_of_phase_is_same_as_at_end_of_the(previous), EXISTS_AT_BEFORE_ASSERT_MAIN, prologue=execution_environment_prologue_for_post_act_phase(), environment_variables_prologue=env_vars_prologue_for_inherited_from_previous_phase()) @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.SANDBOX_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, phase_infos.ACT.cross_reference_target, phase_infos.ASSERT.cross_reference_target, ]
class ActPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithoutInstructions): def __init__(self, name: str): super().__init__(name) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'setup': phase_infos.SETUP.name, 'action_to_check': concepts.ACTION_TO_CHECK_CONCEPT_INFO.name, 'home_directory': formatting.conf_param_(conf_params.HOME_CASE_DIRECTORY_CONF_PARAM_INFO), 'timeout_conf_param': formatting.conf_param_(conf_params.TIMEOUT_CONF_PARAM_INFO), 'sandbox': formatting.concept_(concepts.SANDBOX_CONCEPT_INFO), 'result_dir': tc_fs.SDS_RESULT_INFO.identifier, 'actor_option': OPTION_FOR_ACTOR, 'actor': concepts.ACTOR_CONCEPT_INFO.name, 'actor_instruction': formatting.InstructionName(ACTOR_INSTRUCTION_NAME), 'default_actor': actors.DEFAULT_ACTOR_SINGLE_LINE_VALUE, 'null_actor': formatting.entity_(actors.NULL_ACTOR), 'os_process': misc_texts.OS_PROCESS_NAME, 'act': phase_infos.ACT.name, 'stdin_instruction': InstructionName(instruction_names.CONTENTS_OF_STDIN_INSTRUCTION_NAME), 'conf_param': concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.name, 'directive': concepts.DIRECTIVE_CONCEPT_INFO.name, 'including': formatting.keyword(directives.INCLUDING_DIRECTIVE_INFO.singular_name), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION) + [result_sub_dir_files_table()] + self._tp.fnap(_RELATION_TO_ACTOR__TO_BE_SEPARATE_SECTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(sequence_info__preceding_phase(phase_names.SETUP), sequence_info__succeeding_phase_of_act(), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def contents_description(self) -> doc.SectionContents: initial_paragraphs = self._tp.fnap(_CONTENTS_DESCRIPTION) + [_escape_sequence_table()] return docs.section_contents(initial_paragraphs) def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( cwd_at_start_of_phase_for_non_first_phases(), env_vars_up_to_act(), environment_variables_prologue=env_vars_prologue_for_inherited_from_previous_phase(), custom_items=self._custom_environment_info_items()) def _custom_environment_info_items(self) -> Sequence[docs.lists.HeaderContentListItem]: return [ docs.list_item( 'stdin', self._tp.fnap(_STDIN) ), docs.list_item( conf_params.TIMEOUT_CONF_PARAM_INFO.singular_name.capitalize(), self._tp.fnap(_TIMEOUT) ), ] @property def see_also_targets(self) -> List[SeeAlsoTarget]: return [ concepts.ACTOR_CONCEPT_INFO.cross_reference_target, concepts.ACTION_TO_CHECK_CONCEPT_INFO.cross_reference_target, concepts.SANDBOX_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, conf_params.ACTOR_CONF_PARAM_INFO.cross_reference_target, conf_params.TIMEOUT_CONF_PARAM_INFO.cross_reference_target, PredefinedHelpContentsPartReference(HelpPredefinedContentsPart.TEST_CASE_CLI), phase_infos.SETUP.cross_reference_target, phase_infos.BEFORE_ASSERT.cross_reference_target, phase_infos.ASSERT.cross_reference_target, phase_infos.SETUP.instruction_cross_reference_target(instruction_names.CONTENTS_OF_STDIN_INSTRUCTION_NAME), ]
class ActPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithoutInstructions): def __init__(self, name: str): super().__init__(name) self._tp = TextParser({ 'program_name': program_info.PROGRAM_NAME, 'phase': phase_names.PHASE_NAME_DICTIONARY, 'setup': phase_infos.SETUP.name, 'act': phase_infos.ACT.name, 'action_to_check': concepts.ACTION_TO_CHECK_CONCEPT_INFO.name, 'home_directory': formatting.conf_param_(conf_params.HDS_CASE_DIRECTORY_CONF_PARAM_INFO), 'sandbox': formatting.concept_(concepts.SDS_CONCEPT_INFO), 'result_dir': tc_fs.SDS_RESULT_INFO.identifier, 'actor_option': OPTION_FOR_ACTOR, 'actor': concepts.ACTOR_CONCEPT_INFO.name, 'actor_instruction': formatting.InstructionName(ACTOR_INSTRUCTION_NAME), 'default_actor': actors.DEFAULT_ACTOR_SINGLE_LINE_VALUE, 'null_actor': formatting.entity_(actors.NULL_ACTOR), 'os_process': misc_texts.OS_PROCESS_NAME, 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name, 'stdin_instruction': InstructionName(instruction_names.CONTENTS_OF_STDIN_INSTRUCTION_NAME), 'env_instruction': InstructionName(instruction_names.ENV_VAR_INSTRUCTION_NAME), 'timeout': concepts.TIMEOUT_CONCEPT_INFO.name, 'timeout_default': concepts.TIMEOUT_CONCEPT_INFO.default, 'timeout_instruction': InstructionName(instruction_names.TIMEOUT_INSTRUCTION_NAME), 'conf_param': concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.name, 'env_var': concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.name, 'PROGRAM': syntax_elements.PROGRAM_SYNTAX_ELEMENT.singular_name, 'stdin': misc_texts.STDIN, 'directive': concepts.DIRECTIVE_CONCEPT_INFO.name, 'including': formatting.keyword(directives.INCLUDING_DIRECTIVE_INFO.singular_name), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION) + [result_sub_dir_files_table()] + self._tp.fnap(_RELATION_TO_ACTOR__TO_BE_SEPARATE_SECTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(sequence_info__preceding_phase(phase_names.SETUP), sequence_info__succeeding_phase_of_act(), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def contents_description(self) -> doc.SectionContents: initial_paragraphs = self._tp.fnap(_CONTENTS_DESCRIPTION) + [_escape_sequence_table()] return docs.section_contents(initial_paragraphs) def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( cwd_at_start_of_phase_for_non_first_phases(), environment_variables_prologue=self._tp.fnap(_ENV_VARS_DESCRIPTION), timeout_prologue=timeout_prologue_for_inherited_from_previous_phase(), custom_items=self._custom_environment_info_items()) def _custom_environment_info_items(self) -> Sequence[docs.lists.HeaderContentListItem]: return [ docs.list_item( misc_texts.STDIN.capitalize(), self._tp.fnap(_STDIN) ), ] @property def see_also_targets(self) -> List[SeeAlsoTarget]: return [ concepts.ACTOR_CONCEPT_INFO.cross_reference_target, concepts.ACTION_TO_CHECK_CONCEPT_INFO.cross_reference_target, concepts.SDS_CONCEPT_INFO.cross_reference_target, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, concepts.TIMEOUT_CONCEPT_INFO.cross_reference_target, conf_params.ACTOR_CONF_PARAM_INFO.cross_reference_target, PredefinedHelpContentsPartReference(HelpPredefinedContentsPart.TEST_CASE_CLI), phase_infos.SETUP.cross_reference_target, phase_infos.BEFORE_ASSERT.cross_reference_target, phase_infos.ASSERT.cross_reference_target, phase_infos.SETUP.instruction_cross_reference_target(instruction_names.TIMEOUT_INSTRUCTION_NAME), phase_infos.SETUP.instruction_cross_reference_target(instruction_names.ENV_VAR_INSTRUCTION_NAME), phase_infos.SETUP.instruction_cross_reference_target(instruction_names.CONTENTS_OF_STDIN_INSTRUCTION_NAME), ]
def root(header: str) -> generator.SectionHierarchyGenerator: tp = TextParser({ 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'conf_param': formatting.concept_(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO), 'tcds_concept': formatting.concept_(concepts.TCDS_CONCEPT_INFO), 'TCDS': concepts.TCDS_CONCEPT_INFO.acronym, 'SDS': concepts.SDS_CONCEPT_INFO.acronym, 'sds_concept': formatting.concept_(concepts.SDS_CONCEPT_INFO), 'Sds_concept_header': concepts.SDS_CONCEPT_INFO.singular_name.capitalize(), 'sds_single_line_description': concepts.SDS_CONCEPT_INFO.single_line_description_str.capitalize(), 'HDS': concepts.HDS_CONCEPT_INFO.acronym, 'hds_concept': formatting.concept_(concepts.HDS_CONCEPT_INFO), 'Hds_concept_header': concepts.HDS_CONCEPT_INFO.singular_name.capitalize(), 'hds_single_line_description': concepts.HDS_CONCEPT_INFO.single_line_description_str.capitalize(), 'conf_phase': phase_names.CONFIGURATION, 'act_phase': phase_names.ACT, 'act_hds_conf_param': formatting.conf_param(test_case_file_structure.HDS_ACT_INFO.identifier), 'path_type': types.PATH_TYPE_INFO.name, 'symbol_concept': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME), 'os_process': misc_texts.OS_PROCESS_NAME, 'env_var': concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.name, 'timeout': concepts.TIMEOUT_CONCEPT_INFO.name, 'timeout_instruction': InstructionName(instruction_names.TIMEOUT_INSTRUCTION_NAME), 'type': concepts.TYPE_CONCEPT_INFO.name, 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name, 'relativity': formatting.concept(misc_texts.RELATIVITY.singular), 'relativities': formatting.concept(misc_texts.RELATIVITY.plural), 'cd': formatting.emphasis(instruction_names.CHANGE_DIR_INSTRUCTION_NAME), 'env': formatting.emphasis(instruction_names.ENV_VAR_INSTRUCTION_NAME), 'CD': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), }) def const_paragraphs_child(local_target_name: str, header_: str, paragraphs_: List[ParagraphItem]) -> generator.SectionHierarchyGenerator: return h.child(local_target_name, h.leaf(header_, sections.constant_contents(section_contents(paragraphs_))) ) return h.hierarchy( header, children=[ h.child_hierarchy( 'dir-structure', 'Directory structure and Current directory', paragraphs.constant(tp.fnap(_DS_CD_PREAMBLE)), [ const_paragraphs_child( 'sds', concepts.SDS_CONCEPT_INFO.singular_name.capitalize() + ' and Current directory', tp.fnap(_SDS_AND_CD) ), const_paragraphs_child( 'hds', concepts.HDS_CONCEPT_INFO.singular_name.capitalize(), tp.fnap(_HDS), ), const_paragraphs_child( 'file-ref', 'File references', tp.fnap(_FILE_REFERENCES) ), h.leaf_not_in_toc( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_dir_struct_see_also_targets()) )), ] ), h.child_hierarchy( 'symbols', concepts.SYMBOL_CONCEPT_INFO.plural_name.capitalize(), paragraphs.constant(tp.fnap(_SYMBOLS)), [ h.leaf_not_in_toc( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_symbols_see_also_targets()) )) ] ), h.child_hierarchy( 'os-proc', tp.text(misc_texts.OS_PROCESS_ENVIRONMENT_SECTION_HEADER), paragraphs.constant(tp.fnap(_OS_PROC_INTRO)), [ const_paragraphs_child( 'cd', 'Current directory', tp.fnap(_OS_PROC_CURRENT_DIRECTORY), ), const_paragraphs_child( 'env-vars', tp.format('{env_var:s/u}'), environment_variable.common_description(), ), const_paragraphs_child( 'timeout', 'Timeout', tp.fnap(_OS_PROC_TIMEOUT), ), h.leaf_not_in_toc( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_os_process_see_also_targets()) ) ), ], ), ] )
class AssertPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'PASS': exit_values.EXECUTION__PASS.exit_identifier, 'FAIL': exit_values.EXECUTION__FAIL.exit_identifier, 'HARD_ERROR': exit_values.EXECUTION__HARD_ERROR.exit_identifier, 'result_subdir': sds.SUB_DIRECTORY__RESULT, 'sandbox': formatting.concept_(concepts.SDS_CONCEPT_INFO), 'ENV_VAR_RESULT': SYMBOL_RESULT, 'ATC': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(sequence_info__preceding_phase(phase_names.BEFORE_ASSERT), self._tp.fnap(_SEQUENCE_INFO__SUCCEEDING_PHASE), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def instruction_purpose_description(self) -> List[docs.ParagraphItem]: paragraphs = self._tp.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) paragraphs += self._instruction_groups_list() return paragraphs def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( cwd_at_start_of_phase_for_non_first_phases(), prologue=execution_environment_prologue_for_post_act_phase(), environment_variables_prologue=env_vars_prologue_for_inherited_from_previous_phase(), timeout_prologue=timeout_prologue_for_inherited_from_previous_phase()) @property def instruction_group_by(self) -> Callable[[List[WithAssertPhasePurpose]], List[InstructionGroup]]: return self._instruction_group_by @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.SDS_CONCEPT_INFO.cross_reference_target, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, concepts.TIMEOUT_CONCEPT_INFO.cross_reference_target, phase_infos.BEFORE_ASSERT.cross_reference_target, phase_infos.CLEANUP.cross_reference_target, ] def _instruction_group_by(self, instr_docs: List[WithAssertPhasePurpose]) -> List[InstructionGroup]: purpose_2_instructions = { value: [] for value in AssertPhasePurpose } for doc in instr_docs: assert isinstance(doc, WithAssertPhasePurpose), str(type(doc)) purpose_2_instructions[doc.assert_phase_purpose].append(doc) ret_val = [] for p in AssertPhasePurpose: instructions = purpose_2_instructions[p] if instructions: ret_val.append(self._group_of(p, instructions)) return ret_val def _group_of(self, purpose_type: AssertPhasePurpose, instructions: list) -> InstructionGroup: info = _INSTRUCTION_TYPES[purpose_type] return InstructionGroup(info[0], info[1], self._tp.fnap(info[2]), instructions) def _instruction_groups_list(self) -> List[docs.ParagraphItem]: def item(purpose: AssertPhasePurpose) -> lists.HeaderContentListItem: info = _INSTRUCTION_TYPES[purpose] return docs.list_item(info[0], self._tp.fnap(info[2])) return [ docs.simple_list_with_space_between_elements_and_content(map(item, list(AssertPhasePurpose)), ListType.ITEMIZED_LIST) ]
class ContentsConstructor(SectionContentsConstructor): def __init__(self): self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name, 'ATC': concepts.ACTION_TO_CHECK_CONCEPT_INFO.singular_name, 'symbol': concepts.SYMBOL_CONCEPT_INFO.name, 'directive': concepts.DIRECTIVE_CONCEPT_INFO.name, 'actor': concepts.ACTOR_CONCEPT_INFO.name, 'exit_code': misc_texts.EXIT_CODE, 'exit_identifier': misc_texts.EXIT_IDENTIFIER, 'act_phase': phase_infos.ACT.name, 'cli_option_for_preprocessor': formatting.cli_option(OPTION_FOR_PREPROCESSOR), 'an_error_in_source': misc_texts.SYNTAX_ERROR_NAME.singular_determined, 'including': formatting.keyword( directives.INCLUDING_DIRECTIVE_INFO.singular_name), 'stdout': misc_texts.STDOUT, 'execution': processing.STEP_EXECUTION, 'validation': processing.STEP_VALIDATION, 'preprocessing': processing.STEP_PRE_PROCESSING, }) def apply(self, environment: ConstructionEnvironment) -> SectionContents: preamble_paragraphs = self._tp.fnap(BEFORE_STEP_LIST) paragraphs = (preamble_paragraphs + [self.processing_step_list()]) return docs.SectionContents(paragraphs, [ see_also.SeeAlsoSectionConstructor( see_also.items_of_targets( _see_also_targets())).apply(environment) ]) def processing_step_list(self) -> docs.ParagraphItem: items = [ docs.list_item( processing.STEP_PRE_PROCESSING.singular.capitalize(), step_with_single_exit_value( self._tp.fnap(PURPOSE_OF_PREPROCESSING), self._tp.para(FAILURE_CONDITION_OF_PREPROCESSING), exit_values.NO_EXECUTION__PRE_PROCESS_ERROR)), docs.list_item( self._tp.text('Syntax checking and {directive:s} processing'), step_with_multiple_exit_values( self._tp.fnap(PURPOSE_OF_SYNTAX_CHECKING), self._tp.fnap(FAILURE_CONDITION_OF_SYNTAX_CHECKING), [ NameAndValue('Syntax error', exit_values.NO_EXECUTION__SYNTAX_ERROR), NameAndValue( 'File inclusion error', exit_values.NO_EXECUTION__FILE_ACCESS_ERROR), ], )), docs.list_item( self._tp.text( '{validation:/u} and syntax checking of {act_phase:syntax}' ), step_with_multiple_exit_values( self._tp.fnap(PURPOSE_OF_VALIDATION), self._tp.fnap(FAILURE_CONDITION_OF_VALIDATION), [ NameAndValue( self._tp.text( 'Invalid syntax of {act_phase:syntax}'), exit_values.EXECUTION__SYNTAX_ERROR), NameAndValue( self._tp.text( 'Invalid reference to {symbol} or external resource' ), exit_values.EXECUTION__VALIDATION_ERROR), ], )), docs.list_item(processing.STEP_EXECUTION.singular.capitalize(), self._tp.fnap(EXECUTION_DESCRIPTION)), ] return lists.HeaderContentList( items, lists.Format( lists.ListType.ORDERED_LIST, custom_separations=docs.SEPARATION_OF_HEADER_AND_CONTENTS))
class ContentsConstructor(SectionContentsConstructor): def __init__(self, setup: Setup): self._setup = setup self._tp = TextParser({ 'phase': setup.phase_names, 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name.singular, 'instructions': concepts.INSTRUCTION_CONCEPT_INFO.name.plural, 'ATC': concepts.ACTION_TO_CHECK_CONCEPT_INFO.singular_name, 'act_phase': phase_infos.ACT.name, 'symbol': concepts.SYMBOL_CONCEPT_INFO.name.singular, 'symbols': concepts.SYMBOL_CONCEPT_INFO.name.plural, 'cli_option_for_preprocessor': formatting.cli_option(OPTION_FOR_PREPROCESSOR), 'an_error_in_source': misc_texts.SYNTAX_ERROR_NAME.singular_determined, 'directive': concepts.DIRECTIVE_CONCEPT_INFO.name, 'including': formatting.keyword(directives.INCLUDING_DIRECTIVE_INFO.singular_name), }) def apply(self, environment: ConstructionEnvironment) -> SectionContents: preamble_paragraphs = self._tp.fnap(BEFORE_STEP_LIST) paragraphs = ( preamble_paragraphs + [self.processing_step_list()] ) return docs.SectionContents( paragraphs, [ see_also.SeeAlsoSectionConstructor( see_also.items_of_targets(_see_also_targets()) ).apply(environment) ] ) def processing_step_list(self) -> docs.ParagraphItem: items = [ docs.list_item('Preprocessing', step_with_single_exit_value( self._tp.fnap(PURPOSE_OF_PREPROCESSING), self._tp.para(FAILURE_CONDITION_OF_PREPROCESSING), exit_values.NO_EXECUTION__PRE_PROCESS_ERROR) ), docs.list_item(self._tp.text('Syntax checking and {directive:s} processing'), step_with_multiple_exit_values( self._tp.fnap(PURPOSE_OF_SYNTAX_CHECKING), self._tp.fnap(FAILURE_CONDITION_OF_SYNTAX_CHECKING), [ ('Syntax error', exit_values.NO_EXECUTION__SYNTAX_ERROR), ('File inclusion error', exit_values.NO_EXECUTION__FILE_ACCESS_ERROR), ]) ), docs.list_item('Validation', step_with_single_exit_value( self._tp.fnap(PURPOSE_OF_VALIDATION), self._tp.para(FAILURE_CONDITION_OF_VALIDATION), exit_values.EXECUTION__VALIDATION_ERROR) ), docs.list_item('Execution', self._tp.fnap(EXECUTION_DESCRIPTION) + [self.execution_sub_steps_description()] + self._tp.fnap(OUTCOME_OF_EXECUTION)), ] return lists.HeaderContentList(items, lists.Format(lists.ListType.ORDERED_LIST, custom_separations=docs.SEPARATION_OF_HEADER_AND_CONTENTS) ) def execution_sub_steps_description(self) -> docs.ParagraphItem: return lists.HeaderContentList([ docs.list_item(self._tp.text('execution of {phase[setup]:syntax}')), docs.list_item(docs.text(post_setup_validation_step_name(self._setup))), docs.list_item(docs.text('execution of remaining phases')), ], lists.Format(lists.ListType.ORDERED_LIST, custom_separations=docs.SEPARATION_OF_HEADER_AND_CONTENTS) )
def root(header: str, setup: Setup) -> generator.SectionHierarchyGenerator: tp = TextParser({ 'default_suite_file_name': file_names.DEFAULT_SUITE_FILE, 'act': phase_infos.ACT.name, 'action_to_check': concepts.ACTION_TO_CHECK_CONCEPT_INFO.name, 'ATC': concepts.ACTION_TO_CHECK_CONCEPT_INFO.acronym, 'actor': concepts.ACTOR_CONCEPT_INFO.name, 'os_process': misc_texts.OS_PROCESS_NAME, 'null_actor': actors.NULL_ACTOR.singular_name, 'shell_command_marker': SHELL_COMMAND_MARKER, }) def const_paragraphs(header_: StrOrStringText, initial_paragraphs: List[docs.ParagraphItem]) -> generator.SectionHierarchyGenerator: return h.leaf(header_, sections.constant_contents(docs.section_contents(initial_paragraphs))) def phases_documentation() -> List[ParagraphItem]: return (tp.fnap(_PHASES_INTRO) + [sections_short_list(setup.test_case_help.phase_helps_in_order_of_execution, phase_identifier.DEFAULT_PHASE.section_name, phase_names_plain.SECTION_CONCEPT_NAME)]) act_contents = sections.contents( paragraphs.constant(tp.fnap(_ACT)), [ _act_examples(tp), see_also.SeeAlsoSectionConstructor( see_also.items_of_targets(_act_see_also_targets()) ) ] ) instructions_contents = sections.contents( paragraphs.constant(tp.fnap(_INSTRUCTIONS)), [ see_also.SeeAlsoSectionConstructor( see_also.items_of_targets(_instructions_see_also_targets()) ) ] ) return h.hierarchy( header, children=[ h.child('phases', const_paragraphs('Phases', phases_documentation()) ), h.child('act', h.leaf( tp.text('The {act} phase, {action_to_check:/q} and {actor:s/q}'), act_contents ) ), h.child('instructions', h.leaf('Instructions', instructions_contents) ), h.child('suites', h.hierarchy( 'Relation to test suites', children=[ h.child('suite-contents', const_paragraphs('Inclusion of phase contents from suites', tp.fnap(_SUITE_CONTENTS_INCLUSION)) ), h.child('part-of-suite', const_paragraphs('Part of suite', tp.fnap(_PART_OF_SUITE)) ), h.with_not_in_toc( h.leaf( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_suite_see_also_targets()) ))) , ]), ), ] )
class AssertPhaseDocumentation(TestCasePhaseDocumentationForPhaseWithInstructions): def __init__(self, name: str, instruction_set: SectionInstructionSet): super().__init__(name, instruction_set) self._tp = TextParser({ 'phase': phase_names.PHASE_NAME_DICTIONARY, 'PASS': exit_values.EXECUTION__PASS.exit_identifier, 'FAIL': exit_values.EXECUTION__FAIL.exit_identifier, 'HARD_ERROR': exit_values.EXECUTION__HARD_ERROR.exit_identifier, 'result_subdir': sds.SUB_DIRECTORY__RESULT, 'sandbox': formatting.concept_(concepts.SANDBOX_CONCEPT_INFO), 'ENV_VAR_RESULT': ENV_VAR_RESULT, 'ATC': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO), }) def purpose(self) -> Description: return Description(self._tp.text(ONE_LINE_DESCRIPTION), self._tp.fnap(REST_OF_DESCRIPTION)) def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(sequence_info__preceding_phase(phase_names.BEFORE_ASSERT), self._tp.fnap(_SEQUENCE_INFO__SUCCEEDING_PHASE), prelude=sequence_info__not_executed_if_execution_mode_is_skip()) def instruction_purpose_description(self) -> List[docs.ParagraphItem]: paragraphs = self._tp.fnap(INSTRUCTION_PURPOSE_DESCRIPTION) paragraphs += self._instruction_groups_list() return paragraphs def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( cwd_at_start_of_phase_for_non_first_phases(), EXISTS_AT_BEFORE_ASSERT_MAIN, prologue=execution_environment_prologue_for_post_act_phase(), environment_variables_prologue=env_vars_prologue_for_inherited_from_previous_phase()) @property def instruction_group_by(self) -> Callable[[List[WithAssertPhasePurpose]], List[InstructionGroup]]: return self._instruction_group_by @property def _see_also_targets_specific(self) -> List[SeeAlsoTarget]: return [ concepts.SANDBOX_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, phase_infos.BEFORE_ASSERT.cross_reference_target, phase_infos.CLEANUP.cross_reference_target, ] def _instruction_group_by(self, instr_docs: List[WithAssertPhasePurpose]) -> List[InstructionGroup]: purpose_2_instructions = { value: [] for value in AssertPhasePurpose } for doc in instr_docs: assert isinstance(doc, WithAssertPhasePurpose), str(type(doc)) purpose_2_instructions[doc.assert_phase_purpose].append(doc) ret_val = [] for p in AssertPhasePurpose: instructions = purpose_2_instructions[p] if instructions: ret_val.append(self._group_of(p, instructions)) return ret_val def _group_of(self, purpose_type: AssertPhasePurpose, instructions: list) -> InstructionGroup: info = _INSTRUCTION_TYPES[purpose_type] return InstructionGroup(info[0], info[1], self._tp.fnap(info[2]), instructions) def _instruction_groups_list(self) -> List[docs.ParagraphItem]: def item(purpose: AssertPhasePurpose) -> lists.HeaderContentListItem: info = _INSTRUCTION_TYPES[purpose] return docs.list_item(info[0], self._tp.fnap(info[2])) return [ docs.simple_list_with_space_between_elements_and_content(map(item, list(AssertPhasePurpose)), ListType.ITEMIZED_LIST) ]
class _HdsConcept(ConceptDocumentation): def __init__(self): super().__init__(concepts.HDS_CONCEPT_INFO) self._tp = TextParser({ 'HDS': concepts.HDS_CONCEPT_INFO.acronym, 'hds_concept': formatting.concept_(concepts.HDS_CONCEPT_INFO), 'phase': phase_names.PHASE_NAME_DICTIONARY, 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'symbol': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'symbols': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.plural_name), 'conf_params': formatting.concept( concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name), 'PATH': syntax_elements.PATH_SYNTAX_ELEMENT.singular_name, 'Note': headers.NOTE_LINE_HEADER, }) def purpose(self) -> DescriptionWithSubSections: sub_sections = [ self._tp.section( concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name. capitalize(), _CONFIGURATION_PARAMETER), self._tp.section('Relative paths', _RELATIVITY), self._tp.section( self._tp.format( BUILTIN_SYMBOL_ENTITY_TYPE_NAMES.name.plural.capitalize()), _BUILTIN_SYMBOL), docs.section('Directories', self._directory_listing()), ] return DescriptionWithSubSections( self.single_line_description(), SectionContents(self._tp.fnap(_MAIN_DESCRIPTION_REST), sub_sections)) def see_also_targets(self) -> List[SeeAlsoTarget]: ret_val = [ concepts.TCDS_CONCEPT_INFO.cross_reference_target, concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO. cross_reference_target, concepts.SYMBOL_CONCEPT_INFO.cross_reference_target, types.PATH_TYPE_INFO.cross_reference_target, ] ret_val += [ dir_info.conf_param.cross_reference_target for dir_info in _ALL_DIRECTORIES ] ret_val += [ phase_infos.CONFIGURATION.instruction_cross_reference_target( dir_info.instruction_name) for dir_info in _ALL_DIRECTORIES ] return ret_val def _directory_listing(self) -> List[docs.ParagraphItem]: items = [self._dir_item(d) for d in _ALL_DIRECTORIES] return [docs.simple_list(items, lists.ListType.VARIABLE_LIST)] def _dir_item(self, x: _DirInfo) -> HeaderContentListItem: def prop_row(header: str, value_str_or_text) -> List[docs.TableCell]: return [ docs.text_cell(header), docs.text_cell(value_str_or_text), ] from exactly_lib.tcfs.relative_path_options import REL_HDS_OPTIONS_MAP properties_table = docs.first_column_is_header_table([ prop_row('Default value', x.default_value_description), prop_row( concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.singular_name. capitalize(), x.conf_param.configuration_parameter_name_text), prop_row('Set by instruction', instruction_name_text(x.instruction_name)), prop_row( BUILTIN_SYMBOL_ENTITY_TYPE_NAMES.name.singular.capitalize(), REL_HDS_OPTIONS_MAP[ x.relativity_option_type].directory_symbol_name_text), prop_row( 'Path relativity option', REL_HDS_OPTIONS_MAP[ x.relativity_option_type].option_name_text), ]) paras = [ docs.para(x.conf_param.single_line_description_str), properties_table, ] return docs.list_item(self._tp.text(x.item_name), paras)
def root(header: str, test_case_help: TestCaseHelp) -> generator.SectionHierarchyGenerator: tp = TextParser({ 'default_suite_file_name': file_names.DEFAULT_SUITE_FILE, 'act': phase_infos.ACT.name, 'assert': phase_infos.ASSERT.name, 'setup': phase_infos.SETUP.name, 'action_to_check': concepts.ACTION_TO_CHECK_CONCEPT_INFO.name, 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name, 'ATC': concepts.ACTION_TO_CHECK_CONCEPT_INFO.acronym, 'actor': concepts.ACTOR_CONCEPT_INFO.name, 'os_process': misc_texts.OS_PROCESS_NAME, 'null_actor': actors.NULL_ACTOR.singular_name, 'shell_command_marker': SHELL_COMMAND_MARKER, 'shell_command': formatting.misc_name_with_formatting(misc_texts.SHELL_COMMAND), 'shell_command_line': formatting.misc_name_with_formatting(misc_texts.SHELL_COMMAND_LINE), }) def const_paragraphs(header_: StrOrStringText, initial_paragraphs: List[docs.ParagraphItem]) -> generator.SectionHierarchyGenerator: return h.leaf(header_, sections.constant_contents(docs.section_contents(initial_paragraphs))) def phases_documentation() -> List[ParagraphItem]: return (tp.fnap(_PHASES_INTRO) + [sections_short_list(test_case_help.phase_helps_in_order_of_execution, phase_identifier.DEFAULT_PHASE.section_name, phase_names_plain.SECTION_CONCEPT_NAME)]) act_contents = sections.contents( paragraphs.constant(tp.fnap(_ACT)), [ _act_examples(tp), see_also.SeeAlsoSectionConstructor( see_also.items_of_targets(_act_see_also_targets()) ) ] ) instructions_contents = sections.contents( paragraphs.constant(tp.fnap(_INSTRUCTIONS)), [ see_also.SeeAlsoSectionConstructor( see_also.items_of_targets(_instructions_see_also_targets()) ) ] ) return h.hierarchy( header, children=[ h.child('phases', const_paragraphs('Phases', phases_documentation()) ), h.child('act', h.leaf( tp.text('The {act} phase, {action_to_check:/q} and {actor:s/q}'), act_contents ) ), h.child('instructions', h.leaf(tp.text('{instruction:s/u}'), instructions_contents) ), h.child('suites', h.hierarchy( 'Relation to test suites', children=[ h.child('suite-contents', const_paragraphs('Inclusion of phase contents from suites', tp.fnap(_SUITE_CONTENTS_INCLUSION)) ), h.child('part-of-suite', const_paragraphs('Part of suite', tp.fnap(_PART_OF_SUITE)) ), h.leaf_not_in_toc( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_suite_see_also_targets()) ) ), ]), ), ] )
class _HdsConcept(ConceptDocumentation): def __init__(self): super().__init__(concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO) self._tp = TextParser({ 'HDS': formatting.concept_(concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO), 'phase': phase_names.PHASE_NAME_DICTIONARY, 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'symbol': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'symbols': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.plural_name), 'conf_params': formatting.concept(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name), 'PATH': syntax_elements.PATH_SYNTAX_ELEMENT.singular_name, }) def purpose(self) -> DescriptionWithSubSections: rest_paragraphs = [] rest_paragraphs += self._tp.fnap(_MAIN_DESCRIPTION_REST) rest_paragraphs += self._directory_listing() sub_sections = [ self._section(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.singular_name.capitalize(), _CONFIGURATION_PARAMETER), self._section('Relative paths', _RELATIVITY), self._section(self._tp.format('Builtin {symbols} and environment variables'), _BUILTIN_SYMBOL_ENVIRONMENT_VARIABLE), ] return DescriptionWithSubSections(self.single_line_description(), SectionContents(rest_paragraphs, sub_sections)) def _section(self, header: str, text_to_format: str) -> docs.Section: return docs.section(header, self._tp.fnap(text_to_format)) def see_also_targets(self) -> List[SeeAlsoTarget]: ret_val = [ concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO.cross_reference_target, concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.cross_reference_target, types.PATH_TYPE_INFO.cross_reference_target, ] ret_val += [ dir_info.conf_param.cross_reference_target for dir_info in _ALL_DIRECTORIES ] ret_val += [ phase_infos.CONFIGURATION.instruction_cross_reference_target(dir_info.instruction_name) for dir_info in _ALL_DIRECTORIES ] return ret_val def _directory_listing(self) -> List[docs.ParagraphItem]: items = [ self._dir_item(d) for d in _ALL_DIRECTORIES ] return [ docs.simple_list(items, lists.ListType.VARIABLE_LIST) ] def _dir_item(self, x: _DirInfo) -> HeaderContentListItem: def prop_row(header: str, value_str_or_text) -> List[docs.TableCell]: return [docs.text_cell(header), docs.text_cell(value_str_or_text), ] from exactly_lib.test_case_file_structure.relative_path_options import REL_HOME_OPTIONS_MAP properties_table = docs.first_column_is_header_table( [ prop_row('Default value', x.default_value_description), prop_row(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.singular_name.capitalize(), x.conf_param.configuration_parameter_name_text), prop_row('Set by instruction', instruction_name_text(x.instruction_name)), prop_row('Variable name', REL_HOME_OPTIONS_MAP[x.relativity_option_type].directory_variable_name_text), prop_row('Relativity option', REL_HOME_OPTIONS_MAP[x.relativity_option_type].option_name_text), ] ) paras = [ docs.para(x.conf_param.single_line_description_str), properties_table, ] return docs.list_item(self._tp.text(x.item_name), paras)
class CommandLineActorDocumentation(ActorDocumentation): def __init__(self): super().__init__(COMMAND_LINE_ACTOR) self._tp = TextParser({ 'LINE_COMMENT_MARKER': formatting.string_constant(LINE_COMMENT_MARKER), 'PROGRAM': syntax_elements.PROGRAM_SYNTAX_ELEMENT.singular_name, 'STRING_TRANSFORMER': syntax_elements.STRING_TRANSFORMER_SYNTAX_ELEMENT.singular_name, 'PATH': syntax_elements.PATH_SYNTAX_ELEMENT.singular_name, 'path': types.PATH_TYPE_INFO.name, 'executable_file': formatting.misc_name_with_formatting(misc_texts.EXECUTABLE_FILE), 'relativity': formatting.misc_name_with_formatting(misc_texts.RELATIVITY), 'stdout': misc_texts.STDOUT, 'stdin': misc_texts.STDIN, 'os_process': misc_texts.OS_PROCESS_NAME, 'setup_phase': phase_names.SETUP, }) def act_phase_contents(self) -> doc.SectionContents: return doc.SectionContents(self._tp.fnap(_ACT_PHASE_CONTENTS)) def act_phase_contents_syntax(self) -> doc.SectionContents: return doc.SectionContents( self._tp.fnap( SINGLE_LINE_PROGRAM_ACT_PHASE_CONTENTS_SYNTAX_INITIAL_PARAGRAPH ), self._act_phase_contents_syntax_sub_sections(), ) def notes(self) -> SectionContents: return docs.section_contents(sub_sections=[ docs.section( self._tp.text('{path:/u} {relativity:s}'), self._notes_section_paragraphs(), ), docs.section( self._tp.text(misc_texts.STDIN.capitalize()), self._tp.fnap(_STDIN_DESCRIPTION), ), docs.section( self._tp.text('Transformations'), self._tp.fnap(_TRANSFORMATION_DESCRIPTION), ), ]) def _act_phase_contents_syntax_sub_sections(self) -> List[doc.Section]: return [ doc_utils.synopsis_section( invokation_variants_content(None, self._invokation_variants(), ())) ] @staticmethod def _invokation_variants() -> List[InvokationVariant]: return [ invokation_variant_from_args( [syntax_elements.PROGRAM_SYNTAX_ELEMENT.single_mandatory]), ] def _notes_section_paragraphs(self) -> List[ParagraphItem]: ret_val = self._tp.fnap(_PATH_RELATIVITY_HEADER) ret_val += relative_path_options_documentation.path_element_relativity_paragraphs( rel_opt_conf.REL_OPTIONS_CONFIGURATION) return ret_val def _see_also_specific(self) -> List[SeeAlsoTarget]: return cross_reference_id_list([ conf_params.HDS_ACT_DIRECTORY_CONF_PARAM_INFO, syntax_elements.PATH_SYNTAX_ELEMENT, syntax_elements.PROGRAM_SYNTAX_ELEMENT, ])
def root(header: str) -> generator.SectionHierarchyGenerator: tp = TextParser({ 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'conf_param': formatting.concept_(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO), 'tcds_concept': formatting.concept_(concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO), 'TCDS': concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO.acronym, 'SDS': concepts.SANDBOX_CONCEPT_INFO.acronym, 'sds_concept': formatting.concept_(concepts.SANDBOX_CONCEPT_INFO), 'Sds_concept_header': concepts.SANDBOX_CONCEPT_INFO.singular_name.capitalize(), 'sds_single_line_description': concepts.SANDBOX_CONCEPT_INFO.single_line_description_str.capitalize(), 'HDS': concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO.acronym, 'hds_concept': formatting.concept_(concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO), 'Hds_concept_header': concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO.singular_name.capitalize(), 'hds_single_line_description': concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO.single_line_description_str.capitalize(), 'conf_phase': phase_names.CONFIGURATION, 'act_phase': phase_names.ACT, 'act_home_conf_param': formatting.conf_param(test_case_file_structure.HDS_ACT_INFO.identifier), 'data': type_system.DATA_TYPE_CATEGORY_NAME, 'path_type': formatting.term(types.PATH_TYPE_INFO.singular_name), 'symbol_concept': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME), 'os_process': misc_texts.OS_PROCESS_NAME, 'time_out_conf_param': formatting.conf_param_(conf_params.TIMEOUT_CONF_PARAM_INFO), 'relativity': formatting.concept(misc_texts.RELATIVITY.singular), 'relativities': formatting.concept(misc_texts.RELATIVITY.plural), 'cd': formatting.emphasis(instruction_names.CHANGE_DIR_INSTRUCTION_NAME), 'env': formatting.emphasis(instruction_names.ENV_VAR_INSTRUCTION_NAME), 'CD': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), }) def const_paragraphs_child(local_target_name: str, header_: str, paragraphs_: List[ParagraphItem]) -> generator.SectionHierarchyGenerator: return h.child(local_target_name, h.leaf(header_, sections.constant_contents(section_contents(paragraphs_))) ) return h.hierarchy( header, children=[ h.child_hierarchy( 'dir-structure', 'Directory structure and Current directory', paragraphs.constant(tp.fnap(_DS_CD_PREAMBLE)), [ const_paragraphs_child( 'sds', concepts.SANDBOX_CONCEPT_INFO.singular_name.capitalize() + ' and Current directory', tp.fnap(_SDS_AND_CD) ), const_paragraphs_child( 'hds', concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO.singular_name.capitalize(), tp.fnap(_HDS), ), const_paragraphs_child( 'file-ref', 'File references', tp.fnap(_FILE_REFERENCES) ), h.child('see-also', h.with_not_in_toc( h.leaf( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_dir_struct_see_also_targets()) ))) ), ] ), h.child_hierarchy( 'symbols', concepts.SYMBOL_CONCEPT_INFO.plural_name.capitalize(), paragraphs.constant(tp.fnap(_SYMBOLS)), [ h.with_not_in_toc( h.child_leaf( 'see-also', see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_symbols_see_also_targets()) )) ) ] ), h.child_hierarchy( 'os-proc', tp.text('{os_process} environment'), paragraphs.constant(tp.fnap(_OS_PROC_INTRO)), [ const_paragraphs_child( 'cd', 'Current directory', tp.fnap(_OS_PROC_CURRENT_DIRECTORY), ), const_paragraphs_child( 'env-vars', 'Environment variables', tp.fnap(_OS_PROC_ENVIRONMENT_VARIABLES), ), const_paragraphs_child( 'timeout', 'Timeout', tp.fnap(_OS_PROC_TIMEOUT), ), h.with_not_in_toc( h.child_leaf( 'see-also', see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_os_process_see_also_targets()) ))) , ], ), ] )