ge/quicker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Compare commits

base: ge:master
Branches Tags
ge:master
ge:v0.3.0
ge:v0.2.0
ge:v0.1.0
..
compare: ge:v0.2.0
Branches Tags
ge:master
ge:v0.3.0
ge:v0.2.0
ge:v0.1.0

No commits in common. "master" and "v0.2.0" have entirely different histories.
master ... v0.2.0

7 changed files with 86 additions and 209 deletions
Show Stats Expand all files Collapse all files

2
.gitignore vendored
View File

@ -1,5 +1,3 @@
__pychache__/
*.pyc
dist/
db.sqlite3
*.db

24
COPYING
View File

@ -1,24 +0,0 @@
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.
In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
For more information, please refer to <http://unlicense.org/>

136
README.md
View File

@ -1,20 +1,20 @@
<img width="320px" src="logo.svg"/>
```
____ _ __
/ __ \__ __(_)____/ /_____ _____
/ / / / / / / / ___/ //_/ _ \/ ___/
/ /_/ / /_/ / / /__/ ,< / __/ /
\___\_\__,_/_/\___/_/|_|\___/_/
```
**Quicker** is a pythonic 🐍 tool for querying databases.
**Quicker** is a pythonic tool for querying databases.
Quicker wraps Python libraries:
Quicker wraps Python bindings on DBMS libraries:
- `mysqlclient` for MySQL.
- `psycopg2` for PostgreSQL.
- `sqlite3` from Python standard library for SQLite.
- `sqlite` from Python standard library for SQLite (not implemented yet).
# Why is it needed?
At work, I periodically have to make queries to different databases and then somehow process the information received. This may be necessary for one-time use, so I don't want to write a lot of code. You may also want to do all the work right in the interactive Python shell.
Quicker interface is as simple as possible, thanks to which lazy system administrators can now effortlessly extract data from the database.
Of course, this library **should not be used in production**. This is just a small assistant in routine tasks.
Connection parameters will passed to "backend" module as is.
# Installation
@ -24,32 +24,30 @@ pip install git+https://git.nxhs.cloud/ge/quicker
# Usage
Quicker uses a context manager. All that is needed for work is to pass connection parameters to object and write the queries themselves. See MySQL example:
`Connection` is context manages and must be used with `with` keyword. `Connection` returns `Query` callable object. `Query` can be called in this ways:
```python
from quicker import Connection
with Connection(**config) as db:
db.execute("sql query here...")
db.query("sql query here...") # query is alias for exec()
with Connection(provider='mysql', read_default_file='~/.my.cnf') as query:
users = query("SELECT * FROM `users` WHERE admin = 'N'")
# Query is callable and you can also do this:
with Connection(**config) as query:
query("sql query here...")
```
`Connection` object initialises `Query` callable object for interacting with cursor. You can use `query("sql there..")` or `query.execute("sql...")` syntax. There are the same.
`Query` cannot be called itself, you must use `Connection` to correctly initialise `Query` object. Available methods and properties:
`Query` object methods and properties:
- `query()`, `execute()`. Execute SQL. There is you can use here this syntax: `query('SELECT * FROM users WHERE id = %s', (15,))`.
- `query()`, `execute()`. Execute SQL. There is You can use here this syntax: `query('SELECT * FROM users WHERE id = %s', (15,))`.
- `commit()`. Write changes into database.
- `cursor`. Access cursor object directly.
- `connection`. Access connection object directly.
You don't need to commit to the database, Quicker will do it for you, but if you need to, you can commit manually calling `query.commit()`. You can also turn off automatic commit when creating a `Connection` object — pass it the argument `commit=Fasle`.
That's not all — Quicker converts the received data into a list of dictionaries. The list will be empty if nothing was found for the query. If the request does not imply a response, `None` will be returned.
## MySQL example
Full example:
```python
import json
from quicker import Connection
@ -63,86 +61,58 @@ config = {
}
with Connection(**config) as query:
query(
"""
CREATE TABLE IF NOT EXISTS users (
id int AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
"""
)
query(
"INSERT INTO users VALUES (NULL, %s, %s, current_timestamp)",
('john', 'john@exmpl.org',)
)
query.commit()
users = query("SELECT * FROM users")
users = query("SELECT * FROM `users`")
print('ID\t NAME\t EMAIL')
for user in users:
print(user['id'], '\t', user['name'], '\t', user['email'])
print(json.dumps(users, indent=4))
```
## PostgreSQL example
`users` will presented as list of dicts:
```python
import logging
[
{
'id': 1,
'name': 'test',
'email': 'noreply@localhost'
},
{
'id': 2,
'name': 'user1',
'email': 'my@example.com'
}
]
```
Changing database:
```python
from quicker import Connection
logging.basicConfig(level=logging.DEBUG)
config = {
'provider': 'postgres',
'host': '127.0.0.1',
'port': 5432,
'user': 'myuser',
'database': 'mydb',
'password': 'example',
}
with Connection(**config) as query:
query(
"""
CREATE TABLE IF NOT EXISTS users (
id serial PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
"""
)
query(
"INSERT INTO users VALUES ((SELECT MAX(id)+1 FROM users), %s, %s, current_timestamp)",
('phil', 'phil@exmpl.org',)
)
with Connection(provider='mysql', read_default_file='~/.my.cnf') as db:
db.query("INSERT INTO `users` VALUE (3, 'user2', 'user2@example.org')")
```
Quicker by default make commit after closing context. Set option `commit=False` to disable automatic commit.
## Logging
For logging add following code:
For logging add following code in your module:
```python
```
import logging
logging.basicConfig(level=logging.DEBUG)
```
## Direct access to Cursor object
Direct access to Cursor object:
```python
from quicker import Connection, mklist
```
from quicker import Connection, make_list
# config declaration here...
with Connection(**config) as db:
db.cursor.execute('SELECT id, name, email FROM users WHERE name = %s', ('John',))
db.cursor.execute('SELECT `id`, `name`, `email` FROM `users` WHERE `name` = %s', ('John',))
users = db.cursor.fetchall()
# Note: "users" is tuple! Convert it to list of dicts!
# Note: user is tuple! Convert it to list of dicts!
colnames = [desc[0] for desc in db.cursor.description]
users_list = mklist(colnames, users)
users_list = make_list(colnames, users)
```

