Bewährte Softwareentwicklungsmethoden für Notebooks

Artikel
05/03/2024

Dieser Artikel enthält eine praktische exemplarische Vorgehensweise, die veranschaulicht, wie Sie bewährte Softwareentwicklungsmethoden wie Versionskontrolle, Codefreigabe und Tests sowie optional Continuous Integration und Continuous Delivery oder Continuous Deployment (CI/CD) auf Ihre Azure Databricks-Notebooks anwenden.

In dieser exemplarischen Vorgehensweise wird Folgendes thematisiert:

Hinzufügen von Notebooks zu Azure Databricks Git-Ordnern für die Versionskontrolle
Extrahieren von Teilen des Codes aus einem der Notebooks in ein freigabefähiges Modul
Testen des freigegebenen Codes
Ausführen der Notebooks über einen Azure Databricks-Auftrag
Optional: Anwenden von CI/CD auf den freigegebenen Code

Anforderungen

Für diese exemplarische Vorgehensweise sind folgende Ressourcen erforderlich:

Ein Remoterepository mit einem von Databricks unterstützten Git-Anbieter. In der exemplarischen Vorgehensweise dieses Artikels wird GitHub verwendet. In dieser exemplarischen Vorgehensweise wird davon ausgegangen, dass Sie über ein GitHub-Repository mit dem Namen best-notebooks verfügen. (Sie können Ihrem Repository einen anderen Namen geben. In diesem Fall ersetzen Sie best-notebooks in dieser Anleitung durch den Namen Ihres Repositorys.) Erstellen Sie ein GitHub-Repository, wenn Sie noch nicht über eines verfügen.

Hinweis

Wenn Sie ein neues Repository erstellen, stellen Sie sicher, dass Sie das Repository mit mindestens einer Datei initialisieren, z. B. mit einer README-Datei.
Ein Azure Databricks-Arbeitsbereich. Erstellen Sie einen Arbeitsbereich, falls noch keiner vorhanden ist.
Ein Universalcluster für Azure Databricks im Arbeitsbereich. Sie müssen die Notebooks an einen ausgeführten Universalcluster anfügen, um sie während der Entwurfsphase ausführen zu können. Im weiteren Verlauf dieser exemplarischen Vorgehensweise wird ein Azure Databricks-Auftrag verwendet, um die Ausführung der Notebooks in diesem Cluster zu automatisieren. (Sie können auch Aufträge in Auftragsclustern ausführen, die nur für die Lebensdauer der Aufträge vorhanden sind.) Erstellen Sie einen Universalcluster, falls noch keiner vorhanden ist.

Schritt 1: Einrichten von Databricks Git-Ordnern

In diesem Schritt verbinden Sie Ihr vorhandenes GitHub-Repository mit Azure Databricks Git-Ordnern in Ihrem vorhandenen Azure Databricks-Arbeitsbereich.

Damit Ihr Arbeitsbereich eine Verbindung mit Ihrem GitHub-Repository herstellen kann, müssen Sie zuerst Ihre GitHub-Anmeldeinformationen in Ihrem Arbeitsbereich angeben, sofern noch nicht geschehen.

Schritt 1.1: Angeben Ihrer GitHub-Anmeldeinformationen

Klicken Sie oben rechts im Arbeitsbereich auf Ihren Benutzernamen, und klicken Sie dann in der Dropdownliste auf Einstellungen.
Klicken Sie in der Randleiste Einstellungen unter Benutzer auf Verknüpfte Konten.
Wählen Sie unter Git-Integration für Git-Anbieter die Option GitHub aus.
Klicken Sie auf Persönliches Zugriffstoken.
Geben Sie unter Benutzername oder E-Mail des Git-Anbieters Ihren GitHub-Benutzernamen ein.
Geben Sie unter Token Ihr persönliches GitHub-Zugriffstoken (klassisch) ein. Dieses persönliche Zugriffstoken (klassisch) muss über Berechtigungen für das Repository und den Workflow verfügen.
Klicken Sie auf Speichern.

Schritt 1.2: Herstellen einer Verbindung mit Ihrem GitHub-Repository

