Ir para o conteúdo principal

desenvolvimento · Referência do comando

qzx addPythonDocstrings

O que faz

Visualiza ou adiciona docstrings geradas a funções, métodos e classes de um arquivo Python.

Maturidade do comando: Alpha

Disponível para uso real e feedback enquanto a interface e o comportamento ainda podem evoluir. Esta é a avaliação atual do checkout de desenvolvimento. Cada tag de release imutável futuro preservará a avaliação exata incluída nessa versão. Disponível no PyPI 0.2.2.0.9. A documentação corresponde ao checkout alpha 0.2.2.0.9.

Comportamento e proteções integradas

O modo real aplica as alterações solicitadas

Prévia disponível

Funciona sem invocar programas nativos

Funciona sem usar a rede

Projetado para funcionar sem elevação

O QZX cria um arquivo de recuperação antes das alterações reais; use --dangerously-bypass-approvals-and-sandbox/--yolo somente quando decidir ignorá-lo deliberadamente.

Esta classificação de segurança foi revisada por OpenAI GPT-5.6 Pro em relação ao digest de implementação sha256:49adb01eeda3ea929526a4b1d90b8cf67df0072bf654c68e41fe9118603e147d em 2026-08-25.

Sintaxe exata

qzx addPythonDocstrings <file_path> [style] [overwrite] [dry_run] --json

Parâmetros

Deslize ou use a barra horizontal para ver todas as colunas.

NomeTipoObrigatórioPadrãoDescrição
file_pathstrSimNão declaradoCaminho do arquivo Python que será processado
stylestrNão"google"Estilo de documentação (google, numpy ou sphinx)
overwriteboolNãofalseIndica se os docstrings existentes serão sobrescritos
dry_runboolNãotrueVisualiza as alterações sem modificar o arquivo

Exemplos de entrada

qzx addPythonDocstrings myfile.py

Visualizar modelos de docstring no estilo Google para myfile.py

qzx addPythonDocstrings myfile.py sphinx

Visualizar modelos de docstring no estilo Sphinx para myfile.py

qzx addPythonDocstrings myfile.py --dry-run false

Criar um backup de myfile.py e depois adicionar os docstrings ausentes no estilo Google

qzx addPythonDocstrings myfile.py --overwrite --dry-run false

Criar um backup de myfile.py e depois substituir os docstrings existentes

Para obter o payload estruturado completo, adicione --json: qzx addPythonDocstrings <file_path> [style] [overwrite] [dry_run] --json

Exemplo de saída representativa

Este JSON ilustrativo deriva do contrato de resultado respaldado pela implementação atual. Mostra o que o comando pode retornar sem afirmar que seja uma execução gravada; os valores variam conforme entradas, máquina, permissões e ferramentas opcionais.

Comando do exemplo: qzx addPythonDocstrings myfile.py --json

{
    "success": true,
    "message": "Previews or adds generated docstring templates to functions, methods, and classes in one Python file. In this illustrative example, the command completed successfully.",
    "meta": {
        "command": "addPythonDocstrings",
        "command_maturity": {
            "stage": "alpha",
            "label": "Alpha",
            "sequence": 2,
            "public_executable": true,
            "stability": "interface_may_change",
            "summary": "Available for real use and feedback while its interface and behavior can still evolve.",
            "promotion_review_required": false,
            "assessment_scope": "development_checkout"
        },
        "duration_ms": 0,
        "schema_version": 1
    },
    "changes_applied": "Example value",
    "changes_detected": "Example value",
    "changes_made": "Example value",
    "changes_preview": [
        "Add a module docstring.",
        "Document the public function."
    ],
    "details": {
        "file_path": "C:\\project\\example.txt"
    },
    "dry_run": true,
    "file_path": "C:\\project\\example.txt",
    "overwrite": true,
    "stats": {
        "summary": "Additional structured context is included here."
    },
    "status": "ok",
    "style": "Example value"
}
Ver o contrato de resultado JSON
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
        "success",
        "message",
        "meta"
    ],
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "meta": {
            "type": "object",
            "required": [
                "command",
                "command_maturity",
                "duration_ms",
                "schema_version"
            ],
            "properties": {
                "command": {
                    "type": "string"
                },
                "command_maturity": {
                    "type": "object",
                    "required": [
                        "stage",
                        "label",
                        "sequence",
                        "public_executable",
                        "stability",
                        "summary",
                        "promotion_review_required",
                        "assessment_scope"
                    ],
                    "properties": {
                        "stage": {
                            "type": "string"
                        },
                        "label": {
                            "type": "string"
                        },
                        "sequence": {
                            "type": "integer"
                        },
                        "public_executable": {
                            "type": "boolean"
                        },
                        "stability": {
                            "type": "string"
                        },
                        "summary": {
                            "type": "string"
                        },
                        "promotion_review_required": {
                            "type": "boolean"
                        },
                        "assessment_scope": {
                            "type": "string"
                        },
                        "note": {
                            "type": "string"
                        },
                        "review": {
                            "type": "object",
                            "required": [
                                "reviewed_on",
                                "rationale",
                                "evidence"
                            ],
                            "properties": {
                                "reviewed_on": {
                                    "type": "string",
                                    "format": "date"
                                },
                                "rationale": {
                                    "type": "string"
                                },
                                "evidence": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "replacement": {
                                    "type": "string"
                                }
                            },
                            "additionalProperties": false
                        }
                    },
                    "additionalProperties": true
                },
                "duration_ms": {
                    "type": "number"
                },
                "schema_version": {
                    "type": "integer"
                }
            },
            "additionalProperties": true
        },
        "changes_applied": [],
        "changes_detected": [],
        "changes_made": [],
        "changes_preview": [],
        "details": {
            "type": "object",
            "properties": {
                "file_path": []
            },
            "additionalProperties": true
        },
        "dry_run": [],
        "error": {
            "type": "string"
        },
        "error_code": {
            "type": "string"
        },
        "file_path": [],
        "overwrite": [],
        "stats": [],
        "status": {
            "type": "string"
        },
        "style": []
    },
    "additionalProperties": true
}

Erros e limites

O contrato público exige success=false e uma message descritiva em caso de falha. Este catálogo ainda não declara uma taxonomia de erros específica para cada comando; revise o resultado e não infira códigos inexistentes.

O QZX está em alpha. Dependências opcionais, permissões e recursos do host podem alterar o resultado.

Fluxo de evidência: requer um destino descartável isolado.

Evidência e procedência

Canal de documentação
Documentação de desenvolvimento 0.2.2.0.9 · main · sha256:cfba936e39931c286ca23add0ae546693db17d8b316e7cbc3891d26642d9b7e8
Disponibilidade
0.2.2.0.9 ou anterior

Continue explorando

Comandos relacionados

Estes comandos também pertencem à categoria desenvolvimento. Compare-os para escolher a operação que melhor resolve sua tarefa.

Explorar todos os comandos do QZX