3. Verwalten historischer Daten – DataSource-Objekt

DataSource ist für die Schnittstelle zum lokalen historischen Datenspeicher verantwortlich. Es kann dateibasierten Speicher (z. B. CSV/HDF/Feather) oder datenbankbasierten Speicher (z. B. MySQL/MariaDB) verwalten und stellt den oberen Schichten ein einheitliches Tabellenschema und eine Leseschnittstelle zur Verfügung. Das Herunterladen und Aktualisieren von Daten erfolgt normalerweise über „qt.refill_data_source()“ und nicht automatisch über DataSource.

class qteasy.DataSource(source_type: str = 'file', file_type: str = 'csv', file_loc: str = 'data/', host: str = 'localhost', port: int = 3306, user: Optional[str] = None, password: Optional[str] = None, db_name: str = 'qt_db', allow_drop_table: bool = False)[Quellcode]

Ein einheitliches Einstiegspunktobjekt zur Verwaltung des lokalen historischen Datenspeichers (Dateien oder Datenbanken).

DataSource ist für die Interaktion mit lokalen Dateien oder Datenbanken, die zentrale Verwaltung des Lesens, Schreibens und der Übersicht historischer Datentabellen verantwortlich und stellt sicher, dass die generierten Datenstrukturen von HistoryPanel und APIs der oberen Ebene korrekt verwendet werden können. Wenn einige Tabellen fehlen, lädt DataSource selbst die Daten nicht automatisch herunter; Stattdessen arbeitet es mit Funktionen wie „refill_data_source“, um Wartungsarbeiten durchzuführen. Informationen zu unterstützten Dateitypen, Datenbanktypen und weiteren Initialisierungsdetails finden Sie im entsprechenden Abschnitt der Dokumentation, „DataSource und lokale Datenquellen“.

Examples

Das folgende Beispiel zeigt den Klassennamen DataSource (stabile Ausgabe); Bei der tatsächlichen Verwendung müssen Sie es mit den Verbindungsparametern Ihres lokalen Datenverzeichnisses oder Ihrer Datenbank kombinieren:

>>> import qteasy as qt
>>> qt.DataSource.__name__
'DataSource'
property all_basic_tables: list

Rufen Sie die Liste aller Basisdatentabellen ab

property all_data_tables: list

Rufen Sie die Liste aller historischen Datentabellen ab (ausgenommen Anpassungstabellen).

property all_sys_tables: list

Rufen Sie die Liste aller Systemdatentabellen ab

property all_tables: list

Rufen Sie die Liste aller Datentabellen ab

property allow_drop_table: bool

Ermitteln Sie, ob das Löschen von Datentabellen zulässig ist

db_run_in_transaction(action: Callable[[...], Any], *args, **kwargs) → Any[Quellcode]

Führen Sie einen minimalen Transaktions-Wrapper auf DataSource aus (echte DB-Transaktion; kein Betrieb für die Dateispeicherung).

Parameter:

  • action (Callable[..., Any]) – Zur Ausführung innerhalb der Transaktion aufrufbar

  • *args – An „action“ übergebene Positionsargumente

  • **kwargs – An „action“ übergebene Schlüsselwortargumente

Rückgabe:

Rückgabewert von „action“.

Rückgabetyp:

Any

delete_sys_table_data(table: str, record_ids: (<class 'list'>, <class 'tuple'>)) → int[Quellcode]

Bestimmte Datensätze aus der Systemdatentabelle löschen; Übergeben Sie die IDs der zu löschenden Datensätze als Liste oder Tupel

Parameter:

  • table (str) – Der Name der Tabelle, deren Daten gelöscht werden müssen

  • record_ids (list of int or tuple of int) – Liste der IDs der zu löschenden Datensätze

Rückgabe:

Anzahl der gelöschten Datensätze

Rückgabetyp:

int

drop_empty_tables() → int[Quellcode]

Löschen Sie alle leeren Tabellen aus der Datenquelle, d. h. Tabellen mit 0 Zeilen

Rückgabe:

Anzahl der gelöschten Tabellen

Rückgabetyp:

int

drop_table_data(table)[Quellcode]

Löschen Sie eine lokal gespeicherte Datentabelle (dieser Vorgang ist irreversibel; mit Vorsicht verwenden). Wenn „allow_drop_table“ für die Datenquelle auf „False“ gesetzt ist, kann die Datentabelle nicht gelöscht werden und es wird ein Fehler ausgegeben.

Parameter:

table (str,) – Name der lokalen Datentabelle

Rückgabetyp:

None

Verursacht:

