Como melhorar a qualidade do código com linting em Python

Python é uma linguagem em constante crescimento. À medida que ela evolui e se expande, também aumenta o número de ferramentas e estratégias de desenvolvimento disponíveis para trabalhar com ela. Um processo que vem ganhando popularidade é o linting, ou seja, a verificação do código em busca de possíveis problemas. Com o linting, os erros no código são sinalizados para que possamos corrigir práticas de programação incomuns que poderiam causar problemas.

O linting é feito enquanto o código-fonte está sendo escrito, antes de ele ser compilado. Em outras palavras, é uma verificação pré-build, também chamada de “análise estática de código”. Verificar o código regularmente com linting garante consistência em todo o código e na base de código. Isso reduz as chances de pequenos erros se transformarem em problemas complexos depois que o código é executado.

Muitos desenvolvedores não usam linting porque não percebem o valor que ele agrega, já que não impede bugs. Mas essa visão subestima o quanto o linting pode melhorar a qualidade do código.

Neste artigo prático, vamos explorar como é rápido e fácil fazer verificações de linting em Python com o Pylint, uma das ferramentas de linting mais populares. Também veremos como o linting pode ajudar você a seguir o guia de estilo de código PEP8.

Pré-requisitos

Antes de começar, confira se você tem:

• Python e pip instalados na sua máquina

• Conhecimentos básicos sobre interfaces de linha de comando (CLIs)

• Conhecimento de conceitos de Python, como funções e classes

Observe também que, embora os comandos apresentados aqui sejam compatíveis com sistemas Linux e macOS, é preciso ter cuidado ao trabalhar com Windows.

Fazendo linting de código Python

Antes de mostrar como usar um linter em Python, vamos preparar o ambiente criando um diretório e um ambiente virtual.

Configurando o ambiente

Primeiro, crie um diretório para o projeto. Neste tutorial, vamos chamá-lo de pylint-demo.

1$ mkdir pylint-demo
2
3$ cd pylint-demo

Em seguida, crie um ambiente virtual. Ele vai isolar as dependências do projeto e evitar conflitos com outros projetos.

1$ pip install pipenv
2
3$ pipenv shell

O prompt deve ficar parecido com: (pylint-demo) $. Isso indica que o ambiente virtual está ativo.

Com o ambiente virtual ativo, instale o linter com o comando a seguir:

1$ pipenv install pylint

Agora podemos executar o linter com o comando pylint. Para confirmar que o Pylint foi instalado corretamente, execute o seguinte comando:

1$ pylint –help

Primeiros passos com linting

Vamos escrever um programa Python básico e usar o Pylint nele para ver como funciona. Crie um arquivo main.py e copie o código a seguir:

1def is_number_even(num):
2    return "Even" if num % 2 == 0 else "Odd"
3
4num = 5
5print(f"The number {num} is {is_number_even(num)}")

No código acima, adicionamos uma função para verificar se um número é par ou ímpar. Para usar o Pylint e verificar se há erros nesse código, executamos o seguinte comando:

1$ pylint <<file_name>>
2$ pylint main.py

A saída do Pylint é a seguinte:

1************* Module main
2main.py:12:0: C0304: Final newline missing (missing-final-newline)
3main.py:1:0: C0114: Missing module docstring (missing-module-docstring)
4main.py:8:0: C0116: Missing function or method docstring (missing-function-docstring)
5main.py:8:19: W0621: Redefining name 'num' from outer scope (line 11) (redefined-outer-name)
6main.py:11:0: C0103: Constant name "num" doesn't conform to UPPER_CASE naming style (invalid-name)
7
8------------------------------------------------------------------
9Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)

Podemos identificar vários problemas autoexplicativos no código, cada um identificado por um código, como C0304. O Pylint atribui uma letra a cada erro para diferenciar a gravidade e a natureza do problema. Há cinco categorias de erros:

• C: Convenção (para violações de convenções de código)

