pgsqldatatool 1.0.0__tar.gz

pgsqldatatool-1.0.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.3
+Name: pgsqldatatool
+Version: 1.0.0
+Summary: Add your description here
+Author: manji
+Author-email: manji <pnsm@qq.com>
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: polars>=1.41.2
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: sqlalchemy>=2.0.51
+Requires-Dist: tzdata>=2026.2
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+## 使用教程
+
+### 安装
+```python
+pip install pgsqldatatool
+```
+
+### date_clean（数据清洗）
+
+``` python
+# 基础清洗 （去掉列名两端空白字符、去掉数据两段空白字符、删除空行）
+lf_basic_clean(df)
+
+# 根据字典重命名列
+lf_rename_cols
+
+# 移除重复行
+lf_remove_dup_rows
+
+# 删除指定列
+lf_remove_cols
+
+# 移除数字千分号
+lf_remove_per_mille
+
+# 移除数字百分号
+lf_remove_percent
+
+# 添加时间列
+lf_add_time
+
+# 删除完全为空的列 -- 这一步不是惰性计算，可能会降低性能
+df_drop_empty_cols
+```
+示例
+
+```python
+from pgsqldatatool import data_clean as dc
+df = pl.read_excel(r"D:\manji\Downloads\判断中国域名.xlsx")
+df = dc.lf_basic_clean(df)
+df = dc.lf_remove_cols(df,["域名22"])
+df = dc.lf_remove_dup_rows(df)
+df = dc.df_drop_empty_cols(df)
+df = dc.lf_remove_dup_rows(df)
+df = df.collect()
+print(df)
+```
+
+### PoolSingleton（连接池单例模式）
+
+归还连接（Release）：把连接还给池子，让别的任务继续用。（async with 已经帮你自动做了）
+关闭连接池（Close）：彻底断开与数据库的所有连接，销毁这个池子。这通常只在整个程序/服务准备退出时才需要做。
+```python
+from pgsqldatatool import PoolSingleton
+
+# 示例1：使用异步连接池
+async def main_test_1():
+
+    # 调用方式1，
+    async with  PoolSingleton.acquire() as conn:
+        records = await conn.fetch(""" SELECT * FROM public."test20260211" """)
+        print(records)
+
+    # 销毁整个连接池
+    await PoolSingleton.close()
+
+```
+
+
+```python
+
+# 示例2：使用静态方法
+async def main_test_2():
+    # 调用方式2：使用静态方法
+    records2 = await PoolSingleton.fetch(""" SELECT * FROM public."test20260211" """)
+    print(records2)
+
+    # 调用方式3：使用静态方法
+    records3 = await PoolSingleton.fetchrow(""" SELECT * FROM public."test20260211" """)
+    print(records3)
+
+    # 调用方式4：使用静态方法
+    records4 = await PoolSingleton.execute(""" SELECT * FROM public."test20260211" """)
+    print(records4)
+    
+    
+if __name__ == "__main__":
+    asyncio.run(main_test_1())
+```
+
+
+## 创建异步数据库链接
+
+### 推荐方案：asyncpg（性能最好，原生 asyncio）
+适合：FastAPI / aiohttp / asyncio 项目
+```python
+pip install asyncpg
+```
+
+```python
+import asyncpg
+import asyncio
+
+async def main():
+    # 创建连接
+    conn = await asyncpg.connect(
+        host="localhost",
+        port=5432,
+        user="postgres",
+        password="password",
+        database="testdb"
+    )
+
+    # 查询
+    row = await conn.fetchrow("SELECT NOW()")
+    print(row)
+
+    # 参数化查询
+    rows = await conn.fetch(
+        "SELECT * FROM users WHERE age > $1",
+        18
+    )
+
+    await conn.close()
+
+asyncio.run(main())
+```
+
+### 使用连接池（生产必选 ✅）
+
+```python
+import asyncpg
+import asyncio
+
+async def get_pool():
+    return await asyncpg.create_pool(
+        dsn="postgresql://postgres:password@localhost:5432/testdb",
+        min_size=5,
+        max_size=20
+    )
+
+async def main():
+    pool = await get_pool()
+
+    async with pool.acquire() as conn:
+        result = await conn.fetch("SELECT * FROM users")
+
+    await pool.close()
+
+asyncio.run(main())
+```
+
+事务
+```python
+async with conn.transaction():
+    await conn.execute(
+        "INSERT INTO users(name) VALUES($1)",
+        "Alice"
+    )
+```
+
+
+### SQLAlchemy 2.0 + asyncpg（ORM 场景）
+适合：需要 ORM、多数据库兼容
+
+```python
+pip install sqlalchemy[asyncio] asyncpg
+```
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy import select
+
+engine = create_async_engine(
+    "postgresql+asyncpg://postgres:password@localhost/testdb",
+    pool_size=10,
+    max_overflow=20
+)
+
+AsyncSessionLocal = sessionmaker(
+    engine, class_=AsyncSession, expire_on_commit=False
+)
+
+async def query_users():
+    async with AsyncSessionLocal() as session:
+        result = await session.execute(select(User))
+        return result.scalars().all()
+```
+

pgsqldatatool-1.0.0/README.md

@@ -0,0 +1,190 @@
+## 使用教程
+
+### 安装
+```python
+pip install pgsqldatatool
+```
+
+### date_clean（数据清洗）
+
+``` python
+# 基础清洗 （去掉列名两端空白字符、去掉数据两段空白字符、删除空行）
+lf_basic_clean(df)
+
+# 根据字典重命名列
+lf_rename_cols
+
+# 移除重复行
+lf_remove_dup_rows
+
+# 删除指定列
+lf_remove_cols
+
+# 移除数字千分号
+lf_remove_per_mille
+
+# 移除数字百分号
+lf_remove_percent
+
+# 添加时间列
+lf_add_time
+
+# 删除完全为空的列 -- 这一步不是惰性计算，可能会降低性能
+df_drop_empty_cols
+```
+示例
+
+```python
+from pgsqldatatool import data_clean as dc
+df = pl.read_excel(r"D:\manji\Downloads\判断中国域名.xlsx")
+df = dc.lf_basic_clean(df)
+df = dc.lf_remove_cols(df,["域名22"])
+df = dc.lf_remove_dup_rows(df)
+df = dc.df_drop_empty_cols(df)
+df = dc.lf_remove_dup_rows(df)
+df = df.collect()
+print(df)
+```
+
+### PoolSingleton（连接池单例模式）
+
+归还连接（Release）：把连接还给池子，让别的任务继续用。（async with 已经帮你自动做了）
+关闭连接池（Close）：彻底断开与数据库的所有连接，销毁这个池子。这通常只在整个程序/服务准备退出时才需要做。
+```python
+from pgsqldatatool import PoolSingleton
+
+# 示例1：使用异步连接池
+async def main_test_1():
+
+    # 调用方式1，
+    async with  PoolSingleton.acquire() as conn:
+        records = await conn.fetch(""" SELECT * FROM public."test20260211" """)
+        print(records)
+
+    # 销毁整个连接池
+    await PoolSingleton.close()
+
+```
+
+
+```python
+
+# 示例2：使用静态方法
+async def main_test_2():
+    # 调用方式2：使用静态方法
+    records2 = await PoolSingleton.fetch(""" SELECT * FROM public."test20260211" """)
+    print(records2)
+
+    # 调用方式3：使用静态方法
+    records3 = await PoolSingleton.fetchrow(""" SELECT * FROM public."test20260211" """)
+    print(records3)
+
+    # 调用方式4：使用静态方法
+    records4 = await PoolSingleton.execute(""" SELECT * FROM public."test20260211" """)
+    print(records4)
+    
+    
+if __name__ == "__main__":
+    asyncio.run(main_test_1())
+```
+
+
+## 创建异步数据库链接
+
+### 推荐方案：asyncpg（性能最好，原生 asyncio）
+适合：FastAPI / aiohttp / asyncio 项目
+```python
+pip install asyncpg
+```
+
+```python
+import asyncpg
+import asyncio
+
+async def main():
+    # 创建连接
+    conn = await asyncpg.connect(
+        host="localhost",
+        port=5432,
+        user="postgres",
+        password="password",
+        database="testdb"
+    )
+
+    # 查询
+    row = await conn.fetchrow("SELECT NOW()")
+    print(row)
+
+    # 参数化查询
+    rows = await conn.fetch(
+        "SELECT * FROM users WHERE age > $1",
+        18
+    )
+
+    await conn.close()
+
+asyncio.run(main())
+```
+
+### 使用连接池（生产必选 ✅）
+
+```python
+import asyncpg
+import asyncio
+
+async def get_pool():
+    return await asyncpg.create_pool(
+        dsn="postgresql://postgres:password@localhost:5432/testdb",
+        min_size=5,
+        max_size=20
+    )
+
+async def main():
+    pool = await get_pool()
+
+    async with pool.acquire() as conn:
+        result = await conn.fetch("SELECT * FROM users")
+
+    await pool.close()
+
+asyncio.run(main())
+```
+
+事务
+```python
+async with conn.transaction():
+    await conn.execute(
+        "INSERT INTO users(name) VALUES($1)",
+        "Alice"
+    )
+```
+
+
+### SQLAlchemy 2.0 + asyncpg（ORM 场景）
+适合：需要 ORM、多数据库兼容
+
+```python
+pip install sqlalchemy[asyncio] asyncpg
+```
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy import select
+
+engine = create_async_engine(
+    "postgresql+asyncpg://postgres:password@localhost/testdb",
+    pool_size=10,
+    max_overflow=20
+)
+
+AsyncSessionLocal = sessionmaker(
+    engine, class_=AsyncSession, expire_on_commit=False
+)
+
+async def query_users():
+    async with AsyncSessionLocal() as session:
+        result = await session.execute(select(User))
+        return result.scalars().all()
+```
+

