Modificando comportamento da biblioteca conforme #6.

README.md

@@ -33,47 +33,54 @@ open_cnl_importer.importar_base()
 
 ## Exemplo prático
 
-Vamos utilizar como exemplo os telefones das prefeituras municipais das
-seguintes cidades:
+Vamos utilizar como exemplo o telefone da prefeitura municipal de Natal/RN:
+(84) 3211-8243. Veja este código no arquivo `exemplo.py`.
 
-- Natal/RN - (84) 3211-8243
-- Parnamirim/RN - (84) 3644-8100
-- Mossoró/RN - (84) 3315-4935
-- São Paulo/SP - (11) 3124-5100
+```python
+from open_cnl.open_cnl import OpenCNL
+
+# Inicializamos a classe que se
+# conecta ao banco de dados
+cnl = OpenCNL('./cnl_anatel.sqlite3')
+
+# Pesquisando por um número de Natal/RN
+cnl.pesquisar_localidade('843211', '8243')
+```
+
+Os dados retornados estarão num dicionário no seguinte formato:
+
+```python
+{
+    'prestadora': u'TELEMAR NORTE LESTE S.A.',
+    'nome_da_localidade': u'NATAL',
+    'hemisferio': u'S',
+    'numero_da_faixa_final': u'8999',
+    'sigla_cnl_da_area_local': u'NTL',
+    'numero_da_faixa_inicial': u'8000',
+    'longitude': u'351232',
+    'prefixo': u'843211',
+    'codigo_da_area_de_tarifacao': u'842',
+    'latitude': u'547419',
+    'codigo_cnl': u'84000',
+    'sigla_uf': u'RN',
+    'nome_do_municipio': u'NATAL',
+    'sigla_cnl': u'NTL'
+}
+```
+
+Caso uma localidade não seja encontrada será retornado o valor `None`.
+
+### JSON
 
-Nosso centro de custo será Natal/RN, que está na mesma região metropolitana de
-Parnamirim/RN. Mossoró/RN, por sua vez, se localiza no interior do estado. Por
-último, São Paulo, que fica em outro estado. Veja o código do arquivo
-`exemplo.py`.
+Na inicialização da classe podemos definir o parâmetro `as_json` como `True`.
+O padrão desse argumento é `False` e quando verdadeiro, permite que os dados
+sejam retornados em uma string no formato JSON.
 
 ```python
 from open_cnl.open_cnl import OpenCNL
 
-# Inicializamos a classe especificando
-# nosso centro de custo: Natal/RN
-cnl = OpenCNL('./cnl_anatel.sqlite3', '843211', '8243')
-
-# Ligando de Natal/RN para
-# Parnamirim/RN - Área conurbada
-# >>> 'VC1'
-cnl.buscar_localidade('843644', '8100')
-
-# Agora ligando de Natal/RN para
-# Mossoró/RN - Mesmo estado
-# >>> 'VC2'
-cnl.buscar_localidade('843315', '4935')
-
-# Ligando de Natal/RN para
-# São Paulo/SP - Outro estado
-# >>> 'VC3'
-cnl.buscar_localidade('113124', '5100')
-
-# Escolhendo outro centro de custo
-# sem reiniciar a classe (apenas essa consulta)
-# Ligando de Mossoró/RN para
-# Parnamirim/RN - Mesmo estado
-# >>> 'VC2'
-cnl.buscar_localidade('843644', '8100', '843315', '4935')
+cnl = OpenCNL('./cnl_anatel.sqlite3')
+cnl.pesquisar_localidade('843211', '8243', as_json=True)
 ```
 
 ## Autor

exemplo.py

@@ -2,34 +2,28 @@
 from datetime import datetime
 from open_cnl.open_cnl import OpenCNL
 
+# Inicializamos a classe que se
+# conecta ao banco de dados
+cnl = OpenCNL('./cnl_anatel.sqlite3')
 
-# Natal/RN - Centro de custo
-cnl = OpenCNL('dist/banco.sqlite3', '843211', '8243')
-
+# Pesquisando por um número de Natal/RN
+print(cnl.pesquisar_localidade('843211', '8243'))
 # Parnamirim/RN - Área conurbada
-# >>> 'VC1'
-print cnl.buscar_localidade('843644', '8100')
-
+print(cnl.pesquisar_localidade('843644', '8100'))
 # Mossoró/RN - Mesmo estado
-# >>> 'VC2'
-print cnl.buscar_localidade('843315', '4768')
-
+print(cnl.pesquisar_localidade('843315', '4768'))
 # São Paulo/SP - Outro estado
-# >>> 'VC3'
-print cnl.buscar_localidade('113124', '5100')
+print(cnl.pesquisar_localidade('113124', '5100'))
 
 def teste(cnl):
     # Parnamirim/RN - Área conurbada
-    # >>> 'VC1'
-    cnl.buscar_localidade('843644', '8100')
+    cnl.pesquisar_localidade('843644', '8100')
 
     # Mossoró/RN - Mesmo estado
-    # >>> 'VC2'
-    cnl.buscar_localidade('843315', '4768')
+    cnl.pesquisar_localidade('843315', '4768')
 
     # São Paulo/SP - Outro estado
-    # >>> 'VC3'
-    cnl.buscar_localidade('113124', '5100')
+    cnl.pesquisar_localidade('113124', '5100')
 
 inicio = datetime.now()
 quantidade = 100

open_cnl/open_cnl.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import io
+import json
 import sqlite3
 
 
@@ -9,62 +10,78 @@ class OpenCNL(object):
     dados da ANATEL gerado pelo OpenCNLImporter.
     """
 
-    def __init__(self, caminho_da_base, prefixo_de_referencia,
-                 sufixo_de_referencia):
+    def __init__(self, caminho_da_base):
         """
         Lê o arquivo da base de um banco SQLite3, previamente importado.
-        Realiza uma pesquisa pelo prefixo de referência e salva o número para
-        futuras comparações (centro de custo), caso ele tenha sido especificado.
         """
         try:
             self.conn = sqlite3.connect(caminho_da_base)
         except Exception:
             raise ErroAoConectarComBancoDeDados
 
-        self.localidade_de_referencia = self._buscar_localidade(
-            prefixo_de_referencia, sufixo_de_referencia)
-
-    def buscar_localidade(self, prefixo, sufixo, prefixo_de_referencia=None,
-                          sufixo_de_referencia=None):
+    def pesquisar_localidade(self, prefixo, sufixo, as_json=False):
         """
-        Procura pelo prefixo de um número na base e retorna a tarifação, que
-        pode ser dos tipos: VC1, VC2 e VC3. Por padrão utiliza o centro de custo
-        definido na inicialização da classe, caso novos prefixo e sufixo não
-        tenham sido definidos.
+        Procura pelo por um número cujo prefixo e o sufixo (com DDD) esteja na
+        base e retorna os resultados encontrados.
         """
-        if not prefixo_de_referencia or not sufixo_de_referencia:
-            # Utilizar localidade de referência especificado na inicialização
-            # da classe.
-            localidade_de_referencia = self.localidade_de_referencia
-        else:
-            # Utilizar localidade de referência especificado na chamada do
-            # método.
-            localidade_de_referencia = self._buscar_localidade(
-                prefixo_de_referencia, sufixo_de_referencia)
-
-        # Buscar localidade para comparação.
-        localidade = self._buscar_localidade(prefixo, sufixo)
-
-        if localidade[5] == localidade_de_referencia[5]:
-            # Código Nacional de Localidade igual em ambas as localidades.
-            return 'VC1'
-        elif localidade[5][0] == localidade_de_referencia[5][0]:
-            # Código Nacional de Localidade diferente entre as localidades, mas
-            # o primeiro dígito é comum às duas.
-            return 'VC2'
-        else:
-            # Código Nacional de Localidade diferente entre as localidades.
-            return 'VC3'
-
-    def _buscar_localidade(self, prefixo, sufixo):
-        """Função de busca auxiliar para prefixo no banco de dados."""
+
+        # Pesquisa a localidade no banco de dados.
+        try:
+            localidade = self._pesquisar_localidade(prefixo, sufixo)
+        except LocalidadeNaoEncontrada:
+            if as_json:
+                # Se a opção estiver ativa, retornar como JSON
+                return json.dumps(None)
+
+            return None
+
+        localidade = dict(
+            sigla_uf=localidade[0],
+            sigla_cnl=localidade[1],
+            codigo_cnl=localidade[2],
+            nome_da_localidade=localidade[3],
+            nome_do_municipio=localidade[4],
+            codigo_da_area_de_tarifacao=localidade[5],
+            prefixo=localidade[6],
+            prestadora=localidade[7],
+            numero_da_faixa_inicial=localidade[8],
+            numero_da_faixa_final=localidade[9],
+            latitude=localidade[10],
+            hemisferio=localidade[11],
+            longitude=localidade[12],
+            sigla_cnl_da_area_local=localidade[13],
+        )
+
+        if as_json:
+            # Se a opção estiver ativa, retornar como JSON
+            return json.dumps(localidade)
+
+        return localidade
+
+    def _pesquisar_localidade(self, prefixo, sufixo):
+        """Função auxiliar para pesquisar número no banco de dados."""
         try:
             c = self.conn.cursor()
             localidade = c.execute("""
-                SELECT * FROM open_cnl
-                WHERE prefixo = ?
-                AND CAST(numero_da_faixa_inicial as INTEGER) <= ?
-                AND CAST(numero_da_faixa_final as INTEGER) >= ?;
+                SELECT
+                    `sigla_uf`,
+                    `sigla_cnl`,
+                    `codigo_cnl`,
+                    `nome_da_localidade`,
+                    `nome_do_municipio`,
+                    `codigo_da_area_de_tarifacao`,
+                    `prefixo`,
+                    `prestadora`,
+                    `numero_da_faixa_inicial`,
+                    `numero_da_faixa_final`,
+                    `latitude`,
+                    `hemisferio`,
+                    `longitude`,
+                    `sigla_cnl_da_area_local`
+                FROM `open_cnl`
+                WHERE `prefixo` = ?
+                AND CAST(`numero_da_faixa_inicial` as INTEGER) <= ?
+                AND CAST(`numero_da_faixa_final` as INTEGER) >= ?;
             """, (prefixo, int(sufixo), int(sufixo))).fetchone()
         except Exception:
             raise ErroAoLerDoBancoDeDados