delete_user_data()

Löscht den über Name und Typ bestimmten benutzerbezogenen Datensatz des aktuell angemeldeten Benutzers über dms.DeleteUserData.

Das ist das Gegenstück zu set_user_data(). Ein Datensatz mit einem leeren Wert zu überschreiben entfernt ihn nicht — das tut nur delete_user_data().

1. Signatur

  • Sync

  • Async

ecm.system.delete_user_data(
    name: str,
    data_type: ECMUserDataType | int,
) -> None
await ecm.system.delete_user_data(
    name: str,
    data_type: ECMUserDataType | int,
) -> None

2. Parameter

Parameter Typ Standard Beschreibung

name

str

—

Bezeichner des Datensatzes (max. 100 Zeichen). Die Suche unterscheidet keine Gross- und Kleinschreibung.

data_type

ECMUserDataType | int

—

Typkennung. ECMUserDataType enthält die dokumentierten Standard-Typen (z. B. STORED_QUERIES, EXTERNAL_PROGRAMS, AS_INI, ADDITIONAL_APP_CONFIG_80…85). Eigene registrierte Typen können als int übergeben werden.

3. Rückgabewert

Keiner. Liefert der Server-Job einen Fehlercode, wird eine Exception ausgelöst.

4. Wichtig: Löschen ist nicht idempotent

Der Server akzeptiert das Löschen eines nicht vorhandenen Datensatzes nicht. Er antwortet mit dem Ergebniscode -1, den der Client als ECMException auslöst:

from ecmind_blue_client.ecm import ECMException, ECMUserDataType

try:
    ecm.system.delete_user_data("nie_gespeichert", ECMUserDataType.ADDITIONAL_APP_CONFIG_80)
except ECMException:
    pass  # der Datensatz war bereits weg

Dasselbe gilt, wenn der Name zwar existiert, aber unter einem anderen Typ — Name und Typ zusammen bestimmen den Datensatz.

Soll nur gelöscht werden, wenn der Datensatz vorhanden ist, vorher prüfen:

if ecm.system.get_user_data("my_settings", ECMUserDataType.ADDITIONAL_APP_CONFIG_80) is not None:
    ecm.system.delete_user_data("my_settings", ECMUserDataType.ADDITIONAL_APP_CONFIG_80)

5. Wichtig: leerer Wert vs. gelöschter Datensatz

Einen leeren Wert zu speichern hinterlässt eine Zeile. Der Datensatz existiert weiterhin, liefert beim Lesen b"" (bzw. "") statt None und wird von get_user_data_names() weiterhin aufgeführt:

from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

ecm.system.set_user_data("my_settings", SLOT, b"")
assert ecm.system.get_user_data("my_settings", SLOT) == b""          (1)
assert "MY_SETTINGS" in ecm.system.get_user_data_names(SLOT)

ecm.system.delete_user_data("my_settings", SLOT)
assert ecm.system.get_user_data("my_settings", SLOT) is None         (2)
assert "MY_SETTINGS" not in ecm.system.get_user_data_names(SLOT)
1 Leerer Wert — die Zeile ist noch da.
2 Gelöscht — die Zeile ist weg.

6. Beispiele

6.1. Round Trip

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

ecm.system.set_user_data("my_app_config", SLOT, b'{"schema": 1}')
assert ecm.system.get_user_data("my_app_config", SLOT) is not None

ecm.system.delete_user_data("my_app_config", SLOT)
assert ecm.system.get_user_data("my_app_config", SLOT) is None
from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

await ecm.system.set_user_data("my_app_config", SLOT, b'{"schema": 1}')
assert await ecm.system.get_user_data("my_app_config", SLOT) is not None

await ecm.system.delete_user_data("my_app_config", SLOT)
assert await ecm.system.get_user_data("my_app_config", SLOT) is None

6.2. Alle Datensätze eines Typs entfernen

from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

for name in ecm.system.get_user_data_names(SLOT):
    ecm.system.delete_user_data(name, SLOT)

7. Siehe auch

  • get_user_data() — Wert lesen

  • set_user_data() — Wert speichern oder überschreiben

  • get_user_data_names() — alle Namen für einen Typ auflisten

  • dms.IsUserData — Existenz prüfen (noch nicht in der Python-API; mit get_user_data() is not None lässt sich dasselbe erreichen)