• R: Refatoração (para problemas relacionados a code smells e refatoração)

• W: Aviso (para problemas de programação que não são erros)

• E: Erro (para problemas de programação que são erros)

• F: Fatal (para problemas graves que interromperam a execução do Pylint)

O Pylint também atribui ao código uma nota de 0 a 10, com base no número de erros encontrados.

No nosso exemplo, todos os códigos de erro, exceto um, indicam problemas de convenção; o único restante é um aviso. Para corrigir esses problemas, vamos fazer algumas alterações no código e executar o Pylint novamente para ver que nota ele recebe.

1""" File contains various function to under Pylint """
2
3def is_number_even(num):
4    """Function to check if number is even or odd"""
5    return "Even" if num % 2 == 0 else "Odd"
6
7NUM = 5
8print(f"The number {NUM} is {is_number_even(NUM)}")

Nesse código, adicionamos docstrings ao módulo e à função, inserimos uma nova linha no final e renomeamos a variável do código anterior. Ao executar o Pylint novamente, recebemos nota 10/10, sem nenhum problema.

Executando o Pylint em um único arquivo

Agora que entendemos melhor como o Pylint funciona, vamos ver outro exemplo. Digite o código a seguir:

1""" File contains various function to under Pylint """
2
3class animal:
4  def __init__(self, name):
5    self.name = name
6
7obj1 = animal("Horse", 21)
8print(obj1.name)

Neste trecho, temos uma classe simples chamada animal e um objeto dessa classe chamado obj1. Agora, vamos usar o Pylint nesse código.

1************* Module main
2main.py:4:0: W0311: Bad indentation. Found 2 spaces, expected 4 (bad-indentation)
3main.py:5:0: W0311: Bad indentation. Found 4 spaces, expected 8 (bad-indentation)
4main.py:3:0: C0115: Missing class docstring (missing-class-docstring)
5main.py:3:0: C0103: Class name "animal" doesn't conform to PascalCase naming style (invalid-name)
6main.py:3:0: R0903: Too few public methods (0/2) (too-few-public-methods)
7main.py:7:7: E1121: Too many positional arguments for constructor call (too-many-function-args)

Observe que, desta vez, os problemas de qualidade do código deram lugar a erros mais substanciais. Com os problemas sinalizados, vamos tentar corrigi-los com o código abaixo:

1""" File contains various function to under Pylint """
2
3class Animal:
4    "Animal Class"
5    def __init__(self, name):
6        self.name = name
7
8obj1 = Animal("John")
9print(obj1.name)

Em seguida, execute o Pylint novamente. Depois de mudar o nome da classe de animal para Animal, adicionar uma docstring à classe, remover argumentos desnecessários das chamadas de função e incluir a indentação correta, quase eliminamos todos os erros do código. Ainda resta um:

1************* Module main
2main.py:3:0: R0903: Too few public methods (0/2) (too-few-public-methods)

Vamos ver como corrigir esse erro restante. O Pylint informa que não temos dois ou mais métodos públicos, mas é bem provável que nosso código realmente não tenha dois ou mais métodos públicos. Então, como corrigimos isso?

Nesse caso, podemos usar comentários em Python para suprimir esses problemas. A sintaxe para fazer isso é:

1# pylint: disable=<<issue_name>>

Veja como ficará o código:

1""" File contains various function to under Pylint """
2
3# pylint: disable=too-few-public-methods
4class Animal:
5    "Animal Class"
6    def __init__(self, name):
7        self.name = name
8
9obj1 = Animal("John")
10print(obj1.name)

Ao verificar a saída do Pylint agora, veremos que o problema desapareceu.

Executando o Pylint em um diretório

Vimos como executar o Pylint em um único arquivo, mas, ao trabalhar em um projeto, não teremos apenas um arquivo para verificar. Precisaremos fazer linting do diretório.

Para usar o Pylint em todo o diretório, execute o seguinte comando:

1$ pylint <<name_of_directory>>

