Easy SQL

Reference documentation (auto-generated by mkdocstrings) for the py_simple.easy_sql module.

`py_simple.easy_sql`

Beginner friendly helpers for handling databases.

`EasySqlError`

Bases: Exception

Custom exception for py_simple SQL helpers.

Raised when a database operation fails — for example, when the connection to the database file cannot be established.

Parameters:

Name	Type	Description	Default
`message`	`str`	Description of what went wrong.	required

`run_insert(connection, cursor, to_insert, table_name, columns, close_conn_after=False)`

Inserts a single row into a table.

Validates table_name and columns first — only letters, numbers, and underscores are allowed — to guard against SQL injection before building the query string. Values in to_insert are passed as parameters, not interpolated into the query.

Parameters:

Name	Type	Description	Default
`connection`	`Connection`	Open connection to the database.	required
`cursor`	`Cursor`	Cursor for executing SQL statements.	required
`to_insert`	`list`	Values to insert, in the same order as `columns`.	required
`table_name`	`str`	Name of the table to insert into.	required
`columns`	`list`	Column names the values in `to_insert` map to.	required
`close_conn_after`	`bool`	If True, closes `connection` after the insert runs. Defaults to False.	`False`

Raises:

Type	Description
`EasySqlError`	If `table_name` or `columns` contain anything other than letters, numbers, or underscores, or if the insert itself fails.

Example

The Py_simple WayThe Traditional Way

from py_simple import open_db, run_insert

connection, cursor = open_db('mydb.db')
run_insert(connection, cursor, ['Ada', 'ada@example.com'],
           'users', ['name', 'email'])

import sqlite3

conn = sqlite3.connect('test.db')
cursor = conn.cursor()
cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)",
               ['Ada', 'ada@example.com'])
conn.commit()

`run_select(connection, cursor, table_name, to_select, close_conn_after=False)`

Runs a SELECT query against a table and returns all matching rows.

Validates table_name and to_select first — only letters, numbers, and underscores are allowed (or * for to_select) — to guard against SQL injection before building the query string.

Parameters:

Name	Type	Description	Default
`connection`	`Connection`	Open connection to the database.	required
`cursor`	`Cursor`	Cursor for executing SQL statements.	required
`table_name`	`str`	Name of the table to select from.	required
`to_select`	`str`	Column name(s) to select, comma-separated, or "*" for all columns.	required
`close_conn_after`	`bool`	If True, closes `connection` after the query runs. Defaults to False.	`False`

Returns:

Type	Description
	list[tuple]: All rows returned by the query.

Raises:

Type	Description
`EasySqlError`	If `table_name` or `to_select` contain anything other than letters, numbers, underscores, or "*", or if the query itself fails.

Example

The Py_simple WayThe Traditional Way

from py_simple import open_db, run_select

connection, cursor = open_db('mydb.db')
rows = run_select(connection, cursor, 'users', 'name, email')

import sqlite3

conn = sqlite3.connect('test.db')
cursor = conn.cursor()
rows = cursor.execute("SELECT name, email FROM users").fetchall()