56
logo.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 107 KiB

2
pyproject.toml
View File

@ -1,6 +1,6 @@
[tool.poetry]
name = "quicker"
version = "0.3.0"
version = "0.2.0"
description = "Query databases quickly."
authors = ["ge <ge@nixhacks.net>"]
license = "Unlicense"

9
quicker/__init__.py Normal file
View File

@ -0,0 +1,9 @@
# ____ _ __
# / __ \__ __(_)____/ /_____ _____
# / / / / / / / / ___/ //_/ _ \/ ___/
# / /_/ / /_/ / / /__/ ,< / __/ /
# \___\_\__,_/_/\___/_/|_|\___/_/
#
# Quicker -- pythonic tool for querying databases
from .main import Connection, make_list

66
quicker.py → quicker/main.py
View File

@ -1,15 +1,3 @@
#
# .88888. oo dP
# d8' `8b 88
# 88 88 dP dP dP .d8888b. 88 .dP .d8888b. 88d888b.
# 88 db 88 88 88 88 88' `"" 88888" 88ooood8 88' `88
# Y8. Y88P 88. .88 88 88. ... 88 `8b. 88. ... 88
# `8888PY8b `88888P' dP `88888P' dP `YP `88888P' dP
#
# Quicker -- pythonic tool for querying databases.
__all__ = ['Connection', 'mklist', 'Provider']
import logging
import importlib.util
from enum import Enum
@ -33,12 +21,10 @@ def _import(module_name: str, symbol: Optional[str] = None):
return module
def mklist(column_names: List[str], rows: Union[tuple, Tuple[dict, ...]]) -> List[dict]:
"""
Convert output to list of dicts from tuples. `rows` can be
default tuple or tuple of dicts if MySQL provider is used with
MySQLdb.cursors.DictCursor cursor class.
"""
def make_list(
column_names: List[str], rows: Union[tuple, Tuple[dict, ...]]
) -> List[dict]:
"""Convert output to list of dicts from tuples."""
data = []
for row in rows:
if isinstance(row, dict):
@ -52,6 +38,7 @@ def mklist(column_names: List[str], rows: Union[tuple, Tuple[dict, ...]]) -> Lis
class Provider(str, Enum):
MYSQL = 'mysql'
POSTGRES = 'postgres'
SQLITE = 'sqlite'
@ -68,17 +55,26 @@ class Connection:
>>>
"""
def __init__(self, provider: Provider, commit: bool = True, **kwargs):
def __init__(self,
provider: Provider = None,
commit: bool = True,
**kwargs
):
if not provider:
raise ValueError('Database provider is not set')
self._provider = Provider(provider)
self._commit = commit
self._connection_args = kwargs
logger.debug(f'Database provider={self._provider}')
def __enter__(self):
logger.debug(f'Database provider={self._provider}')
# -- MySQL / MariaDB --
if self._provider == Provider.MYSQL:
MySQLdb = _import('MySQLdb')
DictCursor = _import('MySQLdb.cursors', 'DictCursor')
try:
cursorclass = self._connection_args.pop('cursorclass')
if self._connection_args['cursorclass']:
cursorclass = DictCursor
except KeyError:
cursorclass = DictCursor
self._connection = MySQLdb.connect(
@ -87,35 +83,23 @@ class Connection:
)
logger.debug('Session started')
self._cursor = self._connection.cursor()
self._queryobj = Query(self)
return Query(self)
# -- PostgreSQL --
if self._provider == Provider.POSTGRES:
psycopg2 = _import('psycopg2')
dbname = self._connection_args.pop('database')
self._connection_args['dbname'] = dbname
self._connection = psycopg2.connect(**self._connection_args)
self._cursor = self._connection.cursor()
self._queryobj = Query(self)
if self._provider == Provider.SQLITE:
sqlite3 = _import('sqlite3') # Python may built without SQLite
self._connection = sqlite3.connect(**self._connection_args)
self._cursor = self._connection.cursor()
self._queryobj = Query(self)
def __enter__(self):
return self._queryobj
return Query(self)
def __exit__(self, exception_type, exception_value, exception_traceback):
self.close()
def close(self):
if self._commit:
logger.debug('Commiting changes into database')
self._connection.commit()
logger.debug('Closing cursor and connection')
logger.debug('Changes commited into database')
self._cursor.close()
self._connection.close()
logger.debug('Connection closed')
class Query:
@ -144,17 +128,13 @@ class Query:
self._fetchall = self._cursor.fetchall()
except pgProgrammingError as e:
self._fetchall = None
if self._provider == Provider.SQLITE:
self._cursor.execute(*args, **kwargs)
logger.debug(f'sqlite3 ran: {args}')
self._fetchall = self._cursor.fetchall()
if self._fetchall is not None:
self._colnames = []
if self._cursor.description is not None:
self._colnames = [
desc[0] for desc in self._cursor.description
]
return mklist(self._colnames, self._fetchall)
return make_list(self._colnames, self._fetchall)
return None
def commit(self) -> None: