Criar um Pacote Python

Introdução

Neste laboratório, você aprenderá como criar e organizar um pacote Python. Pacotes Python são uma ótima maneira de estruturar seu código, tornando-o mais modular, reutilizável e fácil de manter.

Os objetivos deste laboratório são entender o que é um pacote Python, criar uma estrutura básica de pacote, organizar módulos Python relacionados em um pacote coeso e atualizar as instruções de importação para trabalhar com a nova estrutura do pacote.

Entendendo Pacotes Python

Antes de começarmos a criar um pacote Python, vamos entender o que é um pacote Python. Um pacote Python é essencialmente um diretório. Dentro deste diretório, existem múltiplos arquivos de módulo Python, que são apenas arquivos .py contendo código Python. Adicionalmente, existe um arquivo especial chamado __init__.py. Este arquivo pode estar vazio, mas sua presença indica que o diretório é um pacote Python. O propósito desta estrutura é ajudá-lo a organizar código relacionado em uma única hierarquia de diretórios.

Pacotes oferecem diversos benefícios. Primeiro, eles permitem que você estruture seu código logicamente. Em vez de ter todos os seus arquivos Python espalhados, você pode agrupar funcionalidades relacionadas em um pacote. Segundo, eles ajudam a evitar conflitos de nomes entre módulos. Uma vez que pacotes criam um namespace, você pode ter módulos com o mesmo nome em pacotes diferentes sem nenhum problema. Terceiro, eles tornam a importação e o uso do seu código mais convenientes. Você pode importar um pacote inteiro ou módulos específicos dele com facilidade.

Agora, vamos dar uma olhada nos arquivos que temos atualmente em nosso diretório de projeto. Para listar os arquivos, usaremos o seguinte comando no terminal:

ls -l

Quando você executar este comando, deverá ver os seguintes arquivos:

portfolio.csv
reader.py
stock.py
structure.py
tableformat.py
validate.py

Estes arquivos Python estão todos relacionados e trabalham juntos, mas atualmente, eles são apenas módulos separados. Neste laboratório, nosso objetivo é organizá-los em um pacote coeso chamado structly.

Vamos entender brevemente o que cada arquivo faz:

• structure.py: Este arquivo define uma classe base Structure e vários descritores. Estes descritores são usados para validação de tipo, o que significa que eles ajudam a garantir que os dados usados em seu programa tenham o tipo correto.
• validate.py: Ele contém funcionalidades de validação que são usadas pelo módulo structure. Isso ajuda na validação dos dados de acordo com certas regras.
• reader.py: Este arquivo fornece funções que são usadas para ler dados CSV. CSV (Valores Separados por Vírgula) é um formato de arquivo comum para armazenar dados tabulares.
• tableformat.py: Ele contém classes e funções que são usadas para formatar dados em tabelas. Isso é útil quando você deseja exibir dados de uma maneira mais organizada.
• stock.py: Este arquivo usa os outros módulos para definir uma classe Stock e processar dados de ações. Ele combina a funcionalidade dos outros módulos para realizar tarefas específicas relacionadas a dados de ações.

No próximo passo, criaremos nossa estrutura de pacote.

Criando a Estrutura do Pacote

Agora, vamos criar nosso pacote Python. Mas primeiro, vamos entender o que é um pacote Python. Um pacote Python é uma maneira de organizar módulos Python relacionados em uma única hierarquia de diretórios. Ele ajuda a gerenciar e reutilizar o código de forma mais eficaz. Para criar um pacote Python, precisamos seguir estes passos:

1. Crie um diretório com o nome do pacote. Este diretório servirá como o contêiner para todos os módulos que pertencem ao pacote.
2. Crie um arquivo __init__.py dentro deste diretório. Este arquivo é crucial porque faz com que o Python reconheça o diretório como um pacote. Quando você importa o pacote, o código em __init__.py é executado, o que pode ser usado para inicializar o pacote.
3. Mova nossos arquivos de módulo Python para dentro deste diretório. Este passo garante que todo o código relacionado seja agrupado dentro do pacote.