RuntimeError – Wenn für die Datenquelle „allow_drop_table“ auf „False“ gesetzt ist, können Sie keine Tabellen löschen und es wird ein Fehler ausgegeben:

export_table_data(table, file_name=None, file_path=None, shares=None, start=None, end=None)[Quellcode]

Nachdem Sie die Daten aus der Datentabelle gelesen haben, exportieren Sie sie in eine Datei, sodass Benutzer bequem kleine Datenmengen übertragen oder Daten während der Verwendung anzeigen können.

Bei Verwendung dieser Funktion müssen sich Benutzer nicht um die Art der Datenquelle kümmern. Sie müssen lediglich den Tabellennamen und die Filterbedingungen angeben. Die exportierten Daten werden als CSV-Datei gespeichert. Benutzer können den Dateinamen und den Speicherpfad selbst festlegen. Wenn kein Dateiname angegeben wird, wird der Tabellenname als Standarddateiname verwendet. Wenn kein Speicherpfad angegeben ist, wird das aktuelle Arbeitsverzeichnis als Standardspeicherpfad verwendet.

Parameter:

  • table (str) – Tabellenname

  • file_name (str, optional) – Name der exportierten Datei. Wenn nicht angegeben, wird standardmäßig der Tabellenname als Dateiname verwendet

  • file_path (str, optional) – Speicherpfad für die exportierte Datei. Wenn nicht angegeben, wird standardmäßig das aktuelle Arbeitsverzeichnis als Dateispeicherpfad verwendet.

  • shares (list of str, optional) – ts_code-Filterbedingung; wenn leer, werden alle Datensätze zurückgegeben

  • start (DateTime like, optional) – Datum im Format JJJJMMTT; Wenn es leer ist, wird keine Filterung angewendet

  • end (Datetime like，optional) – Datum im Format JJJJMMTT. Wirksam, wenn Start nicht leer ist; Wird zum Filtern des Datumsbereichs verwendet.

Rückgabe:

Dateipfadname – Vollständiger Pfad der exportierten Datei

Rückgabetyp:

str

get_all_basic_table_data(refresh_cache=False, raise_error=True)[Quellcode]

Eine Funktion zum schnellen Abrufen aller Basisdatentabellen. Typischerweise wird Caching verwendet, um Dinge zu beschleunigen. Wenn „refresh_cache“ auf „True“ gesetzt ist, wird der Cache geleert und die Daten werden erneut heruntergeladen.

Parameter:

  • refresh_cache (Bool, Default False) – Wenn True, leeren Sie den Cache und laden Sie die Daten erneut herunter.

  • raise_error (Bool, Default True) – Wenn True, wird ValueError ausgelöst, wenn die Datentabelle leer ist.

Rückgabetyp:

DataFrame

get_data_table_size(table, human=True, string_form=True)[Quellcode]

Rufen Sie den von der Datentabelle verwendeten Speicherplatz ab.

Parameter:

  • table (str) – Tabellenname

  • human (bool, default True) – Wenn True, wird es in einem leicht lesbaren Format angezeigt, z. B. 1,5 MB statt 1590868; Wenn False, wird die Anzahl der Bytes zurückgegeben.

  • string_form (bool, default True) – Wenn True, wird das Ergebnis zum einfacheren Drucken als Zeichenfolge zurückgegeben

Rückgabe:

tuple (size, rows)

Rückgabetyp:

tuple of int or str:

get_sys_table_last_id(table)[Quellcode]

Holen Sie sich die letzte ID aus einer vorhandenen Tabelle

Parameter:

table (str) – Tabellenname

Rückgabe:

last_id

Rückgabetyp:

int 当前使用的最后一个ID（自增ID）

get_table_data_coverage(table, column, min_max_only=False)[Quellcode]

Ermitteln Sie den Abdeckungsbereich des Inhalts der lokalen Datentabelle: Rufen Sie die deduplizierten Werte aus der Spalte „Spalte“ der Tabelle ab und geben Sie sie zurück.

Parameter:

  • table (str,) – Name der Datentabelle

  • column (str or list of str) – Datenspalten, die dedupliziert und zurückgegeben werden müssen

  • min_max_only (bool, default False) – Bei „True“ ist es nicht erforderlich, die gesamte Datenspalte zurückzugeben. Gibt nur die Maximal- und Minimalwerte zurück. Wenn nur die Maximal- und Minimalwerte zurückgegeben werden, ist der Rückgabewert eine Liste mit zwei Elementen: Das erste Element ist der Minimalwert, das zweite der Maximalwert und das dritte die Gesamtzahl.

Rückgabetyp:

