Use o pydoc para obter ajuda rápida sobre o Python

Durante a fase de construção de um programa em Python, há várias formas de se obter ajuda rápida e, por vezes, contextual.
Algumas IDE’s possuem todo um sistema de consulta para o desenvolvedor, inclusive.
No terminal, em qualquer instalação comum do Python, é possível obter ajuda baseada na documentação oficial com o programa pydoc.
Basta dar a ele o nome do item para o qual você deseja obter ajuda.
No Linux/MacOS ou no FreeBSD, use-o assim:


pydoc input

Help on built-in function input in module __builtin__:

input(...)
    input([prompt]) -> value
    
    Equivalent to eval(raw_input(prompt)).

No Windows, caso a sua versão do Python seja a 3.6, use assim:


python3.6 -m pydoc input

Para sair do pydoc, tecle ‘q’.

Resumidamente, o pydoc pode fornecer informações sobre palavras-chave, tópicos, funções, módulos, pacotes etc.
Quando está em execução, tem um funcionamento semelhante ao programa man, presente em ambientes Linux/UNIX.
Você pode fazer buscas dentro da documentação com a opção -k:


pydoc -k string

cStringIO - A simple fast partial StringIO replacement.
strop - Common string manipulations, optimized for speed.
StringIO - File-like objects that read from or write to a string buffer.
UserString - A user-defined wrapper around string objects
distutils.versionpredicate - Module for parsing and testing package version predicate strings.
doctest - Module doctest -- a framework for running examples in docstrings.
encodings.string_escape - Python 'escape' Codec
lib2to3.fixes.fix_basestring - Fixer for basestring -> str.
lib2to3.pgen2.literals - Safely evaluate Python string literals without using eval().
string - A collection of string operations (most are no longer used).
stringold - Common string manipulations.
stringprep - Library that exposes various tables found in the StringPrep RFC 3454.
numpy.core.defchararray - This module contains a set of functions for vectorized string
numpy.lib._version - Utility to compare (NumPy) version strings.

Na lista acima, os tópicos em que o assunto “string” é abordado, na documentação do pydoc.

Rode um servidor pydoc

Para atender um maior número de desenvolvedores dentro da mesma rede, é possível colocar a documentação online.
Use o comando


sudo pydoc -p 80

[sudo] senha para justincase: 
pydoc server ready at http://localhost:80/

para por no ar um servidor com a documentação, acessível através (neste exemplo) do site “http://localhost:80”. Se a porta 80 estiver ocupada, use outra após a opção ‘-p’.

pydoc documentação python online

Para encerrar o servidor, pressione ^C (Ctrl + c) na linha de comando, onde você o ativou.
Se quiser enviar um tópico da documentação para um documento HTML, a ser usado em consulta posterior, dê o comando assim:


pydoc -w input

wrote input.html

Como você pode ver, acima, o comando cria um arquivo html com o conteúdo do tópico pedido.

Assinar blog por e-mail

Digite seu endereço de e-mail para assinar este blog e receber notificações de novas publicações por e-mail.

Junte-se a 48 outros assinantes

Use as docstrings para documentar seu código Python

Se você está lendo isso, provavelmente sabe o quanto é importante documentar seu trabalho, desde o início.
Depois de escrito, o código ainda vai ser lido inúmeras vezes.
Programadores experientes conhecem bem a situação de revisitar código escrito meses atrás e — se não estiver bem documentado — ficar coçando a cabeça para entender “o que diabos esta porcaria faz?”
O Python facilita escrever código legível e você só precisa se aproveitar disso.
Um destes recursos são as documentation strings ou texto de documentação — ou docstrings.

Quando posicionada adequadamente, dentro de uma função, a docstring pode informar o que a função faz e como usar corretamente seus parâmetros.
Em editores e IDEs avançadas, o texto da docstring passará a ser exibido a cada vez que a função for invocada dentro do código — como uma ajuda sensível ao contexto.
python docstrings in komodo editor
Na figura, acima, é possível ver o exemplo dentro do Komodo Editor.
Use 3 aspas simples para iniciar uma docstring e, novamente, para finalizar.
Veja um exemplo:

def minha_funcao(parametro=True):
    ''' texto de documentação específico da função minha_funcao
    que leva um único parâmetro, que é verdadeiro por padrão
    '''
    
minha_funcao()

As aspas triplas podem ser usadas aonde você quiser. Serão mais comumente encontradas em docstrings.
Mas você pode usá-las apenas para inserir comentários em múltiplas linhas, em qualquer ponto do seu codigo.

As aspas simples triplas informam ao interpretador Python que se trata de uma string em múltiplas linhas.
Tudo o que você quiser escrever cabe dentro deste espaço — o que inclui, além do texto, as quebras de linha, os espaços em branco ou outras aspas.
Se você for usar docstrings para documentar uma função, tenha em mente que elas devem ser iniciadas logo abaixo da função, como no exemplo dado, logo acima.

Assinar blog por e-mail

Digite seu endereço de e-mail para assinar este blog e receber notificações de novas publicações por e-mail.

Junte-se a 48 outros assinantes