diff --git a/docs/authors.rst b/docs/authors.rst index b892b68c..3fb9468e 100644 --- a/docs/authors.rst +++ b/docs/authors.rst @@ -107,6 +107,7 @@ Authors * Paul Cunnane * Paul Donohue * Paulo Poiati +* Pedro Henrique Vicente de Sousa * Peter J. Farrell * Rael Max * Ramiro Morales diff --git a/docs/changelog.rst b/docs/changelog.rst index b2c6de40..27d61311 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -10,6 +10,9 @@ New flavors: New fields for existing flavors: +- Added `get_state_name_from_state_abbreviation` and `STATE_CHOICES_DICT` to ``localflavor.br.utils``. + The new utility returns the full Brazilian state name from a UF abbreviation, or ``None`` for invalid inputs + (`gh-510 `_). - Added CIN Number field in Morocco flavor (`gh-705 `_). diff --git a/localflavor/br/utils.py b/localflavor/br/utils.py new file mode 100644 index 00000000..cb65d79d --- /dev/null +++ b/localflavor/br/utils.py @@ -0,0 +1,24 @@ +from .br_states import STATE_CHOICES + +# Mapping UF -> full state name +STATE_CHOICES_DICT = dict(STATE_CHOICES) + +def get_state_name_from_state_abbreviation(abbreviation=None): + """ + Given a Brazilian state abbreviation (UF), return the full state name. + + Returns: + str | None: + - The full state name if the abbreviation exists + - None if the abbreviation is invalid + + Example: + get_state_name_from_state_abbreviation("RJ") -> "Rio de Janeiro" + get_state_name_from_state_abbreviation("sp") -> "São Paulo" + get_state_name_from_state_abbreviation("XX") -> None + get_state_name_from_state_abbreviation() -> None + """ + if not isinstance(abbreviation, str): + return None + + return STATE_CHOICES_DICT.get(abbreviation.upper()) diff --git a/tests/test_br/test_br.py b/tests/test_br/test_br.py index 44067cd4..6f14213f 100644 --- a/tests/test_br/test_br.py +++ b/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_state_name_from_state_abbreviation from tests.test_br.forms import BRPersonProfileForm @@ -281,3 +282,26 @@ 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 GetStateNameFromAbbreviationTests(SimpleTestCase): + + def test_valid_state_abbreviation(self): + self.assertEqual( + get_state_name_from_state_abbreviation("pb"), + "Paraíba" + ) + self.assertEqual( + get_state_name_from_state_abbreviation("RJ"), + "Rio de Janeiro" + ) + + def test_invalid_state_abbreviation(self): + self.assertIsNone(get_state_name_from_state_abbreviation("XX")) + self.assertIsNone(get_state_name_from_state_abbreviation("None")) + + def test_non_string_input(self): + self.assertIsNone(get_state_name_from_state_abbreviation(123)) + self.assertIsNone(get_state_name_from_state_abbreviation(1.5)) + self.assertIsNone(get_state_name_from_state_abbreviation(None)) + self.assertIsNone(get_state_name_from_state_abbreviation([None]))