Merge branch '394' of github.com:BeneBr/brutils-python into 394

.github/workflows/comment-commands.yml

@@ -0,0 +1,29 @@
+name: Comandos nos comentários
+on:
+  issue_comment:
+    types: created
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  issue_assign:
+    runs-on: ubuntu-22.04
+    if: (!github.event.issue.pull_request) && github.event.comment.body == 'bora!'
+    concurrency:
+      group: ${{ github.actor }}-issue-assign
+    steps:
+      - run: |
+          echo "Issue ${{ github.event.issue.number }} atribuida a ${{ github.event.comment.user.login }}"
+          echo "Verifique [o guia de contribuição](https://github.com/brazilian-utils/brutils-python/blob/main/CONTRIBUTING.md) para mais informações sobre como submeter sua Pull Request."
+          curl -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" -d '{"assignees": ["${{ github.event.comment.user.login }}"]}' https://api.github.com/repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/assignees
+
+      - name: Create or Update Comment
+        uses: peter-evans/[email protected]
+        with:
+          issue-number: ${{ github.event.issue.number }}
+          body: |
+            Issue ${{ github.event.issue.number }} atribuida a ${{ github.event.comment.user.login }} :rocket:"
+            "Verifique [o guia de contribuição](https://github.com/brazilian-utils/brutils-python/blob/main/CONTRIBUTING.md) para mais informações sobre como submeter sua Pull Request."

.github/workflows/run-tests.yml

@@ -18,7 +18,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Generate Report
         run: |
-          pip install coverage
+          pip install coverage num2words
           coverage run -m unittest discover tests/
       - name: Upload Coverage to Codecov
         uses: codecov/codecov-action@v4

CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+
+- Utilitário `convert_code_to_uf` [#397](https://github.com/brazilian-utils/brutils-python/pull/410)
 
 ## [2.2.0] - 2024-09-12
 

CONTRIBUTING.md

@@ -35,11 +35,7 @@ Caso não tenha uma conta, siga os passos de [como criar de uma conta pessoal no
 Visite a [página de issues do brutils][brutils-issues] e encontre uma issue com a qual você gostaria
 de trabalhar e que ainda não tenha sido atribuída a ninguém.
 
-Deixe um comentário na issue perguntando se você pode trabalhar nela. Algo como: "Olá, posso
-trabalhar nessa issue?".
-
-Aguarde até que alguém atribua a issue a você. Uma vez atribuída, você pode prosseguir para a próxima
-etapa.
+Deixe um comentário na issue com conteúdo "bora!" Em seguida, um bot vai atribuir a issue a você. Uma vez atribuída, você pode prosseguir para a próxima etapa.
 
 Sinta-se à vontade para fazer qualquer pergunta na página da issue antes ou durante o processo de
 desenvolvimento.

CONTRIBUTING_EN.md

@@ -32,9 +32,7 @@ Make sure you have a [GitHub account][github-join] and you are logged in with it
 Visit the [brutils issues page][brutils-issues] and find an issue you would like to work with
 and no one assigned to it yet.
 
-Send a comment in the issue asking to work with it. Something like: "hey, can I work on this?".
-
-Wait until someone assign you to the ticket. Once you are assigned to it, you can move to the next
+Send a comment in the issue with the content "bora!" This will trigger a bot that will assign you to the ticket. Once you are assigned to it, you can move to the next
 step.
 
 Please, feel free to ask any questions in the issue's page before or during the development

README.md

@@ -89,6 +89,8 @@ False
   - [is_valid_voter_id](#is_valid_voter_id)
   - [format_voter_id](#format_voter_id)
   - [generate_voter_id](#generate_voter_id)
+- [IBGE](#ibge)
+  - [convert_code_to_uf](#convert_code_to_uf)
 
 ## CPF
 
@@ -1113,6 +1115,29 @@ Exemplo:
 '950125640248'
 ```
 
+## IBGE
+### convert_code_to_uf
+Converte um determinado código do IBGE (string de 2 dígitos) para sua UF (abreviatura estadual) correspondente.
+
+Args:
+  * code (str): O código IBGE de 2 dígitos a ser convertido.
+
+Retorna:
+  * str or None: O código UF correspondente ao código IBGE, ou None se o
+                 código IBGE for inválido.
+
+Exemplo:
+
+```python
+>>> from brutils.ibge.uf import convert_code_to_uf
+>>> convert_code_to_uf("12")
+'AC'
+>>> convert_code_to_uf("33")
+'RJ'
+>>> convert_code_to_uf("99")
+>>>
+```
+
 
 # Novos Utilitários e Reportar Bugs
 

README_EN.md

@@ -87,6 +87,8 @@ False
   - [is_valid_voter_id](#is_valid_voter_id)
   - [format_voter_id](#format_voter_id)
   - [generate_voter_id](#generate_voter_id)
+- [IBGE](#ibge)
+  - [convert_code_to_uf](#convert_code_to_uf)
 
 ## CPF
 
@@ -1087,6 +1089,29 @@ Example:
 '950125640248'
 ```
 
+## IBGE
+### convert_code_to_uf
+Converts a given IBGE code (2-digit string) to its corresponding UF (state abbreviation).
+
+Args:
+  * code (str): The 2-digit IBGE code to be converted.
+
+Retorna:
+  * str or None: The UF code corresponding to the IBGE code, or None if the
+                 IBGE code is invalid.
+
+Exemplo:
+
+```python
+>>> from brutils.ibge.uf import convert_code_to_uf
+>>> convert_code_to_uf("12")
+'AC'
+>>> convert_code_to_uf("33")
+'RJ'
+>>> convert_code_to_uf("99")
+>>>
+```
+
 # Feature Request and Bug Report
 
 If you want to suggest new features or report bugs, simply create

brutils/__init__.py

@@ -48,6 +48,11 @@
 # Email Import
 from brutils.email import is_valid as is_valid_email
 
+# IBGE Imports
+from brutils.ibge.uf import (
+    convert_code_to_uf,
+)
+
 # Legal Process Imports
 from brutils.legal_process import (
     format_legal_process,
@@ -170,4 +175,6 @@
     "format_voter_id",
     "generate_voter_id",
     "is_valid_voter_id",
+    # IBGE
+    "convert_code_to_uf",
 ]

brutils/data/enums/__init__.py

@@ -1 +1 @@
-from .uf import UF
+from .uf import CODE_TO_UF, UF

brutils/data/enums/uf.py

@@ -29,3 +29,33 @@ class UF(BetterEnum):
     SP = "São Paulo"
     SE = "Sergipe"
     TO = "Tocantins"
+
+
+class CODE_TO_UF(BetterEnum):
+    AC = "12"
+    AL = "27"
+    AP = "16"
+    AM = "13"
+    BA = "29"
+    CE = "23"
+    DF = "53"
+    ES = "32"
+    GO = "52"
+    MA = "21"
+    MT = "51"
+    MS = "52"
+    MG = "31"
+    PA = "15"
+    PB = "25"
+    PR = "41"
+    PE = "26"
+    PI = "22"
+    RJ = "33"
+    RN = "24"
+    RS = "43"
+    RO = "11"
+    RR = "14"
+    SC = "42"
+    SP = "35"
+    SE = "28"
+    TO = "17"

brutils/ibge/uf.py

@@ -0,0 +1,32 @@
+from brutils.data.enums.uf import CODE_TO_UF
+
+
+def convert_code_to_uf(code):  # type: (str) -> str | None
+    """
+    Converts a given IBGE code (2-digit string) to its corresponding UF (state abbreviation).
+
+    This function takes a 2-digit IBGE code and returns the corresponding UF code.
+    It handles all Brazilian states and the Federal District.
+
+    Args:
+        code (str): The 2-digit IBGE code to be converted.
+
+    Returns:
+        str or None: The UF code corresponding to the IBGE code,
+            or None if the IBGE code is invalid.
+
+    Example:
+        >>> convert_code_to_uf('12')
+        'AC'
+        >>> convert_code_to_uf('33')
+        'RJ'
+        >>> convert_code_to_uf('99')
+        >>>
+    """
+
+    result = None
+
+    if code in CODE_TO_UF.values:
+        result = CODE_TO_UF(code).name
+
+    return result

tests/ibge/test_uf.py

@@ -0,0 +1,18 @@
+from unittest import TestCase
+
+from brutils.ibge.uf import convert_code_to_uf
+
+
+class TestUF(TestCase):
+    def test_convert_code_to_uf(self):
+        # Testes para códigos válidos
+        self.assertEqual(convert_code_to_uf("12"), "AC")
+        self.assertEqual(convert_code_to_uf("33"), "RJ")
+        self.assertEqual(convert_code_to_uf("31"), "MG")
+        self.assertEqual(convert_code_to_uf("52"), "GO")
+
+        # Testes para códigos inválidos
+        self.assertIsNone(convert_code_to_uf("99"))
+        self.assertIsNone(convert_code_to_uf("00"))
+        self.assertIsNone(convert_code_to_uf(""))
+        self.assertIsNone(convert_code_to_uf("AB"))