Documentação
pydoc
Python para Todos – Evaldo Wolkers
pydoc
O pydoc é uma ferramenta de documentação que já é instalada
junto com o Python.
O módulo pydoc gera automaticamente documentação para
módulos Python.
Esta documentação pode ser apresentada como páginas de
texto no console, servidas em um navegador da Web ou salvas
em arquivos HTML.
Para módulos, classes, funções e métodos, a documentação
exibida é derivada do docstring (ou seja, o atributo __doc__) do
objeto e, recursivamente de seus membros documentáveis.
Python para Todos – Evaldo Wolkers
pydoc
Se não houver nenhuma docstring, o pydoc tenta obter uma
descrição do bloco de linhas de comentários acima da definição
da classe, função ou método no arquivo de origem ou na parte
superior do módulo.
A função help() invoca o sistema de ajuda on-line no
interpretador interativo, que usa o pydoc para gerar sua
documentação como texto no console.
A mesma documentação de texto também pode ser visualizada
de fora do interpretador Python executando pydoc como um
script no prompt de comando (terminal) do sistema operacional.
Python para Todos – Evaldo Wolkers
pydoc
Veja como usar o pydoc no Windows:
C:\>python –m pydoc argumento
Onde argumento é o nome de uma função, módulo ou
pacote que você queira ver a documentação.
No Linux você pode usar similar ao uso no Windows ou
usar o pydoc diretamente assim:
$ pydoc argumento
Python para Todos – Evaldo Wolkers
pydoc
Veja o resultado do comando “python –m pydoc os” no
Windows:
Você pode pressionar enter
para ir passando o conteúdo
ou pressionar “q” par sair.
Python para Todos – Evaldo Wolkers
pydoc
Veja o resultado do comando “pydoc sys” no Linux:
Python para Todos – Evaldo Wolkers
pydoc
A saída do pydoc é similar às páginas de manual mostradas
pelo comando man do Unix.
Veja o resultado do comando “man cp”
no Linux. O comando “cp” é utilizado para
cópia de arquivos.
Python para Todos – Evaldo Wolkers
pydoc
Você pode iniciar um servidor web com o pydoc
para ler a documentação do Python.
No Windows use: “python –m pydoc –p 8000”,
onde 8000 é uma porta de sua escolha.
Veja o resultado:
Em seguida acesse [Link] em
seu browser e navegue pela documentação.
Python para Todos – Evaldo Wolkers
pydoc
No Linux use:
“pydoc –p 8000”.
Python para Todos – Evaldo Wolkers
pydoc
É possível também consultar a documentação de dentro
do interpretador com o comando help(argumento).
Exemplo:
>>> help(int)
Python para Todos – Evaldo Wolkers
pydoc
No Linux, o pydoc também tem uma interface gráfica, mas
que depende da biblioteca Tkinter.
Use o comando abaixo para instalar esta dependência:
$ sudo apt-get install python-tk
Após a instalação, execute o comando abaixo:
$ pydoc -g
Python para Todos – Evaldo Wolkers
pydoc
Aparece uma interface com um campo de pesquisa “Search for”,
onde você pode digitar um texto para pesquisar. Eu digite
“float” nesta caixa e pressionei enter, na segunda imagem, estão
sendo exibidos 3 resultados para “float”, veja que na terceira
imagem temos o resultado ao escolher o primeiro item exibido e
clicar em “go to selected”
Python para Todos – Evaldo Wolkers
pydoc
Documentando seu código
Vamos agora ver como usar docstrings para gerar
documentos em HTML para nossos programas.
Python para Todos – Evaldo Wolkers
pydoc
"""
Este módulo possui uma classe para a realização de diversos cálculos utilizando dois números
Sintaxe:
Calculo(valor1, valor2)
Métodos implementados:
somar, subtrair, dividir.
"""
class Calculo(object):
"""
Classe para realização dos cálculos
"""
def __init__(self, numero1, numero2):
"""
Construindo um novo objeto Calculo
:param numero1: Variável que armazena o primeiro número
:param numero2: Variável que armazena o segundo número
:return: Sem retorno
"""
self.numero1 = numero1
self.numero2 = numero2
Python para Todos – Evaldo Wolkers
pydoc
def somar(self):
"""
Método que realiza a soma de dois números
:return: Retorna o resultado da soma de dois números
"""
return self.numero1 + self.numero2
def subtrair(self):
"""
Método que realiza a subtração de dois números
:return: Retorna o resultado da subtração de dois números
"""
return self.numero1 - self.numero2
Python para Todos – Evaldo Wolkers
pydoc
def subtrair_do_maior(self):
"""
Método que realiza a subtração de dois números, utilizando sempre maior - menor
:return: Retorna o resultado da subtração de dois números
"""
""" Validando qual número é maior para realizar o subtração -> Não será utilizado"""
if self.numero2 < self.numero1:
resultado = self.numero2 - self.numero1
else:
resultado = self.numero1 - self.numero2
return resultado
def dividir(self):
"""
Método que realiza a divisão de dois números
:return: Retorna a divisão de dois números
"""
return self.numero1 / self.numero2
Python para Todos – Evaldo Wolkers
pydoc
No Linux pode-se usar:
pydoc –w diretório/pasta
Python para Todos – Evaldo Wolkers
FIM
Python para Todos – Evaldo Wolkers