Retornar Município e UF a partir do Código IBGE

[camilamaia]

Seu pedido de recurso está relacionado a um problema? Por favor, descreva.

Dado um código de município do IBGE em formato de string, quero obter uma tupla com o nome do município e a UF correspondente.

Por exemplo, ao passar o código "3550308", a função deve retornar ("São Paulo", "SP").

Descreva a solução que você gostaria

• Uma função get_municipality_by_code, que recebe um código de município (string) e retorna uma tupla com o nome do município e a UF correspondente.
• A função deve verificar a validade do código, ou seja, se ele existe na base de dados do IBGE.
• Para códigos inválidos, a função deve retornar None.
• A função pode usar uma base de dados local contendo os códigos, municípios e UFs ou consultar uma API externa que forneça essa informação.
• A saída deve ser formatada como: ("Município", "UF"). Exemplo: ("São Paulo", "SP").
• Um enum das UFs e seus nomes completos já existe no arquivo brutils/data/enums/uf.py. Ele deve ser reutilizado.

Descreva alternativas que você considerou

1. Seguir até o passo 8 do guia de contribuição.

2. Como parte do passo 8, criar o arquivo: brutils-python/brutils/ibge/municipality.py.

   def get_municipality_by_code(code): # type: (str) -> (str, str) | None
       """
       Returns the municipality name and UF for a given IBGE code.
   
       This function takes a string representing an IBGE municipality code 
       and returns a tuple with the municipality's name and its corresponding UF.
   
       Args:
           code (str): The IBGE code of the municipality.
   
       Returns:
           tuple: A tuple formatted as ("Município", "UF").
               - Returns None if the code is not valid.
   
       Example:
           >>> get_municipality_by_code("3550308")
           ("São Paulo", "SP")
       """
       # Implementar a lógica para recuperar o município e a UF pelo código do IBGE
   

   Importar a nova função no arquivo brutils-python/brutils/__init__.py

   # IBGE Imports    
   from brutils.ibge.municipality import (
       get_municipality_by_code,
   )
   

   E adicionar o nome da nova função na lista __all__ do mesmo arquivo brutils-python/brutils/__init__.py:

   __all__ = [
       ...
       # IBGE
       get_municipality_by_code
   ]
   

3. Como parte do passo 9, criar o arquivo de teste: brutils-python/tests/ibge/municipality.py.

   from unittest import TestCase
   from brutils.ibge.municipality import get_municipality_by_code
   
   class TestIBGE(TestCase):
       def test_get_municipality_by_code(self):
           self.assertEqual(get_municipality_by_code("3550308"), ("São Paulo", "SP"))
           self.assertEqual(get_municipality_by_code("3304557"), ("Rio de Janeiro", "RJ"))
           self.assertEqual(get_municipality_by_code("5208707"), ("Goiânia", "GO"))
           self.assertIsNone(get_municipality_by_code("1234567"))
   
           # implementar mais casos de teste aqui se necessário
   

4. Seguir os passos seguintes do guia de contribuição.

Contexto adicional

• A função deve ser capaz de validar se o código IBGE está correto e se corresponde a um município existente.
• O código IBGE deve ser passado como uma string de sete dígitos.
• Referência de códigos IBGE: https://www.ibge.gov.br/explica/codigos-dos-municipios.php

[jaimenunes]

Olá, posso trabalhar nessa issue?

[camilamaia]

Feito! @jaimenunes