= files()
:description: Lädt alle Dateivarianten eines ECM-Dokumentobjekts vom Server (std.StoreInCacheById). Gibt eine Liste von JobResponseFile-Objekten mit Dateiinhalt und Metadaten zurück.
:keywords: files, StoreInCacheById, Dateivarianten, JobResponseFile, Dokument, Download
:page-tags: api, dms

Lädt die Dateien eines Dokumentobjekts vom Server über `std.StoreInCacheById`.
Das Dokument kann als Modell-Instanz oder direkt als numerische ID übergeben werden.
Optional können Dateien vor der Übertragung konvertiert oder Annotationen eingebrannt werden.

== Signatur

[tabs]
====
Sync::
+
[source,python]
----
ecm.dms.files(
    model: ECMDocumentModel | int,
    *,
    flags: int = 1,
    convert: StoreInCacheByIdConversion = StoreInCacheByIdConversion.NONE,
    when_cold_then_tiff: bool = False,
    add_annotations: bool = False,
) -> list[JobResponseFile]
----

Async::
+
[source,python]
----
await ecm.dms.files(
    model: ECMDocumentModel | int,
    *,
    flags: int = 1,
    convert: StoreInCacheByIdConversion = StoreInCacheByIdConversion.NONE,
    when_cold_then_tiff: bool = False,
    add_annotations: bool = False,
) -> list[JobResponseFile]
----
====

== Parameter

[cols="1,1,3"]
|===
|Parameter |Standard |Beschreibung

|`model`
|—
|`ECMDocumentModel`-Instanz (deren `id` wird verwendet) oder eine plain `int`-Dokument-ID.

|`flags`
|`1`
|Steuert, welche Dateien übertragen werden:

`0` — Dokumentdateien und die DIA-Datei werden übertragen. +
`1` — Nur die Dokumentdateien selbst (Standard). +
`2` — Nur die DIA-Datei des Objekts.

|`convert`
|`NONE`
|Optionale Konvertierung vor der Übertragung (`StoreInCacheByIdConversion`):

`NONE` — Keine Konvertierung (Standard). +
`PDF` — Dokumente der Haupttypen 1, 2, 3 oder 4 werden als PDF übertragen. +
`MULTIPAGE_TIFF` — TIFF-Dokumente der Haupttypen 2 oder 3 werden zu einer einzelnen mehrseitigen TIFF-Datei zusammengeführt.

|`when_cold_then_tiff`
|`False`
|Bei `True` werden ASCII-COLD-Dateien als TIFF zurückgegeben. Wird nur ausgewertet, wenn `convert=NONE`.

|`add_annotations`
|`False`
|Bei `True` werden Bild-Annotationen in die zurückgegebenen Dateien eingebrannt.
|===

== Rückgabewert

Liste von `JobResponseFile`-Objekten. Kleine Dateien werden als Byte-Array im Speicher gehalten,
größere Dateien werden in eine temporäre Datei auf dem Dateisystem geschrieben.

Eigenschaften und Methoden von `JobResponseFile`:

[cols="1,3"]
|===
|Eigenschaft / Methode |Beschreibung

|`.name`
|Dateiname inkl. Endung (z.B. `"rechnung.pdf"`).

|`.extension`
|Dateiendung (z.B. `".pdf"`).

|`.size()`
|Dateigröße in Bytes.

|`.bytes()`
|Dateiinhalt als `bytes`. Bei Dateipfad-Typ wird der Inhalt beim ersten Aufruf gelesen und im Speicher gecacht.

|`.store(path=None)`
|Schreibt die Datei auf den Datenträger. Ohne `path` wird das Systemverzeichnis für temporäre Dateien verwendet. Gibt den Speicherpfad zurück.
|===

== Ausnahmen

`ValueError`:: `model` ist eine `ECMDocumentModel`-Instanz mit `id = None`.

== Beispiele

=== Dateien einer Modell-Instanz laden

