Código Python: ler uma série de preços e descrevê-la (download grátis)

Código Python: ler uma série de preços e descrevê-la (download grátis)

Uma série de preços é, no fundo, uma lista de números com data: quanto custou algo em cada dia. Lê-la bem, isto é, saber quanto variou, quanto se mexeu e que forma tem, é a primeira tarefa de quem acompanha mercados e também de um dono de negócio que quer comparar os preços do seu produto com os dos meses anteriores. Este programa em Python faz exatamente isso: abre um arquivo com duas colunas, calcula o resumo da série e a desenha na tela com caracteres, sem janela de gráfico e sem bibliotecas de terceiros. Está escrito para quem não programa: roda com um comando e não há nada mais para instalar.

Aviso: este programa é material educativo. Não é uma recomendação de compra nem de venda. Os preços de exemplo que viajam dentro do ZIP são inventados e os dados históricos são citados só para praticar. Um resultado passado não garante nada no futuro. Consulte um profissional autorizado antes de investir.

O que o ZIP traz

Fonte dos dados históricos: CoinGecko (api.coingecko.com) para o bitcoin e o Federal Reserve Bank de St. Louis, série SP500, para o índice (https://fred.stlouisfed.org/series/SP500). As duas séries foram baixadas em 25 de setembro de 2026 e são usadas apenas como dados de prática. Se você preferir trabalhar com os seus próprios números, troque o arquivo da pasta datos/ pelo seu CSV: o formato está explicado na tabela abaixo e não é preciso mexer em uma linha do programa.

O que o programa faz

1. Lê datos/precos.csv, a série de exemplo inventada, com 180 fechamentos diários.
2. Calcula o retorno diário de cada dia: quanto o fechamento mudou em relação ao dia anterior, em porcentagem.
3. Resume a série: quantidade de dados, data inicial e final, fechamento mínimo e máximo, primeiro e último fechamento, variação total, variação média diária e volatilidade.
4. Confere a própria aritmética: que o último fechamento seja o da última linha do arquivo e que a variação total, calculada de duas maneiras diferentes, dê o mesmo.
5. Repete o mesmo resumo em datos/precos_reais.csv, agora agrupando por ativo: uma linha por ativo.
6. Desenha a série de exemplo na tela como sessenta colunas feitas de blocos, com uma legenda que aponta o mínimo e o máximo.
7. Salva o resumo completo em salida/resumen_series.csv, pronto para abrir no Excel.
8. Imprime o aviso legal ao começar e ao terminar.

Como executar

Você precisa do Python 3.11 ou superior. No Windows ele é instalado pelo site python.org e vale marcar a caixa que coloca o Python no PATH. Depois descompacte o ZIP em qualquer pasta, abra o terminal nessa pasta e digite o comando abaixo. Um jeito rápido de chegar lá é clicar com o botão direito na pasta e escolher a opção que abre o terminal ali mesmo.

python serie_precios.py

Não há nada mais para instalar: o programa usa somente a biblioteca padrão. Também não precisa de internet, porque os dois arquivos de preços viajam dentro do ZIP. Se a tela do Windows não conseguir desenhar os blocos do gráfico, o próprio programa passa a saída para UTF-8 em vez de quebrar, então roda igual no Windows, no Linux e no Mac.

O formato do arquivo de dados

O arquivo com a série real acrescenta mais uma coluna, ativo, com o nome do ativo, para o programa saber onde começa e onde termina cada série. Os cabeçalhos ficam na primeira linha e cada linha é um dia. Se o seu arquivo tiver mais de cem dias, melhor ainda: a volatilidade e o gráfico se leem com mais calma. Só é preciso respeitar a ordem das colunas e o ponto decimal dentro do arquivo; o resto o programa resolve.

O código, explicado

O programa tem menos de duzentas e cinquenta linhas e está comentado em português. Estes são os cinco trechos que vale a pena entender, copiados palavra por palavra do arquivo do ZIP.

As ferramentas e os caminhos

Esses quatro import são a caixa de ferramentas inteira: csv para ler o arquivo, sys para saber como a tela desenha, Decimal para que preços e porcentagens não carreguem erros de arredondamento e pathlib para montar caminhos que funcionam igual no Windows, no Linux e no Mac. A variável BASE é a pasta do próprio programa, e é por isso que ele roda de qualquer lugar: não depende de onde você está quando o chama.

import csv                                        # csv: ler o arquivo de preços sem instalar nada
import sys                                        # sys: saber com que conjunto de caracteres a tela desenha
from decimal import Decimal, ROUND_HALF_UP        # Decimal: preços e porcentagens exatos, sem surpresas binárias
from pathlib import Path                          # pathlib: caminhos que funcionam no Windows, Linux e Mac

# A pasta deste mesmo arquivo: assim o programa roda de qualquer lugar
BASE = Path(__file__).resolve().parent
ENTRADA = BASE / "datos" / "precos.csv"      # série de exemplo inventada, que viaja dentro do ZIP
ENTRADA_REAL = BASE / "datos" / "precos_reais.csv"    # série histórica citada só para praticar (dois ativos)
SALIDA = BASE / "salida" / "resumen_series.csv"   # resumo das séries, pronto para abrir no Excel

O retorno diário: a matéria-prima

O retorno de um dia é quanto o fechamento mudou em relação ao dia anterior, em porcentagem. A função percorre os fechamentos com um índice e divide cada um pelo anterior; o menos um deixa a mudança na forma limpa de porcentagem. Com essa lista na mão já é possível medir a variação média e, sobretudo, a volatilidade. A função devolve um dicionário com as datas, os extremos, o primeiro fechamento, o último e as três porcentagens do resumo.

def estadisticas(filas: list[dict]) -> dict:
    """Calcula o resumo da série: datas, extremos, variação e volatilidade."""
    fechas = [fila["data"] for fila in filas]
    cierres = [Decimal(fila["fechamento"]) for fila in filas]
    # Retorno diário (%): quanto o fechamento mudou de um dia para o outro
    retornos = [(cierres[i] / cierres[i - 1] - 1) * CIEN for i in range(1, len(cierres))]

A volatilidade: um desvio padrão

A volatilidade não passa de um desvio padrão desses retornos: um único número que resume o quanto as mudanças diárias se afastam da média delas. Se o preço se mexe pouco, o desvio é pequeno; se dá saltos, ele cresce. Usa-se a fórmula populacional, que divide pelo número de retornos e não pelo número menos um, e a raiz quadrada fecha a conta. Comparar esse número entre duas séries diz bem mais do que olhar os preços soltos.

def desviacion(valores: list[Decimal]) -> Decimal:
    """Desvio padrão populacional de uma lista de números."""
    media = sum(valores) / len(valores)
    # Populacional: a variância divide pelo número de retornos, não por n-1
    varianza = sum((valor - media) ** 2 for valor in valores) / len(valores)
    return varianza.sqrt()

O gráfico da tela: um nível por caractere

Como o terminal não tem janelas, o gráfico é desenhado com caracteres. A função nivel traduz um fechamento em um número de zero a sete, que é a posição do caractere dentro da escada de blocos; o valor é escalado entre o mínimo e o máximo da série. Depois, a função dibujar faz a média de vários dias em cada uma das sessenta colunas e escreve a linha. É assim que você vê a forma da série de uma vez, sem abrir planilha.

def nivel(valor: Decimal, minimo: Decimal, maximo: Decimal) -> int:
    """Traduz um fechamento em um nível de 0 a 7: o índice do caractere do gráfico."""
    if maximo == minimo:
        return 0
    posicion = (valor - minimo) / (maximo - minimo)
    indice = (posicion * (len(ESCALONES) - 1)).quantize(Decimal("1"), rounding=ROUND_HALF_UP)
    return max(0, min(len(ESCALONES) - 1, int(indice)))

As conferências: não confiar em si mesmo

O programa calcula o último fechamento de duas maneiras e a variação total também de duas maneiras, e compara. Quando as duas contas batem, ele imprime que fecha. É um hábito saudável: quando um número aparece igual por dois caminhos diferentes, a gente confia muito mais nele do que em um resultado solto. Na prática, é isso que separa um resumo utilizável de um número inventado.

def comprobar(filas: list[dict], datos: dict) -> None:
    """Mostra as duas conferências da série."""
    # Conferência 1: o último fechamento é o da última linha do arquivo
    cuadra1 = Decimal(filas[-1]["fechamento"]) == datos["ultimo"]
    # Conferência 2: a variação total, calculada de outro jeito, deve dar o mesmo
    directa = (datos["ultimo"] / datos["primero"] - 1) * CIEN
    cuadra2 = redondear(directa * 10000) == redondear(datos["var_total"] * 10000)

O que você vai ver na tela

Ao executar, a primeira coisa que aparece é o aviso legal; depois vem a tabela da série de exemplo com o resumo dela: 180 dados, o primeiro e o último dia do arquivo e os três números de sempre. Embaixo vêm as duas conferências. Na série real, a tabela é impressa com uma linha por ativo. Este é um trecho da saída real, copiado tal como sai:

SÉRIE DE EXEMPLO
---------------------------------------------------------------------------------------------------------------------------------------------------
Série                    Dados       Início         Fim       Mínimo       Máximo     Primeiro       Último      Var. % Var. média % Volatilidade %
---------------------------------------------------------------------------------------------------------------------------------------------------
Exemplo                  180     2026-01-02  2026-06-30        92,25       123,61        99,94       117,24     17,31 %       0,10 %         1,23 %
---------------------------------------------------------------------------------------------------------------------------------------------------
    Conferência: último fechamento = última linha do arquivo: FECHA
    Conferência: variação total = (último/primeiro - 1) × 100: FECHA
DADOS REAIS
  Fonte dos dados reais: CoinGecko, api.coingecko.com e Reserva Federal de St. Louis (série SP500), baixados em 2026-09-25
RESUMO POR ATIVO
---------------------------------------------------------------------------------------------------------------------------------------------------
Série                    Dados       Início         Fim       Mínimo       Máximo     Primeiro       Último      Var. % Var. média % Volatilidade %
---------------------------------------------------------------------------------------------------------------------------------------------------
Bitcoin (USD)            120     2026-05-30  2026-09-25    58.566,09    86.596,74    73.500,92    83.706,64     13,89 %       0,13 %         2,16 %
S&P 500 (índice)         120     2026-04-06  2026-09-24     6.611,83     7.798,99     6.611,83     7.704,13     16,52 %       0,13 %         0,79 %
---------------------------------------------------------------------------------------------------------------------------------------------------

E no fim chega o momento didático: o gráfico. Cada caractere é a média de três dias seguidos, e a escada de blocos vai do nível mais baixo ao mais alto. Lendo da esquerda para a direita vê-se a forma desses meses: sobe, corrige, fica de lado e volta a subir, com o ponto mais baixo marcado perto do meio do período. Um gráfico feito de caracteres não prevê nada, mas organiza o olhar bem melhor que uma lista de números.

GRÁFICO DA SÉRIE DE EXEMPLO (60 colunas)
---------------------------------------------------------------------------------------------------------------------------------------------------
  ▃▃▃▄▄▄▃▃▄▄▄▅▅▅▅▅▅▅▅▆▅▄▄▃▃▂▂▂▂▂▂▁▁▁▂▂▃▃▃▃▃▄▄▅▆▆▇▇▇▇▇█▇▇▇▇▇▇▆▇
---------------------------------------------------------------------------------------------------------------------------------------------------
Legenda: ▁ mínimo 92,25 (2026-04-08) | █ máximo 123,61 (2026-06-04)

Erros comuns e dicas

• Se o terminal responder que python não é um programa reconhecido, tente o nome python3, que é o usado no Linux e em alguns Macs.
• Rode o programa a partir da pasta onde você descompactou o ZIP, ou passe o caminho completo do arquivo. Se mudar de lugar, a pasta datos/ tem de ir junto.
• Se alterar o arquivo de preços, mantenha os cabeçalhos e os nomes das colunas. Uma vírgula a mais em uma linha bagunça a análise inteira sem avisar.
• Cuidado com o ponto decimal no arquivo de dados: o programa lê ponto, não vírgula, mesmo imprimindo os números no formato local depois.
• Uma série de poucos dias dá uma volatilidade em que não se pode confiar. Com menos de vinte fechamentos, o resumo serve para praticar, não para tirar conclusões.
• Se faltar um dia no arquivo, o salto conta como um único retorno. As lacunas não se preenchem sozinhas.

Quando isso não basta

Este programa é um bom exercício e dá conta de uma série, ou de duas. Quando o estoque de uma pequena empresa entra em cena, a conversa muda: chegam as compras, as vendas, os saldos por depósito, os custos e o rastro que é preciso deixar para conseguir revisar um movimento meses depois. É aí que Kardex Tauro passa a fazer sentido, porque controla o estoque e o custo de verdade e guarda o histórico. Se o seu problema é um arquivo de preços, fique com o script; quando os movimentos se multiplicam e as contas têm de fechar com a contabilidade, o script fica curto.

Aviso: este artigo e o programa são material educativo. Não é uma recomendação de compra nem de venda. A fonte dos dados está citada acima e o ZIP traz o aviso legal por escrito, junto com as instruções. Os preços de exemplo são inventados e os históricos são citados só para praticar: um resultado passado não garante nada no futuro, então consulte um profissional autorizado antes de investir.

Baixe o ZIP, execute o programa com uma única linha de comando e veja a sua primeira série de preços descrita com números e com caracteres. Depois troque o arquivo pelos seus próprios preços e compare: o mesmo exercício, com dados que importam para você.