Vamos criar a estrutura do pacote passo a passo:

1. Primeiro, crie um diretório chamado structly. Este será o diretório raiz do nosso pacote.

mkdir structly

2. Em seguida, crie um arquivo __init__.py vazio dentro do diretório structly.

touch structly/__init__.py

O arquivo __init__.py pode estar vazio, mas é necessário para fazer com que o Python trate o diretório como um pacote. Quando você importa o pacote, o código em __init__.py é executado, o que pode ser usado para inicializar o pacote.

3. Agora, vamos mover nossos arquivos de módulo Python para o diretório structly. Esses arquivos de módulo contêm as funções e classes que queremos incluir em nosso pacote.

mv structure.py validate.py reader.py tableformat.py structly/

4. Verifique se todos os arquivos foram movidos corretamente. Podemos usar o comando ls -l para listar o conteúdo do diretório structly.

ls -l structly/

Você deve ver os seguintes arquivos listados:

__init__.py
reader.py
structure.py
tableformat.py
validate.py

Agora criamos uma estrutura básica de pacote. A hierarquia de diretórios deve ser assim:

project/
├── portfolio.csv
├── stock.py
└── structly/
    ├── __init__.py
    ├── reader.py
    ├── structure.py
    ├── tableformat.py
    └── validate.py

No próximo passo, corrigiremos as instruções de importação para fazer o pacote funcionar corretamente.

Corrigindo Declarações de Importação

Agora, vamos entender por que precisamos fazer isso. Quando movemos nossos arquivos para o pacote structly, a forma como o Python procura por módulos mudou. As declarações de importação em cada arquivo precisam ser atualizadas para corresponder à nova estrutura do pacote. Isso é crucial porque o Python usa essas declarações de importação para encontrar e usar o código de outros módulos.

O arquivo structure.py é muito importante de ser atualizado. Ele importa funções e classes do arquivo validate.py. Como ambos esses arquivos agora estão no mesmo pacote structly, precisamos ajustar a declaração de importação de acordo.

Vamos começar abrindo o arquivo structly/structure.py no editor. Você pode clicar em structly/structure.py no explorador de arquivos ou executar o seguinte comando no terminal:

## Clique em structly/structure.py no explorador de arquivos ou execute:
code structly/structure.py

Assim que o arquivo estiver aberto, olhe para a primeira linha da declaração de importação. Atualmente, ela se parece com isto:

from validate import validate_type

Esta declaração estava correta quando os arquivos estavam em uma estrutura diferente. Mas agora, precisamos alterá-la para dizer ao Python para procurar o módulo validate dentro do mesmo pacote. Portanto, mudamos para:

from .validate import validate_type

O ponto (.) antes de validate é uma parte fundamental aqui. É uma sintaxe especial em Python chamada importação relativa (relative import). Ela diz ao Python para procurar o módulo validate no mesmo pacote que o módulo atual (que é structure.py neste caso).

Após fazer essa alteração, certifique-se de salvar o arquivo. Salvar é importante porque torna as alterações permanentes, e o Python usará a declaração de importação atualizada quando você executar seu código.

Agora, vamos verificar nossos outros arquivos para ver se eles precisam de alguma atualização.

1. structly/reader.py - Este arquivo não importa de nenhum dos nossos módulos personalizados. Isso significa que não precisamos fazer nenhuma alteração nele.
2. structly/tableformat.py - Semelhante ao arquivo reader.py, este também não importa de nenhum dos nossos módulos personalizados. Portanto, nenhuma alteração é necessária aqui também.
3. structly/validate.py - Assim como os dois arquivos anteriores, ele não importa de nenhum dos nossos módulos personalizados. Logo, não precisamos modificá-lo.

