cpdocs API documentation
Project documentation Docs

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)