Kundenanpassungen ======================================================================================================================== Kundenanpassungen können auf verschiedenen Ebenen in der Programmiersprache Python relativ einfach durchgeführt werden. Dazu wurden viele Schnittstellen geschaffen, um eine einfache Erweiterung von NCDiff zu ermöglichen. Zuerst ist es nötig einen Überblick über den Aufbau von NCDiff zu geben. Aufbau von NCDiff ------------------------------------------------------------------------------------------------------------------------ Nach dem auspacken von NCDiff-X.Y.zip liegt folgende Verzeichnisstruktur unterhalb von NCDiff-X.Y.zip vor: * doc - Dokumentation zu NCDiff * guide - NCDiff Benutzerhandbuch * examples - Beispiele für NCDiff * data - Dateien für den alt vs. neu Vergleich * new - „ALT“ Report Dateien * old - „NEU“ Report Dateien * results - Verzeichnis für die diff Ergebnisse * libs - Python Bibliotheken von NCDiff * extensions - Ort für Kundenerweiterungen * ncdiff - Standardmodule von NCDiff * .... - verschiedene 3rd Party Python Module * python - Windows Portable Python Installation * resources - Verzeichnis für Ressourcen zur Ergebnisdarstellung * html - Ressourcen für das HTML Diff Ergebnis * css - Stylesheets * font - Schriftarten * img - Bilder * js - JavaScript * gui - GUI Icons und Konfigurationsdatei * templates - Templates für das Diff Ergebnis, z.B.: Excel, ResultFilter Python Module in libs/ncdiff ------------------------------------------------------------------------------------------------------------------------ comparator Dieses Modul führt den aktuellen Zellvergleich mit Differenzbildung für unterschiedliche Datentypen durch. Verwendet den Converter um die Zellwerte umzuwandeln. configuration Enthält einen Parser für Konfigurationsdateien und erstellt Konfigurationsobjekte für Diff Targets (TargetConfiguration). Jede TargetConfiguration beinhaltet die gesamte Konfigurationsinformation die nötig ist um ein Target zu diffen. constants Konstanten für alle NCDiff Standardmodule. constraint Enthält Constraint Klassen welche Constraint Funktionen implementieren die sich in der Constraint Sprache verwenden lassen. Die Constraint Sprache wird bei Row Filter, Result Filter und bei der Definition von Toleranzen die vom Inhalt einer anderen Spalte abhängen verwendet. constraint_translator Dieses Modul übersetzt die Ausdrücke aus der Constraint Sprache in ausführbaren Python Code. converter Um effektiv Differenzen bilden zu können, ist es nötig die Zell Werte von Text in andere Datentypen (Zahlen, Datum, …) umzuwandeln. Dieses Modul enthält Implementierungen, die sich in oldColumnFormats/newColumnFormats Konfigurationseinträgen angeben lassen. diff_value Enthält die Klassen welche die Ergebnisse eines diffs representieren. differ Der Differ verarbeitet die sortierten Dateien um einen Zeilenvergleich durchzuführen und übermittelt den Writern die gefunden Unterschiede. Verwendet den Comparator für den Zellvergleich. history Code des ``ncdiff-history`` Tools zum visualisieren der zeitlichen Entwicklung von Vergleichen. launcher Code des ``ncdiff-launcher`` Tools zum starten vom NCDiff vergleichen. licenses Der Lizenztext von NCDiff und 3rd Party Modulen. main Beinhaltet das Hauptprogramm. Dieses Modul wird vom Befehlsskript ``ncdiff`` geladen und aufgerufen. postprocessing Code der nach der Verarbeitung von NCDiff aufgerufen wird. Enthält hauptsächlich die Erweiterungspunkte um Kunden-Code auszuführen. preprocessing Code der vor der Verarbeitung von NCDiff aufgerufen wird. Enthält hauptsächlich die Erweiterungspunkte um Kunden-Code auszuführen. result_filter Das Modul ist für die optionale Filterung von vorgefundenen Unterschieden verantwortlich. In der ResultFilter Excel Datei können Regeln definiert werden um vorgefundenen Unterschiede als „bereits Bekannt“ markieren zu können. Es besteht die Möglichkeit diese bekannten Unterschiede erst gar nicht in der Ausgabe anzugeben bzw. diese durch entsprechenden Status von „normalen“ Differenzen zu unterscheiden. sorter Damit ein Zeilenvergleich effizient durchgeführt werden kann, müssen die Zeilen nach Schlüssel sortiert vorliegen. Diese Aufgabe wird von diesem Modul erledigt. Für die Sortierung gibt es zwei Implementierungen: 1. Sortierung innerhalb des Hauptspeichers 2. Sortierung über Datei basiertem Merge-Sort Variante 2 wird automatisch für Dateien >50MB verwendet, um Hauptspeicher zu sparen. statistics Modul zum einsammeln von Diff Lauf Statistiken. utils Hilfsfunktionen für NCDiff Standardmodule. validator Ein Validator ist dazu da, eine TargetConfiguration zu validieren um Nutzungsfehler frühzeitig zu melden. reader.base Enthält Reader Basisklassen und Fuktionen, um unterschiedliche Report Dateiformate zu lesen. reader.csv Reader für das CSV Format. reader.dir Reader um Dateiverzeichnisse zu lesen und für einen Vergleich der Dateistruktur auf zu bereiten. reader.fixed_width Reader für textbasierte Formate mit Felder mit definierter Breite. reader.sql Reader für SQL Datenbanken. reader.tar Reader für den Inhalt von *.tar Dateien um einen Vergleich der Dateistruktur auf zu bereiten. reader.xls Reader für XLS und XLSX Dateien. reader.xml Reader für XML Dateien. writer.base Basismodul der writer um die verschiedenen Ausgabeformate zu schreiben. writer.cl Kommandozeilen writer für die Textausgabe auf der Kommandozeile. writer.converter Konverter Klassen um die Ausgabe bestimmter Werte zu konvertieren. writer.csv Implementierung des writers für das CSV Format. writer.formatter Formatierungsklassen um die verschiedensten Datentypen für die Ausgabe zu formatieren. writer.html Implementierung des writers für das HTML Format. Dazu wird die HTML Template Bibliothek ``mako`` verwendet. Die benutzen Template-Dateien sind unter ``/templates`` zu finden. writer.junit Implementierung des writers für das Junit Format. writer.xlsx Implementierung des writers für das XLSX Format. Python Anpassungen mittels Erweiterungsmodulen ------------------------------------------------------------------------------------------------------------------------ Um NCDiff anzupassen ist es nicht nötig die Standardmodule umzuschreiben, da in NCDiff vorgesehen ist, Funktionalität in Erweiterungsmodule auszulagern. Für jeden vorgesehenen Erweiterungstyp ist eine Python „Factory“ Funktion zu schreiben, welche die Alternativ Implementierung zur Verfügung stellt. Erweiterungsmodule müssen im ``libs/extensions`` Ordner abgelegt werden und können mit dem globalen Konfigurationsparameter extensionModules aktiviert werden. In jedem der angegebenen Extension Module wird nach bekannten Factory Funktionen gesucht, um über deren Aufruf an eine gewünschte Implementierung zu gelangen. Im Auslieferungszustand von NCDiff ist ein leeres Beispielmodul mit dem Namen ExtensionTemplate.py enthalten, welches für alle vorgesehenen Erweiterungstypen bereits eine leere Factory Funktion beinhaltet. Liefert eine Factory Funktion nichts zurück, so verwendet NCDiff die Standard Funktionalität. Um eigene Erweiterungen zu erstellen, ist der einfachste Weg ist sich eine Klasse aus der Standard Implementierung zu suchen, von dieser abzuleiten und die benötigte Funktionalität zu implementieren. Diese Implementierung muss dann nur noch in der zugehörigen Factory Funktion zurückgegeben werden. Die folgende Tabelle gibt eine Übersicht über die vorgesehenen Erweiterungsmöglichkeiten und deren zugehörige Factory Funktion. create_basic_target_configuration_validator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_basic_target_configuration_validator :Modul: validator :Beschreibung: Validierung der Konfiguration nach Einlesen aus der Datei create_target_configuration_validator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_target_configuration_validator :Modul: validator :Beschreibung: Validierung der Konfiguration nach dem einlesen und anreichern mit basis Werten. create_configuration_preprocessor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_configuration_preprocessor :Modul: preprocessing :Beschreibung: Definition eines Preprocessor für eine bestimmte Konfiguration. create_target_preprocessor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_target_preprocessor :Modul: preprocessing :Beschreibung: Definition eines Preprocessor für ein bestimmtes Diff Target. create_execution_preprocessor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_execution_preprocessor :Modul: preprocessing :Beschreibung: Definition eines Preprocessor für die gesamt NCDiff Ausführung. create_configuration_postprocessor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_configuration_postprocessor :Modul: preprocessing :Beschreibung: Definition eines Postprocessor für eine bestimmte Konfiguration. create_target_postprocessor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_target_postprocessor :Modul: preprocessing :Beschreibung: Definition eines Postprocessor für ein bestimmtes Diff Target. create_execution_postprocessor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_execution_postprocessor :Modul: preprocessing :Beschreibung: Definition eines Postprocessor für die gesamt NCDiff Ausführung. create_old_reader ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_old_reader :Modul: reader :Beschreibung: Einlesen der alten Report Datei Formate create_new_reader ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_new_reader :Modul: reader :Beschreibung: Einlesen der neuen Report Datei Formate get_constraints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: get_constraints :Modul: constraints :Beschreibung: Definition neuer Constraint Funktionen create_old_sorter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_old_sorter :Modul: sorter :Beschreibung: Ersatz des Sortieralgorithmus create_new_sorter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_new_sorter :Modul: sorter :Beschreibung: Ersatz des Sortieralgorithmus create_converter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_converter :Modul: converter :Beschreibung: Implementierung neuer Konverter für Zellenwerte create_comparator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_comparator :Modul: comparator :Beschreibung: Ersatz der Zellvergleichslogik create_differ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_differ :Modul: differ :Beschreibung: Ersatz der Diff Logik create_writer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_writer :Modul: writer :Beschreibung: Implementierung neuer Ausgabeformate create_statistic_writer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_statistic_writer :Modul: writer :Beschreibung: Implementierung neuer Ausgabeformate create_result_interpreter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_result_interpreter :Modul: result_filter :Beschreibung: Einlesen von ResultFilter Daten create_result_interpreter_reader ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :Factory: create_result_interpreter_reader :Modul: result_filter :Beschreibung: Ersatz der ResultFilter Logik Excel Templates ------------------------------------------------------------------------------------------------------------------------ Unter NCDiff-X.Y/templates finden Sie bereits von uns vordefinierte Templates, welche bei ``resultFormats=XLSX`` verwendet werden. Gerne können Sie auch eigene Templates erzeugen, welche für Excel basierte Diff-Ergebnisdateien verwendet werden. Die XLSX Templates für das Excel 2007 Dateiformat müssen als XLSX Templates mit der Dateiendung ``xltx`` abgespeichert werden. NCDiff enthält ein Default-Template ``template_green-grey.xltx`` welches als Vorlage für eigene Templates dienen kann. XLSX Templates lassen analog zu XLS Templates sich mit den Konfigurationseinstellungen ``XLSXTemplate`` und ``templateDirectory`` auswählen. Für die XLSX Templates müssen Sie folgendes beachten: * Die Formatierung der Ersten Zeile der verschiedenen Sheets wird für die jeweilige Überschrift verwendet * Die Formatierung der Zweiten und Dritten Zeile wird übernommen und wechselt sich in den Ergebnisdateien ab um die gerade und ungeraden Zeilen besser hervorzuheben. * Statistic Sheet: Die vierte Zeile bestimmt die Formatierung der letzten Zeile im Ergebnis welches die Summen enthält. * Overview, Old, New: die Zeilen 4 bis 8 enthalten die Formatierungen für die verschiedenen Fehler und sind im Template dokumentiert. * Config Sheet: hier wird nur die erste Zeile zur Formatierung der Titelzeile verwendet. HTML Darstellung ------------------------------------------------------------------------------------------------------------------------ Die HTML Darstellung verwendet Cascading Style Sheets (CSS), JavaScript zusammen mit Standard HTML Notation. Diese Ressourcen liegen in Unterverzeichnissen von ``resources/html`` und werden beim erstellen der Ergebnisse ins das Ausgabeverzeichnis kopiert. Das Logo lässt sich austauschen in dem das Bild logo.png in ``resources/html/img`` durch ein anderes Bild ersetzt wird. Falls Anpassungen erforderlich sind, welche über den Austausch des Logos hinausgehen, sind Web Technologie Kenntnisse erforderlich.