fix: improve PydangoSession __init__ method

README.md

@@ -17,7 +17,9 @@
 
 - **Asynchronous Support**: Perform asynchronous database operations for optimized I/O-bound tasks.
 
-### [Full Documentation](https://nadobando.github.io/pydangorm)
+______________________________________________________________________
+
+## [Full Documentation](https://nadobando.github.io/pydangorm)
 
 ## Installation
 
@@ -42,7 +44,7 @@ from pydango import (
     VertexCollectionConfig,
     Relation,
 )
-from pydango.index import PersistentIndex
+from pydango.indexes import PersistentIndex
 
 
 class Visited(EdgeModel):
@@ -95,10 +97,11 @@ Construct and execute queries in a Pythonic manner:
 
 ```python
 from aioarango import ArangoClient
-from models import Person, City, Visited, LivesIn
+from app.models import Person, City, Visited, LivesIn
 
-from pydango import PydangoSession, ORMQuery
-from pydango.connection.utils import get_or_create_db
+from pydango import PydangoSession
+from pydango.orm import for_
+from pydango.connection.utils import get_or_create_db, deplete_cursor
 
 person = Person(
     name="John",
@@ -120,43 +123,29 @@ person = Person(
 
 async def main():
     db = await get_or_create_db(ArangoClient(), "app")
-    session = PydangoSession(db)
+    session = PydangoSession(database=db)
     # Retrieving users older than 10 years
     await session.save(person)
     assert person.id.startswith("people/")
 
-    db_person = await session.get(Person, person.key, include_edges=True, depth=(1, 1))
+    db_person = await session.get(Person, person.key, fetch_edges=True, depth=(1, 1))
     assert db_person == person
 
-    query = (
-        ORMQuery()
-        .for_(Person)
-        .filter(Person.age > 10)
-        .sort(-Person.age)
-        .return_(Person)
-    )
-    query_result = await query.execute(session)
-    db.find(Person).filter(Person.age > 10).all()
-    users = Person.query().filter(User.age > 10).all()
-
-    # Fetching related data with edges
-    visits = Visited.query().filter(Visited.rating > 4.0).join(User).all()
+    query = for_(Person).filter(Person.age > 10).sort(-Person.age).return_(Person)
+    query_result = await session.execute(query)
+    result = await deplete_cursor(query_result)
 ```
 
 More detailed examples and scenarios can be found in the `tests` directory, which showcases modeling and querying for different use-cases like cities, families, and e-commerce operations.
 
 ## Detailed Documentation
 
