Introdução a módulos em Python

Claro, aqui está a tradução:

Módulos, que tópico! Não temos essa noção no ObjectScript, mas é um conceito fundamental em Python. Vamos descobri-lo juntos.

O que é um Módulo?

Eu vejo módulos como uma camada intermediária entre classes e pacotes. Vamos ver por exemplo.

Um exemplo ruim:

# MyClass.py
class MyClass:
    def my_method(self):
        print("Hello from MyClass!")

Quando você tentar usar essa classe em outro script, você faz:

# class_usage.py
from MyClass import MyClass # estranho, né?

my_instance = MyClass()
my_instance.my_method()

Por que este é um exemplo ruim?

Primeiro porque os nomes de arquivos devem estar em snake_case de acordo com a PEP 8, então deveria ser my_class.py.
Segundo, porque você está importando uma classe de um arquivo que tem o mesmo nome da classe. Esta não é uma boa prática em Python.

Sei que isso pode ser confuso, especialmente se você vem do ObjectScript, onde as classes são definidas em arquivos com o mesmo nome da classe.

Noções Avançadas

Um Módulo é um Arquivo Python

Então, acabamos de ver que módulos podem ser um arquivo Python, mas sem a extensão .py.

Mas espere, isso significa que um script Python também é um módulo? Sim, é!

É por isso que você deve ter cuidado ao importar um script, pois ele executará o código contido nele. Consulte o artigo Introdução ao Python para mais detalhes.

Um Módulo é uma Pasta com um Arquivo __init__.py

Uau, uma pasta pode ser um módulo? Sim, pode!

Uma pasta pode ser um módulo se contiver um arquivo __init__.py file. Este arquivo pode estar vazio ou conter código de inicialização para o módulo.

Vamos ver um exemplo:

src/python/article/
└── my_folder_module/
    ├── __init__.py
    ├── my_sub_module.py
    └── another_sub_module.py

# my_folder_module/my_sub_module.py
class MySubModule:
    def my_method(self):
        print("Hello from MySubModule!")

# my_folder_module/another_sub_module.py
class AnotherSubModule:
    def another_method(self):
        print("Hello from AnotherSubModule!")

# my_folder_module/__init__.py
# Este arquivo pode estar vazio ou conter código de inicialização para o módulo.

Neste caso, my_folder_module e você pode importá-lo assim:

from my_folder_module import my_sub_module, another_sub_module

Ou se você definir um arquivo __init__.py com o seguinte conteúdo:

# my_folder_module/__init__.py
from .my_sub_module import MySubModule
from .another_sub_module import AnotherSubModule

Você pode importá-lo assim:

from my_folder_module import MySubModule, AnotherSubModule

Você percebe a sutileza? Você pode importar as classes diretamente do módulo sem especificar o submódulo, porque o arquivo __init__.py é executado quando você importa o módulo, e ele pode definir o que está disponível no namespace do módulo.

sys.path

Quando você importa um módulo, o Python o procura nos diretórios listados emsys.path. Esta é uma lista de strings que especifica o caminho de busca por módulos.

Você pode ver o sys.path atual executando o seguinte código:

import sys
print(sys.path)

Por padrão, ele inclui o diretório atual e outros vários diretórios, dependendo da sua instalação Python.

Você também pode adicionar diretórios ao sys.path em tempo de execução, o que é útil quando você deseja importar módulos de um local específico. Por exemplo:

import sys
sys.path.append('/path/to/your/module')
from your_module import YourClass

É por isso que no artigo anterior, adicionamos o caminho para o módulo antes de importá-lo:

Set sys = ##class(%SYS.Python).Import("sys")
do sys.path.append("/irisdev/app/src/python/article")
set my_module = ##class(%SYS.Python).Import("my_module")

sys.path e os outros diretórios

Quais são os outros diretórios em sys.path? Eles geralmente são:

• O diretório contendo o script de entrada (ou o diretório atual se nenhum script for especificado).
• Os diretórios da biblioteca padrão, que contêm os módulos built-in que vêm com o Python.
• site-packages diretórios onde pacotes de terceiros são instalados.d.

site-packages

Como site-packages funciona? Quando você instala um pacote usando pip, ele é instalado no diretório site-packages que é automaticamente incluído em sys.path. Isso permite que você importe o pacote sem ter que especificar sua localização.This allows you to import the package without having to specify its location.

🤨🔍 Mas como e onde o diretório site-packages é definido e por quem?

O diretório site-packages é criado durante a instalação do Python e geralmente está localizado no diretório lib da sua instalação Python. O local exato depende do seu sistema operacional e de como o Python foi instalado.

Por exemplo, em uma instalação Linux típica, o diretório site-packages pode estar localizado em:

/usr/local/lib/python3.x/site-packages

No Windows, pode estar localizado em:

C:\Python3x\Lib\site-packages

Quando você instala um pacote usando pip, ele é instalado no diretório site-packages que é automaticamente incluído em sys.path. Isso permite que você importe o pacote sem ter que especificar sua localização.

import site
print(site.getsitepackages())

🤨🔍 Quando e onde o interpretador Python lê o arquivo site.py?

O arquivo site.py (que está localizado no diretório da biblioteca padrão) é executado automaticamente quando o interpretador Python é iniciado. Ele é responsável por configurar o diretório site-packages e adicioná-lo ao sys.path. Este arquivo está localizado no diretório da biblioteca padrão da sua instalação Python.

sys.path no IRIS

No IRIS, também temos um arquivo site.pyque está localizado em <installation_directory>/lib/python/iris_site.py. Este arquivo é executado quando você inicia ou importa um script/módulo no IRIS, e ele configura o sys.path para você.

e forma geral, o arquivo iris_site.pyfaz o seguinte:

• Mantém o diretório site-packages padrão
• Adiciona o diretório<installation_directory>/lib/python/ ao sys.path
  • É aqui que os módulos Python do IRIS estão localizados, por favor, não coloque seus módulos aqui.
• Adiciona o diretório <installation_directory>/mgr/python/ ao sys.path
  -É aqui que você pode colocar seus módulos Python personalizados.
• Adiciona a string de configuração PythonPath ao sys.path
  • PythonPath pode ser configurado no Portal de Gerenciamento do IRIS ou em um arquivo merge/cfg.
  • https://docs.intersystems.com/iris20251/csp/docbook/Doc.View.cls?KEY=GEP...

Conclusão

Um módulo pode ser:

• Um arquivo Python (com ou sem a extensão .py)
• Uma pasta com um arquivo __init__.py.
• Um script Python (que também é um módulo).
• Se você não conseguir importar um módulo, verifique se ele está na lista sys.path.