List, 代表数据覆盖范围的列表

Examples

>>> import qteasy
>>> qteasy.QT_DATA_SOURCE.get_table_data_coverage('stock_daily', 'ts_code')
Out:
['000001.SZ',
 '000002.SZ',
 '000003.SZ',
 '000004.SZ',
 '000005.SZ',
 '000006.SZ',
 ...,
 '002407.SZ',
 '002408.SZ',
 '002409.SZ',
 '002410.SZ',
 '002411.SZ',
 ...]
>>> import qteasy as qt
>>> qt.QT_DATA_SOURCE.get_table_data_coverage('stock_daily', 'ts_code', min_max_only=True)
Out:
['000001.SZ', '873593.BJ']
get_table_info(table, verbose=True, print_info=True, human=True) → dict[Quellcode]
Rufen Sie Informationen über die Tabelle ab und drucken Sie sie aus, einschließlich der Frage, ob sie bereits Daten enthält, des Datenvolumens, der Speicherplatznutzung und des Datenabdeckungsbereichs.

und die Datendownload-Methode

3. Parameters:

table: str

Tabellenname

verbose: bool, Default: True

Ob weitere Informationen angezeigt werden sollen; Wenn ja, zeigen Sie das Tabellenschema und andere Details an.

print_info: bool, Default: True

Ob alle Ergebnisse gedruckt werden sollen.

human: bool, Default: True

Ob eine leicht lesbare Zeichenfolgendarstellung bereitgestellt werden soll.

returns:

  • Ein Diktat, das strukturierte Informationen über die Datentabelle enthält:

  • { – Tabellenname: 1, str, Tabellenname table_exists: 2, bool, ob die Tabelle existiert table_size: 3, int/str, von der Tabelle verwendeter Speicherplatz; Wenn „human“ True ist, wird eine leicht lesbare Zeichenfolge zurückgegeben. table_rows: 4, int/str, Anzahl der Zeilen in der Tabelle; Wenn „human“ True ist, wird eine leicht lesbare Zeichenfolge zurückgegeben. Primary_key1: 5, str, Name des ersten Primärschlüssels. pk_count1: 6, int, Datensatzanzahl für den ersten Primärschlüssel für den zweiten Primärschlüssel pk_min2: 11, obj, Startdatensatz von Primärschlüssel 2 pk_max2: 12, obj, Enddatensatz von Primärschlüssel 2

  • }

info()[Quellcode]

Formatieren und drucken Sie verschiedene wichtige Informationen zum Datenbankobjekt

insert_sys_table_data(table: str, **data) → int[Quellcode]

Fügen Sie Daten in die Systembetriebstabelle ein.

Fügen Sie jeweils einen Datensatz ein. Die Daten werden als Diktat bereitgestellt. Sie müssen die Daten-ID nicht angeben, da die ID automatisch generiert wird. Wenn die bereitgestellten Datenfelder unvollständig sind, wird eine Ausnahme ausgelöst. Wenn die bereitgestellten Daten nicht verfügbare Felder enthalten, wird eine Ausnahme ausgelöst.

Parameter:

  • table (str) – Name der zu aktualisierenden Tabelle

  • data (dict) – Daten zum Aktualisieren oder Einfügen. Die Schlüssel in den Daten müssen mit den Feldern in der Datenbanktabelle übereinstimmen; andernfalls wird eine Ausnahme ausgelöst.

Rückgabe:

record_id – ID des zu aktualisierenden Datensatzes

Rückgabetyp:

int

Verursacht:

KeyError – Wenn die bereitgestellten Felder unvollständig sind oder nicht verfügbare Felder enthalten:

none_sys_tables() → list[Quellcode]

Rufen Sie eine Liste aller Nicht-Systemtabellen ab

overview(tables=None, print_out=True, include_sys_tables=False) → DataFrame[Quellcode]

Listen Sie den aktuellen Datenstand aller Datentabellen tabellarisch auf

Parameter:

  • tables (str or list of str, Default None) – Geben Sie die aufzulistenden Datentabellen an. Wenn „Keine“, werden alle Datentabellen aufgelistet.

  • print_out (bool, Default True) – Ob eine Tabellenübersicht gedruckt werden soll

  • include_sys_tables (bool, Default False) – Ob Systemtabellen einbezogen werden sollen

Rückgabetyp:

pd.DataFrame, 包含所有数据表的数据状态

read_cached_table_data(table: str, *, shares: str = None, start: str = None, end: str = None, primary_key_in_index: bool = True) → DataFrame[Quellcode]

