Modo local — desenvolver sem o servidor
Até aqui o ParamManager só sabia trabalhar contra a API: qualquer
leitura ou escrita precisava do servidor no ar. O modo local remove
essa dependência para o dia a dia de desenvolvimento — você cria a
aplicação, escreve os parâmetros e lê tudo de um arquivo na sua máquina,
sem nenhuma chamada de rede. Quando quiser, sincroniza com o servidor.
O padrão não mudou
O modo padrão continua sendo remote, com exatamente o mesmo
comportamento de sempre. Se você não pedir o modo local, nada muda
para o seu código.
Ligando o modo local
Pelo construtor:
from param_manager import ParamManager
params = ParamManager.get_instance(
instance_name='dev',
mode='local',
)
Ou por variável de ambiente, sem tocar no código:
# vale para todas as instâncias
PARAM_MANAGER_MODE=local
# ou só para a instância chamada "dev"
DEV_PARAM_MANAGER_MODE=local
A precedência é a mesma do resto da biblioteca: argumento do construtor > variável prefixada pela instância > variável global.
Para saber em que modo você está:
params.mode # 'local' ou 'remote'
Trabalhando offline
As funções são as mesmas dos dois modos — o que muda é o destino:
params.create_app('financeiro', 'Contas a pagar')
params.upsert_params(
'financeiro', 'porta',
value=8080,
param_type='int',
)
params.get_param('financeiro', 'porta') # 8080
params.get_all_params('financeiro')
params.list_apps()
params.delete_param('financeiro', 'porta')
params.delete_app('financeiro')
O rascunho fica num arquivo próprio, ao lado do cache:
<base>/param_manager/<instancia>/local_<instancia>.json
Ele é separado do cache de propósito
A biblioteca limpa o cache automaticamente quando a API responde algo ilegível. Se o rascunho morasse no mesmo arquivo, essa limpeza apagaria o que você ainda não sincronizou — por causa de uma falha que não tem nada a ver com ele.
Parâmetros protegidos não são criados offline
Os tipos secret, user e users não podem ser criados no modo
local. A cifragem desses valores acontece no servidor, e gravá-los
localmente significaria guardar o conteúdo em claro no seu disco.
params.upsert_params('financeiro', 'senha', value='x', param_type='secret')
# LocalStoreError: ... só pode ser criado com o servidor ...
Ler um parâmetro protegido que já foi sincronizado continua funcionando normalmente: o valor cifrado está no cache e a biblioteca sabe decifrá-lo.
Aviso antecipado de valor inválido
Ao gravar, a biblioteca compara o valor com o catálogo de tipos do servidor e avisa no log quando ele provavelmente será recusado:
params.upsert_params('financeiro', 'nome', value='x' * 40, param_type='string')
# WARNING ... comprimento 40 passa do máximo 30; informe max_length no upsert
O aviso não impede a gravação. Quem valida de verdade é o servidor, na sincronização — o objetivo aqui é que o erro apareça na hora, e não no fim de uma sessão inteira de trabalho.
O limite padrão de 30 caracteres é do servidor, e vale quando o pedido não informa outro. Para elevá-lo, mande o limite junto:
params.upsert_params(
'financeiro', 'nome',
value='x' * 40,
param_type='string',
max_length=100,
)
Para manter o catálogo atualizado — útil antes de ficar sem servidor por um tempo:
params.refresh_type_catalog()
Enviando para o servidor
A sincronização tem duas etapas, e isso é proposital: você vê o que vai acontecer antes de acontecer.
plano = params.sync_plan()
plano['apps_to_create'] # apps que ainda não existem no servidor
plano['summary'] # {'create': 2, 'update': 1, 'conflict': 1}
for item in plano['params']:
print(item['app'], item['name'], item['action'], item['reason'])
sync_plan() não grava nada — nem local, nem no servidor. Quando
estiver satisfeito:
resultado = params.sync_apply(plano)
resultado['apps_created'] # apps criados no servidor
resultado['synced'] # parâmetros enviados com sucesso
resultado['rejected'] # recusados, com a mensagem do servidor
resultado['forbidden'] # sem permissão
resultado['skipped_conflicts'] # deixados de fora
Conflitos nunca são resolvidos sozinhos
Quando o mesmo parâmetro mudou dos dois lados, ele é marcado como conflito, fica de fora da aplicação e é apresentado com os dois valores para você decidir:
for item in plano['params']:
if item['action'] == 'conflict':
print(item['name'], 'local:', item['local'], 'servidor:', item['remote'])
Para forçar o envio de um conflito, mude a ação do item para 'update'
antes de aplicar — assim a decisão fica explícita:
item['action'] = 'update'
params.sync_apply(plano)
O que acontece quando o servidor recusa
Cada caso é tratado de forma diferente, porque significam coisas diferentes:
| Situação | O que acontece |
|---|---|
| Valor inválido | O parâmetro continua guardado localmente, com a mensagem exata do servidor, e os demais continuam sendo enviados |
| Sem permissão | O parâmetro segue pendente, para ser tentado de novo quando a credencial for corrigida |
| App não existe | O app é criado no servidor antes dos parâmetros |
A sincronização é retomável: se ela for interrompida no meio, a execução seguinte continua de onde parou.
Voltando para o servidor
Depois de sincronizar, construa uma instância nova em modo remoto:
params.sync_apply(params.sync_plan())
producao = ParamManager.get_instance(
instance_name='producao',
api_url='https://params.exemplo.com',
mode='remote',
)
Por que uma instância nova
Uma instância já criada não é reconfigurada — essa proteção existe para evitar que parte do seu código passe a enxergar uma configuração diferente da outra parte no meio da execução.
Interface gráfica
Para aplicações com interface, o módulo param_manager.api oferece as
mesmas operações em funções que devolvem sempre um dicionário com ok,
em vez de lançar exceções:
from param_manager import api
api.configure(instance_name='front', mode='local', api_url='...')
resposta = api.get_all_params('financeiro', instance_name='front')
if resposta['ok']:
print(resposta['params'])
else:
print(resposta['error'])
As funções bloqueiam
Elas fazem requisições, leitura de disco e decifragem. Chame-as fora do laço de eventos da interface, sob pena de a janela congelar.