Added a utils.py get_states_of_brazil

docs/authors.rst

@@ -104,6 +104,7 @@ Authors
 * Paul Cunnane
 * Paul Donohue
 * Paulo Poiati
+* Pedro Henrique Vicente de Sousa
 * Peter J. Farrell
 * Rael Max
 * Ramiro Morales

docs/changelog.rst

@@ -11,6 +11,8 @@ New flavors:
 New fields for existing flavors:
 
 - Added CIN Number field in Morocco flavor (`gh-705 <https://github.com/django/django-localflavor/pull/507>`_).
+- Added get_states_of_brazil to br.utils to return a state or all available options with some settings
+  (`gh-510 <https://github.com/django/django-localflavor/pull/510>`_).
 
 Modifications to existing flavors:
 

localflavor/br/utils.py

@@ -0,0 +1,31 @@
+from .br_states import STATE_CHOICES
+
+
+def get_states_of_brazil(federative_unit=None, capital_letter=False):
+    """
+    Return a state of Brazil or available options
+
+    Parametes:
+    federative_unit (Any, optional): The Federative Unit. If not provided, defaults to None.
+    capital_letter (bool, optional): A boolean flag to return the state with capital letter. Defaults to False
+
+    returns:
+    Union[str, dict]:
+        - If federative_unit not is None and his value is valid, returns a string
+        - If federative_unit is None, returns a dictionary
+        - If capital_letter is True, returns all values with capital letters
+    """
+
+    state_choices_available = {
+        acronym: state.upper() if capital_letter else state for acronym, state in STATE_CHOICES
+    }
+
+    if federative_unit is None:
+        return state_choices_available
+
+    federative_unit = federative_unit.upper() if isinstance(federative_unit, str) else ""
+
+    if federative_unit in state_choices_available:
+        return state_choices_available[federative_unit]
+
+    return state_choices_available

tests/test_br/test_br.py

@@ -3,6 +3,7 @@
 from localflavor.br import models
 from localflavor.br.forms import (BRCNPJField, BRCPFField, BRProcessoField, BRStateChoiceField, BRStateSelect,
                                   BRZipCodeField)
+from localflavor.br.utils import get_states_of_brazil
 from tests.test_br.forms import BRPersonProfileForm
 
 
@@ -250,3 +251,35 @@ def test_BRPostalCodeField(self):
         self.assertEqual(instance.max_length, new_instance.max_length)
         self.assertEqual(instance.description, new_instance.description)
         self.assertEqual(instance.validators, new_instance.validators)
+
+
+class GetStatesOfBrazil(SimpleTestCase):
+
+    ALL_EXPECTED_STATES = dict
+
+    def test_get_valid_state(self):
+        federative_unit = "pb"
+        state_of_brazil = get_states_of_brazil(federative_unit=federative_unit)
+        expected_value = "Paraíba"
+
+        self.assertEqual(state_of_brazil, expected_value)
+
+    def test_get_return_all_states_dict(self):
+        states_of_brazil_capital_letter = get_states_of_brazil(capital_letter=True)
+        states_of_brazil_without_capital_letter = get_states_of_brazil()
+
+        self.assertEqual(
+            type(states_of_brazil_capital_letter),
+            self.ALL_EXPECTED_STATES
+        )
+        self.assertEqual(
+            type(states_of_brazil_without_capital_letter),
+            self.ALL_EXPECTED_STATES
+        )
+
+    def test_federative_unit_invalid(self):
+        invalid_inputs = [1, 1.0, "None", [None]]
+
+        for invalid_input in invalid_inputs:
+            result = get_states_of_brazil(invalid_input)
+            self.assertIsInstance(result, self.ALL_EXPECTED_STATES)