-For a comprehensive understanding of `pydangorm`'s capabilities, refer to the documentation:
-
-- **[Query Package Documentation](./docs/query)**: Dive deep into query construction, operations, and functionalities.
-- **[ORM Package Documentation](./docs/orm)**: Understand model definitions, relationships, and ORM-specific operations.
-- **[Connection Package Documentation](./docs/connection)**: Explore session management, database connections, and related utilities.
+For detailed documentation, please refer to the [documentation](https://nadobando.github.io/pydangorm).
 
 ## Contributing
 
 Contributions to `pydangorm` are welcome! Please refer to the `CONTRIBUTING.md` file for guidelines.
 
 ## License
 
-`pydangorm` is licensed under \[specific license name\]. See the `LICENSE` file for details.
+`pydangorm` is licensed under [MIT](./LICENSE). See the `LICENSE` file for details.

docs/index.md

@@ -54,11 +54,13 @@ multi-model NoSQL database.
 
 ______________________________________________________________________
 
-### **Contributions**
+## **Contributions**
 
 We're actively looking for contributors to help improve `pydangorm` and expand its capabilities.
 
 Whether you're a seasoned
-developer or just starting out, your contributions are valuable to us. If you have ideas for new features,
+developer or just starting out, your contributions are valuable to us.
+
+If you have ideas for new features,
 optimizations, or simply want to fix a bug, please check our contribution guidelines or reach out. Together, we can make
-pydangorm the best ArangoDB ORM for Python!
+`pydangorm` the best ArangoDB ORM for Python!

docs/quickstart.md

@@ -22,6 +22,7 @@ With `pydangorm`, you can easily define vertex and edge models:
 ```python
 from typing import Annotated
 import datetime
+from pydango.indexes import PersistentIndex
 
 from pydango import (
     VertexModel,
@@ -38,6 +39,9 @@ class Visited(EdgeModel):
 
     class Collection(EdgeCollectionConfig):
         name = "visited"
+        indexes = [
+            PersistentIndex(fields=["rating"]),
+        ]
 
 
 class LivesIn(EdgeModel):
@@ -53,6 +57,7 @@ class City(VertexModel):
 
     class Collection(VertexCollectionConfig):
         name = "cities"
+        indexes = [PersistentIndex(fields=["name"])]
 
 
 class Person(VertexModel):
@@ -63,6 +68,10 @@ class Person(VertexModel):
 
     class Collection(VertexCollectionConfig):
         name = "people"
+        indexes = [
+            PersistentIndex(fields=["name"]),
+            PersistentIndex(fields=["age"]),
+        ]
 ```
 
 ## **CRUD Operations**

pydango/connection/session.py

@@ -55,6 +55,7 @@
 if TYPE_CHECKING:
     from pydango.orm.models.base import ArangoModel
     from pydango.orm.models.vertex import TVertexModel
+    from pydango.query.types import Range
 
 logger = logging.getLogger(__name__)
 _INDEX_MAPPING: dict[Type[Indexes], Callable[..., Awaitable["Result[Json]"]]] = {
@@ -90,16 +91,18 @@ def __init__(
         auth_method: str = "basic",
     ):
         if isinstance(database, str):
+            if client is None:
+                raise ValueError("client is required when database is a string")
             self._db_name = database
             self.database = None
-        else:
-            self.database = database
-
-        if not isinstance(database, StandardDatabase):
             self.password = password
             self.username = username
             self.client = client
             self.auth_method = auth_method
+        elif isinstance(database, StandardDatabase):
+            self.database = database
+        else:
+            raise ValueError("database should be a string or a StandardDatabase instance")
 
     async def initialize(self):
         if self.database is None:
@@ -166,7 +169,7 @@ async def get(
         fetch_edges: Union[set[str], bool] = False,
         # fetch_edges_data: Union[set[str], bool] = False,
         fetch_path: bool = False,
-        depth: range = range(1, 1),
+        depth: "Range" = range(1, 1),
         prune: bool = False,
         projection: Optional[Type["ArangoModel"]] = None,
         return_raw: bool = False,

pydango/orm/query.py

@@ -39,10 +39,10 @@
         Expression,
         IterableExpression,
         ObjectExpression,
-        RangeExpression,
         VariableExpression,
     )
     from pydango.query.operations import ForParams, SortParams, TraversalDirection
+    from pydango.query.types import Range
 
 logger = logging.getLogger(__name__)
 
@@ -372,7 +372,7 @@ def traverse(
         iterators: TraverseIterators,
         edges: Union[str, CollectionExpression, Sequence[Union[str, CollectionExpression]]],
         start: Union["LiteralExpression", "VariableExpression", FieldExpression, str],
-        depth: Union["RangeExpression", range, tuple[int, int]],
+        depth: "Range",
         direction: "TraversalDirection",
     ):
         return super().traverse(iterators, edges, start, depth, direction)
@@ -390,7 +390,7 @@ def traverse(
     iterators: TraverseIterators,
     edges: Union[str, CollectionExpression, Sequence[Union[str, CollectionExpression]]],
     start: Union["LiteralExpression", "VariableExpression", FieldExpression, str],
-    depth: Union["RangeExpression", range, tuple[int, int]],
+    depth: "Range",
     direction: "TraversalDirection",
 ):
     return ORMQuery().traverse(iterators, edges, start, depth, direction)

pydango/query/types.py

@@ -0,0 +1,12 @@
+import sys
+from typing import TYPE_CHECKING, Union
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+if TYPE_CHECKING:
+    from pydango.query.expressions import RangeExpression
+
+Range: TypeAlias = Union["RangeExpression", range, tuple[int, int]]

pyproject.toml

@@ -88,7 +88,8 @@ classifiers = [
   "Framework :: Pydantic :: 1"
 ]
 description = "pydantic based ArangoDB ODM"
-homepage = "https://nadobando.github.io/pydangorm"
+documentation = "https://nadobando.github.io/pydangorm"
+homepage = "https://github.com/nadobando/pydangorm"
 license = "MIT"
 name = "pydangorm"
 packages = [{include = "pydango"}]