def test_first_paragraph() -> None:
assert (first_paragraph(
dedent("""\
Hello! I'm spread out
over multiple
lines.
Second paragraph.
""")) == "Hello! I'm spread out over multiple lines.")
assert first_paragraph("Only one paragraph.") == "Only one paragraph."
def create(
cls,
target_type: type[Target],
*,
provider: str,
union_membership: UnionMembership,
get_field_type_provider: Callable[[type[Field]], str] | None,
) -> TargetTypeHelpInfo:
fields = list(target_type.class_field_types(union_membership=union_membership))
if issubclass(target_type, TargetGenerator):
# NB: Even though the moved_fields will never be present on a constructed
# TargetGenerator, they are legal arguments... and that is what most help consumers
# are interested in.
fields.extend(target_type.moved_fields)
return cls(
alias=target_type.alias,
provider=provider,
summary=first_paragraph(target_type.help),
description=target_type.help,
fields=tuple(
TargetFieldHelpInfo.create(
field,
provider=""
if get_field_type_provider is None
else get_field_type_provider(field),
)
for field in fields
if not field.alias.startswith("_") and field.removal_version is None
),
)
def _print_all_goals(self) -> None:
goal_descriptions: Dict[str, str] = {}
for goal_info in self._all_help_info.name_to_goal_info.values():
if goal_info.is_implemented:
goal_descriptions[goal_info.name] = goal_info.description
self._print_title("Goals")
max_width = max((len(name) for name in goal_descriptions.keys()),
default=0)
chars_before_description = max_width + 2
def format_goal(name: str, descr: str) -> str:
name = self.maybe_cyan(name.ljust(chars_before_description))
descr = self._format_summary_description(descr,
chars_before_description)
return f"{name}{descr}\n"
for name, description in sorted(goal_descriptions.items()):
print(format_goal(name, first_paragraph(description)))
specific_help_cmd = f"{self._bin_name} help $goal"
print(
f"Use `{self.maybe_green(specific_help_cmd)}` to get help for a specific goal.\n"
)
def create(cls, target_type: type[Target], *,
union_membership: UnionMembership) -> TargetTypeHelpInfo:
return cls(
alias=target_type.alias,
summary=first_paragraph(target_type.help),
description=target_type.help,
fields=tuple(
TargetFieldHelpInfo.create(field)
for field in target_type.class_field_types(
union_membership=union_membership)
if not field.alias.startswith("_")
and field.removal_version is None),
)
def get_docstring_summary(
cls: Type,
*,
fallback_to_ancestors: bool = False,
ignored_ancestors: Iterable[Type] = (object, )
) -> Optional[str]:
"""Get the summary line(s) of docstring for a class.
If the summary is one more than one line, this will flatten them into a single line.
"""
# This will fix indentation and strip unnecessary whitespace.
all_docstring = get_docstring(cls,
fallback_to_ancestors=fallback_to_ancestors,
ignored_ancestors=ignored_ancestors)
return first_paragraph(all_docstring) if all_docstring else None
def _print_all_subsystems(self) -> None:
self._print_title("Subsystems")
subsystem_description: Dict[str, str] = {}
for alias, help_info in self._all_help_info.scope_to_help_info.items():
if not help_info.is_goal and alias:
subsystem_description[alias] = first_paragraph(help_info.description)
longest_subsystem_alias = max(len(alias) for alias in subsystem_description.keys())
chars_before_description = longest_subsystem_alias + 2
for alias, description in sorted(subsystem_description.items()):
alias = self.maybe_cyan(alias.ljust(chars_before_description))
description = self._format_summary_description(description, chars_before_description)
print(f"{alias}{description}\n")
specific_help_cmd = f"{self._bin_name} help $subsystem"
print(
f"Use `{self.maybe_green(specific_help_cmd)}` to get help for a "
f"specific subsystem.\n"
)
def create(
cls, target_type: Type[Target], *, union_membership: UnionMembership
) -> TargetTypeHelpInfo:
description: Optional[str]
summary: Optional[str]
if hasattr(target_type, "help"):
description = target_type.help
summary = first_paragraph(description)
else:
description = get_docstring(target_type)
summary = get_docstring_summary(target_type)
return cls(
alias=target_type.alias,
summary=summary,
description=description,
fields=tuple(
TargetFieldHelpInfo.create(field)
for field in target_type.class_field_types(union_membership=union_membership)
if not field.alias.startswith("_") and field.deprecated_removal_version is None
),
)
