Python 3.15 aktiviert den UTF-8-Modus standardmäßig und ändert damit die Standardkodierung für Textdateizugriffe. open() liest und schreibt Textdateien ohne explizites encoding dann als UTF-8 statt mit der Locale-Kodierung. Bei Windows-1252-Dateien scheitert ein solcher Import beispielsweise an einem ü mit einem UnicodeDecodeError.
Für die Migration sind explizite Kodierungsverträge wichtiger als die flächendeckende Umwandlung nach UTF-8: Ein ERP-Export mit zugesagtem Windows-1252-Format muss weiterhin mit dieser Kodierung gelesen werden.
Was ändert der UTF-8-Standard bei Dateiimporten?
Auch Path.read_text() und Path.write_text() verwenden ohne encoding den Standard der Textdateifunktionen. Auf Systemen, die bereits UTF-8 als Standard verwenden, ändert sich die Dateikodierung dadurch nicht. Binärzugriffe wie open("data.csv", "rb") lesen unverändert Bytes, ohne sie zu dekodieren.
Das Betriebssystem verrät nicht, welche Kodierung eine importierte Datei tatsächlich besitzt. Auch ein Linux-Dienst kann Windows-1252-Exporte erhalten; eine Windows-Anwendung kann längst ausschließlich UTF-8 austauschen. Entscheidend sind die Bytefolgen und die Formatvereinbarung mit dem Produzenten.
| Beobachtung | Konkrete Auswirkung |
|---|---|
| Dekodierungsfehler | Das Windows-1252-Byte 0xFC für ü ist keine gültige UTF-8-Bytefolge. Der UTF-8-Decoder meldet einen Fehler. |
| Abweichende Zeichen ohne Ausnahme | Der UTF-8-Decoder liest die Bytes 0xC3 0xBC als ü, der Windows-1252-Decoder als ü. Beide akzeptieren diese Bytes. |
| Geänderte Ausgabekodierung | War bisher Windows-1252 der Standard, schreibt ein Export ohne explizites Encoding im UTF-8-Modus ü als 0xC3 0xBC statt als 0xFC. |
Der erste Test zeigt, wie ein UTF-8-Leseversuch an einer Windows-1252-Datei scheitert.
Schritt 1: Einen Windows-1252-Importfehler reproduzieren
Die Datei repro_encoding.py erzeugt ihre Testdatei selbst. Das Skript schreibt den Text mit ü und € ausdrücklich mit cp1252, dem Python-Namen für Windows-1252. Dadurch hängt die Eingabedatei weder von einem Editor noch von der Locale des Rechners ab.
from pathlib import Path
from tempfile import TemporaryDirectory
expected = "name;betrag\nMüller;12 €\n"
with TemporaryDirectory() as directory:
path = Path(directory) / "preise.csv"
path.write_text(expected, encoding="cp1252")
try:
with path.open() as stream:
stream.read()
except UnicodeDecodeError as error:
print(type(error).__name__, error)
else:
raise AssertionError("Ein UTF-8-Dekodierungsfehler wurde erwartet")
assert path.read_text(encoding="cp1252") == expected
Unter Python 3.15 genügt bei unveränderter Standardkonfiguration python repro_encoding.py. Der folgende Aufruf erzwingt den UTF-8-Modus zusätzlich und reproduziert den Versuch auch mit älteren Python-Versionen, die diesen Modus unterstützen:
python -X utf8 repro_encoding.py
Der Decoder scheitert am Byte für ü. Das abschließende assert bestätigt dagegen den vollständigen Text einschließlich des Eurozeichens. Im Produktionscode lassen sich vergleichbare implizite Annahmen mit EncodingWarning aufspüren.
Schritt 2: Implizite Encoding-Annahmen finden
Seit Python 3.10 steht EncodingWarning zur Verfügung; standardmäßig ist diese Warnung deaktiviert. Mit folgendem Aufruf meldet Python unterstützte Dateioperationen, bei denen kein explizites Encoding angegeben wurde:
python -X warn_default_encoding import_script.py
Alternativ aktiviert die Umgebungsvariable PYTHONWARNDEFAULTENCODING=1 dieselbe Warnung. Erfasst werden nur ausgeführte Codepfade mit entsprechender Warnungsunterstützung. Ein Testlauf mit einer einzigen Importdatei deckt deshalb keine unbenutzten Exportfunktionen ab.
Eine Warnung verrät nicht, welche Kodierung der Dateiproduzent liefert. Für jeden Fund hältst du den Produzenten, die dokumentierte Kodierung und die betroffene Lese- oder Schreibstelle in einem Schnittstellenverzeichnis fest. Ungeklärte Kodierungen bleiben dort ausdrücklich als ungeklärt markiert.
Im eigenen Code ergänzt du das fehlende Argument. Bei Bibliotheken bestimmt deren Schnittstelle, ob sich die Kodierung als Parameter übergeben oder in einer Konfiguration festlegen lässt. Die konkrete Kodierung richtet sich in beiden Fällen nach dem vereinbarten Produzentenformat.
Schritt 3: Dateikodierungen als Schnittstellenvertrag festlegen
Eigene UTF-8-Austauschdateien erhalten beim Lesen und Schreiben encoding="utf-8". Für dokumentierte Windows-1252-Dateien lautet das Argument encoding="cp1252". Mit encoding="locale" wird dagegen ausdrücklich die Locale-Kodierung angefordert, wenn die Schnittstelle tatsächlich dieses Verhalten verlangt.
CSV-Encoding am Dateihandle konfigurieren
csv.reader verarbeitet bereits dekodierte Zeichenketten. Deshalb wird die Kodierung beim Öffnen der Textdatei festgelegt. Die Funktionen in import_csv.py verlangen das Argument encoding beim Aufruf; newline="" überlässt die Behandlung der CSV-Zeilenenden dem CSV-Modul.
import csv
def read_rows(path, *, encoding):
with open(path, encoding=encoding, newline="") as stream:
return list(csv.reader(stream, delimiter=";"))
def write_rows(path, rows, *, encoding):
with open(path, "w", encoding=encoding, newline="") as stream:
writer = csv.writer(stream, delimiter=";", lineterminator="\n")
writer.writerows(rows)
Mit PYTHONUTF8=0 oder -X utf8=0 lässt sich der UTF-8-Modus für einen Prozess deaktivieren. Windows-1252 ist damit nicht garantiert, denn die Locale kann selbst UTF-8 verwenden. Die Schalter ändern die Voreinstellung für alle betroffenen Textdateizugriffe des Prozesses, während ein encoding-Argument nur den jeweiligen Zugriff festlegt.
Bei einem verlustfreien Import bleibt die standardmäßige strikte Fehlerbehandlung aktiv. Mit errors="ignore" würden fehlerhafte Bytes verschwinden; errors="replace" würde Ersatzzeichen einsetzen. Die folgenden Tests kontrollieren deshalb den vollständigen Text und die exportierten Bytes.
Schritt 4: Dateiimporte mit Regressionstests absichern
Die Testdatei test_import_csv.py erzeugt UTF-8- und Windows-1252-Fixtures mit identischem Text. Beide enthalten ü und €. Neben einem absichtlich ausgelösten Dekodierungsfehler zeigt ein weiterer Test, dass das Lesen mit falscher Kodierung auch ohne Ausnahme gelingen kann.
import pytest
from import_csv import read_rows, write_rows
TEXT = "name;betrag\nMüller;12 €\n"
ROWS = [["name", "betrag"], ["Müller", "12 €"]]
@pytest.mark.parametrize("encoding", ["utf-8", "cp1252"])
def test_import_and_export(tmp_path, encoding):
source = tmp_path / "quelle.csv"
source.write_bytes(TEXT.encode(encoding))
assert read_rows(source, encoding=encoding) == ROWS
target = tmp_path / "export.csv"
write_rows(target, ROWS, encoding=encoding)
assert target.read_bytes() == TEXT.encode(encoding)
def test_wrong_encoding_fails(tmp_path):
source = tmp_path / "falsch_kodiert.csv"
source.write_bytes(TEXT.encode("cp1252"))
with pytest.raises(UnicodeDecodeError):
read_rows(source, encoding="utf-8")
def test_wrong_encoding_can_silently_change_text(tmp_path):
source = tmp_path / "utf8_als_cp1252.csv"
source.write_bytes(TEXT.encode("utf-8"))
rows = read_rows(source, encoding="cp1252")
assert rows != ROWS
assert rows[1][0] == "Müller"
Die beiden Module liegen im selben Verzeichnis. Mit installiertem pytest startet dort python -m pytest die Tests. Der letzte Test liest den Namen als Müller statt als Müller und zeigt damit, weshalb eine ausbleibende Ausnahme keine korrekte Dekodierung beweist.
In die CI-Matrix gehören die tatsächlich unterstützten Python-Versionen und Betriebssysteme, beispielsweise Python 3.14 und 3.15 auf Windows und Linux. Unter Python 3.14 testet python -X utf8 -X warn_default_encoding -m pytest die neue Voreinstellung bereits vor dem Versionswechsel. Für den Migrationsabschluss werden die Ergebnisse mit dem Schnittstellenverzeichnis abgeglichen.
Migrationscheckliste und nächster Schritt
- Du hast alle Dateiimporte und Dateiexporte einschließlich selten ausgeführter Codepfade inventarisiert
- Für jede Schnittstelle stehen der Produzent und die vereinbarte Kodierung fest
- Die Lese- und Schreiboperationen verwenden das vereinbarte Encoding explizit
- Regressionstests vergleichen die vollständigen Inhalte, prüfen zugesagte Exportbytes und erwarten bei bekannten ungültigen Eingaben einen Fehler
In der Übersicht der Python-Schulungen von cmt stehen die angebotenen Trainings. Ob eine Schulung Datei-I/O oder automatisierte Tests behandelt, geht aus ihrer Beschreibung hervor.
Die Byte-Prüfung meldet, wenn ein zugesagter Windows-1252-Export nach einer Änderung als UTF-8 geschrieben wird. Ergänze als nächsten Schritt bei einem bestehenden Import eine explizit kodierte Fixture samt exakter Inhaltsprüfung.