Final push

Author: zeval

.vscode/settings.json

@@ -1,4 +1,4 @@
 {
-    "python.pythonPath": "/bin/python3",
+    "python.pythonPath": "C:\\Users\\Miguel Lages\\AppData\\Local\\Programs\\Python\\Python38-32\\python.exe",
     "discord.enabled": true
 }

v2/README.txt

@@ -1,28 +1,54 @@
-Grupo 22 - Novembro/2020
+Grupo 22 - Dezembro/2020
 
 55373 - José Almeida
 55371 - Augusto Gouveia
 54975 - Miguel Lages
 
 Funcionalidades:
 
-• Suporta duas versões de paralelismo: multiprocessing (pgrepwc.py) e multithreading (pgrepwc_threads.py).
+[pgrepwc.py]: 
 
-		- O uso do pacote multiprocessing neste projeto permite-nos certificar que este funciona de maneira igualmente eficiente em Linux e Windows (algo impossibilitado pelo uso de os.fork(), visto que este não funciona em Windows).
+• Utilização: pgrepwc [-c|-l] [-p n] [-a s] [-f file] [-h] palavra <ficheiros>
 
-• Realçamento dos números das linhas a verde e das correspondências a vermelho, em ambas versões do programa (disponível em ambos Linux e Windows).
+• Opção "-h" que permite esconder o output.
 
-• Uso de mecanismos de exclusão mútua (mutex lock) para assegurar que não se dão problemas de sincronização (e.g. escrita simultânea na mesma variável por parte de processos/threads diferentes) e que a exposição dos resultados por parte dos processos/threads se dá de maneira intercalada.
+• Uso de mecanismos de memória partilhada para comunicar resultados de pesquisas/contagens ao
+processo pai por parte dos processos-filho.
 
-• Uso de expressões regulares para encontrar correspondências exatas da palavra especi-
-ficada em situações que esta esteja isolada.
+• Suporta paralelismo: multiprocessing.
 
-• Estrutura robusta que permite aceder aos ficheiros-alvo sem ter que os carregar diretamente para a memória (especialmente útil para ficheiros de maiores dimensões).
+• Realçamento dos números das linhas a verde e das correspondências a vermelho.
 
-• Programação defensiva que permite que o programa não falhe quando um dos ficheiros referidos não é encontrado. Inclui também prevenção de repetição de procura em ficheiros, descartando ficheiros repetidos que possam ter sido introduzidos pelo utilizador.
+• Uso de mecanismos de exclusão mútua (mutex lock) para assegurar que não se dão problemas de
+sincronização (ex. escrita simultânea na mesma variável por parte de processos/threads diferentes)
+e que a exposição dos resultados por parte dos processos/threads se dá de maneira intercalada.
 
-• [pgrepwc.py] -> Uso de mecanismos de memória partilhada para comunicar resultados de pesquisas/contagens ao processo pai por parte dos processos-filho.
+• Uso de expressões regulares para encontrar correspondências exatas da palavra especificada em
+situações que esta se encontre isolada.
+
+• Estrutura robusta que permite aceder aos ficheiros-alvo sem ter que os carregar diretamente para
+a memória (especialmente útil para ficheiros de maiores dimensões).
+
+• Programação defensiva que permite que o programa não falhe quando um dos ficheiros referidos não
+é encontrado. Inclui também prevenção de repetição de procura em ficheiros, descartando ficheiros
+repetidos que possam ter sido introduzidos pelo utilizador.
 
 • Leitura de nomes dos ficheiros-alvo através de stdin ou como argumento.
 
+• Processamento seguro do sinal SIGINT: ao ser recebido o sinal SIGINT, é necessária confirmação
+para que o programa termine o processamento, de modo a evitar acidentes. Ao ser recebida
+confirmação, a paragem de processamento é efectuada de maneira segura e não abrupta, assegurando-se
+que todos os dados recolhidos até ao momento são corretamente apresentados e possivelmente
+guardados (opção "-f").
+
+• Código detalhadamente documentado.
+
+[hpgrepwc.py]: 
+
+• Utilização: hpgrepwc <ficheiro>
+
+• Realçamento de dados considerados mais importantes a verde, há excepção de quando o total de
+bytes processado não corresponde a 100% (neste caso a percentagem do total de bytes processado
+apresenta-se realçada a vermelho).
+
 • Código detalhadamente documentado.

v2/hpgrepwc.py

@@ -35,11 +35,11 @@
 def main(argv):
 
     try:
-        # Obter nome do ficheiro
+        # Obter nome do ficheiro.
         file = argv[0]
 
     except:
-        # Mensagem de ajuda caso o comando seja malformado
+        # Mensagem de ajuda caso o comando seja mal formado.
         print("Utilização: hpgrepwc <ficheiro>")
         sys.exit(2)
 
@@ -48,25 +48,37 @@ def main(argv):
         with open(file, "rb") as f:
             data = pickle.load(f)
 
