Added more documentation

Author: chandr-andr

Cargo.toml

@@ -10,7 +10,14 @@ crate-type = ["cdylib"]
 
 [dependencies]
 deadpool-postgres = { git = "https://github.com/chandr-andr/deadpool.git", branch = "psqlpy" }
-pyo3 = { version = "0.23.4", features = ["chrono", "experimental-async", "rust_decimal", "py-clone", "macros", "multiple-pymethods"] }
+pyo3 = { version = "0.23.4", features = [
+    "chrono",
+    "experimental-async",
+    "rust_decimal",
+    "py-clone",
+    "macros",
+    "multiple-pymethods",
+] }
 pyo3-async-runtimes = { git = "https://github.com/chandr-andr/pyo3-async-runtimes.git", branch = "psqlpy", features = [
     "tokio-runtime",
 ] }

docs/.vuepress/sidebar.ts

@@ -46,6 +46,15 @@ export default sidebar({
             "advanced_type_usage",
           ]
         },
+        {
+          text: "Row Factories Usage",
+          prefix: "row_factories/",
+          collapsible: true,
+          children: [
+            "row_factories",
+            "predefined_row_factories",
+          ]
+        },
         {
           text: "Frameworks Usage",
           prefix: "frameworks/",
@@ -58,15 +67,6 @@ export default sidebar({
             "robyn",
           ]
         },
-        {
-          text: "Row Factories Usage",
-          prefix: "row_factories/",
-          collapsible: true,
-          children: [
-            "row_factories",
-            "predefined_row_factories",
-          ]
-        },
       ],
     },
     {

docs/README.md

@@ -28,10 +28,9 @@ highlights:
         details: PSQLPy is under active development.
 ---
 ## What is PSQLPy
-`PSQLPy` is a new Python driver for `PostgreSQL` fully written in Rust. It was inspired by `Psycopg3` and `AsyncPG`.
+`PSQLPy` is a Python driver for `PostgreSQL` fully written in Rust. It was inspired by `Psycopg3` and `AsyncPG`.
 This project has two main goals:
-Make a interaction with the database as fast as possible and now `PSQLPy` shows itself to be times faster than the above drivers.
-Don't make useless abstractions and make it like a mirror to `PostgreSQL`.
+We found that communication with the database can be faster and safer, so we tried to implement a new PostgreSQL driver in Rust for Python.
 
 It has all necessary components to create high-load and fault tolerance applications.
 
@@ -59,4 +58,5 @@ pip install git+https://github.com/psqlpy-python/psqlpy
 
 ## Join community!
 You can get support from the creators and users of `PSQLPy` in some social media:
-- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Discord](https://discord.gg/ugNhzmhZ)

docs/components/cursor.md

@@ -3,44 +3,71 @@ title: Cursor
 ---
 
 `Cursor` objects represents server-side `Cursor` in the `PostgreSQL`. [PostgreSQL docs](https://www.postgresql.org/docs/current/plpgsql-cursors.html).
+::: important
+Cursor always lives inside a transaction. If you don't begin transaction explicitly, it will be opened anyway.
+:::
 
 ## Cursor Parameters
 
 - `querystring`: specify query for cursor.
 - `parameters`: parameters for the querystring. Default `None`
-- `fetch_number`: default fetch number. It is used in `fetch()` method and in async iterator. Default 10
-- `scroll`: is cursor scrollable or not. Default as in `PostgreSQL`.
+- `fetch_number`: default fetch number. It is used in `fetch()` method and in async iterator.
 
-## Cursor as async iterator
+## Usage
 
-The most common situation is using `Cursor` as async iterator.
+Cursor can be used in different ways.
 
+::: tabs
+@tab Pre-Initialization
 ```python
 from psqlpy import ConnectionPool, QueryResult
 
-
 async def main() -> None:
     db_pool = ConnectionPool()
+    connection = await db_pool.connection()
 
+    cursor = connection.cursor(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
+        fetch_number=10,
+    )
+    await cursor.start()
+```
 
+@tab Post-Initialization
+```python
+from psqlpy import ConnectionPool, QueryResult
+
+async def main() -> None:
+    db_pool = ConnectionPool()
     connection = await db_pool.connection()
-    transaction = await connection.transaction()
-
-    # Here we fetch 5 results in each iteration.
-    async with cursor in transaction.cursor(
-        querystring="SELECT * FROM users WHERE username = $1",
-        parameters=["Some_Username"],
-        fetch_number=5,
-    ):
-        async for fetched_result in cursor:
-            dict_result: List[Dict[Any, Any]] = fetched_result.result()
-            ... # do something with this result.
+
+    cursor = connection.cursor()
+    await cursor.execute(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
+    )
+    result: QueryResult = await cursor.fetchone()
 ```
 
-## Cursor methods
+@tab Async Context Manager
+```python
+from psqlpy import ConnectionPool, QueryResult
 
-There are a lot of methods to work with cursor.
+async def main() -> None:
+    db_pool = ConnectionPool()
+    connection = await db_pool.connection()
+
+    async with connection.cursor(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
+        fetch_number=10,
+    ) as cursor:
+        result: QueryResult = await cursor.fetchone()
+```
+:::
 
+## Cursor methods
 ### Start
 Declare (create) cursor.
 
@@ -58,14 +85,53 @@ async def main() -> None:
     await cursor.close()
 ```
 
-### Fetch
+### Execute
+
+Initialize cursor and make it ready for fetching.
 
-You can fetch next `N` records from the cursor.
-It's possible to specify `N` fetch record with parameter `fetch_number`, otherwise will be used `fetch_number` from the `Cursor` initialization.
+::: important
+If you initialized cursor with `start` method or via context manager, you don't have to use this method.
+:::
+
+#### Parameters:
+- `querystring`: specify query for cursor.
+- `parameters`: parameters for the querystring. Default `None`
 
 ```python
 async def main() -> None:
-    result: QueryResult = await cursor.fetch(
-        fetch_number=100,
+    await cursor.execute(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
     )
+    result: QueryResult = await cursor.fetchone()
+```
+
+### Fetchone
+
+Fetch one result from the cursor.
+
+```python
+async def main() -> None:
+    result: QueryResult = await cursor.fetchone()
+```
+
+### Fetchmany
+
+Fetch N results from the cursor.
+
+#### Parameters:
+- `size`: number of records to fetch.
+
+```python
+async def main() -> None:
+    result: QueryResult = await cursor.fetchmany(size=10)
+```
+
+### Fetchall
+
+Fetch all results from the cursor.
+
+```python
+async def main() -> None:
+    result: QueryResult = await cursor.fetchall()
 ```

docs/components/transaction.md

@@ -407,8 +407,6 @@ async def main() -> None:
 - `querystring`: Statement string.
 - `parameters`: List of list of parameters for the statement string.
 - `fetch_number`: rewrite default fetch_number. Default is 10.
-- `scroll`: make cursor scrollable or not. Default is like in `PostgreSQL`.
-- `prepared`: prepare querystring or not.
 
 From `Transaction` you can create new `Cursor` object which represents cursor in the `PostgreSQL`. [PostgreSQL Docs](https://www.postgresql.org/docs/current/plpgsql-cursors.html)
 

docs/introduction/introduction.md

@@ -5,15 +5,14 @@ title: What is PSQLPy?
 `PSQLPy` is a new Python driver for PostgreSQL fully written in Rust. It was inspired by `Psycopg3` and `AsyncPG`.
 
 With `PSQLPy` you can:
-- Make an interaction with the PostgeSQL in your application much faster (2-3 times).
+- Make an interaction with the PostgeSQL in your application faster.
 - Be sure that there won't be any unexpected errors.
-- Don't usually go to the documentation to search every question - we have awesome docstrings for every component.
+- Don't usually go to the documentation to search every question - we have docstrings for every component.
 - Use `MyPy` (or any other Python type checker) with confidence that exactly the types specified in the typing will be returned.
 - Concentrate on writing your code, not understanding new abstractions in this library, we only have classes which represents PostgreSQL object (transaction, cursor, etc).
 
 ::: info
-It is extremely important to understand that the library will provide a noticeable acceleration in working with the database only if your queries are optimized.
-Otherwise, there will be acceleration, but not so significant
+The library will provide a noticeable acceleration in working with the database only if your queries are optimized.
 :::
 
 ## Important notes
@@ -22,4 +21,5 @@ But in some situations this behavior can break you application. As an example, i
 
 ## Join community!
 You can get support from the creators of `PSQLPy` in some social media:
-- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Discord](https://discord.gg/ugNhzmhZ)

src/connection/traits.rs

@@ -101,39 +101,3 @@ pub trait CloseTransaction: StartTransaction {
 
     fn rollback(&mut self) -> impl std::future::Future<Output = PSQLPyResult<()>>;
 }
-
-// pub trait Cursor {
-//     fn build_cursor_start_qs(
-//         &self,
-//         cursor_name: &str,
-//         scroll: &Option<bool>,
-//         querystring: &str,
-//     ) -> String {
-//         let mut cursor_init_query = format!("DECLARE {cursor_name}");
-//         if let Some(scroll) = scroll {
-//             if *scroll {
-//                 cursor_init_query.push_str(" SCROLL");
-//             } else {
-//                 cursor_init_query.push_str(" NO SCROLL");
-//             }
-//         }
-
-//         cursor_init_query.push_str(format!(" CURSOR FOR {querystring}").as_str());
-
-//         cursor_init_query
-//     }
-
-//     fn start_cursor(
-//         &mut self,
-//         cursor_name: &str,
-//         scroll: &Option<bool>,
-//         querystring: String,
-//         prepared: &Option<bool>,
-//         parameters: Option<pyo3::Py<PyAny>>,
-//     ) -> impl std::future::Future<Output = PSQLPyResult<()>>;
-
-//     fn close_cursor(
-//         &mut self,
-//         cursor_name: &str,
-//     ) -> impl std::future::Future<Output = PSQLPyResult<()>>;
-// }