Datentabellendaten zwischenspeichern, um die Lesezeit zu verkürzen. Diese Funktion wird verwendet, um die lokale Datenextraktion zu beschleunigen.

Wenn ein Benutzer ein DataType-Objekt zum Lesen großer Datenmengen verwendet, ist es normalerweise erforderlich, wiederholt Daten aus derselben Tabelle mit denselben Parametern abzurufen. Um die Lesegeschwindigkeit zu verbessern, können Sie die Tabellendaten im Speicher zwischenspeichern, um die Lesezeit zu verkürzen. Bei normalen Tabellenoperationen ist das Caching jedoch nicht geeignet, da Tabellen normalerweise in Echtzeit aktualisiert werden müssen. Daher ist diese Funktion nur für DataType-Objekte zum Lesen von Daten vorgesehen.

read_sys_table_data(table, **kwargs) → DataFrame[Quellcode]

Lesen Sie Daten aus der Systembetriebstabelle, einschließlich des Lesens aller Datensätze und des Lesens von Datensätzen basierend auf den angegebenen Bedingungen.

Der zurückgegebene Datentyp ist pd.DataFrame. Wenn Kwargs bereitgestellt werden, werden die gemäß den Bedingungen gefilterten Daten zurückgegeben.

Parameter:

  • table (str) – Name der zu lesenden Datentabelle.

  • kwargs (dict) – Bedingungen zum Filtern von Daten, einschließlich eines Wörterbuchs, das als Filterkriterium verwendet wird, z. B.: {account_id = 123}.

Rückgabe:

Die zurückgegebenen Daten sind ein DataFrame. Wenn Kwargs bereitgestellt werden, umfassen die zurückgegebenen Daten nur die gefilterten Daten.

Rückgabetyp:

pd.DataFrame

read_sys_table_record(table, *, record_id: int, **kwargs) → dict[Quellcode]

Lesen Sie Daten aus der Systembetriebstabelle. Liest Daten anhand der angegebenen ID und gibt ein Diktat zurück.

Diese Funktion ruft read_sys_table_data() auf, um die gesamte Tabelle zu lesen und gibt die Daten für die Zeile „record_id“ zurück. Das zurückgegebene Diktat enthält die Werte aller Felder, wobei der Schlüssel der Feldname und der Wert der Feldwert ist.

Parameter:

  • table (str) – Name der zu lesenden Datentabelle.

  • record_id (int) – ID der zu lesenden Daten.

  • kwargs (dict) – Filterbedingungen, einschließlich eines Wörterbuchs, das als Filterkriterium verwendet wird, z. B.: account_id = 123

Rückgabe:

Daten – Die gelesenen Daten, einschließlich der Schemainformationen der Tabelle und der Datensätze in der Tabelle.

Rückgabetyp:

dict

read_table_data(table, *, shares: Optional[Union[str, list]] = None, start: Optional[str] = None, end: Optional[str] = None, primary_key_in_index: bool = True) → DataFrame[Quellcode]

Daten aus einer lokalen Tabelle lesen und einen DataFrame zurückgeben, ohne das Datenformat zu ändern; Primary_key wird als DataFrame-Index verwendet.

Lesen Sie beim Lesen der Tabelle alle Spalten, filtern Sie jedoch im Rückgabewert nach ts_code und trade_date zwischen Start und Ende.

Parameter:

  • table (str) – Tabellenname

  • shares (str or list of str,) – ts_code-Filterbedingung: eine durch Kommas getrennte Zeichenfolge. Wenn leer, werden alle Datensätze zurückgegeben.

  • start (str，) – Datum im Format JJJJMMTT; Wenn es leer ist, wird keine Filterung angewendet

  • end (str，) – Datum im Format JJJJMMTT. Wirksam, wenn Start nicht leer ist; Wird zum Filtern des Datumsbereichs verwendet.

  • primary_key_in_index (bool, default True) – Ob der Primärschlüssel als DataFrame-Index festgelegt werden soll. Bei False wird der Primärschlüssel als reguläre Spalte zurückgegeben und der DataFrame-Index ist der Standard-Integer-Index.

Rückgabetyp:

pd.DataFrame 返回数据表中的数据

reconnect()[Quellcode]
Wenn die Datenbankverbindung aufgrund einer Zeitüberschreitung oder aus anderen Gründen verloren geht, pingen Sie die Datenbank an, um ihren Status zu überprüfen.

Stellen Sie nach Möglichkeit erneut eine Verbindung zur Datenbank her.

Rückgabe:

  • True (Verbindung erfolgreich)

  • Falsch (Verbindung fehlgeschlagen)

