Kiln — framework web

Referência do Kiln

As 64 funções do módulo e as dez palavras da linguagem.

Esta página é gerada a partir de dataforge/stdlib/kiln.py. São 64 funções — a sintaxe da linguagem (server, route, respond…) chama estas mesmas.

As palavras da linguagem#

Palavra	Equivale a
`server nome on porta:`	`Kiln.forge(nome)`
`route GET "/x":`	`Kiln.get(app, "/x", handler)`
`respond json d`	`yield Kiln.json(d)`
`render "x" with d`	`yield Kiln.render(app, "x", d)`
`redirect "/x"`	`yield Kiln.redirect("/x")`
`middleware m`	`Kiln.use(app, m)`
`mount o at "/p"`	`Kiln.mount(app, "/p", o)`
`assets "/p" from "d"`	`Kiln.static(app, "/p", "d")`
`views "d"`	`Kiln.templates(app, "d")`
`ignite app on 8080`	`Kiln.listen(app, 8080)`

As dez são contextuais: só valem dentro de um bloco server. Fora dali continuam sendo nomes livres.

Aplicação#

Função	Faz
`Kiln.forge(nome='kiln', …)`	Cria uma aplicação. `Kiln.app` é o mesmo.
`Kiln.app(nome='kiln', …)`	Apelido de `forge`.
`Kiln.config(app, chave, valor)`	Ajusta uma opção: `debug`, `limite_corpo`.
`Kiln.stats(app)`	Pedidos, erros, rotas e tempo no ar.

Rotas#

Função	Faz
`Kiln.route(app, metodo, padrao, handler)`	Registra uma rota com o verbo dado.
`Kiln.get(app, padrao, handler)`	Registra uma rota GET.
`Kiln.post(app, padrao, handler)`	Registra uma rota POST.
`Kiln.put(app, padrao, handler)`	Registra uma rota PUT.
`Kiln.patch(app, padrao, handler)`	Registra uma rota PATCH.
`Kiln.delete(app, padrao, handler)`	Registra uma rota DELETE.
`Kiln.options(app, padrao, handler)`	Registra uma rota OPTIONS.
`Kiln.head(app, padrao, handler)`	Registra uma rota HEAD.
`Kiln.any(app, padrao, handler)`	Registra uma rota que casa qualquer verbo.
`Kiln.resource(app, base, controlador)`	Sete rotas RESTful de uma vez, a partir de um vault com `index`, `show`, `create`, `update`, `patch` e `destroy` — só as que existirem.
`Kiln.mount(app, prefixo, outro)`	Junta as rotas de outro server sob um prefixo.
`Kiln.group(app, prefixo, meio=None)`	Sub-app cujas rotas herdam prefixo e middleware.
`Kiln.routes(app)`	Lista as rotas registradas.

Middleware#

Função	Faz
`Kiln.use(app, funcao)`	Acrescenta um middleware.
`Kiln.after(app, funcao)`	Roda com a resposta já pronta.
`Kiln.on_error(app, status, handler)`	Troca a resposta de um status (404, 500…).
`Kiln.cors(origens='*', metodos=None, cabecalhos=None)`	Libera origens e responde o preflight.
`Kiln.logger(formato='dev')`	Uma linha por pedido no terminal.
`Kiln.rate_limit(maximo=60, janela=60)`	429 + `Retry-After` ao estourar o teto por IP.
`Kiln.auth(verificador, esquema='Bearer')`	401 sem credencial; põe o usuário em `req["state"]["user"]`.
`Kiln.guard(condicao, status=403, mensagem='sem permissão')`	Middleware a partir de uma condição qualquer.

Segurança#

Função	Faz
`Kiln.secure_headers(csp="default-src 'self'", hsts=False, frame='DENY', referrer='strict-origin-when-cross-origin', permissoes='geolocation=(), microphone=(), camera=()')`	Middleware de saída com nosniff, X-Frame-Options, CSP, Referrer-Policy e Permissions-Policy. HSTS opcional — ligue só com o certificado de pé.
`Kiln.cabecalhos_seguros(csp="default-src 'self'", hsts=False, frame='DENY', referrer='strict-origin-when-cross-origin', permissoes='geolocation=(), microphone=(), camera=()')`	O mesmo que `secure_headers`, em português.
`Kiln.csrf(segredo, campo='_csrf', cabecalho='X-CSRF-Token')`	Recusa POST/PUT/PATCH/DELETE sem um token que você assinou. Métodos seguros passam.
`Kiln.csrf_token(req, segredo=None)`	Um token para pôr no formulário ou no fetch.
`Kiln.limite_de_corpo(bytes_maximos=1048576)`	Recusa corpo acima do teto, com 413. Sem ele, um POST de 2 GB derruba o processo sem exploit nenhum.
`Kiln.body_limit(bytes_maximos=1048576)`	O mesmo que `limite_de_corpo`, em inglês.

Validação#

