File: cpdocs/languages/python/render.py
1# --------------------------------------------------------------------------------------------------2# SPDX-License-Identifier: Apache-2.03# SPDX-FileCopyrightText: 2026 cpdocs developers4# --------------------------------------------------------------------------------------------------5"""Python presentation rules."""6 7from __future__ import annotations8 9import cpdocs.languages.base10import cpdocs.languages.python.entities11import cpdocs.model12 13 14def _parameters(signature: cpdocs.model.ApiSignature) -> str:15 values: list[str] = []16 parameters = list(signature.parameters)17 positional_only = [item for item in parameters if item.kind == "positional-only"]18 has_var_positional = any(item.kind == "var-positional" for item in parameters)19 keyword_marker_emitted = False20 for index, parameter in enumerate(parameters):21 if parameter.kind == "keyword-only" and not has_var_positional and not keyword_marker_emitted:22 values.append("*")23 keyword_marker_emitted = True24 prefix = ""25 if parameter.kind == "var-positional":26 prefix = "*"27 keyword_marker_emitted = True28 elif parameter.kind == "var-keyword":29 prefix = "**"30 value = prefix + parameter.name31 if parameter.type:32 value += f": {parameter.type}"33 if parameter.default is not None:34 value += f" = {parameter.default}"35 values.append(value)36 if positional_only and index + 1 == len(positional_only):37 values.append("/")38 return ", ".join(values)39 40 41def entity_declaration(entity: cpdocs.model.ApiEntity) -> str:42 if entity.kind in {"class", "protocol"}:43 bases = f"({', '.join(entity.bases)})" if entity.bases else ""44 return f"class {entity.qualified_name}{bases}"45 if entity.kind in {"module", "package"}:46 return f"module {entity.qualified_name}"47 if entity.kind == "type_alias":48 return f"{entity.qualified_name} = {cpdocs.languages.base.assigned_property(entity)}".rstrip()49 if entity.kind in {"attribute", "variable", "constant", "property"}:50 type_name = cpdocs.languages.base.typed_property(entity, ignored=frozenset({"property"}))51 assigned = cpdocs.languages.base.assigned_property(entity)52 value = entity.qualified_name + (f": {type_name}" if type_name else "")53 return value + (f" = {assigned}" if assigned else "")54 return entity.qualified_name55 56 57def signature_spelling(entity: cpdocs.model.ApiEntity, signature: cpdocs.model.ApiSignature) -> str:58 if signature.spelling:59 return signature.spelling60 prefix = "async def" if "async" in signature.qualifiers else "def"61 value = f"{prefix} {entity.qualified_name}({_parameters(signature)})"62 if signature.returns:63 value += f" -> {signature.returns}"64 return value65 66 67def member_summary(entity: cpdocs.model.ApiEntity) -> str:68 if entity.kind in {"attribute", "variable", "constant", "property"}:69 type_name = cpdocs.languages.base.typed_property(entity, ignored=frozenset({"property"}))70 assigned = cpdocs.languages.base.assigned_property(entity)71 value = entity.name + (f": {type_name}" if type_name else "")72 return value + (f" = {assigned}" if assigned else "")73 if entity.kind == "type_alias":74 return f"{entity.name} = {cpdocs.languages.base.assigned_property(entity)}".rstrip()75 if entity.kind in {"class", "protocol"}:76 return f"{entity.kind} {entity.name}"77 return entity.name78 79 80RENDERING = cpdocs.languages.base.LanguageRendering(81 separator=".",82 kinds=cpdocs.languages.python.entities.ENTITY_KINDS,83 source_suffixes=frozenset({".py", ".pyi"}),84 signature_spelling=signature_spelling,85 entity_declaration=entity_declaration,86 member_summary=member_summary,87)