MODELO
======

Modelo das entidades e como elas se relacionam.

Nenhum dos campos deve permitir acentos e/ou cedilhas.

Todas as entidades devem referenciar uma Fonte de Dados, de forma a evitar
redundancia de dados (com o objetivo de melhorar o desempenho e possibilitar
o uso de cache de persistencia de dados serializados).

    >>> from pynfe.entidades import FonteDados
    >>> fonte_dados = FonteDados()

Nao eh da funcao do PyNFe efetuar a persistencia dos objetos, mas a classe
FonteDados deve facilitar esse processo ao software que for implementa-la.

    >>> hasattr(FonteDados, 'carregar_objetos')
    True

    >>> from pynfe.entidades import Emitente

Populando fonte de dados com objetos

    >>> bool(Emitente(cnpj='12.345.678/0001-90', _fonte_dados=fonte_dados))
    True

    >>> bool(Emitente(razao_social='JKL Calcados Ltda.', _fonte_dados=fonte_dados))
    True

    >>> bool(Emitente(razao_social='JKL Calcados Ltda.', _fonte_dados=fonte_dados))
    True

O metodo carregar_objetos pode ser sobrecarregado para alterar o carregamento de
objetos da memoria para forcar mocking ou para carregar de camada persistente.
Ele sempre retorna uma lista de objetos, independente se vazia ou com qualquer
quantidade de objetos.

    >>> def carregar_objetos(self, **kwargs):
    ...     if kwargs.get('cnpj', None) == 'xxx':
    ...         return ['encontrado!']
    ... 
    ...     return self.antigo_carregar_objetos(**kwargs)

Substituindo metodo 'carregar_objetos'

    >>> fonte_dados.antigo_carregar_objetos = fonte_dados.carregar_objetos

    >>> import new
    >>> fonte_dados.carregar_objetos = new.instancemethod(carregar_objetos, fonte_dados, FonteDados)

    >>> fonte_dados.obter_objeto(cnpj='xxx')
    'encontrado!'

O metodo 'obter_objeto' retorna um unico objeto que atende aos atributos informados.
O argumento especial '_classe' eh utilizado para indicar que a classe da entidade eh
a atribuida a esse argumento.

    >>> emitente = fonte_dados.obter_objeto(cnpj='12.345.678/0001-90', _classe=Emitente)

    >>> isinstance(emitente, Emitente)
    True

Caso nenhum objeto seja encontrado, uma excecao deve ser levantada.

    >>> from pynfe.excecoes import NenhumObjetoEncontrado

    >>> try:
    ...     fonte_dados.obter_objeto(cnpj='98.765.432/0001-10', _classe=Emitente)
    ... except NenhumObjetoEncontrado, e:
    ...     print e.message
    Nenhum objeto foi encontrado!

Caso mais de um objeto sejam encontrados, uma excecao deve ser levantada tambem.

    >>> from pynfe.excecoes import MuitosObjetosEncontrados

    >>> try:
    ...     fonte_dados.obter_objeto(razao_social='JKL Calcados Ltda.', _classe=Emitente)
    ... except MuitosObjetosEncontrados, e:
    ...     print e.message
    Muitos objetos foram encontrados!

O metodo 'obter_lista' retorna uma lista de objetos, mesmo que vazia.

    >>> len(fonte_dados.obter_lista(razao_social='JKL Calcados Ltda.'))
    2

    >>> len(fonte_dados.obter_lista(razao_social='Inexistente S/A'))
    0

Qualquer entidade que for instanciada deve ser acrescentada automaticamente a lista de
objetos da Fonte de Dados, atraves de um metodo especifico pra isso

    >>> conta_antes = fonte_dados.contar_objetos()
    >>> emitente = Emitente(razao_social='Emitente Novo', _fonte_dados=fonte_dados)
    >>> fonte_dados.contar_objetos() - conta_antes
    1

O contador de objetos retorna a quantidade de instancias que casem com os argumentos passados

    >>> fonte_dados.contar_objetos(_classe=Emitente, razao_social='Emitente Novo')
    1

    >>> fonte_dados._objetos

Permitir tambem remover objetos (que por padrao remove apenas da lista da memoria e nao
eh persistente.

    >>> fonte_dados.remover_objeto(emitente)