cherrypick master fix (#410)

* run ruff and fix lint (#385)

* [Feature] Support borrow session for contextual execution (#386)

* support borrow session on client

* add doc

* run lint

* fix typo (#387)

* add example for NebulaPool (#390)

* fix time overflow for hour 25 (#391)

* fix None list value (#392)

* fix duration type bug (#395)

* update doc for special types (#396)

* upadte doc for special types

* update start desc

* update doc (#397)

---------

Co-authored-by: 盐粒 Yanli <yanli.yu@vesoft.com>

Author: Nicole00

.github/workflows/update_version.py

@@ -7,7 +7,9 @@
 from typing import Optional
 
 
-def update_version(version_type: str = "dev", custom_suffix: Optional[str] = None) -> str:
+def update_version(
+    version_type: str = "dev", custom_suffix: Optional[str] = None
+) -> str:
     """
     Update the `version` field in `pyproject.toml` for supported manual build types.
 
@@ -25,17 +27,21 @@ def update_version(version_type: str = "dev", custom_suffix: Optional[str] = Non
     content: str = pyproject_path.read_text()
 
     # Extract current version
-    version_match: Optional[re.Match[str]] = re.search(r'^version\s*=\s*"([^"]+)"', content, re.MULTILINE)
+    version_match: Optional[re.Match[str]] = re.search(
+        r'^version\s*=\s*"([^"]+)"', content, re.MULTILINE
+    )
     if not version_match:
         raise ValueError("Could not find version in pyproject.toml")
 
     current_version: str = version_match.group(1)
-    
+
     # Parse the base version (remove any existing suffixes)
-    base_version_match: Optional[re.Match[str]] = re.match(r'^(\d+\.\d+\.\d+)', current_version)
+    base_version_match: Optional[re.Match[str]] = re.match(
+        r"^(\d+\.\d+\.\d+)", current_version
+    )
     if not base_version_match:
         raise ValueError(f"Invalid version format: {current_version}")
-    
+
     base_version: str = base_version_match.group(1)
 
     # Only dev/custom builds mutate the version; all others keep current version

.gitignore

@@ -161,7 +161,6 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
-.idea
+.idea/
 .DS_Store
 docs/.DS_Store

docs/1_started.md

@@ -1,15 +1,17 @@
 # NebulaGraph Python Client Getting Started
 
 ## Installation
+from pypi
 
 ```bash
-pip install ng-python # not yet published
+pip install nebula5_python==5.2.0
 ```
 
 from source
 
 ```bash
-cd python
+git clone -b dev https://github.com/vesoft-inc/nebula-python.git
+cd nebula-python
 pip install -e .
 ```
 
@@ -125,6 +127,23 @@ with NebulaClient(
 
 If you prefer manual lifecycle control, you can explicitly open and close clients.
 
+- Sync version:
+
+```python
+from nebulagraph_python import NebulaClient
+
+client = NebulaClient(
+    hosts=["127.0.0.1:9669"],
+    username="root",
+    password="NebulaGraph01",
+)
+try:
+    result = client.execute("RETURN 1 AS a, 2 AS b")
+    result.print()
+finally:
+    client.close()
+```
+
 - Async version:
 
 ```python
@@ -152,4 +171,4 @@ Run `ngcli --help` to get the help message. An example to connect to NebulaGraph
 
 ```bash
 ngcli -h 127.0.0.1:9669 -u root -p NebulaGraph01
-```
+```

docs/2_concurrency.md

@@ -62,6 +62,26 @@ async def concurrent_example():
 asyncio.run(concurrent_example())
 ```
 
+## Contextual Execution
+
+By default, statements run on a random session from the pool. When you need to run several queries on the same session, call `borrow` to obtain and reuse a specific session.
+
+```python
+async def contextual_example():
+    async with await NebulaAsyncClient.connect(
+        hosts=["127.0.0.1:9669"],
+        username="root",
+        password="NebulaGraph01",
+        session_pool_config=SessionPoolConfig(),
+    ) as client:
+        print("Connected to the server...")
+        async with client.borrow() as session:
+            await session.execute("SESSION SET GRAPH movie")
+            res = await session.execute("MATCH (v:Movie) RETURN count(v)")
+            res.print()
+```
+
+
 ## Understanding Timeout Values
 
 The client uses three different timeouts that apply at different stages:

docs/5_vector_and_special_types.md

@@ -53,15 +53,15 @@ cli.close()
 ### NDuration
 
 `NDuration` represents a duration with support for both month-based and time-based forms.
-- If `months != 0`, the instance is month-based (`is_month_based = True`), and `years`/`months` are derived from the `months` argument.
-- If `months == 0`, the instance is time-based (days default to 0 in current implementation) and uses the `seconds` and `microseconds` arguments to derive `hour`, `minute`, `second`, `microsec`.
+- If `is_month_based = True`, the instance uses `year` and `month` fields for duration representation.
+- If `is_month_based = False`, the instance uses `day`, `hour`, `minute`, `second`, and `microsecond` fields for duration representation.
 
 The `__str__` produces an ISO-8601–like string:
 - Month-based examples: `P1Y2M`, `P0M`
 - Time-based examples: `PT0S`, `PT1H2M3S`, `PT3.5S`, `PT-0.000123S`
 
 API:
-- Constructor: `NDuration(seconds: int, microseconds: int, months: int)`
+- Constructor: `NDuration(is_month_based: bool, year: int, month: int, day: int, hour: int, minute: int, seconds: int, microseconds: int)`
 - Properties/Methods:
   - `is_month_based: bool`
   - `get_year() -> int`, `get_month() -> int`, `get_day() -> int`

docs/7_orm_example.py

@@ -117,7 +117,9 @@ class Edge1(
 
 if input("Execute the DDL? (y/N)") == "y":
     client.execute_py(graph_type.to_gql())
-    client.execute_py("CREATE GRAPH IF NOT EXISTS define_type_test define_type_test_type")
+    client.execute_py(
+        "CREATE GRAPH IF NOT EXISTS define_type_test define_type_test_type"
+    )
 
 
 q = upsert_gql(

example.py

@@ -187,6 +187,7 @@ def sync_session_pool_example():
 if __name__ == "__main__":
     import asyncio
     import logging
+
     logging.basicConfig(level=logging.DEBUG)
     logging.getLogger("nebulagraph_python").setLevel(logging.DEBUG)
 

example/NebulaPoolExample.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from typing import Optional, Dict
+from nebulagraph_python.client.pool import NebulaPool
+from nebulagraph_python.data import HostAddress
+from dataclasses import dataclass, field
+
+@dataclass
+class SessionConfig:
+    schema: Optional[str] = None
+    graph: Optional[str] = None
+    timezone: Optional[str] = None
+    values: Dict[str, str] = field(default_factory=dict)
+    configs: Dict[str, str] = field(default_factory=dict)
+
+graph_name = "test_graph"
+
+def main():
+    # config the connect information
+    hosts = ["127.0.0.1:9669"]
+    username = "root"
+    password = "NebulaGraph01"
+
+    # create NebulaPool
+    pool = NebulaPool(
+        hosts=hosts,
+        username=username,
+        password=password,
+        session_config=SessionConfig(graph=graph_name)
+    )
+
+    try:
+        print("use execute_py to execute `SHOW GRAPHS` ...")
+        result = pool.execute_py("SHOW GRAPHS")
+
+        # 打印结果
+        print("\n query result:")
+        print("-" * 50)
+        result.print(style="table")
+
+        print("\n\nuse execute to execute `SHOW GRAPHS`:")
+        print("-" * 50)
+        result2 = pool.execute("SHOW GRAPHS")
+        result2.print(style="table")
+
+        # get the query result
+        print("-" * 50)
+        if result.size > 0:
+            for row in result:
+                print(f"Row: {row}")
+        else:
+            print("Empty")
+
+    except Exception as e:
+        print(f"\nerror: {e}")
+        import traceback
+        traceback.print_exc()
+    finally:
+        print("\nclose the pool...")
+        pool.close()
+        print("closed")
+
+
+if __name__ == "__main__":
+    main()

run_example.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# run example program, using local source code and dependencies
+
+export PYTHONPATH="${PYTHONPATH}:$(pwd)/src:$(pwd)/deps"
+
+python3 example/NebulaPoolExample.py

scripts/add_apache_headers.py

@@ -203,4 +203,3 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
-