postgresdb3 0.6.0__tar.gz → 0.7.0__tar.gz

{postgresdb3-0.6.0 → postgresdb3-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postgresdb3
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python uchun oddiy PostgreSQL wrapper
 Author: Abdulbosit Alijonov
 Project-URL: Source Code, https://github.com/AlijonovUz/PostgresDB

{postgresdb3-0.6.0 → postgresdb3-0.7.0}/postgresdb3/core/async_db.py

@@ -3,25 +3,7 @@ from typing import Any, List, Optional
 
 
 class AsyncPostgresDB:
-    """
-    Async PostgreSQL helper class for CRUD operations and schema management.
-
-    Ushbu class `asyncpg` kutubxonasidan foydalanib,
-    PostgreSQL bilan asynchronous CRUD va schema operatsiyalarini bajaradi.
-    Aiogram kabi async frameworklar bilan to‘g‘ridan-to‘g‘ri ishlash uchun mos.
-    """
-
     def __init__(self, database: str, user: str, password: str, host: str = "localhost", port: int = 5432) -> None:
-        """
-        PostgreSQL bazasiga ulanishni tayyorlaydi.
-
-        Args:
-            database (str): Bazaning nomi.
-            user (str): Foydalanuvchi nomi.
-            password (str): Parol.
-            host (str): Server manzili (default: "localhost").
-            port (int): Port (default: 5432).
-        """
         self.database = database
         self.user = user
         self.password = password
@@ -30,21 +12,6 @@ class AsyncPostgresDB:
         self.pool: Optional[asyncpg.pool.Pool] = None
 
     async def _manager(self, sql: str, *params, fetchone=False, fetchall=False, commit=False) -> Any:
-        """
-        Markaziy metod: barcha SQL so‘rovlarni bajaradi.
-
-        Args:
-            sql (str): Bajariladigan SQL so‘rov.
-            *params: SQL parametrlarini berish.
-            fetchone (bool): True bo‘lsa, faqat bitta qator qaytaradi.
-            fetchall (bool): True bo‘lsa, barcha natijalarni qaytaradi.
-            commit (bool): True bo‘lsa, tranzaksiya commit qilinadi.
-
-        Returns:
-            fetchone=True bo‘lsa: asyncpg.Record
-            fetchall=True bo‘lsa: list[asyncpg.Record]
-            commit=True bo‘lsa: None
-        """
         if not self.pool:
             self.pool = await asyncpg.create_pool(
                 database=self.database,
@@ -56,39 +23,21 @@ class AsyncPostgresDB:
 
         async with self.pool.acquire() as conn:
             if commit:
-                await conn.execute(sql, *params)
-                return
+                return await conn.execute(sql, *params)
             if fetchone:
                 return await conn.fetchrow(sql, *params)
             if fetchall:
                 return await conn.fetch(sql, *params)
 
     async def close_pool(self) -> None:
-        """
-        Connection poolni yopadi.
-        """
         if self.pool:
             await self.pool.close()
             self.pool = None
 
     async def create(self, table: str, columns: str) -> None:
-        """
-        Jadval yaratadi (agar mavjud bo‘lsa o‘tkazib yuboradi).
-
-        Args:
-            table (str): Jadval nomi.
-            columns (str): Ustunlar va turlari, misol: "id SERIAL PRIMARY KEY, name TEXT".
-        """
         await self._manager(f"CREATE TABLE IF NOT EXISTS {table} ({columns})", commit=True)
 
     async def drop(self, table: str, cascade: bool = False) -> None:
-        """
-        Jadvalni o‘chiradi (agar mavjud bo‘lsa).
-
-        Args:
-            table (str): Jadval nomi.
-            cascade (bool): Agar True bo‘lsa, jadval bilan bog‘liq barcha obyektlar ham o‘chiradi. Default: True
-        """
         sql = f"DROP TABLE IF EXISTS {table}"
         if cascade:
             sql += " CASCADE"
@@ -96,10 +45,6 @@ class AsyncPostgresDB:
         await self._manager(sql, commit=True)
 
     def _validate_identifier(self, value: str, name: str = "identifier") -> str:
-        """
-        Jadval yoki ustun nomi uchun minimal tekshiruv.
-        Faqat harf, raqam, underscore va nuqtaga ruxsat beradi.
-        """
         if not isinstance(value, str) or not value.strip():
             raise ValueError(f"{name} bo'sh bo'lmasligi kerak")
 
@@ -110,11 +55,6 @@ class AsyncPostgresDB:
         return value
 
     def _normalize_columns(self, columns: str | list[str]) -> str:
-        """
-        columns list bo'lsa stringga aylantiradi.
-        list bo'lsa har bir column validate qilinadi.
-        str bo'lsa SQL expression bo'lishi mumkinligi uchun o'z holicha qaytariladi.
-        """
         if isinstance(columns, list):
             if not columns:
                 raise ValueError("columns bo'sh list bo'lmasligi kerak")
@@ -128,28 +68,6 @@ class AsyncPostgresDB:
         return columns
 
     def _build_where(self, where: Any, start_index: int = 1) -> tuple[str, list]:
-        """
-        Qo'llab-quvvatlanadi:
-
-        1) tuple:
-           ("age > $1", [18])
-
-        2) dict:
-           {
-               "age__gt": 18,
-               "name__ilike": "%ali%",
-               "status": "active",
-               "id__in": [1, 2, 3],
-               "deleted_at__isnull": True
-           }
-
-        3) list[tuple]:
-           [
-               ("age", ">", 18),
-               ("name", "ILIKE", "%ali%"),
-               ("status", "=", "active")
-           ]
-        """
         if where is None:
             return "", []
 
@@ -268,26 +186,6 @@ class AsyncPostgresDB:
             offset: Optional[int] = None,
             fetchone: bool = False
     ) -> Any:
-        """
-        Jadvaldan ma'lumotlarni tanlash.
-
-        Args:
-            table (str): Asosiy jadval nomi.
-            columns (str | list[str]): Tanlanadigan ustunlar.
-            where:
-                tuple — ("age > $1", [18])
-                dict  — {"age__gt": 18, "name__ilike": "%ali%"}
-                list  — [("age", ">", 18), ("name", "ILIKE", "%ali%")]
-            join (Optional[List[tuple]]): [("INNER JOIN", "orders", "users.id = orders.user_id")]
-            group_by (Optional[str]): GROUP BY ustuni.
-            order_by (Optional[str]): ORDER BY qoidasi.
-            limit (Optional[int]): LIMIT qiymati.
-            offset (Optional[int]): OFFSET qiymati.
-            fetchone (bool): True bo‘lsa faqat bitta qator qaytaradi.
-
-        Returns:
-            asyncpg.Record yoki list[asyncpg.Record]
-        """
         table = self._validate_identifier(table, "table")
         columns = self._normalize_columns(columns)
 
@@ -321,44 +219,17 @@ class AsyncPostgresDB:
 
         return await self._manager(sql, *params, fetchone=fetchone, fetchall=not fetchone)
 
-    async def insert(self, table: str, columns: str, values: List[Any]) -> None:
-        """
-        Jadvalga yangi qator qo‘shadi.
-
-        Args:
-            table (str): Jadval nomi.
-            columns (str): Ustunlar nomi, misol: "name, age".
-            values (List[Any]): Qiymatlar, misol: ["Ali", 25].
-        """
+    async def insert(self, table: str, columns: str, values: list, returning: str | None = None):
         placeholders = ", ".join(f"${i + 1}" for i in range(len(values)))
         sql = f"INSERT INTO {table} ({columns}) VALUES ({placeholders})"
+
+        if returning:
+            sql += f" RETURNING {returning}"
+            return await self._manager(sql, *values, fetchone=True)
+
         await self._manager(sql, *values, commit=True)
 
     async def insert_many(self, table: str, columns: str, values_list: List[List[Any]]) -> None:
-        """
-        Jadvalga bir nechta qator qo‘shish (bulk insert).
-
-        Args:
-            table (str): Jadval nomi.
-            columns (str): Ustunlar nomi, misol: "name, age".
-            values_list (List[List[Any]]): Qiymatlar ro‘yxati, misol: [["Ali", 25], ["Vali", 30]].
-
-        Raises:
-            ValueError: Agar `values_list` bo‘sh bo‘lsa.
-
-        Notes:
-            - `asyncpg` kutubxonasida har bir parametr uchun unikal `$n` indekslari kerak,
-              shuning uchun har bir qator uchun ketma-ket `$1, $2, ...` ishlatiladi.
-            - Metod barcha qatorlarni bir so‘rovda qo‘shadi.
-            - `fetchmany` kerak emas, chunki bu insert operatsiyasi natija qaytarmaydi.
-
-        Example:
-            await db.insert_many(
-                "users",
-                "name, age",
-                [["Ali", 25], ["Vali", 30], ["Guli", 22]]
-            )
-        """
         if not values_list:
             raise ValueError("values_list bo'sh bo'lishi mumkin emas")
 
@@ -376,41 +247,124 @@ class AsyncPostgresDB:
         await self._manager(sql, *flat_values, commit=True)
 
     async def update(self, table: str, set_column: str, set_value: Any, where_column: str, where_value: Any) -> None:
-        """
-        Jadvaldagi qatorni yangilaydi.
-
-        Args:
-            table (str): Jadval nomi.
-            set_column (str): O‘zgartiriladigan ustun.
-            set_value (Any): Yangi qiymat.
-            where_column (str): Filtrlash ustuni.
-            where_value (Any): Filtrlash qiymati.
-        """
         sql = f"UPDATE {table} SET {set_column} = $1 WHERE {where_column} = $2"
         await self._manager(sql, set_value, where_value, commit=True)
 
+    async def update_fields(self, table: str, data: dict, where_column: str, where_value: Any) -> int:
+        table = self._validate_identifier(table, "table")
+        where_column = self._validate_identifier(where_column, "where column")
+
+        if not data:
+            raise ValueError("Yangilash uchun data bo'sh bo'lmasligi kerak")
+
+        set_parts = []
+        params = []
+        index = 1
+
+        for key, value in data.items():
+            key = self._validate_identifier(key, "column")
+            set_parts.append(f"{key} = ${index}")
+            params.append(value)
+            index += 1
+
+        sql = f"UPDATE {table} SET {', '.join(set_parts)} WHERE {where_column} = ${index}"
+        params.append(where_value)
+
+        result = await self._manager(sql, *params, commit=True)
+        return int(result.split()[-1])
+
+    async def update_where(self, table: str, data: dict, where: tuple | dict | list) -> int:
+        table = self._validate_identifier(table, "table")
+
+        if not data:
+            raise ValueError("Yangilash uchun data bo'sh bo'lmasligi kerak")
+
+        if not where:
+            raise ValueError("update_where uchun where bo'sh bo'lmasligi kerak")
+
+        set_parts = []
+        params = []
+        index = 1
+
+        for key, value in data.items():
+            key = self._validate_identifier(key, "column")
+            set_parts.append(f"{key} = ${index}")
+            params.append(value)
+            index += 1
+
+        where_sql, where_params = self._build_where(where, start_index=index)
+
+        if not where_sql:
+            raise ValueError("WHERE sharti noto'g'ri")
+
+        sql = f"UPDATE {table} SET {', '.join(set_parts)} WHERE {where_sql}"
+
+        result = await self._manager(
+            sql,
+            *(params + where_params),
+            commit=True
+        )
+
+        return int(result.split()[-1])
+
     async def delete(self, table: str, where_column: str, where_value: Any) -> None:
-        """
-        Jadvaldan qator o‘chiradi.
-
-        Args:
-            table (str): Jadval nomi.
-            where_column (str): Filtrlash ustuni.
-            where_value (Any): Filtrlash qiymati.
-        """
         sql = f"DELETE FROM {table} WHERE {where_column} = $1"
         await self._manager(sql, where_value, commit=True)
 
-    async def list_tables(self, schema: str = "public") -> List[str]:
-        """
-        Bazadagi barcha jadvallarni ro‘yxat sifatida qaytaradi.
+    async def delete_where(self, table: str, where: tuple | dict | list) -> int:
+        table = self._validate_identifier(table, "table")
+
+        if not where:
+            raise ValueError("delete_where uchun where bo'sh bo'lmasligi kerak")
+
+        where_sql, where_params = self._build_where(where, start_index=1)
 
-        Args:
-            schema (str): Schema nomi, default "public".
+        if not where_sql:
+            raise ValueError("WHERE sharti noto'g'ri")
 
-        Returns:
-            List[str]: Jadval nomlari
-        """
+        sql = f"DELETE FROM {table} WHERE {where_sql}"
+
+        result = await self._manager(
+            sql,
+            *where_params,
+            commit=True
+        )
+
+        return int(result.split()[-1])
+
+    async def exists_where(
+            self,
+            table: str,
+            where: tuple | dict | list | None = None,
+            join: list[tuple] | None = None,
+            group_by: str | None = None,
+    ) -> bool:
+        table = self._validate_identifier(table, "table")
+
+        sql = f"SELECT 1 FROM {table}"
+        params = []
+
+        if join:
+            for join_type, join_table, on_condition in join:
+                join_table = self._validate_identifier(join_table, "join table")
+                sql += f" {join_type} {join_table} ON {on_condition}"
+
+        if where:
+            condition, values = self._build_where(where, start_index=1)
+            if condition:
+                sql += f" WHERE {condition}"
+                params.extend(values)
+
+        if group_by:
+            sql += f" GROUP BY {group_by}"
+
+        sql += f" LIMIT ${len(params) + 1}"
+        params.append(1)
+
+        record = await self._manager(sql, *params, fetchone=True)
+        return record is not None
+
+    async def list_tables(self, schema: str = "public") -> List[str]:
         sql = """
               SELECT table_name
               FROM information_schema.tables
@@ -421,16 +375,6 @@ class AsyncPostgresDB:
         return [r["table_name"] for r in result]
 
     async def describe_table(self, table: str, schema: str = "public") -> List[str]:
-        """
-        Jadval ustunlari haqida ma'lumot beradi.
-
-        Args:
-            table (str): Jadval nomi.
-            schema (str): Schema nomi, default "public".
-
-        Returns:
-            list[asyncpg.Record]: Har bir ustun bo‘yicha ma’lumot
-        """
         sql = """
               SELECT column_name, data_type, is_nullable, column_default
               FROM information_schema.columns
@@ -441,12 +385,5 @@ class AsyncPostgresDB:
         return await self._manager(sql, schema, table, fetchall=True)
 
     async def alter(self, table: str, action: str) -> None:
-        """
-        Jadval strukturasi o‘zgartirish (ALTER TABLE).
-
-        Args:
-            table (str): Jadval nomi.
-            action (str): ALTER TABLE dan keyingi SQL qismi, misol: "ADD COLUMN age INT".
-        """
         sql = f"ALTER TABLE {table} {action}"
         await self._manager(sql, commit=True)