3. Gestión de datos históricos: objeto DataSource

DataSource es responsable de la interfaz con el almacenamiento de datos históricos local. Puede administrar el almacenamiento basado en archivos (como csv/hdf/feather) o el almacenamiento basado en bases de datos (como MySQL/MariaDB) y expone un esquema de tabla unificado y una interfaz de lectura a las capas superiores. La descarga de datos y las actualizaciones generalmente se realizan a través de qt.refill_data_source() en lugar de ser extraídas automáticamente por 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)[fuente]

Un objeto de punto de entrada unificado para gestionar el almacenamiento de datos históricos locales (archivos o bases de datos).

DataSource es responsable de interactuar con archivos o bases de datos locales, administrar de forma centralizada la lectura, escritura y descripción general de las tablas de datos históricos y garantizar que las estructuras de datos generadas puedan ser consumidas correctamente por HistoryPanel y las API de capa superior. Cuando faltan algunas tablas, DataSource no descargará datos automáticamente; en cambio, trabaja con funciones como refill_data_source para realizar el mantenimiento. Para conocer los tipos de archivos admitidos, los tipos de bases de datos y más detalles de inicialización, consulte la sección correspondiente de la documentación, «DataSource y fuentes de datos locales».

Ejemplos

El siguiente ejemplo muestra el nombre de clase DataSource (salida estable); en uso real, debe combinarlo con su directorio de datos local o los parámetros de conexión de la base de datos:

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

Obtenga la lista de todas las tablas de datos base

property all_data_tables: list

Obtenga la lista de todas las tablas de datos históricos (excluidas las tablas de ajuste)

property all_sys_tables: list

Obtenga la lista de todas las tablas de datos del sistema

property all_tables: list

Obtener la lista de todas las tablas de datos

property allow_drop_table: bool

Obtenga información sobre si se permite eliminar tablas de datos

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

Ejecute un contenedor de transacciones mínimo en DataSource (transacción de base de datos real; no operativa para el almacenamiento de archivos).

Parámetros:

  • action (Callable[..., Any]) – Invocable para ejecutarse dentro de la transacción

  • *args – Argumentos posicionales pasados ​​a action

  • **kwargs – Argumentos de palabras clave pasados ​​a action

Devuelve:

Valor de retorno de action

Tipo del valor devuelto:

Any

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

Eliminar ciertos registros de la tabla de datos del sistema; pasar los ID de los registros que se eliminarán como una lista o tupla

Parámetros:

  • table (str) – El nombre de la tabla cuyos datos deben eliminarse.

  • record_ids (list of int or tuple of int) – Lista de ID de registros para eliminar

Devuelve:

Número de registros eliminados

Tipo del valor devuelto:

int

drop_empty_tables() → int[fuente]

Elimine todas las tablas vacías de la fuente de datos, es decir, tablas con 0 filas

Devuelve:

Número de tablas eliminadas

Tipo del valor devuelto:

int

drop_table_data(table)[fuente]

Elimine una tabla de datos almacenada localmente (esta operación es irreversible; úsela con precaución). Si la fuente de datos tiene enable_drop_table establecido en False, la tabla de datos no se puede eliminar y se generará un error.

Parámetros:

table (str,) – Nombre de la tabla de datos local.

Tipo del valor devuelto:

None

Muestra:

RuntimeError – Cuando la fuente de datos tiene enable_drop_table establecido en False, no puede eliminar tablas y se generará un error:

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

Después de leer los datos de la tabla de datos, expórtelos a un archivo, lo que hace que sea conveniente para los usuarios transferir pequeñas cantidades de datos o ver datos durante el uso.

Al utilizar esta función, los usuarios no necesitan preocuparse por el tipo de fuente de datos. Solo necesitan especificar el nombre de la tabla y las condiciones del filtro. Los datos exportados se guardarán como un archivo CSV. Los usuarios pueden especificar ellos mismos el nombre del archivo y la ruta de almacenamiento. Si no se especifica ningún nombre de archivo, el nombre de la tabla se utiliza como nombre de archivo predeterminado. Si no se especifica ninguna ruta de almacenamiento, el directorio de trabajo actual se utiliza como ruta de almacenamiento predeterminada.

