Engines

Sync Engine

Bases: BaseEngine

The sync engine that uses sqlite3.Connection and sqlite3.Cursor

Parameters:

Name Type Description Default
path str

a pathlike object that points to the sqlite database

required
enable_foreing_keys bool

specifies if the pragma should be enforced. Defaults to False.

False

Attributes:

Name Type Description
path str

the path to the db

schemas set[str]

a set of table schemas

tables_created set[str]

the tables that have been setup by the engine

enable_foreing_keys bool

if True, the engine enables the pragma on all connections

Source code in ardilla/engine.py
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class Engine(BaseEngine):
    """The sync engine that uses `sqlite3.Connection` and `sqlite3.Cursor`

    Args:
        path (str): a pathlike object that points to the sqlite database
        enable_foreing_keys (bool, optional): specifies if the pragma should be enforced. Defaults to False.

    Attributes:
        path (str): the path to the db
        schemas (set[str]): a set of table schemas
        tables_created (set[str]): the tables that have been setup by the engine
        enable_foreing_keys (bool): if True, the engine enables the pragma on all connections
    """
    con: sqlite3.Connection

    def __init__(self, path: str, enable_foreing_keys: bool = False):
        super().__init__(path, enable_foreing_keys)

    def get_connection(self) -> sqlite3.Connection:
        """Gets the connections or makes a new one but it doesn't set it as an attrib

        Returns:
            sqlite3.Connection: the connection
        """
        con: Union[sqlite3.Connection, None] = getattr(self, 'con', None)
        if not self.check_connection():
            con = sqlite3.connect(self.path)
            con.row_factory = sqlite3.Row

            if self.enable_foreing_keys:
                con.execute("PRAGMA foreign_keys = on;")

            return con
        else:
            return self.con

    def __enter__(self):
        self.connect()
        return self

    def __exit__(self, *_):
        self.close()

    def connect(self) -> sqlite3.Connection:
        self.close()
        self.con = self.get_connection()
        return self.con

    def close(self) -> None:
        if self.check_connection():
            self.con.close()
        self._cruds.clear()

    def crud(self, Model: type[M]) -> Crud[M]:
        """returns a Crud instances for the given model type

        Args:
            Model (type[M]): the model type for the crud object

        Returns:
            Crud[M]: the crud for the model type
        """
        if not self.check_connection():
            raise DisconnectedEngine("Can't create crud objects with a disconnected engine")

        if Model.__schema__ not in self.tables_created:
            self.con.execute(Model.__schema__)
            self.con.commit()
            self.tables_created.add(Model.__schema__)

        crud = self._cruds.setdefault(Model, Crud(Model, self.con))

        return crud

crud(Model)

returns a Crud instances for the given model type

Parameters:

Name Type Description Default
Model type[M]

the model type for the crud object

required

Returns:

Type Description
Crud[M]

Crud[M]: the crud for the model type

Source code in ardilla/engine.py
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def crud(self, Model: type[M]) -> Crud[M]:
    """returns a Crud instances for the given model type

    Args:
        Model (type[M]): the model type for the crud object

    Returns:
        Crud[M]: the crud for the model type
    """
    if not self.check_connection():
        raise DisconnectedEngine("Can't create crud objects with a disconnected engine")

    if Model.__schema__ not in self.tables_created:
        self.con.execute(Model.__schema__)
        self.con.commit()
        self.tables_created.add(Model.__schema__)

    crud = self._cruds.setdefault(Model, Crud(Model, self.con))

    return crud

get_connection()

Gets the connections or makes a new one but it doesn't set it as an attrib

Returns:

Type Description
sqlite3.Connection

sqlite3.Connection: the connection

Source code in ardilla/engine.py
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def get_connection(self) -> sqlite3.Connection:
    """Gets the connections or makes a new one but it doesn't set it as an attrib

    Returns:
        sqlite3.Connection: the connection
    """
    con: Union[sqlite3.Connection, None] = getattr(self, 'con', None)
    if not self.check_connection():
        con = sqlite3.connect(self.path)
        con.row_factory = sqlite3.Row

        if self.enable_foreing_keys:
            con.execute("PRAGMA foreign_keys = on;")

        return con
    else:
        return self.con

Async Engine

Bases: BaseEngine

Async Engine that uses aiosqlite.Connection and aiosqlite.Cursor

