Criando e Conectando Módulos - Python

Em Python, um módulo é um arquivo individual com código que pode ser reutilizado em outros programas.

Para criar um módulo, é necessário criar um arquivo com a extensão *.py, que representará o módulo. O nome do arquivo será o nome do módulo. Em seguida, é preciso definir uma ou mais funções dentro desse arquivo.

Por exemplo, suponha que o arquivo principal do programa seja chamado main.py e queremos conectar módulos externos a ele.

Para isso, primeiro definimos um novo módulo: na mesma pasta onde está main.py, criamos um novo arquivo chamado message.py. Por padrão, o interpretador Python procura módulos em diversos caminhos padrão, sendo um deles a pasta onde o script principal está localizado. Assim, para simplificar, colocaremos os dois arquivos em um mesmo projeto para que o interpretador encontre o módulo message.py.

.
├── main.py
└── message.py

Assim, o módulo será chamado message. Vamos definir o seguinte código no arquivo message.py:

hello = "Hello all"
 
def print_message(text):
    print(f"Message: {text}")

Aqui, temos uma variável hello e uma função print_message, que recebe um texto como parâmetro e o imprime no console.

No arquivo principal main.py, utilizamos este módulo da seguinte maneira:

import message      # importando o módulo message
 
# exibindo o valor da variável hello
print(message.hello)        # Hello all

# chamando a função print_message
message.print_message("Hello Programício")  # Message: Hello Programício

Para usar o módulo, é necessário importá-lo com o comando import seguido do nome do módulo: import message.

Para acessar a funcionalidade do módulo, precisamos usar seu namespace. Por padrão, ele corresponde ao nome do módulo, ou seja, neste caso, o namespace é message.

Após ter o namespace do módulo, podemos acessar suas funções usando a sintaxe:

message.print_message("Hello Programício")

Por exemplo, para chamar a função print_message() do módulo message:

message.print_message("Hello Programício")

Depois disso, podemos executar o script principal main.py, que utilizará o módulo message.py. A saída no console será a seguinte:

Hello all
Message: Hello Programício

Importando Funcionalidade do Módulo no Namespace Global

Outra opção é importar a funcionalidade do módulo para o namespace global do módulo atual, usando a palavra-chave from:

from message import print_message
 
# chamando a função print_message do módulo message
print_message("Hello Programício")  # Message: Hello Programício
    
# a variável hello do módulo message não está acessível, pois não foi importada
# print(message.hello)   
# print(hello)

Neste caso, estamos importando a função print_message() do módulo message para o namespace global, permitindo seu uso sem o namespace do módulo, como se tivesse sido definida no mesmo arquivo.

As demais funções e variáveis do módulo não estarão acessíveis (como a variável hello, neste exemplo). Se quisermos usá-las, podemos importá-las individualmente:

from message import print_message
from message import hello
    
# chamando a função print_message do módulo message
print_message("Hello Programício")  # Message: Hello Programício
    
# chamando a variável hello do módulo message
print(hello)    # Hello all

Se for necessário importar todas as funcionalidades no namespace global, podemos usar o caractere asterisco *:

from message import *
 
# chamando a função print_message do módulo message
print_message("Hello Programício")  # Message: Hello Programício
    
# chamando a variável hello do módulo message
print(hello)    # Hello all

No entanto, é importante observar que a importação para o namespace global pode gerar conflitos de nomes. Por exemplo, se houver uma função com o mesmo nome definida no arquivo atual, será chamada a última função definida:

from message import *
  
print_message("Hello Programício")  # Message: Hello Programício - usa a função do módulo message
    
def print_message(some_text):
    print(f"Local Text: {some_text{")
    
print_message("Hello Programício")  # Local Text: Hello Programício - usa a função do arquivo atual

Neste caso, a função print_message() do arquivo atual é chamada, pois foi definida após a importação do módulo.

Definindo Alias

Ao importar um módulo ou suas funcionalidades, podemos definir um alias(apelido) para o nome do módulo, usando a palavra-chave as:

import message as msg

# exibindo o valor da variável hello
print(mes.hello)     # Hello all

# chamando a função print_message
msg.print_message("Hello Programício")  # Message: Hello Programício

Neste caso, o namespace passa a se chamar msg, e podemos acessar a funcionalidade do módulo através desse alias.

De forma semelhante, é possível definir aliases para funcionalidades específicas do módulo:

from message import print_message as display
from message import hello as welcome
    
print(welcome)          # Hello all - variável hello do módulo message
display("Hello Programício")  # Message: Hello Programício - função print_message do módulo message

Aqui, atribuimos o alias display para a função print_message do módulo message e o alias welcome para a variável hello. Assim, podemos acessá-los por meio desses aliases.

Os aliases são úteis quando os nomes das funções ou variáveis não são ideais, por exemplo, quando são longos demais ou queremos nomes mais descritivos. Eles também ajudam a evitar conflitos de nome caso haja funcionalidades com os mesmos nomes no arquivo atual. Veja o exemplo:

from message import print_message as display
 
def print_message(some_text):
    print(f"Local Text: {some_text}")
    
# função print_message do módulo message
display("Hello Programício")  # Message: Hello  Programício
    
# função print_message do arquivo atual
print_message("Hello Programício")  # Local Text: Hello Programício

Nome do Modulo

No exemplo acima, o módulo main.py, que é o principal, utiliza o módulo message.py. Ao executar o main.py, o programa realiza todas as operações necessárias. No entanto, se executarmos message.py separadamente, não veremos nada no console, pois ele apenas define uma função e uma variável, sem realizar nenhuma outra ação. Podemos, no entanto, configurar message.py para que funcione tanto sozinho quanto ao ser importado por outros módulos.

Ao executar um módulo, o ambiente define seu nome e o atribui à variável global __name__ (com dois sublinhados em cada lado). Se o módulo é o principal, seu nome é __main__. Se o módulo for utilizado por outro módulo, o nome será igual ao do arquivo, sem a extensão .py. Podemos usar essa característica. Vamos modificar o conteúdo de message.py:

hello = "Hello all"
 
def print_message(text):
    print(f"Message: {text}")
    
def main():
    print_message(hello)
    
if __name__ == "__main__": 
    main()

Neste caso, adicionamos a função main ao módulo message.py para testar sua funcionalidade. Assim, podemos executar message.py isoladamente e testar o código.

Observe a chamada da função main():

if __name__ == "__main__":
    main()

A variável __name__ indica o nome do módulo. Para o módulo principal, que é executado diretamente, essa variável sempre terá o valor __main__, independentemente do nome do arquivo.

Portanto, se executarmos o script message.py isoladamente, o Python atribuirá o valor __main__ à variável __name__, e o código no bloco if chamará a função main do próprio arquivo.

Porém, se executarmos outro script e importarmos message.py como módulo auxiliar, a variável __name__ de message.py será message, e a função main não será executada.

Esse método de verificar o nome do módulo é uma prática recomendada em Python, em vez de chamar a função main diretamente.

No arquivo main.py, também podemos verificar se o módulo é o principal (embora isso geralmente não seja necessário):

import message
 
def main(): 
    message.print_message("Hello work")  # Message: Hello work
    
if __name__ == "__main__":
    main()