Parámetros:

  • table (str) – Nombre de la tabla

  • file_name (str, optional) – Nombre del archivo exportado. Si no se especifica, el nombre de la tabla se utiliza como nombre de archivo de forma predeterminada.

  • file_path (str, optional) – Ruta de almacenamiento del archivo exportado. Si no se especifica, el directorio de trabajo actual se utiliza de forma predeterminada como ruta de almacenamiento de archivos.

  • shares (list of str, optional) – condición de filtro ts_code; si está vacío, se devuelven todos los registros

  • start (DateTime like, optional) – Fecha en formato AAAAMMDD; si está vacío, no se aplica ningún filtrado

  • end (Datetime like，optional) – Fecha en formato AAAAMMDD. Efectivo cuando el inicio no está vacío; Se utiliza para filtrar el rango de fechas.

Devuelve:

file_path_name – Ruta completa del archivo exportado

Tipo del valor devuelto:

str

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

Una función para recuperar rápidamente todas las tablas de datos básicos. Normalmente, el almacenamiento en caché se utiliza para acelerar las cosas. Si refresco_cache se establece en Verdadero, el caché se borra y los datos se descargan nuevamente.

Parámetros:

  • refresh_cache (Bool, Default False) – Si es Verdadero, borre el caché y vuelva a descargar los datos.

  • raise_error (Bool, Default True) – Si es Verdadero, genera ValueError cuando la tabla de datos esté vacía.

Tipo del valor devuelto:

DataFrame

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

Obtenga la cantidad de espacio en disco utilizado por la tabla de datos.

Parámetros:

  • table (str) – Nombre de la tabla

  • human (bool, default True) – Cuando es Verdadero, se muestra en un formato fácil de leer, como 1,5 MB en lugar de 1590868; cuando es falso, devuelve el número de bytes.

  • string_form (bool, default True) – Cuando es Verdadero, devuelve el resultado como una cadena para facilitar la impresión.

Devuelve:

tuple (size, rows)

Tipo del valor devuelto:

tuple of int or str:

get_sys_table_last_id(table)[fuente]

Obtener el último ID de una tabla existente

Parámetros:

table (str) – Nombre de la tabla

Devuelve:

last_id

Tipo del valor devuelto:

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

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

Obtenga el rango de cobertura del contenido de la tabla de datos local: recupere los valores deduplicados de la columna «columna» de la tabla y devuélvalos.

Parámetros:

  • table (str,) – Nombre de la tabla de datos

  • column (str or list of str) – Columnas de datos que deben deduplicarse y devolverse

  • min_max_only (bool, default False) – Cuando es Verdadero, no es necesario devolver la columna de datos completa; solo devuelve los valores máximo y mínimo. Si solo se devuelven los valores máximo y mínimo, el valor devuelto es una lista que contiene dos elementos: el primer elemento es el valor mínimo, el segundo es el valor máximo y el tercero es el recuento total.

Tipo del valor devuelto:

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

Ejemplos

>>> 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[fuente]
Recuperar e imprimir información sobre la tabla, incluido si ya contiene datos, el volumen de datos, el uso de espacio en disco y el rango de cobertura de datos.

y el método de descarga de datos

3. Parameters

table: str

Nombre de la tabla

verbose: bool, Default: True

Ya sea para mostrar más información; si es así, muestre el esquema de la tabla y otros detalles.

print_info: bool, Default: True

Ya sea para imprimir todos los resultados.

human: bool, Default: True

Ya sea para proporcionar una representación de cadena fácil de leer.

Returns:

  • Un dictado que contiene información estructurada sobre la tabla de datos:

  • { – nombre de la tabla: 1, str, nombre de la tabla table_exists: 2, bool, si la tabla existe table_size: 3, int/str, espacio en disco utilizado por la tabla; cuando humano es Verdadero, devuelve una cadena fácil de leer table_rows: 4, int/str, número de filas en la tabla; cuando humano es Verdadero, devuelve una cadena fácil de leer clave_primaria1: 5, cadena, nombre de la primera clave primaria pk_count1: 6, int, recuento de registros para la primera clave primaria pk_min1: 7, obj, registro inicial de la clave primaria 1 pk_max1: 8, obj, registro final de la clave primaria 2 clave_primaria2: 9, cadena, nombre de la segunda clave primaria pk_count2: 10, int, recuento de registros para la segunda clave primaria pk_min2: 11, obj, registro inicial de la clave primaria 2 pk_max2: 12, obj, registro final de la clave primaria 2

  • }

