O módulo array oferece uma sequência mutável de valores numéricos armazenados em formato compacto. Diferente de uma lista, que guarda referências para objetos Python, um array.array mantém elementos de um único tipo C em um bloco contínuo de memória. Isso reduz overhead e facilita troca de dados com arquivos binários, sockets e APIs que aceitam o buffer protocol.
O módulo não substitui NumPy em cálculo vetorizado, álgebra linear ou arrays multidimensionais. Ele é útil quando você precisa de uma estrutura simples da biblioteca padrão, com tipo homogêneo, consumo de memória previsível e métodos semelhantes aos de listas.
Crie um array
O primeiro argumento é o typecode, que define o tipo dos elementos.
from array import array
valores = array("i", [10, 20, 30])
print(valores)
print(valores.itemsize)
O tamanho e o intervalo de alguns typecodes dependem da plataforma. Consulte itemsize quando o layout binário for relevante.
Typecodes comuns
Entre os códigos mais usados estão b/B para bytes com e sem sinal, h/H para short, i/I para int, l/L para long, q/Q para 64 bits, f para float e d para double.
Escolha o menor tipo que representa o domínio com segurança. Valores fora do intervalo geram erro ou não podem ser inseridos.
Operações semelhantes a listas
Arrays suportam indexação, slices, append(), extend(), insert(), pop(), remove(), reverse() e contagem.
valores.append(40)
valores.extend([50, 60])
print(valores[1:4])
Todos os valores precisam ser compatíveis com o typecode.
Conversão para lista
tolist() cria objetos Python comuns.
lista = valores.tolist()
A conversão copia os dados e perde a vantagem de armazenamento compacto. Faça apenas na fronteira com APIs que exigem listas.
Crie a partir de bytes
frombytes() acrescenta valores interpretando um bloco binário.
dados = (1).to_bytes(4, "little") + (2).to_bytes(4, "little")
valores = array("I")
valores.frombytes(dados)
A interpretação usa o layout nativo do tipo e da plataforma. Para protocolos portáteis, use struct ou normalize a ordem de bytes.
Converta para bytes
tobytes() devolve a representação binária dos elementos.
payload = valores.tobytes()
Esse formato não inclui typecode, tamanho ou versão. Um leitor precisa conhecer o contrato por outro meio.
Ordem de bytes
byteswap() troca a ordem dos bytes de cada elemento quando o tamanho permite.
valores.byteswap()
Use apenas quando souber qual ordem os dados possuem e qual ordem deseja. Aplicar duas vezes restaura a representação original.
Leia de um arquivo
fromfile() lê uma quantidade de elementos de um arquivo binário.
valores = array("d")
with open("medidas.bin", "rb") as arquivo:
valores.fromfile(arquivo, 100)
Se o arquivo terminar antes, a operação pode adicionar elementos lidos e depois gerar EOFError. Trate estado parcial.
Grave em arquivo
tofile() escreve a representação nativa.
with open("medidas.bin", "wb") as arquivo:
valores.tofile(arquivo)
Para um formato durável, acrescente cabeçalho com magic bytes, versão, typecode, endianness e quantidade.
Integração com struct
struct é mais adequado quando cada registro possui campos de tipos diferentes.
Use struct no Python para layouts heterogêneos e array para longas sequências homogêneas.
Buffer protocol
Um array pode ser acessado com memoryview sem cópia.
valores = array("I", range(100))
view = memoryview(valores)
try:
consumir(view)
finally:
view.release()
Não redimensione o array enquanto houver views exportadas.
readinto e escrita sem cópia
APIs que aceitam buffers mutáveis podem preencher um array diretamente.
valores = array("B", [0]) * 4096
with open("dados.bin", "rb") as arquivo:
quantidade = arquivo.readinto(valores)
O retorno indica quantos bytes foram lidos. Ajuste a interpretação quando a leitura for parcial.
Slices
Um slice de array produz outro array com o mesmo typecode.
parte = valores[10:20]
Isso copia os elementos. Para uma visão sem cópia, use memoryview.
Multiplicação
Assim como listas, arrays podem ser repetidos.
zeros = array("f", [0.0]) * 1000
Multiplicações enormes podem consumir memória. Valide tamanhos recebidos externamente.
Memória
A economia aparece porque cada elemento usa o tamanho C do typecode, sem um objeto Python separado.
Meça com dados reais. Pequenos arrays podem não justificar a complexidade adicional.
Performance
Loops Python sobre array ainda executam elemento por elemento. O armazenamento compacto não cria vetorização automática.
Para operações numéricas intensivas, NumPy tende a ser mais adequado. Para I/O e armazenamento simples, array pode ser suficiente.
Valores Unicode
Typecodes históricos para caracteres Unicode possuem limitações e mudanças de plataforma. Para texto, prefira str, UTF-8 em bytes ou codecs explícitos.
Não use arrays de caracteres como formato de texto portátil sem um contrato claro.
Overflow e validação
Inserir um inteiro fora do intervalo do typecode gera OverflowError.
try:
valores.append(numero)
except OverflowError as erro:
raise ValueError("valor fora do intervalo") from erro
Valide unidades e limites antes da inserção.
Concorrência
O array é mutável e não oferece sincronização. Threads que escrevem ou redimensionam a mesma estrutura precisam de lock.
Para compartilhamento entre processos, use memória compartilhada ou arquivo mapeado com um protocolo explícito.
Integração com mmap
Um memoryview de um mmap pode ser convertido ou interpretado por ferramentas de buffer, mas copiar para array pode ser mais simples quando você precisa de ownership independente.
Consulte mmap no Python.
Serialização
Não trate tobytes() isolado como formato autodescritivo. Inclua metadados ou utilize um formato padronizado.
Para troca entre máquinas, defina explicitamente tamanho, sinal e endianness.
Segurança
Antes de criar um array com base em uma quantidade externa, aplique limite. Verifique se o tamanho do payload é múltiplo de itemsize.
if len(payload) % valores.itemsize != 0:
raise ValueError("payload truncado")
if len(payload) > LIMITE_BYTES:
raise ValueError("payload grande demais")
Testes
Teste valores mínimos e máximos, byte order, arquivos truncados, leitura parcial, arrays vazios, slices, memoryviews ativas e diferenças de plataforma.
Confirme interoperabilidade com vetores binários conhecidos.
Erros comuns
Os erros mais frequentes são presumir tamanho fixo de typecodes em todas as plataformas, gravar bytes sem cabeçalho, confundir armazenamento compacto com cálculo vetorizado, redimensionar com uma view ativa, ignorar leitura parcial e escolher um tipo pequeno demais.
Conclusão
array fornece sequências numéricas homogêneas e compactas usando apenas a biblioteca padrão. Ele combina uma interface familiar com arquivos binários e buffer protocol.
Escolha o typecode com cuidado, documente endianness e use NumPy quando precisar de operações numéricas avançadas. Consulte a documentação oficial de array, struct no Python e mmap no Python.