Klicken Sie auf der Randleiste des Arbeitsbereichs auf Arbeitsbereich.
Erweitern Sie im Browser Arbeitsbereich den Bereich Arbeitsbereich > Benutzer.
Klicken Sie mit der rechten Maustaste auf den Ordner mit Ihrem Benutzernamen, und klicken Sie dann auf Erstellen > Git-Ordner.
Führen Sie im Dialogfeld Git-Ordner erstellen Folgendes aus:
1. Geben Sie unter Git-Repository-URL die GitHub-URL für Über HTTPS klonen für Ihr GitHub-Repository ein. In diesem Artikel wird davon ausgegangen, dass Ihre URL mit best-notebooks.git endet (Beispiel: https://github.com/<your-GitHub-username>/best-notebooks.git).
2. Wählen Sie unter Git-Anbieter die Option GitHub aus.
3. Behalten Sie unter Git-Ordnername den Namen Ihres Repositorys bei (beispielsweise best-notebooks).
4. Klicken Sie auf Git-Ordner erstellen.

Schritt 2: Importieren und Ausführen des Notebooks

In diesem Schritt importieren Sie ein vorhandenes externes Notebook in Ihr Repository. Sie könnten für diese exemplarische Vorgehensweise zwar auch Ihre eigenen Notebooks erstellen, der Einfachheit halber stellen wir Ihnen hier aber welche zur Verfügung.

Schritt 2.1: Erstellen eines Arbeitsbranchs im Repository

In diesem Teilschritt erstellen Sie einen Branch namens eda in Ihrem Repository. Dank dieses Branchs können Sie unabhängig vom Mainbranch (main) Ihres Repositorys an Dateien und Code arbeiten. Dies hat sich in der Softwareentwicklung bewährt. (Sie können Ihrem Branch auch einen anderen Namen geben.)

Hinweis

In einigen Repositorys kann der main-Branch stattdessen die Bezeichnung master erhalten. Ersetzen Sie in diesem Fall main in dieser Anleitung durch master.

Tipp

Wenn Sie mit der Arbeit in Git-Branches nicht vertraut sind, lesen Sie Git Branches – Branches in a Nutshell auf der Git-Website.

Der Git-Ordner aus Schritt 1.2 sollte geöffnet sein. Wenn nicht, erweitern Sie in der Randleiste des Arbeitsbereichs den Bereich Arbeitsbereich > Benutzer und anschließend den Ordner mit Ihrem Benutzernamen, und klicken Sie auf Ihren Git-Ordner.
Klicken Sie neben dem Ordnernamen unter der Brotkrümelnavigation für den Arbeitsbereich auf die Schaltfläche main des Git-Branchs.
Klicken Sie im Dialogfeld best-notebooks auf die Schaltfläche Branch erstellen.

Hinweis

Wenn Ihr Repository einen anderen Namen hat als best-notebooks, unterscheidet sich der Titel dieses Dialogfelds hier und in der gesamten exemplarischen Vorgehensweise.
Geben Sie eda ein, und klicken Sie auf Erstellen.
Schließen Sie dieses Dialogfeld.

Schritt 2.2: Importieren des Notebooks in das Repository

In diesem Teilschritt importieren Sie ein vorhandenes Notebook aus einem anderen Repository in Ihr Repository. Dieses Notebook führt folgende Aktionen aus:

Kopieren einer CSV-Datei aus dem GitHub-Repository owid/covid-19-data in einen Cluster in Ihrem Arbeitsbereich. Diese CSV-Datei enthält öffentliche Daten zu COVID-19-Krankenhausaufenthalten und Intensivpflegemetriken aus der ganzen Welt.
Lesen des Inhalts der CSV-Datei in einen Pandas-Datenrahmen
Filtern der Daten, sodass nur Metriken aus den USA enthalten sind
Anzeigen eines Plots der Daten
Speichern des Pandas-Datenrahmens als Datenrahmen der Pandas-API in Spark
Bereinigen der Daten für den Datenrahmen der Pandas-API in Spark
Schreiben des Datenrahmens der Pandas-API in Spark als Delta-Tabelle in Ihren Arbeitsbereich
Anzeigen des Inhalts der Delta-Tabelle

Sie könnten zwar auch ein eigenes Notebook in Ihrem Repository erstellen, das Importieren eines vorhandenen Notebooks geht jedoch schneller. Wenn Sie ein Notebook in diesem Branch erstellen oder ein vorhandenes Notebook in diesen Branch verschieben möchten, anstatt ein Notebook zu importieren, lesen Sie Grundlegende Verwendung von Arbeitsbereichsdateien.

Klicken Sie im Git-Ordner best-notebooks auf Erstellen > Ordner.
Geben Sie im Dialogfeld Neuer Ordner den Namen notebooks ein, und klicken Sie anschließend auf Erstellen.
Klicken Sie im Ordner Notebooks auf das Dropdownmenü und dann auf Importieren.
Im Dialogfeld Importieren:
1. Wählen Sie unter Importieren aus die Option URL aus.
2. Geben Sie die URL zum Rohdateninhalt des Notebooks covid_eda_raw im Repository databricks/notebook-best-practices in GitHub ein. Diese URL erhalten Sie wie folgt: i. Wechseln Sie zur Adresse https://github.com/databricks/notebook-best-practices. ii. Klicken Sie auf den Ordner notebooks. iii. Klicken Sie auf die Datei covid_eda_raw.py. iv. Klicken Sie auf Roh. .v Kopieren Sie die vollständige URL aus der Adressleiste Ihres Webbrowsers in das Dialogfeld Importieren.
  
  Hinweis
  
  Das Dialogfeld Importieren funktioniert nur mit Git-URLs für öffentliche Repositorys.
3. Klicken Sie auf Importieren.

Schritt 2.3: Ausführen des Notebooks

Wenn das Notebook noch nicht angezeigt wird, öffnen Sie den Ordner Notebooks, und klicken Sie dann auf das Notebook covid_eda_raw innerhalb des Ordners.
Wählen Sie den Cluster aus, an den Sie dieses Notebook anfügen möchten. Anweisungen zum Erstellen eines Clusters finden Sie unter Erstellen eines Clusters.
Klicken Sie auf Alle ausführen.
Warten Sie, bis das Notebook ausgeführt wurde.

Nach Abschluss der Notebookausführung sollten im Notebook ein Plot der Daten sowie über 600 Zeilen an Rohdaten in der Delta-Tabelle angezeigt werden. Wenn der Cluster beim Ausführen dieses Notebooks noch nicht aktiv war, kann es mehrere Minuten dauern, bis der Cluster gestartet wurde und Ergebnisse angezeigt werden.

Schritt 2.4: Einchecken und Zusammenführen des Notebooks

In diesem Teilschritt wird Ihre bisherige Arbeit in Ihrem GitHub-Repository gespeichert. Anschließend wird das Notebook aus Ihrem Arbeitsbranch im Mainbranch (main) Ihres Repositorys zusammengeführt.

Klicken Sie neben dem Namen des Notebooks auf die Git-Branch-Schaltfläche eda.
Stellen Sie im Dialogfeld best-notebooks auf der Registerkarte Änderungen sicher, dass die Datei notebooks/covid_eda_raw.py ausgewählt ist.
Geben Sie für Commit-Nachricht (erforderlich)Added raw notebook ein.
Geben Sie unter Beschreibung (erforderlich) Folgendes ein: This is the first version of the notebook.
Klicke auf Committen und pushen.
Klicken Sie im Banner unter Pull Request auf Git-Anbieter erstellen auf den Pull Request-Link.
Erstellen Sie in GitHub den Pull Request, und führen Sie anschließend den Pull Request im Mainbranch (main) zusammen.
Schließen Sie in Ihrem Azure Databricks-Arbeitsbereich das Dialogfeld best-notebooks, falls es immer noch angezeigt wird.

Schritt 3: Verschieben von Code in ein freigegebenes Modul

In diesem Schritt verschieben Sie einen Teil des Codes aus Ihrem Notebook in eine Reihe freigegebener Funktionen außerhalb Ihres Notebooks. Dadurch können Sie diese Funktionen mit anderen ähnlichen Notebooks verwenden, was sowohl die zukünftige Programmierung beschleunigen als auch dazu beitragen kann, besser planbare und konsistentere Notebookergebnisse zu erhalten. Durch Freigeben dieses Codes können Sie die Funktionen außerdem einfacher testen. Hierbei handelt es sich um eine bewährte Softwareentwicklungsmethode, die im weiteren Verlauf zur allgemeinen Verbesserung der Codequalität beitragen kann.

Schritt 3.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Klicken Sie neben dem Namen des Notebooks auf die Git-Branch-Schaltfläche eda.
Klicken Sie im Dialogfeld best-notebooks neben dem Branch eda auf den Dropdownpfeil, und wählen Sie main aus.
Klicken Sie auf die Schaltfläche Pullen. Wenn Sie aufgefordert werden, mit dem Pullen fortzufahren, klicken Sie auf Bestätigen.
Klicken Sie auf die Schaltfläche Branch erstellen.
Geben Sie first_modules ein, und klicken Sie anschließend auf Erstellen. (Sie können Ihrem Branch auch einen anderen Namen geben.)
Schließen Sie dieses Dialogfeld.

Schritt 3.2: Importieren des Notebooks in das Repository

Zur Beschleunigung der exemplarischen Vorgehensweise wird in diesem Teilschritt ein weiteres vorhandenes Notebook in Ihr Repository importiert. Dieses Notebook führt die gleichen Aktionen aus wie das vorherige Notebook. Der einzige Unterschied besteht darin, dass dieses Notebook freigegebene Codefunktionen aufruft, die außerhalb des Notebooks gespeichert sind. Auch hier könnten Sie wieder ein eigenes Notebook in Ihrem Repository erstellen und die Codefreigabe selbst durchführen.

Klicken Sie im Browser Arbeitsbereich mit der rechten Maustaste auf den Notebooks-Ordner, und klicken Sie dann auf Importieren.
Im Dialogfeld Importieren:
1. Wählen Sie unter Importieren aus die Option URL aus.
2. Geben Sie die URL zum Rohdateninhalt des Notebooks covid_eda_modular im Repository databricks/notebook-best-practices in GitHub ein. Diese URL erhalten Sie wie folgt: i. Wechseln Sie zur Adresse https://github.com/databricks/notebook-best-practices. ii. Klicken Sie auf den Ordner notebooks. iii. Klicken Sie auf die Datei covid_eda_modular.py. iv. Klicken Sie auf Roh. v. Kopieren Sie die vollständige URL aus der Adressleiste Ihres Webbrowsers in das Dialogfeld Notebooks importieren.
  
  Hinweis
  
  Das Dialogfeld Notebooks importieren funktioniert nur mit Git-URLs für öffentliche Repositorys.
3. Klicken Sie auf Importieren.

Schritt 3.3: Hinzufügen der unterstützenden freigegebenen Codefunktionen des Notebooks

Klicken Sie im Arbeitsbereich-Browser mit der rechten Maustaste auf den Git-Ordner best-notebooks, und klicken Sie dann auf Erstellen > Ordner.
Geben Sie im Dialogfeld Neuer Ordner den Namen covid_analysis ein, und klicken Sie anschließend auf Erstellen.
Klicken Sie im Ordner covid_analysis auf Erstellen > Datei.
Geben Sie im Dialogfeld Neuer Dateiname den Namen transforms.py ein, und klicken Sie anschließend auf Datei erstellen.

Geben Sie im Editorfenster transforms.py den folgenden Code ein:

import pandas as pd

# Filter by country code.
def filter_country(pdf, country="USA"):
  pdf = pdf[pdf.iso_code == country]
  return pdf

# Pivot by indicator, and fill missing values.
def pivot_and_clean(pdf, fillna):
  pdf["value"] = pd.to_numeric(pdf["value"])
  pdf = pdf.fillna(fillna).pivot_table(
    values="value", columns="indicator", index="date"
  )
  return pdf

# Create column names that are compatible with Delta tables.
def clean_spark_cols(pdf):
  pdf.columns = pdf.columns.str.replace(" ", "_")
  return pdf

# Convert index to column (works with pandas API on Spark, too).
def index_to_col(df, colname):
  df[colname] = df.index
  return df

Tipp

Weitere Codefreigabetechniken finden Sie unter Freigeben von Code zwischen Databricks-Notebooks.

Schritt 3.4: Hinzufügen der Abhängigkeiten des freigegebenen Codes

Der obige Code verfügt über mehrere Python-Paketabhängigkeiten, um die ordnungsgemäße Ausführung des Codes zu ermöglichen. In diesem Teilschritt werden die Paketabhängigkeiten deklariert. Das Deklarieren von Abhängigkeiten verbessert die Reproduzierbarkeit durch die Verwendung präzise definierter Versionen von Bibliotheken.

Klicken Sie im Arbeitsbereich-Browser mit der rechten Maustaste auf den Git-Ordner best-notebooks, und klicken Sie dann auf Erstellen > Datei.

Hinweis

Sie möchten, dass die Datei, die Paketabhängigkeiten auflistet, im Stammordner des Git-Ordners gespeichert wird und nicht in den Ordnern Notebooks oder covid_analysis.
Geben Sie im Dialogfeld Neuer Dateiname den Namen requirements.txt ein, und klicken Sie anschließend auf Datei erstellen.
Geben Sie im Editorfenster requirements.txt den folgenden Code ein:

Hinweis

Sollte die Datei requirements.txt nicht angezeigt werden, müssen Sie möglicherweise Ihren Webbrowser aktualisieren.
```
-i https://pypi.org/simple
attrs==21.4.0
cycler==0.11.0
fonttools==4.33.3
iniconfig==1.1.1
kiwisolver==1.4.2
matplotlib==3.5.1
numpy==1.22.3
packaging==21.3
pandas==1.4.2
pillow==9.1.0
pluggy==1.0.0
py==1.11.0
py4j==0.10.9.3
pyarrow==7.0.0
pyparsing==3.0.8
pyspark==3.2.1
pytest==7.1.2
python-dateutil==2.8.2
pytz==2022.1
six==1.16.0
tomli==2.0.1
wget==3.2
```
Hinweis

In der obigen Datei sind spezifische Paketversionen aufgeführt. Um die Kompatibilität zu verbessern, können Sie diese Versionen mit den Versionen abgleichen, die in Ihrem Universalcluster installiert sind. Weitere Informationen zur Databricks Runtime-Version Ihres Clusters finden Sie im Abschnitt „Systemumgebung“ unter Versionshinweise zu Databricks Runtime-Versionen und -Kompatibilität.

Ihr Repository sollte nun wie folgt strukturiert sein:

|-- covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
└── requirements.txt

Schritt 3.5: Ausführen des umgestalteten Notebooks

In diesem Teilschritt führen Sie das Notebook covid_eda_modular aus. Dadurch wird der freigegebene Code in covid_analysis/transforms.py aufgerufen.

Klicken Sie im Arbeitsbereich-Browser auf das Notebook covid_eda_modular im Ordner Notebooks.
Wählen Sie den Cluster aus, an den Sie dieses Notebook anfügen möchten.
Klicken Sie auf Alle ausführen.
Warten Sie, bis das Notebook ausgeführt wurde.

Nach Abschluss der Notebookausführung sollten im Notebook ähnliche Ergebnisse zu sehen sein wie beim Notebook covid_eda_raw: ein Plot der Daten sowie über 600 Zeilen an Rohdaten in der Delta-Tabelle. Der Hauptunterschied zu diesem Notebook besteht darin, dass ein anderer Filter verwendet wird (an iso_code von DZA anstelle von USA). Wenn der Cluster beim Ausführen dieses Notebooks noch nicht aktiv war, kann es mehrere Minuten dauern, bis der Cluster gestartet wurde und Ergebnisse angezeigt werden.

Klicken Sie neben dem Namen des Notebooks auf die Git-Branch-Schaltfläche first_modules.
Stellen Sie im Dialogfeld best-notebooks auf der Registerkarte Änderungen sicher, dass Folgendes ausgewählt ist:
- requirements.txt
- covid_analysis/transforms.py
- notebooks/covid_eda_modular.py
Geben Sie für Commit-Nachricht (erforderlich)Added refactored notebook ein.
Geben Sie unter Beschreibung (erforderlich) Folgendes ein: This is the second version of the notebook.
Klicke auf Committen und pushen.
Klicken Sie im Banner unter Pull Request auf Git-Anbieter erstellen auf den Pull Request-Link.
Erstellen Sie in GitHub den Pull Request, und führen Sie anschließend den Pull Request im Mainbranch (main) zusammen.
Schließen Sie in Ihrem Azure Databricks-Arbeitsbereich das Dialogfeld best-notebooks, falls es immer noch angezeigt wird.

Schritt 4: Testen des freigegebenen Codes

In diesem Schritt testen Sie den freigegebenen Code aus dem letzten Schritt. Sie möchten diesen Code jedoch testen, ohne das Notebook covid_eda_modular selbst auszuführen. Der Grund: Sollte der freigegebene Code nicht erfolgreich ausgeführt werden, wird wahrscheinlich auch das Notebook selbst nicht erfolgreich ausgeführt. Sie möchten daher zuerst Fehler in Ihrem freigegebenen Code abfangen, um spätere Fehler in Ihrem Hauptnotebook zu vermeiden. Diese Testtechnik ist eine bewährte Softwareentwicklungsmethode.

Tipp

Weitere Ansätze zum Testen von Notebooks sowie zum Testen von R- und Scala-Notebooks finden Sie unter Komponententests für Notebooks.

Schritt 4.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Klicken Sie neben dem Namen des Notebooks auf die Git-Branch-Schaltfläche first_modules.
Klicken Sie im Dialogfeld best-notebooks neben dem Branch first_modules auf den Dropdownpfeil, und wählen Sie main aus.
Klicken Sie auf die Schaltfläche Pullen. Wenn Sie aufgefordert werden, mit dem Pullen fortzufahren, klicken Sie auf Bestätigen.
Klicke auf Branch erstellen.
Geben Sie first_tests ein, und klicken Sie anschließend auf Erstellen. (Sie können Ihrem Branch auch einen anderen Namen geben.)
Schließen Sie dieses Dialogfeld.

Schritt 4.2: Hinzufügen der Tests

In diesem Teilschritt wird Ihr Code mithilfe des Frameworks pytest getestet. Bei diesen Tests wird mittels assert überprüft, ob bestimmte Testergebnisse erzielt werden. Sollte bei einem der Tests ein unerwartetes Ergebnis generiert werden, ist die Assertion und somit der Test selbst nicht erfolgreich.

Klicken Sie im Arbeitsbereich-Browser mit der rechten Maustaste auf Ihren Git-Ordner und dann auf Erstellen > Ordner.
Geben Sie im Dialogfeld Neuer Ordner den Namen tests ein, und klicken Sie anschließend auf Erstellen.
Klicken Sie im Ordner tests auf Erstellen > Datei.
Geben Sie im Dialogfeld Neuer Dateiname den Namen testdata.csv ein, und klicken Sie anschließend auf Datei erstellen.

Geben Sie im Editorfenster testdata.csv folgende Testdaten ein:

entity,iso_code,date,indicator,value
United States,USA,2022-04-17,Daily ICU occupancy,
United States,USA,2022-04-17,Daily ICU occupancy per million,4.1
United States,USA,2022-04-17,Daily hospital occupancy,10000
United States,USA,2022-04-17,Daily hospital occupancy per million,30.3
United States,USA,2022-04-17,Weekly new hospital admissions,11000
United States,USA,2022-04-17,Weekly new hospital admissions per million,32.8
Algeria,DZA,2022-04-18,Daily ICU occupancy,1010
Algeria,DZA,2022-04-18,Daily ICU occupancy per million,4.5
Algeria,DZA,2022-04-18,Daily hospital occupancy,11000
Algeria,DZA,2022-04-18,Daily hospital occupancy per million,30.9
Algeria,DZA,2022-04-18,Weekly new hospital admissions,10000
Algeria,DZA,2022-04-18,Weekly new hospital admissions per million,32.1

Klicken Sie im Ordner tests auf Erstellen > Datei.
Geben Sie im Dialogfeld Neuer Dateiname den Namen transforms_test.py ein, und klicken Sie anschließend auf Datei erstellen.

Geben Sie in Editorfenster transforms_test.py den folgenden Testcode ein. Bei diesen Tests werden standardmäßige pytest-Fixtures sowie ein simulierter In-Memory-Pandas-Datenrahmen verwendet:

# Test each of the transform functions.
import pytest
from textwrap import fill
import os
import pandas as pd
import numpy as np
from covid_analysis.transforms import *
from pyspark.sql import SparkSession

@pytest.fixture
def raw_input_df() -> pd.DataFrame:
  """
  Create a basic version of the input dataset for testing, including NaNs.
  """
  return pd.read_csv('tests/testdata.csv')

@pytest.fixture
def colnames_df() -> pd.DataFrame:
  df = pd.DataFrame(
    data=[[0,1,2,3,4,5]],
    columns=[
      "Daily ICU occupancy",
      "Daily ICU occupancy per million",
      "Daily hospital occupancy",
      "Daily hospital occupancy per million",
      "Weekly new hospital admissions",
      "Weekly new hospital admissions per million"
    ]
  )
  return df

# Make sure the filter works as expected.
def test_filter(raw_input_df):
  filtered = filter_country(raw_input_df)
  assert filtered.iso_code.drop_duplicates()[0] == "USA"

# The test data has NaNs for Daily ICU occupancy; this should get filled to 0.
def test_pivot(raw_input_df):
  pivoted = pivot_and_clean(raw_input_df, 0)
  assert pivoted["Daily ICU occupancy"][0] == 0

# Test column cleaning.
def test_clean_cols(colnames_df):
  cleaned = clean_spark_cols(colnames_df)
  cols_w_spaces = cleaned.filter(regex=(" "))
  assert cols_w_spaces.empty == True

# Test column creation from index.
def test_index_to_col(raw_input_df):
  raw_input_df["col_from_index"] = raw_input_df.index
  assert (raw_input_df.index == raw_input_df.col_from_index).all()

Ihr Repository sollte nun wie folgt strukturiert sein:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

Schritt 4.3: Ausführen der Tests

In diesem Teilschritt wird zum Ausführen der obigen Tests ein importiertes Notebook verwendet, um diese exemplarische Vorgehensweise zu beschleunigen. Dieses Notebook lädt die abhängigen Python-Pakete der Tests in Ihren Arbeitsbereich herunter, installiert sie, führt die Tests aus und meldet die Testergebnisse. pytest kann zwar auch über das Webterminal Ihres Clusters ausgeführt werden, die Ausführung von pytest über ein Notebook ist jedoch ggf. komfortabler.

Hinweis

Wenn Sie pytest ausführen, werden alle Dateien, deren Namen der Form test_*.py oder /*_test.py folgen, im aktuellen Verzeichnis und seinen Unterverzeichnissen ausgeführt.

Klicken Sie im Browser Arbeitsbereich mit der rechten Maustaste auf den Notebooks-Ordner, und klicken Sie dann auf Importieren.
Gehen Sie im Dialogfeld Notebooks importieren wie folgt vor:
1. Wählen Sie unter Importieren aus die Option URL aus.
2. Geben Sie die URL zum Rohdateninhalt des Notebooks run_unit_tests im Repository databricks/notebook-best-practices in GitHub ein. Diese URL erhalten Sie wie folgt: i. Wechseln Sie zur Adresse https://github.com/databricks/notebook-best-practices. ii. Klicken Sie auf den Ordner notebooks. iii. Klicken Sie auf die Datei run_unit_tests.py. iv. Klicken Sie auf Roh. v. Kopieren Sie die vollständige URL aus der Adressleiste Ihres Webbrowsers in das Dialogfeld Notebooks importieren.
  
  Hinweis
  
  Das Dialogfeld Notebooks importieren funktioniert nur mit Git-URLs für öffentliche Repositorys.
3. Klicken Sie auf Importieren.
Wählen Sie den Cluster aus, an den Sie dieses Notebook anfügen möchten.
Klicken Sie auf Alle ausführen.
Warten Sie, bis das Notebook ausgeführt wurde.

Nach Abschluss der Notebookausführung sollten im Notebook Informationen zur Anzahl bestandener und nicht bestandener Tests sowie weitere zugehörige Details angezeigt werden. Wenn der Cluster beim Ausführen dieses Notebooks noch nicht aktiv war, kann es mehrere Minuten dauern, bis der Cluster gestartet wurde und Ergebnisse angezeigt werden.

Ihr Repository sollte nun wie folgt strukturiert sein:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

Klicken Sie neben dem Namen des Notebooks auf die Git-Branch-Schaltfläche first_tests.
Stellen Sie im Dialogfeld best-notebooks auf der Registerkarte Änderungen sicher, dass Folgendes ausgewählt ist:
- tests/transforms_test.py
- notebooks/run_unit_tests.py
- tests/testdata.csv
Geben Sie für Commit-Nachricht (erforderlich)Added tests ein.
Geben Sie unter Beschreibung (erforderlich) Folgendes ein: These are the unit tests for the shared code.
Klicke auf Committen und pushen.
Klicken Sie im Banner unter Pull Request auf Git-Anbieter erstellen auf den Pull Request-Link.
Erstellen Sie in GitHub den Pull Request, und führen Sie anschließend den Pull Request im Mainbranch (main) zusammen.
Schließen Sie in Ihrem Azure Databricks-Arbeitsbereich das Dialogfeld best-notebooks, falls es immer noch angezeigt wird.

Schritt 5: Erstellen eines Auftrags zum Ausführen der Notebooks

In den vorherigen Schritten haben Sie den freigegebenen Code manuell getestet und Ihre Notebooks manuell ausgeführt. In diesem Schritt verwenden Sie einen Azure Databricks-Auftrag, um Ihren freigegebenen Code automatisch zu testen und Ihre Notebooks automatisch auszuführen – entweder bei Bedarf oder nach einem regelmäßigen Zeitplan.

Schritt 5.1: Erstellen einer Auftragsaufgabe zum Ausführen des Testnotebooks

Klicken Sie auf der Randleiste des Arbeitsbereichs auf Workflows.
Klicken Sie auf der Registerkarte Aufträge auf Auftrag erstellen.
Ändern Sie den Namen des Auftrags in covid_report.
Geben Sie unter Name der Aufgabe den Namen run_notebook_tests ein.
Wählen Sie unter Typ die Option Notebook aus.
Wählen Sie für QuelleGit-Anbieter aus.
Klicken Sie auf Git-Verweis hinzufügen.
Gehen Sie im Dialogfeld Git-Informationen wie folgt vor:
1. Geben Sie unter Git-Repository-URL die GitHub-URL für Über HTTPS klonen für Ihr GitHub-Repository ein. In diesem Artikel wird davon ausgegangen, dass Ihre URL mit best-notebooks.git endet (Beispiel: https://github.com/<your-GitHub-username>/best-notebooks.git).
2. Wählen Sie unter Git-Anbieter die Option GitHub aus.
3. Geben Sie unter Git-Verweis (Branch/Tag/Commit) Folgendes ein: main.
4. Wählen Sie neben Git-Verweis (Branch/Tag/Commit) die Option Branch aus.
5. Klicken Sie auf Confirm (Bestätigen).
Geben Sie unter Pfad den Pfad notebooks/run_unit_tests ein. Fügen Sie nicht die Dateierweiterung .py hinzu.
Wählen Sie unter Cluster den Cluster aus dem vorherigen Schritt aus.
Klicken Sie auf Aufgabe erstellen.

Hinweis

In diesem Szenario empfiehlt Databricks nicht, die Schaltfläche „Zeitplan“ im Notebook zu verwenden, wie in Erstellen und Verwalten von geplanten Notebookaufträgen beschrieben, um einen Auftrag zur regelmäßigen Ausführung dieses Notebooks zu planen. Der Grund: Über die Zeitplanschaltfläche wird ein Auftrag mit der neuesten Arbeitskopie des Notebooks im Arbeitsbereichsrepository erstellt. Folgen Sie stattdessen den obigen Anweisungen, um einen Auftrag zu erstellen, der die neueste committete Version des Notebooks im Repository verwendet.

Schritt 5.2: Erstellen einer Auftragsaufgabe zum Ausführen des Hauptnotebooks

Klicken Sie auf das Symbol + Aufgabe hinzufügen.
Ein Popupmenü wird angezeigt. Wählen Sie Notebook aus.
Geben Sie unter Name der Aufgabe den Namen run_main_notebook ein.
Wählen Sie unter Typ die Option Notebook aus.
Geben Sie unter Pfad den Pfad notebooks/covid_eda_modular ein. Fügen Sie nicht die Dateierweiterung .py hinzu.
Wählen Sie unter Cluster den Cluster aus dem vorherigen Schritt aus.
Überprüfen Sie, ob der Wert Abhängig vonrun_notebook-tests lautet.
Klicken Sie auf Aufgabe erstellen.

Schritt 5.3: Ausführen des Auftrags

Klicken Sie auf Jetzt ausführen.
Klicken Sie im Popup auf Ausführung anzeigen.
Hinweis

Sollte das Popup zu schnell ausgeblendet werden, gehen Sie wie folgt vor:
1. Klicken Sie auf der Randleiste in der Umgebung Data Science und Entwicklung oder Databricks Machine Learning auf Workflows.
2. Klicken Sie auf der Registerkarte Auftragsausführungen auf den Wert Startzeit für den neuesten Auftrag mit covid_report in der Spalte Aufträge.
Klicken Sie zum Anzeigen der Auftragsergebnisse auf die Kachel run_notebook_tests oder run_main_notebook (oder auf beide). Die Ergebnisse auf den Kacheln entsprechen den Ergebnissen, die Sie erhalten, wenn Sie die Notebooks nacheinander selbst ausführen.

Hinweis

Dieser Auftrag wurde bei Bedarf ausgeführt. Wie Sie diesen Auftrag einrichten wollen, damit er regelmäßig ausgeführt wird, lesen Sie Hinzufügen eines Auftragszeitplans.

(Optional) Schritt 6: Einrichten des Repositorys, sodass der Code automatisch getestet und das Notebook ausgeführt wird, wenn sich der Code ändert

Im vorherigen Schritt haben Sie einen Auftrag verwendet, um Ihren freigegebenen Code automatisch zu testen und Ihre Notebooks einmalig oder regelmäßig auszuführen. Sie können jedoch vorziehen, Tests automatisch auszulösen, wenn Änderungen in Ihrem GitHub-Repository zusammengeführt werden, indem Sie ein CI/CD-Tool wie GitHub Actions verwenden.

Schritt 6.1: Einrichten von GitHub-Zugriff auf Ihren Arbeitsbereich

In diesem Teilschritt wird ein GitHub Actions-Workflow eingerichtet, der Aufträge im Arbeitsbereich ausführt, wenn Änderungen in Ihrem Repository zusammengeführt werden. Hierzu wird GitHub ein eindeutiges Azure Databricks-Token für den Zugriff bereitgestellt.

Aus Sicherheitsgründen wird davon abgeraten, das persönliche Zugriffstoken Ihres Azure Databricks-Arbeitsbereichsbenutzers an GitHub weiterzugeben. Stattdessen empfiehlt Databricks, dass Sie GitHub ein Token von Microsoft Entra ID (früher Azure Active Directory) geben, das einem Microsoft Entra ID-Dienstprinzipal zugeordnet ist. Eine entsprechende Anleitung finden Sie im GitHub Actions-Marketplace auf der Seite Ausführen eines Databricks-Notebooks im Abschnitt Azure.

Wichtig

Notebooks werden mit allen Arbeitsbereichsberechtigungen der Identität ausgeführt, die dem Token zugeordnet ist. Daher empfiehlt Databricks die Verwendung eines Dienstprinzipals. Falls Sie zur persönlichen Erkundung dennoch das persönliche Zugriffstoken Ihres Azure Databricks-Arbeitsbereichsbenutzers an GitHub weitergeben möchten und sich bewusst sind, dass diese Vorgehensweise aus Sicherheitsgründen nicht empfohlen wird, können Sie die Anleitung unter Generieren eines persönlichen Zugriffstokens verwenden.

Schritt 6.2: Hinzufügen des GitHub Actions-Workflows

In diesem Teilschritt fügen Sie einen GitHub Actions-Workflow hinzu, um das Notebook run_unit_tests auszuführen, sobald ein Pull Request für das Repository vorhanden ist.

Dieser Teilschritt speichert den GitHub Actions-Workflow in einer Datei, die sich auf mehreren Ordnerebenen Ihres GitHub-Repositorys befindet. Damit GitHub Actions ordnungsgemäß funktioniert, muss Ihr Repository eine bestimmte geschachtelte Ordnerhierarchie aufweisen. Für diesen Schritt muss die Website für Ihr GitHub-Repository verwendet werden, da die Erstellung geschachtelter Ordnerhierarchien auf der Benutzeroberfläche vom Azure Databricks Git-Ordner nicht unterstützt wird.

Klicken Sie auf der Website für Ihr GitHub-Repository auf die Registerkarte Code.
Klicken Sie auf den Pfeil neben main, um die Dropdownliste Branches oder Tags wechseln zu erweitern.
Geben Sie im Feld Branch suchen oder erstellen Folgendes ein: adding_github_actions.
Klicken Sie auf Branch erstellen: „adding_github_actions“ aus „main“.
Klicken Sie auf Datei hinzufügen > Neue Datei erstellen.
Geben Sie unter Datei benennen den Namen .github/workflows/databricks_pull_request_tests.yml ein.

Geben Sie im Editorfenster den folgenden Code ein: Mit diesem Code wird der Hook „pull_request“ der GitHub-Aktion Databricks-Notebook ausführen zum Ausführen des Notebooks run_unit_tests verwendet.

Ersetzen Sie im folgenden Code:

<your-workspace-instance-URL> durch den Namen Ihrer Azure Databricks-Instanz.
<your-access-token> durch das weiter oben generierte Token.
<your-cluster-id> durch Ihre Zielcluster-ID.

name: Run pre-merge Databricks tests

on:
  pull_request:

env:
  # Replace this value with your workspace instance name.
  DATABRICKS_HOST: https://<your-workspace-instance-name>

jobs:
  unit-test-notebook:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout repo
        uses: actions/checkout@v2
      - name: Run test notebook
        uses: databricks/run-notebook@main
        with:
          databricks-token: <your-access-token>

          local-notebook-path: notebooks/run_unit_tests.py

          existing-cluster-id: <your-cluster-id>

          git-commit: "${{ github.event.pull_request.head.sha }}"

          # Grant all users view permission on the notebook's results, so that they can
          # see the result of the notebook, if they have related access permissions.
          access-control-list-json: >
            [
              {
                "group_name": "users",
                "permission_level": "CAN_VIEW"
              }
            ]
          run-name: "EDA transforms helper module unit tests"

Klicke auf Änderungen committen.
Geben Sie im Dialogfeld Commit-ÄnderungenCreate databricks_pull_request_tests.yml in Commitnachricht ein.
Wählen Sie Direkten Commit zum Branch adding_github_actions ausführen, und klicken Sie auf Änderungen committen.
Klicken Sie auf der Registerkarte Code auf Vergleich und Pull Request, und erstellen Sie dann den Pull Request.
Warten Sie auf der Pull Request-Seite, bis das Symbol neben Databricks-Tests vor dem Zusammenführen ausführen/unit-test-notebook (pull_request) ein grünes Häkchen angezeigt wird. (Es kann etwas dauern, bis das Symbol angezeigt wird.) Wird anstelle eines grünen Häkchens ein rotes X angezeigt, klicken Sie auf Details, um den Grund dafür zu ermitteln. Wenn das Symbol nicht mehr angezeigt wird bzw. die Details nicht mehr angezeigt werden, klicken Sie auf Alle Prüfungen anzeigen.
Wenn das grüne Häkchen angezeigt wird, führen Sie den Pull Request im Mainbranch (main) zusammen.

(Optional) Schritt 7: Aktualisieren des freigegebenen Codes in GitHub, um Tests auszulösen

In diesem Schritt nehmen Sie eine Änderung an dem freigegebenen Code vor und pushen sie an Ihr GitHub-Repository, woraufhin automatisch die Tests ausgelöst werden (basierend auf der GitHub-Aktion aus dem vorherigen Schritt).

Schritt 7.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Öffnen Sie im Arbeitsbereich-Browser den Git-Ordner best-notebooks.
Klicken Sie neben dem Namen des Ordners auf die Git-Branch-Schaltfläche first_tests.
Klicken Sie im Dialogfeld best-notebooks neben dem Branch first_tests auf den Dropdownpfeil, und wählen Sie main aus.
Klicken Sie auf die Schaltfläche Pullen. Wenn Sie aufgefordert werden, mit dem Pullen fortzufahren, klicken Sie auf Bestätigen.
Klicken Sie auf die Schaltfläche + (Branch erstellen).
Geben Sie trigger_tests ein, und klicken Sie anschließend auf Erstellen. (Sie können Ihrem Branch auch einen anderen Namen geben.)
Schließen Sie dieses Dialogfeld.

Schritt 7.2: Ändern des freigegebenen Codes

Klicken Sie im Arbeitsbereich-Browser im Git-Ordner best-notebooks auf die Datei covid_analysis/transforms.py.

Ändern Sie die dritte Zeile dieser Datei:

# Filter by country code.

Folgendermaßen:

# Filter by country code. If not specified, use "USA."

Schritt 7.3: Einchecken der Änderung, um die Tests auszulösen

Klicken Sie neben dem Dateinamen auf die Schaltfläche trigger_tests des Git-Branchs.
Stellen Sie im Dialogfeld best-notebooks auf der Registerkarte Änderungen sicher, dass covid_analysis/transforms.py ausgewählt ist.
Geben Sie für Commit-Nachricht (erforderlich)Updated comment ein.
Geben Sie unter Beschreibung (erforderlich) Folgendes ein: This updates the comment for filter_country.
Klicke auf Committen und pushen.
Klicken Sie im Banner unter Pull Request auf Git-Anbieter erstellen auf den Pull Request-Link, und erstellen Sie den Pull Request in GitHub.
Warten Sie auf der Pull Request-Seite, bis das Symbol neben Databricks-Tests vor dem Zusammenführen ausführen/unit-test-notebook (pull_request) ein grünes Häkchen angezeigt wird. (Es kann etwas dauern, bis das Symbol angezeigt wird.) Wird anstelle eines grünen Häkchens ein rotes X angezeigt, klicken Sie auf Details, um den Grund dafür zu ermitteln. Wenn das Symbol nicht mehr angezeigt wird bzw. die Details nicht mehr angezeigt werden, klicken Sie auf Alle Prüfungen anzeigen.
Wenn das grüne Häkchen angezeigt wird, führen Sie den Pull Request im Mainbranch (main) zusammen.

Freigeben über

Bewährte Softwareentwicklungsmethoden für Notebooks

Anforderungen

Schritt 1: Einrichten von Databricks Git-Ordnern

Schritt 1.1: Angeben Ihrer GitHub-Anmeldeinformationen

Schritt 1.2: Herstellen einer Verbindung mit Ihrem GitHub-Repository

Schritt 2: Importieren und Ausführen des Notebooks

Schritt 2.1: Erstellen eines Arbeitsbranchs im Repository

Schritt 2.2: Importieren des Notebooks in das Repository

Schritt 2.3: Ausführen des Notebooks

Schritt 2.4: Einchecken und Zusammenführen des Notebooks

Schritt 3: Verschieben von Code in ein freigegebenes Modul

Schritt 3.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Schritt 3.2: Importieren des Notebooks in das Repository

Schritt 3.3: Hinzufügen der unterstützenden freigegebenen Codefunktionen des Notebooks

Schritt 3.4: Hinzufügen der Abhängigkeiten des freigegebenen Codes

Schritt 3.5: Ausführen des umgestalteten Notebooks

Schritt 4: Testen des freigegebenen Codes

Schritt 4.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Schritt 4.2: Hinzufügen der Tests

Schritt 4.3: Ausführen der Tests

Schritt 5: Erstellen eines Auftrags zum Ausführen der Notebooks

Schritt 5.1: Erstellen einer Auftragsaufgabe zum Ausführen des Testnotebooks

Schritt 5.2: Erstellen einer Auftragsaufgabe zum Ausführen des Hauptnotebooks

Schritt 5.3: Ausführen des Auftrags

(Optional) Schritt 6: Einrichten des Repositorys, sodass der Code automatisch getestet und das Notebook ausgeführt wird, wenn sich der Code ändert

Schritt 6.1: Einrichten von GitHub-Zugriff auf Ihren Arbeitsbereich

Schritt 6.2: Hinzufügen des GitHub Actions-Workflows

(Optional) Schritt 7: Aktualisieren des freigegebenen Codes in GitHub, um Tests auszulösen

Schritt 7.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Schritt 7.2: Ändern des freigegebenen Codes

Schritt 7.3: Einchecken der Änderung, um die Tests auszulösen

Feedback

Feedback

Zusätzliche Ressourcen

Freigeben über

Bewährte Softwareentwicklungsmethoden für Notebooks

Anforderungen

Schritt 1: Einrichten von Databricks Git-Ordnern

Schritt 1.1: Angeben Ihrer GitHub-Anmeldeinformationen

Schritt 1.2: Herstellen einer Verbindung mit Ihrem GitHub-Repository

Schritt 2: Importieren und Ausführen des Notebooks

Schritt 2.1: Erstellen eines Arbeitsbranchs im Repository

Schritt 2.2: Importieren des Notebooks in das Repository

Schritt 2.3: Ausführen des Notebooks

Schritt 2.4: Einchecken und Zusammenführen des Notebooks

Schritt 3: Verschieben von Code in ein freigegebenes Modul

Schritt 3.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Schritt 3.2: Importieren des Notebooks in das Repository

Schritt 3.3: Hinzufügen der unterstützenden freigegebenen Codefunktionen des Notebooks

Schritt 3.4: Hinzufügen der Abhängigkeiten des freigegebenen Codes

Schritt 3.5: Ausführen des umgestalteten Notebooks

Schritt 3.6: Einchecken des Notebooks und des zugehörigen Codes

Schritt 4: Testen des freigegebenen Codes

Schritt 4.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Schritt 4.2: Hinzufügen der Tests

Schritt 4.3: Ausführen der Tests

Schritt 4.4: Einchecken des Notebooks und der zugehörigen Tests

Schritt 5: Erstellen eines Auftrags zum Ausführen der Notebooks

Schritt 5.1: Erstellen einer Auftragsaufgabe zum Ausführen des Testnotebooks

Schritt 5.2: Erstellen einer Auftragsaufgabe zum Ausführen des Hauptnotebooks

Schritt 5.3: Ausführen des Auftrags

(Optional) Schritt 6: Einrichten des Repositorys, sodass der Code automatisch getestet und das Notebook ausgeführt wird, wenn sich der Code ändert

Schritt 6.1: Einrichten von GitHub-Zugriff auf Ihren Arbeitsbereich

Schritt 6.2: Hinzufügen des GitHub Actions-Workflows

(Optional) Schritt 7: Aktualisieren des freigegebenen Codes in GitHub, um Tests auszulösen

Schritt 7.1: Erstellen eines weiteren Arbeitsbranchs im Repository

Schritt 7.2: Ändern des freigegebenen Codes

Schritt 7.3: Einchecken der Änderung, um die Tests auszulösen

Feedback

Feedback

Zusätzliche Ressourcen