(#75) Adicionando docstrings.

Co-Authored-By: BlimblimCFT <[email protected]>

.coveragerc

@@ -1,2 +1,2 @@
 [run]
-omit = Certifik8/tests/*,Certifik8/main.py,Certifik8/tests/*,Certifik8/modules/selection/* 
+omit = Certifik8/tests/*,Certifik8/main.py,Certifik8/tests/*,Certifik8/modules/selector/* 

Certifik8/main.py

@@ -8,6 +8,15 @@
 
 
 def run():
+    """
+    Objetivo da classe: controlar o fluxo do programa.
+
+        1. Exibição de menu inicial
+        2. Seleção de tabelas .xlsx para gerar certificados
+        3. Seleção da pasta destino para salvar os certificados
+        4. Chama as funções de geração de certificados
+    """
+
     with open(
         file=path_inicial + "/constants/menu.txt",
         encoding="utf-8",

Certifik8/modules/converter/html2pdf.py

@@ -2,7 +2,28 @@
 
 
 class Html2Pdf:
+    """
+    Uma classe para converter HTML para PDF.
+
+    Atributos:
+        html2pdf (str): Caminho para o arquivo HTML a ser convertido.
+        options (dict): Dicionário de opções para configurar a saída PDF.
+        new_path (str): O novo caminho do arquivo PDF gerado.
+
+    Métodos:
+        convert(output_name, foldername, folder_destino, output_funcao):
+            Converte o arquivo HTML em PDF
+            e o salva no caminho especificado.
+    """
+
     def __init__(self, html):
+        """
+        Construtor da classe Html2Pdf.
+
+        Args:
+            html (str): Caminho para o arquivo HTML a ser convertido.
+        """
+
         self.html2pdf = html
         self.options = {
             "page-size": "A5",
@@ -12,6 +33,18 @@ def __init__(self, html):
         self.new_path = ""
 
     def convert(self, output_name, foldername, folder_destino, output_funcao) -> None:
+        """
+        Converte o arquivo HTML em PDF e o salva no caminho especificado.
+
+        Args:
+            output_name (str): O nome do arquivo PDF de saída.
+            foldername (str): O nome da pasta para salvar o arquivo PDF.
+            folder_destino (str): A pasta de destino para salvar o arquivo PDF.
+            output_funcao (str): A função de saída a ser usada no nome do arquivo.
+
+        Retorna:
+            bool: Verdadeiro se a conversão for bem-sucedida, Falso caso contrário.
+        """
 
         self.new_path = folder_destino + "/" + f"{foldername}" + "/" + output_funcao
         try:
@@ -20,8 +53,6 @@ def convert(self, output_name, foldername, folder_destino, output_funcao) -> Non
                 self.new_path + f"/{output_name}.pdf",
                 options=self.options,
             )
+            return True
         except Exception:
-
             return False
-
-        return True

Certifik8/modules/generator/certificado.py

@@ -7,6 +7,24 @@
 
 
 class Certificados:
+    """
+    Classe responsável por gerar certificados a partir de um template HTML e dados contidos em um data frame.
+
+    Atributos:
+        template (str): HTML que será utilizado como template para geração dos certificados.
+        soup (bs4.BeautifulSoup): Objeto que representa o HTML com os dados de um participante.
+
+    Métodos:
+        substituir_span (str, str):
+            Recebe o nome da classe e o conteúdo a ser inserido no HTML,
+            substitui o primeiro span encontrado com classe igual a
+            `class_name` pelo `content`.
+        gerar_certificados (str, pandas.DataFrame, pandas.DataFrame, str):
+            Recebe o caminho do arquivo CSV, data frames com dados dos participantes
+            e informações do evento, além do caminho de destino dos arquivos PDF gerados,
+            gerando os certificados e salvando-os no caminho especificado.
+    """
+
     def __init__(self):
         with open(
             file=path_inicial + "/constants/template.html",
@@ -16,6 +34,17 @@ def __init__(self):
         self.soup = None
 
     def substituir_span(self, class_name, content):
+        """
+        Substitui o primeiro span encontrado com classe igual a `class_name` pelo `content`.
+
+        Args:
+            class_name (str): Nome da classe do span a ser substituído.
+            content (str): Conteúdo a ser inserido no lugar do span.
+
+        Returns:
+            bool: True caso a substituição tenha sido bem sucedida, False caso contrário.
+        """
+
         try:
             self.soup.find("span", class_=class_name).replace_with(content)
             return True
@@ -25,6 +54,19 @@ def substituir_span(self, class_name, content):
     def gerar_certificados(
         self, filepath, data_frame, data_frame_informacoes, path_destino
     ):
+        """
+        Gera os certificados a partir do template HTML e dados contidos em um data frame.
+
+        Args:
+            filepath (str): Caminho do arquivo CSV com os dados dos participantes.
+            data_frame (pandas.DataFrame): Data frame com os dados dos participantes.
+            data_frame_informacoes (pandas.DataFrame): Data frame com as informações do evento.
+            path_destino (str): Caminho de destino dos arquivos PDF gerados.
+
+        Returns:
+            bool: True caso a geração dos certificados tenha sido bem sucedida, False caso contrário
+        """
+
         for i in tqdm(
             data_frame.index,
             ncols=100,

Certifik8/modules/handler/tabela.py

@@ -5,7 +5,49 @@
 
 
 class Tabela:
+    """
+    Classe utilizada para manipular tabelas em formato .xlsx.
+
+    Atributos:
+        data_frame : pandas.DataFrame
+            Armazena a tabela completa
+        data_frame_informacoes : pandas.DataFrame
+            Armazena a tabela com as informações do evento
+        data_frame_funcao : pandas.DataFrame
+            Armazena a tabela com as funções dos participantes
+        path : str
+            Caminho da tabela de origem
+        path_destino : str
+            Caminho da pasta destino para salvar os certificados
+        foldername : str
+            Nome da pasta que será criada
+
+    Métodos:
+        gerar_pasta_subpastas_cert()
+            Cria a pasta e subpastas para armazenar os certificados
+        set_data_frames(filepath: str) -> bool
+            Carrega a tabela em um objeto pandas.DataFrame
+        separar_tabela(data_frame: pandas.DataFrame)
+            Separa a tabela em informações do evento e funções dos participantes
+        get_data_frame() -> pandas.DataFrame
+            Retorna a tabela completa
+        get_data_frame_informacoes() -> pandas.DataFrame
+            Retorna a tabela com as informações do evento
+        verificar_tab_padrao(folder_destino: str) -> bool
+            Verifica se a tabela é padrão e cria a pasta e subpastas para armazenar os certificados
+    """
+
     def __init__(self):
+        """
+        Construtor da classe Tabela. Inicializa os atributos com valores padrão:
+            data_frame: None
+            data_frame_informacoes: None
+            data_frame_funcao: None
+            path: None
+            path_destino: None
+            foldername: None
+        """
+
         self.data_frame = None
         self.data_frame_informacoes = None
         self.data_frame_funcao = None
@@ -14,6 +56,16 @@ def __init__(self):
         self.foldername = None
 
     def gerar_pasta_subpastas_cert(self):
+        """
+        Cria a pasta e subpastas para armazenar os certificados
+
+            - Cria uma pasta principal com o nome especificado em 'self.foldername'
+                no caminho de destino 'self.path_destino'.
+            - Cria as subpastas com o nome das funções obtido do DataFrame 'self.data_frame_funcao'.
+            - Se a pasta de destino já existe, ela não será recriada.
+            - Em caso de erro de permissão, a execução é interrompida com uma mensagem de erro.
+        """
+
         try:
             if not os.path.exists(self.path_destino + "/" + self.foldername):
                 os.makedirs(self.path_destino + "/" + self.foldername)
@@ -39,6 +91,16 @@ def gerar_pasta_subpastas_cert(self):
             sys.exit()
 
     def set_data_frames(self, filepath):
+        """
+        Carrega a tabela em um objeto pandas.DataFrame
+
+        Parameters:
+            file_path (str): Caminho do arquivo excel.
+
+        Returns:
+            bool: Retorna True em caso de sucesso ou False em caso de erro.
+        """
+
         self.path = filepath
         self.foldername = get_foldername(self.path)
         try:
@@ -62,6 +124,18 @@ def set_data_frames(self, filepath):
             return False
 
     def separar_tabela(self, data_frame):
+        """
+        Divide o dataframe de entrada em duas partes: uma com as informações gerais
+        e outra com as funções. Além disso, remove valores nulos das colunas.
+
+        Args:
+            data_frame (pandas.DataFrame): Dataframe a ser separado em informações e funções
+
+        Atribuições:
+            data_frame_informacoes (pandas.DataFrame): Dataframe com as informações gerais
+            data_frame_funcao (pandas.DataFrame): Dataframe com as funções
+        """
+
         self.data_frame_informacoes = data_frame[["Informações"]].copy()
         self.data_frame_informacoes.dropna(axis=0, how="all", inplace=True)
         self.data_frame.drop(columns=["Informações"], inplace=True)
@@ -70,12 +144,21 @@ def separar_tabela(self, data_frame):
         self.data_frame_funcao.drop_duplicates(keep="first", inplace=True)
 
     def get_data_frame(self):
+        """ Retorna a tabela completa """
         return self.data_frame
 
     def get_data_frame_informacoes(self):
+        """ Retorna a tabela com as informações do evento """
         return self.data_frame_informacoes
 
     def verificar_tab_padrao(self, folder_destino):
+        """
+        Verifica se a tabela é padrão e cria a pasta e subpastas para armazenar os certificados
+
+        Parameters:
+            folder_destino (str): Caminho da pasta de destino, utilizado para criar subpastas.
+        """
+
         self.path_destino = folder_destino
         try:
             # pylint: disable=unused-variable

Certifik8/modules/selector/file_selection.py

@@ -3,10 +3,31 @@
 
 
 class FileSelection:
+    """
+    Classe responsável por selecionar arquivos utilizando o zenity.
+
+    Atributos:
+        command (list): Lista de comandos para o zenity.
+    """
+
     def __init__(self):
+        """
+        Inicializa a classe com o comando para executar o diálogo de seleção de arquivos.
+        """
+
         self.command = ["zenity", "--file-selection", "--multiple"]
 
     def run(self):
+        """
+        Método responsável por rodar o comando do zenity e retornar a lista de nomes de arquivos selecionados.
+
+        Retorna:
+            list: Lista de nomes de arquivos selecionados.
+
+        Lança:
+            Exception: Se ocorrer algum erro inesperado.
+        """
+
         try:
             zenity = subprocess.run(self.command, capture_output=True, check=False)
 

Certifik8/modules/selector/folder_selection.py

@@ -3,10 +3,31 @@
 
 
 class FolderSelection:
+    """
+    Classe responsável por selecionar uma pasta utilizando o zenity.
+
+    Atributos:
+        command (list): Lista de comandos para o zenity.
+    """
+
     def __init__(self):
+        """
+        Inicializa a classe com o comando para executar o diálogo de seleção de pasta.
+        """
+
         self.command = ["zenity", "--file-selection", "--directory"]
 
     def run(self):
+        """
+        Executa o diálogo de seleção de pasta e retorna o caminho da pasta selecionada.
+
+        Returns:
+            str: O caminho da pasta selecionada.
+
+        Raises:
+            Exception: Se ocorrer um erro inesperado durante a execução do diálogo.
+        """
+
         try:
             zenity = subprocess.run(self.command, capture_output=True, check=False)
 

Certifik8/modules/utils.py

@@ -18,15 +18,42 @@
 
 
 def get_data() -> str:
+    """
+    Obtém a data atual formatada como "dd de mês de aaaa".
+
+    Returns:
+        str: Data atual formatada.
+    """
+
     dia = date.today().strftime("%d")
     mes = int(date.today().strftime("%m")) - 1
     ano = date.today().strftime("%Y")
     return f"{dia} de {meses[mes]} de {ano}"
 
 
-def get_foldername(filepath):
+def get_foldername(filepath: str) -> str:
+    """
+    Obtém o nome do diretório a partir do caminho completo do arquivo.
+
+    Args:
+        filepath (str): Caminho completo do arquivo.
+
+    Returns:
+        str: Nome do diretório.
+    """
+
     return filepath.split("/")[-1].split(".")[0]
 
 
-def verificar_xlsx(path):
+def verificar_xlsx(path: str) -> bool:
+    """
+    Verifica se um caminho específico corresponde a um arquivo xlsx válido.
+
+    Args:
+        path (str): Caminho do arquivo.
+
+    Returns:
+        bool: Verdadeiro se o caminho corresponde a um arquivo xlsx, falso caso contrário.
+    """
+
     return os.path.exists(path) and os.path.splitext(path)[1] == ".xlsx"