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 44 outros assinantes

Como declarar funções no Python

Funções são uma forma bastante conveniente de dividir seu código em vários pequenos (ou não) blocos de códigos.
Tal como qualquer outra linguagem de programação, o Python tem suporte a funções.
Com o uso deste recurso, é possível enxugar significativamente a quantidade de código dentro dos scripts principais de um sistema, o que os torna mais fáceis de entender e manter.
São também um meio de compartilhar código entre programadores, poupando todo mundo de recriar código para uma mesma tarefa.
Quando você precisa de uma, no Python, você a declara, com o comando “def” (define).
Veja um exemplo:


def tamanho_aprox(tam, tipo=True):

A palavra-chave def deve ser usada para iniciar toda declaração de uma nova função.
Depois do nome da função, segue (opcionalmente) alguns argumentos entre parênteses, que são separados por vírgulas.

Quando você precisa de uma função, no Python, basta declará-la com def.

python declarar função

Você pode experimentar criar uma função dentro da Python shell:

>>> def fun_hello():
...     print("olá, mundo!")
... 

>>> fun_hello()
olá, mundo!

>>> 

No próximo exemplo, vou mostrar uma função de felicitação pelo aniversário.
Como eu quero que a felicitação seja personalizada, a função irá aceitar o nome do aniversariante através do parâmetro.

>>> def felizAniv(aniversariante):
...     print("Feliz aniversário, "+aniversariante+"!")
... 
>>> felizAniv('Justin')
Feliz aniversário, Justin!

>>> felizAniv('Capitão')
Feliz aniversário, Capitão!

>>> 

Que tal adicionar a idade?

>>> def felizAniv(aniversariante,anos):
...     print("Feliz aniversário, "+aniversariante+"!")
...     print("Você acabou de fazer "+str(anos)+" anos de idade.")
... 

>>> felizAniv('Capitão',72)
Feliz aniversário, Capitão!
Você acabou de fazer 72 anos de idade.

>>>

Referências

http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/functions.html.

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 44 outros assinantes

Primeiros passos na shell do Python

É na shell do Python que você pode começar a explorar a sintaxe dos comandos da linguagem.
Também é possível obter ajuda sobre os comandos e depurar programinhas curtinhos.
Existe uma shell gráfica (GUI), chamada IDLE, que tem editor de textos, suporte a realce da sintaxe etc. — que será abordada melhor em outro post…
Abra a sua shell e faça algumas experiências:

python3

Como você pode ver, no exemplo abaixo, meu interpretador Python está na versão 3.x e roda em uma máquina Linux:

Python 3.5.3 (default, Jan 19 2017, 14:11:04) 
[GCC 6.3.0 20170118] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> 

Não se preocupe com o fato de eu usar Linux nos meus exemplos.
O interpretador Python é universal e funciona do mesmo jeito em qualquer plataforma.

Os caracteres “>>>” indicam o prompt da shell.
É nesta linha que podemos dar comandos para serem interpretados.
Veja alguns exemplos:

>>> 15 + 3
18

Experimente pedir ao Python para escrever alguma coisa:

>>> print("olá, mundo!")
olá, mundo!

O modo ajuda do Python

Obtenha ajuda sobre Python dentro da shell, com a função help():

help()

Note que o prompt, no modo de ajuda muda para “help>”, para ajudar a lembrar que você não está dentro do interpretador Python — mas dentro do modo de ajuda dele.
A partir deste prompt é possível digitar comandos ou outros elementos da linguagem, para obter mais informações sobre eles.

help> print

No exemplo acima pedi ajuda sobre a função print().
Como resposta, o módulo exibe um texto assim:

Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.
(END)

Para sair, tecle “q”.
E, para sair do módulo de ajuda, rode o comando “quit”.
Você também pode obter ajuda rápida, com a função help, sobre comandos, funções, objetos, classes etc.
Por exemplo, para obter ajuda sobre a classe “list”, use o help assim:

help(list)

Neste caso, o assistente exibe o texto na tela.
Para sair do “modo help”, tecle “q” — para voltar ao prompt do Python.
Se você já usou um terminal Bash (no Linux), vai perceber que o “modo help” do Python funciona semelhante a uma man page.

Rode um script Python com o interpretador

Você pode rodar qualquer script a partir do interpretador, direto no terminal:

python meuscript.py

No Windows, é mais parecido com isto aqui:

c:\python31\python.exe meuscript.py

Desta forma, não é necessário abrir uma shell para executar varias linhas de comandos — uma vez que podem ser agrupadas em um arquivo de script.
Aí é que começa a “programação de verdade”.

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 44 outros assinantes

Interpretadores online para Python

Estudantes de programação nem sempre têm à sua disposição todas as ferramentas necessárias para praticar seu aprendizado.

Por sorte, com uma conexão à Internet, é possível continuar as lições, mesmo usando o computador dos outros.

No site oficial da fundação Python Software Foundation é possível usar uma shell online, com uma versão atual do Python.

Para chegar lá, clique no link: https://www.python.org/shell/.
Há vários outros interpretadores e compiladores Python online.
Leia este artigo para conhecer outros:
https://elias.praciano.com/2016/12/6-compiladores-online-para-estudantes-de-programacao/.

Python Anywhere