[tabs]
====
Sync::
+
[source,python]
----
document = ecm.dms.get(InvoiceDocument, 12345)
for f in ecm.dms.files(document):
    print(f.name, f.size())
    content = f.bytes()
----

Async::
+
[source,python]
----
document = await ecm.dms.get(InvoiceDocument, 12345)
for f in await ecm.dms.files(document):
    print(f.name, f.size())
    content = f.bytes()
----
====

=== Dateien per plain ID laden

Ist die Dokument-ID bekannt, muss das Objekt nicht vollständig geladen werden:

[tabs]
====
Sync::
+
[source,python]
----
for f in ecm.dms.files(12345):
    print(f.name, f.size())
----

Async::
+
[source,python]
----
for f in await ecm.dms.files(12345):
    print(f.name, f.size())
----
====

=== Als PDF laden

Dokumente der Haupttypen 1–4 werden vor der Übertragung serverseitig als PDF konvertiert:

[tabs]
====
Sync::
+
[source,python]
----
from ecmind_blue_client import StoreInCacheByIdConversion

files = ecm.dms.files(12345, convert=StoreInCacheByIdConversion.PDF)
pdf = files[0]
print(pdf.name)          # z.B. "rechnung.pdf"
pdf.store("/tmp/rechnung.pdf")
----

Async::
+
[source,python]
----
from ecmind_blue_client import StoreInCacheByIdConversion

files = await ecm.dms.files(12345, convert=StoreInCacheByIdConversion.PDF)
pdf = files[0]
pdf.store("/tmp/rechnung.pdf")
----
====

=== Als mehrseitige TIFF-Datei laden

TIFF-Dokumente (Haupttypen 2 oder 3) werden zu einer einzigen mehrseitigen TIFF-Datei zusammengeführt:

[tabs]
====
Sync::
+
[source,python]
----
from ecmind_blue_client import StoreInCacheByIdConversion

files = ecm.dms.files(12345, convert=StoreInCacheByIdConversion.MULTIPAGE_TIFF)
tiff = files[0]
tiff.store("/tmp/dokument.tiff")
----

Async::
+
[source,python]
----
from ecmind_blue_client import StoreInCacheByIdConversion

files = await ecm.dms.files(12345, convert=StoreInCacheByIdConversion.MULTIPAGE_TIFF)
tiff = files[0]
tiff.store("/tmp/dokument.tiff")
----
====

=== Mit eingebrannten Annotationen laden

[tabs]
====
Sync::
+
[source,python]
----
files = ecm.dms.files(12345, add_annotations=True)
for f in files:
    f.store(f"/tmp/{f.name}")
----

Async::
+
[source,python]
----
files = await ecm.dms.files(12345, add_annotations=True)
for f in files:
    f.store(f"/tmp/{f.name}")
----
====

=== Alle Dateien eines Abfrageergebnisses herunterladen

[tabs]
====
Sync::
+
[source,python]
----
import os

output_dir = "/tmp/rechnungen"
os.makedirs(output_dir, exist_ok=True)

for doc in ecm.dms.select(InvoiceDocument).where(InvoiceDocument.Year == 2024).stream():
    for f in ecm.dms.files(doc):
        f.store(os.path.join(output_dir, f"{doc.system.id}_{f.name}"))
----

Async::
+
[source,python]
----
import os

output_dir = "/tmp/rechnungen"
os.makedirs(output_dir, exist_ok=True)

async for doc in ecm.dms.select(InvoiceDocument).where(InvoiceDocument.Year == 2024).stream():
    for f in await ecm.dms.files(doc):
        f.store(os.path.join(output_dir, f"{doc.system.id}_{f.name}"))
----
====

== Siehe auch

* xref:api/dms/get.adoc[get()] — Einzelnes Dokument anhand seiner ID laden
* xref:api/dms/insert.adoc[insert()] — Neues Dokument mit Datei anlegen
* xref:api/dms/update.adoc[update()] — Datei eines bestehenden Dokuments ersetzen