Source code in ardilla/asyncio/engine.py
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class AsyncEngine(BaseEngine):
    """Async Engine that uses `aiosqlite.Connection` and `aiosqlite.Cursor`
    """
    con: aiosqlite.Connection

    async def get_connection(self) -> aiosqlite.Connection:
        """Gets the connections or makes a new one but it doesn't set it as an attrib

        Returns:
            sqlite3.Connection: the connection
        """
        con: Union[aiosqlite.Connection, None] = getattr(self, 'con', None)
        if not self.check_connection():
            con: aiosqlite.Connection = await aiosqlite.connect(self.path)
            con.row_factory = aiosqlite.Row

            if self.enable_foreing_keys:
                await con.execute("PRAGMA foreign_keys = on;")

            return con
        else:
            return self.con

    async def connect(self) -> aiosqlite.Connection:
        """
        Stablishes a connection to the database
        Returns:
            The connection
        """
        await self.close()

        self.con = await self.get_connection()
        return self.con

    async def close(self) -> None:
        if self.check_connection():
            await self.con.close()
        self._cruds.clear()

    async def __aenter__(self) -> AsyncEngine:
        """Stablishes the connection and if specified enables foreign keys pragma

        Returns:
            The connection
        """
        await self.connect()
        return self

    async def __aexit__(self, *_):
        """Closes the connection"""
        await self.close()

    async def crud(self, Model: type[M]) -> AsyncCrud[M]:
        """
        This function works exactly like `Engine.crud` but
        returns an instance of `ardilla.asyncio.crud.AsyncCrud` instead of `ardilla.crud.Crud`
        and is asynchronous

        Returns:
            The async Crud for the given model
        """
        if not self.check_connection():
            raise DisconnectedEngine("Can't create crud objects with a disconnected engine")

        if Model.__schema__ not in self.tables_created:
            await self.con.execute(Model.__schema__)
            await self.con.commit()
            self.tables_created.add(Model.__schema__)

        crud = self._cruds.setdefault(Model, AsyncCrud(Model, self.con))
        return crud

__aenter__() async

Stablishes the connection and if specified enables foreign keys pragma

Returns:

Type Description
AsyncEngine

The connection

Source code in ardilla/asyncio/engine.py
51
52
53
54
55
56
57
58
async def __aenter__(self) -> AsyncEngine:
    """Stablishes the connection and if specified enables foreign keys pragma

    Returns:
        The connection
    """
    await self.connect()
    return self

__aexit__(*_) async

Closes the connection

Source code in ardilla/asyncio/engine.py
60
61
62
async def __aexit__(self, *_):
    """Closes the connection"""
    await self.close()

connect() async

Stablishes a connection to the database

Returns:

Type Description
aiosqlite.Connection

The connection

Source code in ardilla/asyncio/engine.py
35
36
37
38
39
40
41
42
43
44
async def connect(self) -> aiosqlite.Connection:
    """
    Stablishes a connection to the database
    Returns:
        The connection
    """
    await self.close()

    self.con = await self.get_connection()
    return self.con

crud(Model) async

This function works exactly like Engine.crud but returns an instance of ardilla.asyncio.crud.AsyncCrud instead of ardilla.crud.Crud and is asynchronous

Returns:

Type Description
AsyncCrud[M]

The async Crud for the given model

Source code in ardilla/asyncio/engine.py
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
async def crud(self, Model: type[M]) -> AsyncCrud[M]:
    """
    This function works exactly like `Engine.crud` but
    returns an instance of `ardilla.asyncio.crud.AsyncCrud` instead of `ardilla.crud.Crud`
    and is asynchronous

    Returns:
        The async Crud for the given model
    """
    if not self.check_connection():
        raise DisconnectedEngine("Can't create crud objects with a disconnected engine")

    if Model.__schema__ not in self.tables_created:
        await self.con.execute(Model.__schema__)
        await self.con.commit()
        self.tables_created.add(Model.__schema__)

    crud = self._cruds.setdefault(Model, AsyncCrud(Model, self.con))
    return crud

get_connection() async

Gets the connections or makes a new one but it doesn't set it as an attrib

Returns:

Type Description
aiosqlite.Connection

sqlite3.Connection: the connection

Source code in ardilla/asyncio/engine.py
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
async def get_connection(self) -> aiosqlite.Connection:
    """Gets the connections or makes a new one but it doesn't set it as an attrib

    Returns:
        sqlite3.Connection: the connection
    """
    con: Union[aiosqlite.Connection, None] = getattr(self, 'con', None)
    if not self.check_connection():
        con: aiosqlite.Connection = await aiosqlite.connect(self.path)
        con.row_factory = aiosqlite.Row

        if self.enable_foreing_keys:
            await con.execute("PRAGMA foreign_keys = on;")

        return con
    else:
        return self.con