-    except FileNotFoundError as e:
-        print(f"Ficheiro '{file}' não encontrado. Verifique o seu input.")
+    except:
+        print(f"Ficheiro '{file}' não encontrado ou inválido. Verifique o seu input.")
         sys.exit(2)
 
-    ### Leitura dos dados e envio para stdout 
+    ### Leitura dos dados e envio para stdout.
 
     output = []
 
+    # Obtenção de dados a partir do tuplo de dados no ficheiro binário.
     startDateStamp = data[START_DATE_STAMP]
     duration = data[DURATION]
     processData = data[PROCESS_DATA]
     opts = data[OPTS]
     word = data[WORD]
     haltValue = data[HALT_VALUE]
 
+
+    # Adicionar campos ao output.
     output.append(f"\nPalavra a pesquisar: {colorWrite(word, 'red')}")
     output.append(f"Início da execução: {colorWrite(dt.strftime(startDateStamp, '%d/%m/%Y, %H:%M:%S.%f'), 'green')}")
     output.append(f"Duração da execução: {colorWrite(timedelta(seconds = duration), 'green')}")
 
+
+    
+    # Organização de dados: passagem e um dicionário partilhado de estrutura
+    # orientada a processos, para um dicionário bi-dimensional local de estrutura 
+    # organizada por PROCESSOS -> FICHEIROS, em que a chave de primeira dimensão
+    # é referente ao processo e de segunda dimensão é referente ao ficheiro. 
+    # Esta estrutura mais organizada permite-nos saber com quanto de cada ficheiro 
+    # é que cada processo lidou.
+
     sortedProcessData = dict()
 
     for process in processData:
@@ -77,54 +89,82 @@ def main(argv):
                 sortedProcessData[process][loadData[LOAD].getFile()] = []
             sortedProcessData[process][loadData[LOAD].getFile()].append(loadData)
 
+    # Obtenção dos vários nomes de ficheiros numa lista de valores únicos.
     files = set([processedFile for processedFile in getNested(sortedProcessData, process) for process in sortedProcessData])
+
+    # Transformação de todos esses nomes na sua respetiva versão colorida.
     files = [colorWrite(argFile, 'green') for argFile in files]
 
+    # Adicionar campos ao output.
     output.append(f"Ficheiros em argumento: " + ",\n                        ".join(files))
 
+    # Inicialização de variáveis importantes ao resto do processo.
     fileSizes = {}
     totalProcessed = 0
     totalLC = 0
     totalWC = 0
 
+
     for process in sortedProcessData:
+        
         output.append(f"\nProcesso: {colorWrite(process, 'green')}")
+
+        # Uso da função getNested para aceder à primeira dimensão do dicionário sortedProcessData
+        # e obter os nomes dos vários ficheiros com os quais o processo lidou.
         files = getNested(sortedProcessData, process)
 
+
         for file in files:
+            # Uso da função getNested para aceder à segunda dimensão do dicionário sortedProcessData
+            # e obter informação sobre o processamento do atual ficheiro por parte do atual processo.
             fileData = getNested(sortedProcessData, process, file)
 
             output.append(f"    Ficheiro: {colorWrite(file, 'green')}")
+
+            # Cálculo do tempo total demorado para o processo lidar com o ficheiro atual.
             timeSum = sum([loadData[TIME_TAKEN] for loadData in fileData])
+
             fileSize = fileData[0][SIZE]
+
+            # Cálculo do total de bytes do ficheiro com o qual o processo atual lidou
+            # e cálculo da respetiva percentagem relativamente ao tamanho total do ficheiro
+            # em questão.
             searchSum = sum([loadData[LOAD].getBytesToHandle() for loadData in fileData])
             searchPercentage = (str(round((searchSum/fileSize)*100, 1)) + "%").replace(".0", "")
 
+
+            # Incrementação do total de bytes analisado.
+            totalProcessed += searchSum
+
+            # Organização de dados: dicionário utilizado para registar o tamanho de cada
+            # ficheiro referenciado.
             if file not in fileSizes:
                 fileSizes[file] = fileSize
-            totalProcessed += searchSum
+
 
             allLines = []
             fileWC = 0
 
+
+            # Criação de lista que inclui os números de todas as linhas com ocorrências
+            # (útil para saber o total de linhas com ocorrências encontradas neste ficheiro).
             for loadData in fileData:
                 for match in loadData[LOAD_MATCHES]:
                     allLines.append(match.getLineNumber())
                     fileWC += match.getAmount()
-                    
-
             fileLC = len(set(allLines))
 
+
+            # Incrementação do total de bytes analisado.
             totalWC += fileWC
             totalLC += fileLC
-            
 
-
-            # print(getNested(sortedProcessData, process, file))
+            # Adicionar campos ao output.
             output.append(f"        Tempo de pesquisa: {colorWrite(timedelta(seconds= timeSum), 'green')}")
             output.append(f"        Dimensão do ficheiro: {colorWrite(fileSize, 'green')} bytes")
             output.append(f"        Dimensão processada: {colorWrite(searchSum, 'green')} bytes ({colorWrite(searchPercentage, 'green')})")
 
