Metadata-Version: 2.1
Name: k2magic
Version: 0.1.8
Summary: K2data内部的数据分析工具包
Home-page: https://www.k2data.com.cn
Author: K2data
Author-email: admin@k2data.com.cn
License: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: requests
Requires-Dist: sqlalchemy

# k2magic
K2Magic是K2Assets提供的数据分析开发包（以下简称SDK），用于简化Python里访问各类数据库的操作。

## 安装sdk

执行以下命令安装：
```
pip install k2magic
```

## 使用sdk

### 基本用法

假设数据库里有关系表table1的结构如下::
```
CREATE TABLE table1 (
    k_device VARCHAR(255) PRIMARY KEY,
    col1 FLOAT,
    col2 FLOAT,
    col3 FLOAT
);
```

对上述关系表操作的示例代码：
```
import pandas as pd
from k2magic.dataframe_db import DataFrameDB

db = DataFrameDB('postgresql+psycopg2://...')
df = pd.DataFrame({'k_device': ['a', 'b', 'c'], 'col1': [1, 2, 3], 'col2': [4, 5, 6]})

db.insert('table1', df)
db.update('table1', df, index_keys=['k_device'])
db.upsert('table1', df, index_keys=['k_device'])
df = db.select('table1', condition='col1 > 1')
df = db.select('table1', limit=3, order_by=['k_device DESC'])
df = db.sql_select('select * from table1')
db.delete('table1')

db.create_table(df, 'table2', primary_keys=['k_device'])
db.drop_table('table2')
```

### 切换数据库

SDK兼容多种数据库的方言，用户只需修改初始化`DataFrameDB`时的连接字符串参数，其余代码不需要修改，即可切换到另一个数据库。 各数据库的连接字符串格式如下:

已经过测试的：
- postgresql+psycopg2://username:password@hostname/database_name
- oracle+cx_oracle://username:password@hostname:port/database_name
- mssql+pymssql://username:password@hostname:port/database_name

未经过测试的：
- mysql+pymysql://username:password@hostname/database_name
- 更多请参考：https://docs.sqlalchemy.org/en/20/dialects/

注意：使用前确保已安装相应的数据库的驱动，例如`pip install pymysql`。

### 异常处理

SDK进行数据库操作时，如果遇到异常情况会抛出`DataFrameDBException`，并回滚数据库到原来的状态。用户可以使用`try..except`捕获此异常进行必要的处理：

```
try:
    db.insert('table1', df)
except DataFrameDBException as e:
    print('数据插入(部分)失败，操作已回滚')
```
