Gerador de Título de Eleitor em Python

Como gerar título de eleitor em Python com o SDK?

.titulo_eleitor(n) devolve uma lista de strings.

from fakeforge import FakeForge

ff = FakeForge()

# 1 título formatado (grupos de 4 pra leitura)
titulo = ff.titulo_eleitor(1)[0]
print(titulo)  # "3847 5921 0213"

# 1000 títulos só com os 12 dígitos
titulos = ff.titulo_eleitor(1000, formatted=False)

# Pessoa de teste: CPF + título
cpfs = ff.cpf(10)
titulos = ff.titulo_eleitor(10)
eleitores = list(zip(cpfs, titulos))

Requer internet, porque o SDK chama o endpoint HTTP. A UF de cada título é sorteada e o SDK não tem parâmetro pra fixá-la. Quando o teste exige um estado específico, use o algoritmo da próxima seção.

Qual é o algoritmo do título de eleitor em Python?

O título tem 12 dígitos: NNNNNNNN UU D1 D2. O primeiro dígito verificador usa os 8 sequenciais com pesos 2 a 9. O segundo usa os 2 dígitos da UF e o primeiro verificador com pesos 7, 8 e 9. Versão offline, sem dependência:

# titulo_eleitor.py - implementação pura, offline
import random

# Código de UF do título (TSE): 01 a 28
UFS = {
    "SP": "01", "MG": "02", "RJ": "03", "RS": "04", "BA": "05",
    "PR": "06", "CE": "07", "PE": "08", "SC": "09", "GO": "10",
    "MA": "11", "PB": "12", "PA": "13", "ES": "14", "PI": "15",
    "RN": "16", "AL": "17", "MT": "18", "MS": "19", "DF": "20",
    "SE": "21", "AM": "22", "RO": "23", "AC": "24", "AP": "25",
    "RR": "26", "TO": "27", "ZZ": "28",  # ZZ = exterior
}


def calcula_dv(digitos: list[int], pesos, cod_uf: str) -> int:
    dv = sum(d * p for d, p in zip(digitos, pesos)) % 11
    if dv == 10:
        dv = 0
    if dv == 0 and cod_uf in ("01", "02"):  # regra SP e MG
        dv = 1
    return dv


def gera_titulo_eleitor(uf: str = "SP") -> str:
    cod = UFS[uf]
    base = [random.randint(0, 9) for _ in range(8)]
    dv1 = calcula_dv(base, range(2, 10), cod)
    dv2 = calcula_dv([int(cod[0]), int(cod[1]), dv1], (7, 8, 9), cod)
    return "".join(map(str, base)) + cod + str(dv1) + str(dv2)


def valida_titulo_eleitor(titulo: str) -> bool:
    d = "".join(c for c in titulo if c.isdigit())
    if len(d) != 12 or len(set(d)) == 1:
        return False
    cod = d[8:10]
    if cod not in UFS.values():
        return False
    n = [int(c) for c in d]
    ok1 = calcula_dv(n[:8], range(2, 10), cod) == n[10]
    ok2 = calcula_dv([n[8], n[9], n[10]], (7, 8, 9), cod) == n[11]
    return ok1 and ok2

Vantagens: zero deps, offline e UF à sua escolha. Limitação: só o título, sem zona ou seção eleitoral e sem correlação com o resto da pessoa.

Como testar título de eleitor em pytest?

# tests/test_titulo_eleitor.py
import pytest
from titulo_eleitor import UFS, gera_titulo_eleitor, valida_titulo_eleitor


@pytest.mark.parametrize("uf", list(UFS))
def test_titulo_gerado_passa_no_validador(uf):
    for _ in range(100):
        assert valida_titulo_eleitor(gera_titulo_eleitor(uf))


@pytest.mark.parametrize("uf", ["SP", "MG"])
def test_ufs_com_regra_especial(uf):
    # 2000 títulos garantem casos de resto 0 nos dois estados
    for _ in range(2000):
        assert valida_titulo_eleitor(gera_titulo_eleitor(uf))


def test_codigo_uf_fica_nas_posicoes_9_e_10():
    assert gera_titulo_eleitor("MG")[8:10] == "02"


def test_validador_rejeita_dv_adulterado():
    titulo = gera_titulo_eleitor("RJ")
    dv_errado = str((int(titulo[-1]) + 1) % 10)
    assert not valida_titulo_eleitor(titulo[:-1] + dv_errado)


def test_validador_rejeita_uf_inexistente():
    assert not valida_titulo_eleitor("123456789912")  # UF 99

Como popular um banco Django com título de eleitor?

# cadastro/management/commands/seed_eleitores.py
from django.core.management.base import BaseCommand
from fakeforge import FakeForge
from cadastro.models import Eleitor


class Command(BaseCommand):
    help = "Cria eleitores de teste com CPF e título válidos"

    def add_arguments(self, parser):
        parser.add_argument("--qtd", type=int, default=500)

    def handle(self, *args, **options):
        qtd = options["qtd"]
        ff = FakeForge()
        cpfs = ff.cpf(qtd, formatted=False)
        titulos = ff.titulo_eleitor(qtd, formatted=False)
        nomes = ff.full_name(qtd)

        Eleitor.objects.bulk_create(
            [Eleitor(nome=n, cpf=c, titulo=t) for n, c, t in zip(nomes, cpfs, titulos)],
            ignore_conflicts=True,
        )
        self.stdout.write(f"{qtd} eleitores criados")

SDK ou algoritmo local: qual escolher?

Mais volume ou mais itens por chamada? Veja os planos.

Perguntas frequentes

Próximos passos