O site Python Anywhere, que provê o console Python da PSF, também tem um: https://www.pythonanywhere.com/try-ipython/.

A shell online do SymPy também vale a tentativa: http://live.sympy.org/. Neste caso, a última vez em que visitei o site, eles usavam o interpretador da versão 2.7 da linguagem, sem opção para a série 3.x.

Code Skulptor

O site CodeSkulptor provê uma interface web simples, porém bem funcional.

Nele, você pode escrever seu código e conta com bibliotecas avançadas, como a pygame.

A ferramenta pode ser encontrada aqui: http://www.codeskulptor.org/

Um servidor virtual online também pode ser útil

Uma experiência mais completa, pode ser obtida com o https://termbox.io, que permite simular uma máquina com Linux (com várias opções de distribuições) e dentro desta máquina virtual, rodar o seu interpretador Python.

Infelizmente, o site estava fora do ar em algumas de minhas tentativas de acessar.

Você tem outra sugestão de interpretador ou shell online para Python?! Então, deixe sua sugestão nos comentários!

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 44 outros assinantes

Como usar o Python Shell

É na(o) shell do Python que você pode experimentar a linguagem como interpretada.
Na shell, você obtém a resposta imediata a cada um de seus comandos.
É o lugar perfeito para explorar a sintaxe da linguagem e obter ajuda interativa sobre cada comando e, ainda, “debugar” programas curtos.
Para quem está aprendendo, este é o playground ideal para testar novos conceitos, novas fórmulas e comandos — desde que você esteja se divertindo com o aprendizado, claro! 😉
A shell pode ser executada a partir de um terminal, com o comando ‘python’:

python

É comum as distribuições GNU/Linux incluírem a série 2.x e 3.x do Python. Neste caso, se quiser trabalhar com o Python 3, é necessário indicar isto explicitamente:

python3

Assim que ela começa a funcionar, exibe algumas informações bem básicas sobre si mesma (versão do interpretador Python, data atual do sistema, versão do compilador GNU C etc.):

Python 2.7.12 (default, Nov 19 2016, 06:48:10) 
[GCC 5.4.0 20160609] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> 

Se você propuser um cálculo, na shell, ela irá retornar o resultado. Experimente:

>>> 3 + 12
15

Toda shell tem um prompt. No caso do interpretador do Python, são aqueles 3 sinais “>>>”.
Quando vocẽ cansar de brincar, pode sair da shell com a execução da função quit():

quit()

Meu sistema tem mais de uma versão do Python instalada. O que eu faço?

Nos sistemas operacionais Linux, é comum vir mais de uma versão do Python instalada:
No meu sistema, há 3 opções: python2.7, python3.5 e python3.5m. Veja:

ls -l /usr/bin/python*
lrwxrwxrwx 1 root root       9 Set 20 17:27 /usr/bin/python -> python2.7
lrwxrwxrwx 1 root root       9 Set 20 17:27 /usr/bin/python2 -> python2.7
-rwxr-xr-x 1 root root 3546104 Nov 19 06:35 /usr/bin/python2.7
lrwxrwxrwx 1 root root       9 Set 20 17:27 /usr/bin/python3 -> python3.5
-rwxr-xr-x 2 root root 4460336 Nov 17 16:23 /usr/bin/python3.5
-rwxr-xr-x 2 root root 4460336 Nov 17 16:23 /usr/bin/python3.5m
lrwxrwxrwx 1 root root      10 Set 20 17:27 /usr/bin/python3m -> python3.5m

Os arquivos “python” e “python2” são apenas links para “python2.7” — que é a versão padrão do meu sistema.
Da mesma forma, “python3” é um link para “python 3.5” e “python3m” para “python3.5m”.
No Linux, é comum ter utilitários do sistema que ainda dependem da versão 2.x do Python, o que explica a presença desta versão do interpretador.
Você não precisa se preocupar com isso.
Se quiser entender como lidar com mais de uma versão do Python instalada no seu sistema, leia este artigo.

Como tornar a versão 3 do Python padrão no meu sistema

Se preferir, posso mostrar 2 métodos para obter acesso mais rápido a uma determinada versão do interpretador, da linha de comando, no Linux.
O primeiro método consiste em criar um link ou atalho para ele:

ln -s /usr/bin/python3 py

Você provavelmente terá que invocar o comando, acima, como superusuário.
Depois de criado, basta executar o atalho:

./py

… e o interpretador da versão 3.x será acionado:

Python 3.5.2 (default, Nov 17 2016, 17:05:23) 
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> 

O segundo método (meu preferido) consiste em usar o comando alias para criar um “apelido” para a minha versão predileta do Python.
O resultado é o mesmo, só que dispensa privilégios administrativos. Veja como:

alias py="/usr/bin/python3"

O resultado, contudo, tende a esvanecer com o fim da sessão.
Para torná-lo persistente, inclua a linha, acima, no seu arquivo ~/.bashrc (para usuários Linux).
Qual é o seu método preferido?

Note que nenhum dos métodos torna o Python 3, verdadeiramente, padrão no seu sistema — ele apenas cria uma ligação para a versão que você deseja executar.

Alterar o padrão da versão 2 para a 3, infelizmente, pode causar problemas de compatibilidade em vários utilitários do sistema, que dependem da versão legada para funcionar.

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 44 outros assinantes