Na programação do mundo real, seus projetos podem ter relacionamentos mais complexos entre módulos. Ao mover arquivos para criar ou modificar uma estrutura de pacote, lembre-se sempre de atualizar as declarações de importação. Isso garante que seu código possa encontrar e usar os módulos necessários corretamente.

Atualizando e Testando o Programa stock.py

Agora que criamos nosso pacote e corrigimos as importações internas, é hora de atualizar o arquivo stock.py para usar nossa nova estrutura de pacote. Um pacote em Python é uma maneira de organizar módulos relacionados juntos. Ele ajuda a manter seu código organizado e facilita o gerenciamento e a reutilização do código.

Abra o arquivo stock.py no editor:

## Click on stock.py in the file explorer or run:
code stock.py

As importações atuais em stock.py são baseadas na estrutura antiga, onde todos os arquivos estavam no mesmo diretório. Em Python, quando você importa um módulo, o Python procura o módulo em locais específicos. Na estrutura antiga, como todos os arquivos estavam no mesmo diretório, o Python conseguia encontrar os módulos facilmente. Mas agora, com a nova estrutura do pacote, precisamos atualizar as importações para dizer ao Python onde encontrar os módulos dentro do pacote structly.

Atualize o arquivo stock.py para ficar exatamente assim:

## stock.py

from structly.structure import Structure, String, PositiveInteger, PositiveFloat

class Stock(Structure):
    name = String()
    shares = PositiveInteger()
    price = PositiveFloat()

    @property
    def cost(self):
        return self.shares * self.price

    def sell(self, nshares: PositiveInteger):
        self.shares -= nshares

if __name__ == '__main__':
    from structly.reader import read_csv_as_instances
    from structly.tableformat import create_formatter, print_table
    portfolio = read_csv_as_instances('portfolio.csv', Stock)
    formatter = create_formatter('text')
    print_table(portfolio, ['name','shares','price'], formatter)

As principais mudanças são:

1. Mudou from structure import Structure, String, PositiveInteger, PositiveFloat para from structly.structure import Structure, String, PositiveInteger, PositiveFloat. Essa alteração diz ao Python para procurar o módulo structure dentro do pacote structly.
2. Mudou from reader import read_csv_as_instances para from structly.reader import read_csv_as_instances. Da mesma forma, essa alteração direciona o Python a encontrar o módulo reader dentro do pacote structly.
3. Mudou from tableformat import create_formatter, print_table para from structly.tableformat import create_formatter, print_table. Isso garante que o Python localize o módulo tableformat no pacote structly.

Salve o arquivo após fazer essas alterações. Salvar o arquivo é importante porque garante que as alterações que você fez sejam armazenadas e possam ser usadas quando você executar o programa.

Agora, vamos testar nosso código atualizado para garantir que tudo funcione corretamente:

python stock.py

Você deve ver a seguinte saída:

      name      shares       price
---------- ---------- ----------
      MSFT        100      51.23
       IBM         50       91.1
      AAPL         75     145.89
      ACME        125     123.45
       HPE         75       32.2

Se você vir essa saída, parabéns! Você criou com sucesso um pacote Python e atualizou seu código para usá-lo. Isso significa que seu código agora está organizado de uma forma mais modular, tornando-o mais fácil de manter e expandir no futuro.

Resumo

Neste laboratório, você aprendeu como criar e estruturar um pacote Python. Especificamente, você entendeu o conceito e a utilidade dos pacotes Python para organização de código, criou uma estrutura básica de pacote, moveu módulos Python para dentro dele, atualizou as declarações de importação e modificou o código para usar o pacote corretamente.

Essas habilidades são cruciais para o desenvolvimento de aplicações Python maiores, pois a organização adequada do código se torna cada vez mais importante. Os pacotes Python ajudam a manter o código relacionado junto, evitam conflitos de nomes e tornam seu código mais reutilizável, sustentável e compartilhável. Pacotes bem estruturados são uma pedra angular do desenvolvimento profissional em Python à medida que você continua sua jornada em Python.