Função	Faz
`Kiln.validar(esquema, alvo='body')`	Middleware que recusa com 422 o que não casa com o esquema — e relata todos os campos errados de uma vez.
`Kiln.validate(esquema, alvo='body')`	O mesmo que `validar`, em inglês.
`Kiln.conferir(dados, esquema)`	Os problemas do vault, sem responder nada. Para quando o campo errado não é 422, e sim um padrão ou uma pergunta.

Listagem#

Função	Faz
`Kiln.paginar(itens, req=None, por_pagina=20, teto=100)`	Uma fatia da lista com `pagina`, `total`, `paginas` e `tem_proxima`. `por_pagina` tem teto — ele vem de fora.
`Kiln.ordenar(itens, req=None, campos=None, padrao='')`	Ordena por `?ordenar=campo` ou `-campo`. A lista de campos permitidos não é conforto: ordenar por um campo que você nunca expôs revela a ordem dele.
`Kiln.buscar(itens, req=None, campos=(), parametro='q')`	Filtra por `?q=` nos campos que você indicar.

Transferência#

Função	Faz
`Kiln.cache(segundos=60, privado=False)`	Cache-Control e ETag, com 304 quando o cliente já tem a versão.
`Kiln.comprimir(minimo=1024)`	gzip quando o cliente aceita e o corpo compensa. Não toca em imagem, vídeo nem zip — já comprimidos.
`Kiln.idempotente(janela=86400)`	Repetir com a mesma `Idempotency-Key` devolve o mesmo resultado, em vez de cobrar duas vezes.

Observabilidade#

Função	Faz
`Kiln.request_id(cabecalho='X-Request-Id')`	Um id por pedido, no estado e na resposta. Mantém o que veio do proxy — trocar quebra a corrente.
`Kiln.audit(escrever=None, metodos=('POST', 'PUT', 'PATCH', 'DELETE'))`	Registra quem mudou o quê. Só métodos que mudam estado, e sem o corpo: ele carrega senha, cartão e token.
`Kiln.auditoria(escrever=None, metodos=('POST', 'PUT', 'PATCH', 'DELETE'))`	O mesmo que `audit`, em português.

Respostas#

Função	Faz
`Kiln.json(dados, status=200, cabecalhos=None)`	Resposta JSON.
`Kiln.html(texto, status=200, cabecalhos=None)`	Resposta HTML.
`Kiln.text(texto, status=200, cabecalhos=None)`	Resposta em texto puro.
`Kiln.status(codigo, mensagem=None)`	Só um status, com a frase padrão dele.
`Kiln.redirect(destino, status=302)`	302 (ou o status que você passar) com `Location`.
`Kiln.file(caminho, tipo=None, baixar=None)`	Serve um arquivo do disco; `baixar` força o download.
`Kiln.header(resp, chave, valor)`	Acrescenta um cabeçalho a uma resposta.
`Kiln.cookie(resp, nome, valor, dias=None, http_only=True, caminho='/', same_site='Lax', seguro=False)`	Acrescenta um `Set-Cookie`. Já marca `HttpOnly` e `SameSite`.

Sessão#

Função	Faz
`Kiln.session_start(app, req, resp, dados=None)`	Cria a sessão e devolve a resposta com o cookie.
`Kiln.session_end(app, req, resp)`	Apaga a sessão e o cookie.
`Kiln.sign(dados, segredo)`	Token assinado com HMAC-SHA256.
`Kiln.unsign(token, segredo)`	Lê um token assinado; `void` se foi adulterado.

Views#

Função	Faz
`Kiln.templates(app, pasta)`	Define a pasta dos templates (o mesmo que `views`).
`Kiln.render(app, nome, dados=None, status=200)`	Renderiza um template e devolve a resposta.
`Kiln.render_string(texto, dados=None)`	Preenche um texto em vez de um arquivo.
`Kiln.static(app, prefixo, pasta)`	Serve uma pasta (o mesmo que `assets`).
`Kiln.escape(texto)`	Escapa HTML manualmente.

Ciclo de vida#

Função	Faz
`Kiln.listen(app, porta=8080, host='127.0.0.1', silencioso=False)`	Sobe e bloqueia até Ctrl-C (o mesmo que `ignite`).
`Kiln.serve(app, porta=8080, host='127.0.0.1')`	Sobe em segundo plano e devolve a porta.
`Kiln.stop(app)`	Desliga um servidor que está no ar.
`Kiln.test(app, metodo, caminho, corpo=None, cabecalhos=None)`	Executa um pedido direto na aplicação, sem socket.

A requisição#

Campo	É
`method`	o verbo, em maiúsculas
`path`	o caminho, já decodificado
`params`	os parâmetros do caminho
`query`	a query string
`body`	o corpo interpretado pelo Content-Type
`raw_body`	o corpo em bytes
`headers`	os cabeçalhos, em minúsculas
`cookies`	os cookies do pedido
`session`	a sessão do visitante
`state`	espaço livre para o middleware
`ip`	o endereço de quem pediu

Os status com frase pronta#

Kiln.status(codigo) conhece 20 códigos: 200, 201, 202, 204, 301, 302, 304, 400, 401, 403, 404, 405, 409, 413, 415, 422, 429, 500, 502, 503.