Aula 12 – Python – PyDOC – Documentação
Python – PyDOC – Documentação.
Pydoc é um módulo que gera automaticamente a documentação dos módulos do Python.
Que fazer esse curso com certificação?
Acesse:
https://workover.com.br/python-codigo-fluente
PyDOC – Documentação
Voltar para página principal do blog
Todas as aulas desse curso
Aula 11 Aula 13
Automatize tarefas do dia a dia com python:
Curso Python Bot
PyDOC é portanto, utilizado para documentar códigos Python.
Pode ser utilizado para acessar a documentação dos módulos que acompanham o Python e também a documentação de outros módulos, criados por você ou por outros desenvolvedores.
Para módulos, classes, funções e métodos, a documentação exibida é derivada da docstring (ou seja, o atributo __doc__) do objeto e recursivamente de seus membros documentáveis.
Se não houver docstring, o pydoc tenta obter uma descrição do bloco de linhas de comentário logo 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 interna help () chama 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 vista de fora do interpretador Python, executando o pydoc como um script no prompt de comando do sistema operacional. Por exemplo, execute no linux:
pydoc sys
Ou no cmd do windows execute:
python -m pydoc sys
E então, será exibida a documentação do módulo sys, em um estilo similar às páginas de manual mostradas pelo comando man do Unix.
O argumento para o pydoc pode ser o nome de uma função, de um módulo ou um pacote, ou ainda, uma classe referenciada por um ponto, método ou função, dentro de um módulo ou módulo em um pacote.
Você pode passar o caminho para um arquivo que você quer documentar para o pydoc. Exemplo:
python -m pydoc caminho/para/o/modulo/sys
Nota:
Para localizar objetos e sua documentação, o pydoc importa o(s) módulo(s) a ser(em) documentado(s).
Portanto, qualquer código no nível do módulo será executado nessa ocasião.
Use um:
if __name__ == "__main__":
main()
Para executar o código quando um arquivo é invocado como um script:
python meu_script.py
E também quando for importado dentro de outro arquivo python.
import meu_script
Sempre que o interpretador Python lê um arquivo ponto py(.py), ele faz duas coisas:
- define algumas variáveis especiais como __name__
- depois ele executa todo o código encontrado no arquivo
Vamos ver como isso funciona.
Se o código é importado dentro de outro arquivo .py, __name__ é uma variável interna que avalia o nome do módulo atual.
No entanto, se um módulo está sendo executado diretamente (como em uma chamada direta: python myscript.py), então __name__ é definido como a string “__main__“.
Se ele é importado em outro arquivo, então o __name__ será o nome do arquivo.
Dessa forma, você pode testar se seu script está sendo executado diretamente ou sendo importado por outro arquivo.
Na próxima aula (Aula 13) falaremos sobre módulos e a gente vai ver com mais detalhes essas coisas.
Ao imprimir a saída para o console, o pydoc tenta paginar a saída para facilitar a leitura.
Se a variável de ambiente PAGER estiver definida, o pydoc usará seu valor como um programa de paginação.
Especificar um sinalizador -w antes do argumento fará com que a documentação em HTML seja gravada em um arquivo no diretório atual, em vez de exibir texto no console.
Especificar um sinalizador -k antes do argumento, serão procuradas as linhas de sinopse de todos os módulos disponíveis para a palavra-chave fornecida como argumento, novamente de maneira semelhante ao comando man do Unix.
A linha de sinopse de um módulo é a primeira linha de sua string de documentação.
Você também pode usar o pydoc para iniciar um servidor HTTP na máquina local, que servirá a documentação para os navegadores Web.
O pydoc -p 1234 iniciará um servidor HTTP na porta 1234, permitindo que você navegue na documentação em http://localhost:1234/ em seu navegador da Web preferido.
No windows use: python -m pydoc -p 1234
Especificar 0 como o número da porta, será selecionada uma porta não utilizada arbitrariamente.
Resumindo:
Módulo Pydoc em Python é usado para gerar documentação na forma de páginas html ou até mesmo no console.
python -m pydoc -w arquivo
Este comando dá opções de gravar a documentação pydoc para um arquivo, -k procurar por bibliotecas diferentes, -p define a porta e permite abrir uma página no navegador para visualizar pacotes python, -w escreve uma saída html .
Abaixo alguns comandos para testar
python -m pydoc yourpythonfile
python -m pydoc -k timeit
python -m pydoc -p 314
python -m pydoc -w sys
Crie só para fins de teste um arquivo python(.py), chame-o do que quiser, eu chamei de arquivo1.py e cole esse conteúdo abaixo:
"""
Este módulo de exemplo mostra vários tipos de documentação disponíveis para uso
com pydoc. Para gerar documentação HTML para este módulo,
comando:
pydoc -w foo
"""
class Pessoa(object):
"""
encapsula um nome e uma idade.
"""
def __init__(self, nome, idade):
"""
Construa um novo objeto 'Pessoa (Person)'.
:parâmetro name: O nome da pessoa
:parâmetro age: A idade da pessoa
:return: não retorna nada
"""
self.nome = nome
self.idade = idade
def ImprimeSaudacao(saudacao):
"""
Imprime saudacao no visor.
"""
print(saudacao)
if __name__ == '__main__':
p = Pessoa('Fulano de Tal', 70)
ImprimeSaudacao("Olá, seja bem-vindo.")Pelo shell do windows(cmd) ou do linux, entre na pasta onde está o arquivo1.py:
cd caminho\para\arquivo1.py
Agora vamos gerar a documentação do arquivo1.py em html:
python -m pydoc -w arquivo1
Clique no arquivo1.html gerado e veja o resultado.
O pydoc -n <hostname> iniciará o servidor escutando no nome do host fornecido.
Por padrão, o nome do host é “localhost“, então, se você quiser que o servidor seja acessado de outras máquinas, poderá alterar o nome do host ao qual o servidor responde.
Durante o desenvolvimento, isso é especialmente útil se você deseja executar o pydoc a partir de um contêiner.
O pydoc -b iniciará o servidor e, além disso, abrirá um navegador Web para uma página de índice do módulo.
Quando o pydoc gera documentação, ele usa o ambiente atual e o caminho para localizar os módulos.
Você pode acessar no Windows o “Python 3.5 Module Docs” para a documentação da biblioteca padrão, o manual, para consultar o tutorial, referências e outros documentos.
Digite Module Docs na barra Digite aqui para pesquisar, e clique em Python 3.5 Module Docs.
Automaticamente já abre o browser com a documentação.
Ou utilize no cmd:
python -m pydoc -p 1234
No Linux utilize:
pydoc -p 1234
O PyDOC utiliza as Doc Strings dos módulos, para gerar a documentação.
É possível também, consultar a documentação no shell do python, através da função help().
Exemplo para consultar a documentação sobre listas:
help(list)
Se eu quiser saber sobre dicionário, posso usar:
help(dict)