pgsqldatatool-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "pgsqldatatool"
+version = "1.0.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "manji", email = "pnsm@qq.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "asyncpg>=0.31.0",
+    "polars>=1.41.2",
+    "python-dotenv>=1.2.2",
+    "sqlalchemy>=2.0.51",
+    "tzdata>=2026.2",
+]
+
+[project.scripts]
+pgsqldatatool = "pgsqldatatool:main"
+
+[build-system]
+requires = ["uv_build>=0.10.11,<0.11.0"]
+build-backend = "uv_build"
+
+
+[[tool.uv.index]]
+# 使用清华大学PyPI镜像源以提高下载速度
+url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
+# 设置为默认索引
+default = true

pgsqldatatool-1.0.0/src/pgsqldatatool/__init__.py

@@ -0,0 +1,8 @@
+def main() -> None:
+    print("Hello from pgsqldatatool!")
+
+
+# from .until_async import write_async
+from .until_async import write_pg
+from .tools import records_to_df
+from .pgsql_connection_async import PoolSingleton

pgsqldatatool-1.0.0/src/pgsqldatatool/data_clean.py

@@ -0,0 +1,230 @@
+
+import re
+import logging
+from datetime import datetime
+from zoneinfo import ZoneInfo
+import polars as pl
+
+
+logger = logging.getLogger(__name__)
+
+
+# 基础清洗 （去掉列名两端空白字符、去掉数据两段空白字符、删除空行）
+def lf_basic_clean(df:pl.LazyFrame|pl.DataFrame)->pl.LazyFrame:
+    """
+    基础清洗
+        1、去掉列名中的首尾空格和首尾换行符
+        2、删除数据两端的空白字符（"-",空格、制表符、回车、换行等）
+        3、删除完全为空的行
+    Args:
+        df (pl.LazyFrame | pl.DataFrame): 要清洗的数据集。
+    Returns:
+        pl.LazyFrame: 清洗后的数据集。
+    """
+    if not isinstance(df, pl.LazyFrame):
+        df= df.lazy()
+
+    # 去掉列名中的首尾空格和首尾换行符-------------------------------------------------
+    pattern = r'^[\s\n\r]+|[\s\n\r]+$'
+    new_names = (
+        pl.Series(df.collect_schema().names())
+        .str.replace_all(pattern, "")
+        .to_list()
+    )
+    df = df.rename(dict(zip(df.collect_schema().names(), new_names)))
+    
+
+    # 删除数据两端的空白字符（"-",空格、制表符、回车、换行等）---------------------------
+    df = df.with_columns(
+        pl.col(pl.String)
+            .str.strip_chars()
+            .str.replace("-", "")
+    )
+    # 删除空白行--------------------------------------------------
+    df = df.filter(
+        pl.any_horizontal(pl.all().is_not_null())
+    )    
+
+    return df
+
+# 根据字典重命名列
+def lf_rename_cols(df:pl.LazyFrame|pl.DataFrame, rename_cols: dict)->pl.LazyFrame:
+    """
+    根据字典重命名列
+    Args:
+        df (pl.LazyFrame | pl.DataFrame): 要清洗的数据集。
+        rename_cols (dict, optional): 列名映射字典。
+    Returns:
+        df.LazyFrame: 数据集
+    """
+    if not isinstance(df, pl.LazyFrame):
+        df= df.lazy()
+
+        # 根据参数修改存在的列的列名
+    if rename_cols is not None:
+        df = df.rename({
+            k: v for k, v in rename_cols.items() if k in df.columns
+        })
+
+    return df
+
+# 移除重复行
+def lf_remove_dup_rows(df:pl.LazyFrame|pl.DataFrame)->pl.LazyFrame:
+    """
+    保留第一次出现的行,删除其余完全相同的重复行
+    Args:
+        df (pl.LazyFrame|pl.DataFrame): 数据集
+
+    Returns:
+        pl.LazyFrame: 数据集
+
+    """
+    if isinstance(df, pl.DataFrame): # 转换为懒加载
+        df = df.lazy()
+    df = df.unique(
+        subset=None,      # 所有列
+        keep="first"      # 保留第一个
+    )
+    return df
+
+# 删除指定列
+def lf_remove_cols(df, cols:list[str] | None = None)->pl.LazyFrame:
+    """
+    删除指定列
+    Args:
+        df (pl.LazyFrame|pl.DataFrame): 数据集
+        cols (list[str] | None): 需要删除的列名。
+    Returns:
+        pl.LazyFrame|pl.DataFrame: 处理后的数据集
+    """
+    if isinstance(df, pl.DataFrame): # 转换为懒加载
+        df = df.lazy()
+
+    # 根据参数删除存在的列
+    if cols is not None:
+        df = df.drop([c for c in cols if c in df.columns])
+        
+    return df
+
+# 移除数字千分号
+def lf_remove_per_mille(df, cols: "all" | list[str] | None = None):
+    """
+    移除字符串数字中的千分号
+    Args:
+        df (pl.LazyFrame|pl.DataFrame): 数据集
+        cols (all | list[str] | None): 需要将千分比转换为小数列的列名。\n
+            默认为None。当值为all时，将所有列名转换为小数,返回仍是字符串。
+            
+    Returns:
+        pl.LazyFrame: 数据集
+    """
+    if not isinstance(df, pl.LazyFrame):
+        df= df.lazy()
+
+    # 移除字符串数字中的千分号-------------------------------------------------------
+    if cols:
+        if isinstance(cols, str) and cols=="all":
+            df = df.with_columns(
+                pl.when(
+                    pl.col(pl.String).str.contains(r'^\d{1,3}(,\d{3})*(\.\d+)?$')
+                )
+                .then(pl.col(pl.String).str.replace_all(",", ""))
+                .otherwise(pl.col(pl.String))
+            )
+        elif isinstance(cols, list):
+            df = df.with_columns(
+                pl.when(
+                    pl.col(cols).str.contains(r'^\d{1,3}(,\d{3})*(\.\d+)?$')
+                )
+                .then(pl.col(cols).str.replace_all(",", ""))
+                .otherwise(pl.col(cols))
+            )
+        else:
+            raise ValueError("per_mille_cols参数错误")    
+
+# 移除数字百分号
+def lf_remove_percent(df, cols: "all" | list[str] | None = None):
+    """
+    移除字符串数字中的百分号
+    Args:
+        df (pl.LazyFrame|pl.DataFrame): 数据集
+        cols (all | list[str] | None): 需要将百分比转换为小数列的列名。\n
+            默认为None。当值为all时，将所有列名转换为小数,返回仍是字符串。
+    Returns:
+        pl.LazyFrame: 数据集
+    """
+    if not isinstance(df, pl.LazyFrame):
+        df= df.lazy()
+
+
+    if isinstance(cols, str) and cols == "all":
+        target = pl.col(pl.String)
+    elif isinstance(cols, list):
+        target = pl.col(cols)
+    else:
+        raise ValueError("percent_cols参数错误")
+
+    df = df.with_columns(
+        target                       
+        .str.strip_chars()
+        .str.replace_all(",", "")
+        .str.extract(r"^(\d+\.?\d*)%$")
+        .cast(pl.Float64)
+        .truediv(100)
+        .fill_null(target)             
+    )
+    return df
+
+# 添加时间列
+def lf_add_time(df, time_zone='Asia/Shanghai') -> pl.LazyFrame:
+    """
+    添加时间列
+    Args:
+        df (pl.LazyFrame|pl.DataFrame): 数据集
+        time_zone (str, optional): 时区。默认为'Asia/Shanghai'。
+    Returns:
+        pl.LazyFrame: 数据集
+    """
+    if not isinstance(df, pl.LazyFrame):
+        df= df.lazy()
+
+    return df.with_columns(
+        # 使用 pl.lit(datetime.now(...)) 依然是安全的，
+        # 因为整个 with_columns 表达式在 LazyFrame 下是惰性的，
+        # datetime.now() 会在最终 .collect() 时才被求值！
+        pl.lit(datetime.now(ZoneInfo(time_zone))).alias('数据写入时间')
+    )
+
+# 删除完全为空的列
+def df_drop_empty_cols(df) -> pl.LazyFrame:
+    """
+    删除完全为空的列 \n
+    这个函数不是延迟执行的 \n
+    collect() 会触发运行一次计算，获取所有列的空值状态
+    Args:
+        df (pl.LazyFrame|pl.DataFrame): 数据集
+    Returns:
+        pl.LazyFrame: 数据集
+    """
+
+    # 1. 构建一个表达式：一次性计算每一列是否全为 null
+    # pl.struct 会将所有列打包，pl.all_horizontal 会并行计算
+    is_all_null_expr = pl.all_horizontal(
+        pl.col(c).is_null().alias(c) for c in df.collect_schema().names()
+    )
+    
+    # 2. 仅触发一次收集，获取所有列的空值状态
+    # 注意：这里只计算聚合值，不扫描全表数据，速度极快
+    all_null_flags = df.select(is_all_null_expr).collect().row(0)
+    
+    # 3. 在 Python 端解析出需要删除的列名
+    cols_to_drop = [
+        col_name for col_name, is_null in zip(df.collect_schema().names(), all_null_flags)
+        if is_null
+    ]
+    
+    # 4. 延迟执行 drop 操作（drop 本身是惰性的，直到最终 collect 才生效）
+    if cols_to_drop:
+        df = df.drop(cols_to_drop)
+    
+    return df