Python - Pydoc - Cleiton Bueno

Pydoc é uma grande ferramenta do leque do Python, que pode ser utilizada para gerar documentação dos módulos baseado em docstrings[1] e também ter acesso a essa documentação, naquele famoso estilo man-pages.

Imagina você querendo saber informações ou ajuda sobre um modulo mais esta sem internet, então nosso amigo Google não poderá ajudar, vamos de pydoc[2] então.

O mais trivial e que sempre uso é pydoc e o nome do modulo, irei tomar como exemplo o serial (modulo de comunicação serial do Python [pyserial][3]).

$ pydoc serial
Help on package serial:

NAME
    serial

FILE
    /usr/lib/python2.7/dist-packages/serial/__init__.py

DESCRIPTION
    # portable serial port access with python
    # this is a wrapper module for different platform implementations
    #
    # (C) 2001-2010 Chris Liechti <[email protected]>
    # this is distributed under a free software license, see license.txt

PACKAGE CONTENTS
    rfc2217
    serialcli
    serialjava
    serialposix
    serialutil
    serialwin32
    sermsdos
    tools (package)
    urlhandler (package)
    win32

FUNCTIONS
    serial_for_url(url, *args, **kwargs)
        Get an instance of the Serial class, depending on port/url. The port is not
        opened when the keyword parameter 'do_not_open' is true, by default it
        is. All other parameters are directly passed to the __init__ method when
        the port is instantiated.
        
        The list of package names that is searched for protocol handlers is kept in
        ``protocol_handler_packages``.
        
        e.g. we want to support a URL ``foobar://``. A module
        ``my_handlers.protocol_foobar`` is provided by the user. Then

Irei postar só uma parte do conteúdo, o mais legal e que mais gosto de usar é o acesso direto no que preciso. Como assim? Por exemplo, eu quero conhecer a classe Serial do modulo, então faço assim.

$ pydoc serial.Serial
Help on class Serial in serial:

serial.Serial = class Serial(PosixSerial, io.RawIOBase)
 |  # classic version with our own file-like emulation
 |  
 |  Method resolution order:
 |      Serial
 |      PosixSerial
 |      serial.serialutil.SerialBase
 |      io.RawIOBase
 |      _io._RawIOBase
 |      io.IOBase
 |      _io._IOBase
 |      __builtin__.object
 |  
 |  Data and other attributes defined here:
 |  
 |  __abstractmethods__ = frozenset([])
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from PosixSerial:
 |  
 |  close(self)
 |      Close port
 |  
 |  drainOutput(self)
 |      internal - not portable!
 |  
 |  fileno(self)
 |      For easier use of the serial port instance with select.
 |      WARNING: this function is not portable to different platforms!
 |  
 |  flowControl(self, enable)
 |      manually control flow - when hardware or software flow control is
 |      enabled
 |  
 |  flush(self)
 |      Flush of file like objects. In this case, wait until all data
 |      is written.
:
.....

Muito legal, agora eu sei que quando crio um objeto com serial.Serial(), tenho todos estes métodos para usar, e se eu precisar de ajuda ou queira conhecer algum destes métodos.

$ pydoc serial.Serial.flushInput
Help on method flushInput in serial.Serial:

serial.Serial.flushInput = flushInput(self) unbound serial.serialposix.Serial method
    Clear input buffer, discarding all that is in the buffer.
(END)




$ pydoc serial.Serial.read
Help on method read in serial.Serial:

serial.Serial.read = read(self, size=1) unbound serial.serialposix.Serial method
    Read size bytes from the serial port. If a timeout is set it may
    return less characters as requested. With no timeout it will block
    until the requested number of bytes is read.

No exemplo acima, estou acessando o conteúdo de flushInput e read da classe Serial.

E quando você quer pesquisar algo e não sabe o nome do modulo, vamos de pydoc[2] também.

$ pydoc -k serial
pickle - Create portable serialized representations of Python objects.
html5lib.serializer 
html5lib.serializer.htmlserializer 
No handlers could be found for logger "oneconf.distributor"
piston_mini_client.serializers - Classes that define ways for your API methods to serialize arguments
serial 
serial.rfc2217 
serial.serialcli 
serial.serialjava 
serial.serialposix 
serial.serialutil 
serial.serialwin32 
serial.sermsdos 
serial.tools 
serial.tools.list_ports - This module will provide a function called comports that returns an
serial.tools.list_ports_posix 
serial.tools.list_ports_windows 
serial.tools.miniterm 
serial.urlhandler 
serial.urlhandler.protocol_hwgrep 
serial.urlhandler.protocol_loop 
serial.urlhandler.protocol_rfc2217 
serial.urlhandler.protocol_socket 
serial.win32 
twisted.internet._posixserialport - Serial Port Protocol
twisted.internet._win32serialport - Serial port support for Windows.
twisted.internet.serialport - Serial Port Protocol
twisted.internet.test.test_serialport - Tests for L{twisted.internet.serialport}.
twisted.protocols.gps.rockwell - Rockwell Semiconductor Zodiac Serial Protocol
twisted.protocols.mice.mouseman - Logictech MouseMan serial protocol.
twisted.test.test_jelly - Test cases for L{jelly} object serialization.
twisted.web._flatten - Context-free flattener/serializer for rendering Python objects, possibly

Com o parâmetro -k estamos especificando uma palavra-chave para busca, e no caso usei serial.

Você acha que acabou? Imagina esse poder além dos terminais. E você tem, pois consegue subir um “webserver” para acessar tudo isso localmente pelo navegador.

$ pydoc -p 9876
pydoc server ready at http://localhost:9876/

Procurando o modulo serial na pagina.

Acessando o modulo e visualizando o conteúdo.

E para fechar com chave de ouro, e se pudéssemos pesquisar sobre o que quiséssemos e pudesse gerar uma pagina dessas para visualizar via web, vamos fazer.

$ pydoc -w serial
wrote serial.html

E gerou uma pagina chamada serial.html no local que esta sendo executado o pydoc, com todo o conteúdo do modulo serial que pode ser visualizado via web e até impresso.

Isso porque eu não falei que dentro do Python você pode usar o help() ;)

Espero que tenham gostado, e até a próxima!