Para ver como funciona o linting de um diretório, vamos criar mais dois arquivos e adicionar algum código.

1$ mkdir src; cd src
2$ touch helpers.py config.py __init__.py

Mova o arquivo main.py para o diretório src e cole o código a seguir nos respectivos arquivos:

1<<main.py>>
2""" File contains various function to under Pylint """
3
4from helpers import connect_db
5from config import DB_USER, DB_PASS
6
7is_connected = connect_db(DB_USER, DB_PASS)
8
9if is_connected:
10    print("Connected to DB")
11else:
12    print("Failed to connect to DB")
13
14<<helpers.py>>
15def connect_db(user, password):
16    """Dummy function to connect to DB"""
17    if user is None or password is None:
18        return False
19    return True
20
21<<config.py>>
22DB_USER = "root"
23DB_PASS = "toor"

Temos três arquivos no diretório src: main.py, helpers.py e config.py. Em main.py, temos uma função fictícia que exibe se estamos conectados ao banco de dados. O arquivo helpers.py contém uma função auxiliar fictícia para conectar ao banco de dados, e o arquivo config.py contém o nome de usuário e a senha do banco de dados.

Agora, vamos executar o Pylint em todo o diretório usando o seguinte comando a partir do diretório raiz:

1$ pylint src

A saída do comando será:

1************* Module src.config
2src/config.py:2:0: C0304: Final newline missing (missing-final-newline)
3src/config.py:1:0: C0114: Missing module docstring (missing-module-docstring)
4************* Module src.main
5src/main.py:11:0: C0304: Final newline missing (missing-final-newline)
6src/main.py:3:0: E0401: Unable to import 'helpers' (import-error)
7src/main.py:4:0: E0401: Unable to import 'config' (import-error)
8************* Module src.helpers
9src/helpers.py:6:0: C0304: Final newline missing (missing-final-newline)
10src/helpers.py:1:0: C0114: Missing module docstring (missing-module-docstring)

Como podemos ver, o Pylint exibe os resultados de arquivos diferentes, separados por *** e pelo nome do módulo. Para corrigir os problemas, precisamos fazer as seguintes alterações:

• Adicione uma nova linha no final de cada arquivo.

• Adicione uma docstring a cada arquivo e função.

• Altere a instrução import de helpers import connect_db para .helpers import connect_db.

Depois de corrigir esses problemas, encontraremos outro: precisamos colocar em maiúscula o nome da variável is_connected. Podemos mudar o nome da variável ou suprimir o aviso para lidar com esse erro.

Suprimindo avisos

É bem provável que você precise personalizar ou suprimir vários avisos ao fazer linting do seu código Python. Não faz sentido adicionar um comentário a cada vez. Em vez de suprimir os avisos um por um, você pode criar um arquivo .rc para personalizar o comportamento do Pylint e suprimir os avisos do projeto inteiro diretamente nesse arquivo .rc.

Você pode criar um arquivo desse tipo com o seguinte comando:

1$ pylint --generate-rcfile > pylint.rc

Código melhor e mais seguro com linting

O linting em Python verifica o código-fonte enquanto ele é escrito e sinaliza erros, antes da execução. Você também pode integrar o Pylint aos editores para ver os resultados do linting em tempo real.

Embora o linting não corrija bugs automaticamente, usá-lo de forma consistente ajuda a manter a alta qualidade do código. Por isso, mesmo que alguns desenvolvedores considerem o linting uma perda de tempo, ele é muito eficaz para detectar pequenos problemas antes que se transformem em problemas maiores.

Ao longo deste artigo, vimos como o linting e a aplicação das recomendações do Pylint melhoraram nosso código de exemplo. Além disso, esse processo ajuda a seguir o guia de estilo PEP8. Agora que você sabe como implementar o linting nos seus projetos, pode explorar as diversas ferramentas disponíveis e descobrir qual delas complementa melhor — e aprimora — sua abordagem ao desenvolvimento em Python.