info()[fuente]

Formatee e imprima diversa información clave sobre el objeto de la base de datos.

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

Insertar datos en la tabla de operaciones del sistema.

Inserte un registro a la vez; los datos se proporcionan como un dictado. No es necesario que proporciones los datos de identificación, ya que la identificación se generará automáticamente. Si los campos de datos proporcionados están incompletos, se genera una excepción. Si los datos proporcionados contienen campos no disponibles, se genera una excepción.

Parámetros:

  • table (str) – Nombre de la tabla a actualizar

  • data (dict) – Datos para actualizar o insertar. Las claves de los datos deben coincidir con los campos de la tabla de la base de datos; de lo contrario, se generará una excepción.

Devuelve:

record_id – ID del registro a actualizar

Tipo del valor devuelto:

int

Muestra:

KeyError – Cuando los campos proporcionados están incompletos o contienen campos no disponibles:

none_sys_tables() → list[fuente]

Obtenga una lista de todas las tablas que no pertenecen al sistema

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

Enumere el estado actual de los datos de todas las tablas de datos en forma tabular

Parámetros:

  • tables (str or list of str, Default None) – Especifique las tablas de datos que desea enumerar. Si no hay ninguno, enumere todas las tablas de datos.

  • print_out (bool, Default True) – Si se debe imprimir una descripción general de la tabla

  • include_sys_tables (bool, Default False) – Ya sea para incluir tablas del sistema

Tipo del valor devuelto:

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

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

Almacenar en caché los datos de la tabla de datos para reducir el tiempo de lectura. Esta función se utiliza para acelerar la extracción de datos locales.

Cuando un usuario utiliza un objeto DataType para leer grandes cantidades de datos, normalmente es necesario recuperar datos repetidamente de la misma tabla con los mismos parámetros. Para mejorar la velocidad de lectura, puede almacenar en caché los datos de la tabla en la memoria para reducir el tiempo de lectura. Sin embargo, en las operaciones normales de tablas, el almacenamiento en caché no es adecuado porque las tablas normalmente necesitan actualizarse en tiempo real. Por lo tanto, esta función es solo para que la utilicen objetos DataType al leer datos.

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

Lea los datos de la tabla de operaciones del sistema, incluida la lectura de todos los registros y la lectura de registros según las condiciones dadas.

El tipo de datos devuelto es pd.DataFrame. Si se proporcionan kwargs, devuelve los datos filtrados según las condiciones.

Parámetros:

  • table (str) – Nombre de la tabla de datos a leer.

  • kwargs (dict) – Condiciones para filtrar datos, incluido un diccionario utilizado como criterio de filtrado, por ejemplo: {account_id = 123}.

Devuelve:

Los datos devueltos son un DataFrame. Si se proporcionan kwargs, los datos devueltos incluyen solo los datos filtrados.

Tipo del valor devuelto:

pd.DataFrame

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

Leer datos de la tabla de operaciones del sistema. Lee datos por la identificación especificada y devuelve un dictado.

Esta función llama a read_sys_table_data() para leer la tabla completa y devuelve los datos de la fila record_id. El dictado devuelto contiene los valores de todos los campos, donde la clave es el nombre del campo y el valor es el valor del campo.

Parámetros:

  • table (str) – Nombre de la tabla de datos a leer.

  • record_id (int) – ID de los datos a leer.

  • kwargs (dict) – Condiciones de filtrado, incluido un diccionario utilizado como criterio de filtrado, por ejemplo: account_id = 123

Devuelve:

datos: los datos leídos, incluida la información del esquema de la tabla y los registros de la tabla.

Tipo del valor devuelto:

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[fuente]

