O módulo http.cookiejar gerencia cookies automaticamente em clientes HTTP. Ele recebe valores de cabeçalhos Set-Cookie, decide se devem ser aceitos, armazena-os e adiciona o cabeçalho Cookie às requisições futuras compatíveis com domínio, caminho, expiração e política.
Essa funcionalidade permite manter sessões de login, preferências e fluxos de navegação usando urllib.request. Entretanto, um cookie de sessão pode equivaler a uma senha temporária. Persistência, logs, compartilhamento entre processos e políticas de domínio precisam ser tratados como decisões de segurança.
CookieJar com urllib.request
import http.cookiejar
import urllib.request
jar = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(
urllib.request.HTTPCookieProcessor(jar),
)
with opener.open("https://example.com/", timeout=10) as response:
response.read(100_000)
for cookie in jar:
print(cookie.name, cookie.domain, cookie.path)
HTTPCookieProcessor extrai cookies das respostas e devolve os cookies permitidos nas próximas requisições. Use o mesmo opener durante toda a sessão.
O guia de urllib.request no Python apresenta timeouts, limites, TLS e erros HTTP.
Como um cookie é selecionado
Um cookie possui nome, valor, domínio, caminho, flag secure, expiração e outros atributos. O jar só envia cookies quando a política considera o destino compatível.
for cookie in jar:
print({
"name": cookie.name,
"domain": cookie.domain,
"path": cookie.path,
"secure": cookie.secure,
"expires": cookie.expires,
"session": cookie.discard,
})
Evite imprimir o valor. Tokens de sessão, CSRF e autenticação podem estar dentro dele. Logs devem conter somente metadados necessários.
Cookies Secure e HTTPS
Cookies marcados como Secure devem ser enviados somente por protocolos considerados seguros, por padrão HTTPS e WSS. Isso não autoriza o uso de HTTP para login. Toda sessão autenticada deve trafegar por HTTPS com certificado validado.
O guia de ssl no Python explica verificação de certificados e hostname. Nunca desative TLS para fazer um fluxo com cookies funcionar.
Login com formulário
from urllib.parse import urlencode
from urllib.request import Request
form = urlencode({
"username": username,
"password": password,
}).encode("utf-8")
request = Request(
"https://example.com/login",
data=form,
headers={"Content-Type": "application/x-www-form-urlencoded"},
method="POST",
)
with opener.open(request, timeout=10) as response:
body = response.read(200_000)
Não conclua que o login funcionou apenas porque um cookie apareceu. Valide status, URL final e conteúdo esperado. Credenciais devem vir de um secret manager ou entrada protegida, nunca do código ou log.
Proteção CSRF
Muitos sites exigem um token CSRF presente em HTML ou cookie. O cookie jar cuida apenas do transporte dos cookies; ele não descobre automaticamente o token nem protege seu próprio servidor.
Um fluxo comum é: abrir a página do formulário, extrair o token, enviar token e credenciais, validar a resposta e manter os cookies recebidos. Se precisar analisar HTML controlado, consulte o guia de web scraping com Python.
Política por domínio
DefaultCookiePolicy permite bloquear ou permitir domínios.
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
allowed_domains=["example.com", ".example.com"],
blocked_domains=["ads.example.com"],
strict_ns_domain=DefaultCookiePolicy.DomainStrict,
)
jar = CookieJar(policy)
Entradas iniciadas por ponto incluem subdomínios mais específicos segundo as regras do módulo. Teste a política com os hosts reais. Uma allowlist reduz vazamentos acidentais, mas não substitui validação de URL e TLS.
Cookies de sessão e persistentes
Cookies sem expiração geralmente possuem discard=True e representam a sessão atual. clear_session_cookies() remove esses valores.
jar.clear_session_cookies()
CookieJar em memória desaparece quando o processo termina. Para persistência, use uma subclasse de FileCookieJar.
Persistindo com MozillaCookieJar
from pathlib import Path
from http.cookiejar import MozillaCookieJar
cookie_path = Path("cookies.txt")
jar = MozillaCookieJar(cookie_path)
if cookie_path.exists():
jar.load(ignore_discard=False, ignore_expires=False)
# Após usar o opener:
jar.save(ignore_discard=False, ignore_expires=False)
O formato é compatível com cookies.txt usado por ferramentas como curl. Ele pode perder atributos modernos ou específicos. Faça backup antes de sobrescrever um arquivo importante.
LWPCookieJar
LWPCookieJar usa o formato Set-Cookie3, legível e capaz de preservar mais informações do módulo.
from http.cookiejar import LWPCookieJar
jar = LWPCookieJar("session.cookies")
Escolha o formato pela interoperabilidade necessária. Nenhum deles deve ser considerado um cofre de segredos.
Protegendo o arquivo de cookies
Defina permissões restritas e evite diretórios sincronizados, backups públicos e imagens de container.
import os
from pathlib import Path
path = Path("session.cookies")
path.touch(mode=0o600, exist_ok=True)
os.chmod(path, 0o600)
Em sistemas sem permissões POSIX, use mecanismos equivalentes. Se o risco for alto, evite persistência ou criptografe o armazenamento com gestão correta de chaves.
Carregar, salvar e revert
load() adiciona cookies do arquivo ao estado atual. revert() limpa e recarrega de forma transacional: se ocorrer falha, o estado anterior não é alterado.
try:
jar.revert()
except (OSError, http.cookiejar.LoadError) as error:
raise RuntimeError("Arquivo de cookies inválido") from error
Não use ignore_expires=True ou ignore_discard=True sem compreender que cookies expirados ou de sessão serão preservados.
Limpeza seletiva
jar.clear("example.com", "/", "sessionid")
# ou limpar tudo:
jar.clear()
clear() pode gerar KeyError quando não existe correspondência. Em logout, além de limpar o jar, use o endpoint do servidor para invalidar a sessão.
Expiração
O jar remove cookies expirados quando necessário. Você pode consultar cookie.is_expired() durante auditorias.
active = [cookie for cookie in jar if not cookie.is_expired()]
Não altere manualmente expires para prolongar uma sessão. O servidor pode manter validade própria, e estender localmente um token aumenta risco.
SameSite e atributos modernos
http.cookiejar foi criado em torno de protocolos Netscape, RFC 2109 e RFC 2965. Atributos modernos podem aparecer como não padronizados, mas o módulo não replica integralmente a política de um navegador atual.
if cookie.has_nonstandard_attr("SameSite"):
print(cookie.get_nonstandard_attr("SameSite"))
Não use CookieJar para afirmar que um fluxo possui as mesmas garantias de isolamento de Chrome ou Firefox. Para automação de navegador, use uma ferramenta que implemente o modelo moderno.
Cookies de terceiros
A política possui conceitos de transação verificável e origem, mas a integração com urllib.request não representa toda a navegação de uma página moderna. Ao baixar recursos de terceiros manualmente, mantenha jars separados ou políticas estritas para evitar enviar cookies além do necessário.
Concorrência
Não compartilhe um jar mutável entre threads sem coordenação. Use um lock ao realizar sequências de abertura e salvamento, ou mantenha uma sessão por worker. Ao salvar, grave em temporário e substitua atomicamente para reduzir corrupção.
Cookies importados do navegador
Copiar um arquivo cookies.txt de um navegador pode expor sessões pessoais e sobrescrever dados. Nunca acesse perfis sem consentimento. Navegadores modernos usam bancos e criptografia específicos; MozillaCookieJar não lê automaticamente todos esses formatos.
Automação autenticada
Prefira tokens de API, OAuth ou contas de serviço quando o sistema oferece uma interface oficial. Automatizar login por formulário é mais frágil, pode violar termos e exige acompanhar CSRF, MFA e mudanças de HTML.
O guia de APIs REST no Python mostra uma alternativa mais estável.
Erros comuns
Os erros frequentes são registrar valores de cookies, persistir arquivo com permissões abertas, usar cookies expirados, compartilhar jar entre usuários, ignorar domínio, supor suporte completo a SameSite, desativar TLS, salvar cookies de sessão sem necessidade e tratar presença de cookie como prova de login.
Boas práticas
Use HTTPS validado, um jar por identidade, allowlist de domínios, timeouts e limites HTTP. Mantenha cookies em memória quando possível. Se persistir, proteja o arquivo, não salve sessão descartável sem motivo e limpe no logout. Prefira APIs oficiais a automação de navegador.
Conclusão
http.cookiejar integra sessões baseadas em cookies aos clientes da biblioteca padrão e oferece políticas e persistência. A conveniência vem com responsabilidade: cookies autenticados são segredos, arquivos podem vazar sessões e o modelo não equivale integralmente a um navegador moderno. Use escopo mínimo, TLS e armazenamento protegido.
Consulte a documentação oficial de http.cookiejar e o RFC 6265 sobre cookies HTTP.