table_data_exists(table)[Quellcode]

Logikschichtfunktion, die bestimmt, ob die Tabelle vorhanden ist

Parameter:

table (数据表名称) –

Rückgabe:

bool

Rückgabetyp:

True if table exists, False otherwise

property tables: list

Eine Liste aller bereits erstellten Tabellen

update_sys_table_data(table: str, record_id: int, **data) → int[Quellcode]

Aktualisieren Sie die Daten in der Systembetriebstabelle. Aktualisieren Sie die Daten anhand der angegebenen ID. Der Update-Inhalt wird von kwargs bereitgestellt.

Es kann jeweils nur ein Datensatz aktualisiert werden. Die Daten werden als Diktat bereitgestellt. Ein oder mehrere Felder können aktualisiert werden. Wenn ein bereitgestelltes Feld nicht vorhanden ist, wird eine Ausnahme ausgelöst. Die ID kann nicht aktualisiert werden. Die ID muss vorhanden sein; andernfalls wird eine Ausnahme ausgelöst.

Parameter:

  • table (str) – Name der zu aktualisierenden Tabelle

  • record_id (int) – Die ID der Daten, die aktualisiert werden müssen

  • data (dict) – Zu aktualisierende Daten, einschließlich der zu aktualisierenden Felder, z. B.: account_id = 123

Rückgabe:

id – ID des zu aktualisierenden Datensatzes

Rückgabetyp:

int

Verursacht:

  • KeyError – Wenn die angegebene ID nicht existiert oder None ist:

  • KeyError – Wenn das bereitgestellte Feld nicht vorhanden ist:

update_table_data(table, df, merge_type='update') → int[Quellcode]

Überprüfen Sie die Eingabe df. Nachdem Sie Spalten oder Zeilen entfernt haben, die nicht den Anforderungen entsprechen, führen Sie die Daten in der Tabelle zusammen, einschließlich der folgenden Schritte:

1，检查下载后的数据表的列名是否与数据表的定义相同，删除多余的列 2，如果datasource type是“db“，删除下载数据中与本地数据重复的部分，仅保留新增数据 3，如果datasource type是“file“，将下载的数据与本地数据合并并去重 返回处理完毕的dataFrame

Parameter:

  • table (str,) – Tabellenname; muss eine in der Datenbank definierte Tabelle sein.

  • merge_type (str) –

    指定如何合并下载数据和本地数据： - ‚update‘: 默认值，如果下载数据与本地数据重复，用下载数据替代本地数据；

    对 table_usage=='basics' 的表在重复主键上仅当下载字段非空时才覆盖该列（patch）， 避免稀疏通道（如 AKShare）用空行业/日期等冲掉既有 Tushare 元数据

    • ‘ignore‘ : 如果下载数据与本地数据重复，忽略重复部分

  • df (pd.DataFrame) – Rufen Sie Daten ab, indem Sie einen DataFrame übergeben. Wenn der Datenquellenkanal „df“ ist, muss dieser Parameter angegeben werden.

Rückgabetyp:

int, 写入数据表中的数据的行数

write_table_data(df, table, on_duplicate='ignore')[Quellcode]

Schreiben Sie die Daten in df in die lokale Datentabelle (lokale Datei oder Datenbank).

Wenn die lokale Datentabelle nicht vorhanden ist, erstellen Sie eine neue Tabelle. Wenn die lokale Datentabelle bereits vorhanden ist, hängen Sie die DF-Daten an die lokale Tabelle an. Wenn der Primärschlüssel der angehängten Daten mit den vorhandenen Daten übereinstimmt, wird die Verarbeitungsmethode durch den Parameter on_duplicate bestimmt

Parameter:

  • df (pd.DataFrame) – Eine Datentabelle, deren Spaltennamen mit der lokalen Tabellendefinition übereinstimmen sollten.

  • table (str) – Lokaler Tabellenname,

  • on_duplicate (str) – So gehen Sie mit doppelten Daten um (nur wirksam, wenn mode==db): -ignore: default; Alle Daten an das Ende der Datenbanktabelle anhängen -update: Daten in die Datenbanktabelle schreiben; Wenn ein doppeltes Paket gefunden wird, ändern Sie den Inhalt der Tabelle

Rückgabe:

int

Rückgabetyp:

写入的数据条数

Notes

Warnung!! Verwenden Sie diese Funktion nicht, um Daten direkt in die lokale Datenbank zu schreiben, da die geschriebenen Daten nicht validiert werden. Bitte verwenden Sie update_table_data(), um Daten in die lokale Datenbank zu aktualisieren oder zu schreiben.