Leer datos de una tabla local y devolver un DataFrame sin modificar el formato de los datos; clave_primaria se utiliza como índice de DataFrame.

Al leer la tabla, lea todas las columnas, pero en el valor de retorno filtre por ts_code y trade_date entre inicio y fin.

Parámetros:

  • table (str) – Nombre de la tabla

  • shares (str or list of str,) – Condición de filtro ts_code: una cadena separada por comas. Si está vacío, se devuelven todos los registros.

  • start (str，) – Fecha en formato AAAAMMDD; si está vacío, no se aplica ningún filtrado

  • end (str，) – Fecha en formato AAAAMMDD. Efectivo cuando el inicio no está vacío; Se utiliza para filtrar el rango de fechas.

  • primary_key_in_index (bool, default True) – Si se debe establecer la clave principal como índice del DataFrame. Si es falso, la clave principal se devolverá como una columna normal y el índice del marco de datos será el índice entero predeterminado.

Tipo del valor devuelto:

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

reconnect()[fuente]
Cuando la conexión a la base de datos se pierde debido a un tiempo de espera u otras razones, haga ping a la base de datos para verificar su estado.

Vuelva a conectarse a la base de datos si es posible.

Devuelve:

  • Verdadero (Conexión exitosa)

  • Falso (falló la conexión)

table_data_exists(table)[fuente]

Función de capa lógica que determina si la tabla existe

Parámetros:

table (数据表名称) –

Devuelve:

bool

Tipo del valor devuelto:

True if table exists, False otherwise

property tables: list

Una lista de todas las tablas que ya se han creado.

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

Actualizar datos en la tabla de operaciones del sistema. Actualice los datos según la identificación especificada; el contenido de la actualización lo proporciona kwargs.

Sólo se puede actualizar un registro a la vez. Los datos se proporcionan como un dictado. Se pueden actualizar uno o más campos. Si un campo proporcionado no existe, se genera una excepción. La identificación no se puede actualizar. La identificación debe existir; de lo contrario, se plantea una excepción.

Parámetros:

  • table (str) – Nombre de la tabla a actualizar

  • record_id (int) – La identificación de los datos que deben actualizarse.

  • data (dict) – Datos a actualizar, incluidos los campos a actualizar, por ejemplo: account_id = 123

Devuelve:

id – ID del registro a actualizar

Tipo del valor devuelto:

int

Muestra:

  • KeyError – Cuando la identificación proporcionada no existe o es Ninguna:

  • KeyError – Cuando el campo proporcionado no existe:

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

Verifique la entrada df. Después de eliminar columnas o filas que no cumplen con los requisitos, combine los datos en la tabla, incluidos los siguientes pasos:

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

Parámetros:

  • table (str,) – Nombre de la tabla; debe ser una tabla definida en la base de datos.

  • merge_type (str) –

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

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

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

  • df (pd.DataFrame) – Obtenga datos pasando un DataFrame. Si el canal de origen de datos es «df», se debe proporcionar este parámetro.

Tipo del valor devuelto:

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

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

Escriba los datos en df en la tabla de datos local (archivo local o base de datos).

Si la tabla de datos local no existe, cree una nueva tabla. Si la tabla de datos local ya existe, agregue los datos df a la tabla local. Si la clave principal de los datos adjuntos es la misma que la de los datos existentes, el método de manejo está determinado por el parámetro on_duplicate.

Parámetros:

  • df (pd.DataFrame) – Una tabla de datos cuyos nombres de columnas deben ser coherentes con la definición de la tabla local.

  • table (str) – Nombre de la tabla local,

  • on_duplicate (str) – Cómo manejar datos duplicados (solo efectivo cuando mode==db): -ignore: default; agregar todos los datos al final de la tabla de la base de datos -actualizar: escribir datos en la tabla de la base de datos; si se encuentra un paquete duplicado, modifique el contenido de la tabla

Devuelve:

int

Tipo del valor devuelto:

写入的数据条数

Notas

¡¡Advertencia!! No utilice esta función para escribir datos directamente en la base de datos local, porque los datos escritos no serán validados. Utilice update_table_data() para actualizar o escribir datos en la base de datos local.