Melhora da API

[iurisilvio]

A API atual é confusa, fácil de trocar postmon.Endereco e postmon.endereco.

Uma opção é deixar só a classe, adicionando um kwarg lazy para identificar se é pra buscar já na inicialização da classe. Talvez fazer a busca automaticamente quando uma propriedade não carregada for buscada.

>>> postmon.Endereco('11111-111')
>>> postmon.Endereco('11111-111', lazy=False)

O comportamento padrão seria carregar só quando acessar alguma propriedade (ou quando chamar o buscar), já que hoje o comportamento é semelhante.

O SQLAlchemy tem solução parecida para a busca de relações. O relationship tem um argumento lazy.

http://docs.sqlalchemy.org/en/rel_0_7/orm/relationships.html#sqlalchemy.orm.relationship

Preciso de um nome pt-br equivalente pra lazy ou de outras alternativas para a API.

[iurisilvio]

No caso em que o usuário quer saber os erros do request, a solução continua sendo usar o buscar().

Fica difícil de tratar os erros no lazyload.

>>> e = postmon.Endereco('11111-111')
>>> e.logradouro
None

Deu erro ou o CEP não tem logradouro? Não dá pra saber, então volta pro problema de ter que saber o resultado do carregamento.

>>> e1.postmon.Endereco('11111-111', lazy=False)
>>> if e2._ok:
...     # objeto carregado
>>> e1.postmon.Endereco('11111-111')
>>> if e2.buscar():
...     # objeto carregado

Outra opção é usar um classmethod para fazer o carregamento ao invés de uma função externa, mas aí complica o caso de uso mais comum:

>>> e = postmon.Endereco.buscar('11111-111')

A solução mais simples talvez seja só renomear as funções do módulo e continuar com os comportamentos atuais:

>>> e = postmon.buscar_endereco('11111-111')

Se alguém ler isso e quiser dar opinião, agradeço. Escrevi para documentar minha cabeça, não defini as mudanças. Qualquer quebra de compatibilidade só vai acontecer na versão 1.0.

[aleborba]

Eu usei no PostmonGo o nome BuscarCep("cep") para tratar o mesmo comportamento da sua classe Endereco("cep").

Inicialmente eu tinha, também, colocado Endereco, mas ai achei estranho e fiz uma busca interna (eu comigo e eu mesmo, rsrs) e perguntei a algumas pessoas aleatórias: O que você faz quando precisa saber o endereço de um cep? e as respostas foram sempre as mesmas, Eu busco o cep no site :) Ai fiz a ligação e preferi usar o BuscarCep.

Enfim, meus 2 cents :P

[iurisilvio]

O BuscarCep do PostmonGo é o meu postmon.endereco. Inicialmente, eu tinha usado buscar_cep também, mas achei estranho essa função retornar um objeto Endereco.

Fiquei com medo de ficar tudo buscar_*, buscar_endereco, buscar_cidade, buscar_estado, mas talvez sejam os nomes corretos e evitem a confusão entre uma função e uma classe com mesmo nome.