+            # Imprimir output consoante a presença de opções nos argumentos do utilizador.
             if any("-c" in opt for opt in opts):
                 output.append(f"        Total de ocorrências: {colorWrite(fileWC, 'green')}")
 
@@ -133,19 +173,27 @@ def main(argv):
 
     output.append("")
 
+
+    # Cálculo da soma do tamanho do agregado de ficheiros e respetiva percentagem
+    # relativamente ao total de bytes analisado.
     totalSize = sum([fileSizes[file] for file in fileSizes])
     totalPercentage = str(round((totalProcessed/totalSize)*100, 1)).replace(".0", "")
     totalPercentageString = colorWrite(str(totalPercentage) + "%", 'green') if totalPercentage == "100" else colorWrite(str(totalPercentage) +"%", 'red')
 
+
+    # Imprimir output consoante a presença de opções nos argumentos do utilizador.
     if any("-c" in opt for opt in opts):
         output.append(f"Total de ocorrências: {colorWrite(totalWC, 'green')}")
 
     if any("-l" in opt for opt in opts):
         output.append(f"Total de linhas com ocorrências: {colorWrite(totalLC, 'green')}")
 
+
+    # Adicionar campos ao output.
     output.append(f"Total de bytes: {colorWrite(totalSize, 'green')}")
     output.append(f"Total de bytes processado: {colorWrite(totalProcessed, 'green')} ({totalPercentageString})")
 
+    # Imprimir a flag "[PARAGEM FORÇADA]" caso o utilizador tenha forçado a paragem via sinal SIGINT.
     if haltValue == 2:
         output.append(colorWrite("[PARAGEM FORÇADA]", "red"))
 
@@ -155,9 +203,13 @@ def main(argv):
         print(line)
 
 
-
-
 def colorWrite(text, color):
+    """
+    Devolve o texto recebido na cor especificada.
+    Requires: text é um string e color é 'green' ou 'red'.
+    Ensures: text rodeado pelos códigos de cor referentes à 
+    cor especificada.
+    """
     if color == "green":
         return GREEN_START + str(text) + COLOR_END
 
@@ -166,6 +218,10 @@ def colorWrite(text, color):
 
 
 def getNested(data, *args):
+    """
+    Permite aceder a dicionários ninhados (várias dimensões).
+    Requires: data é um dicionário e args são chaves dos dicionários internos.
+    """
     if args and data:
         element  = args[0]
         if element:
@@ -176,12 +232,11 @@ def getNested(data, *args):
 ### CLASSES (O enunciado explicitamente limita a existência de ficheiros ".py"
 #   a um máximo de 2. Desta forma, incluímos as classes necessárias ao funcionamento
 #   do programa no ficheiro pgrepwc e no ficheiro hpgrepwc separadamente para que estes
-#   possam funcionar indepentendemente um do outro.)
-
+#   possam funcionar indepentendemente um do outro).
 
 class Load:
     """
-    TODO: Comentar
+    Alberga dados sobre carga referente a um processo.
     """
     def __init__(self, file, offset, bytesToHandle):
         self._file = file
@@ -190,20 +245,32 @@ def __init__(self, file, offset, bytesToHandle):
         self._end = offset + bytesToHandle - 1
 
     def getFile(self):
+        """
+        Obtém o ficheiro onde vai correr a pesquisa.
+        """
         return self._file
 
     def getOffset(self):
+        """
+        Obtém a posição inicial onde vai começar a ser corrida a pesquisa.
+        """
         return self._offset
 
     def getBytesToHandle(self):
+        """
+        Obtém o número de bytes a pesquisar.
+        """
         return self._bytesToHandle
 
     def getEnd(self):
+        """
+        Obtém a posição de fim da execução.
+        """
         return self._end
 
 class Match:
     """
-    TODO: Comentar
+    Alberga dados sobre uma linha que contenha ocorrências de uma palavra.
     """
     def __init__(self, file, lineNumber, lineContent, amount):
         self._lineNumber = lineNumber
@@ -212,17 +279,29 @@ def __init__(self, file, lineNumber, lineContent, amount):
         self._amount = amount
 
     def getLineNumber(self):
+        """
+        Obtém o número da linha onde a(s) ocorrência(s) foi/foram encontrada(s).
+        """
         return self._lineNumber
 
     def getLineContent(self):
+        """
+        Obtém o conteúdo correspondente à linha onde a(s) ocorrência(s) foi/foram encontrada(s).
+        """
         return self._lineContent
 
     def getFile(self):
+        """
+        Obtém o ficheiro onde a(s) ocorrência(s) foi/foram encontrada(s).
+        """
         return self._file
 
     def getAmount(self):
+        """
+        Obtém o número de ocorrência(s) que se repete(m) ao longo da linha.
+        """
         return self._amount
 
-
+# Invocação de main
 if __name__ == "__main__":
     main(sys.argv[1:])