diff --git a/README.md b/README.md index 06d5aee..dce248c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,343 @@ # KamalSQL Kamal's version of a Python wrapper for MySQL database stuff. + +## Installation + +To install the `kamalsql` package, you can execute the below command. + +``` +pip install kamalsql +``` + +If you have already installed `kamalsql` and would like to upgrade +to the latest version you could do this: + +``` +python -m pip install --upgrade kamalsql +``` + +## Usage + +Before getting into how to use this, here is the database info for the +below examples. + +- Tables present: `department`, `student` +- Table description of `department` + + | Field | Type | Null | Key | Default | Extra | + | ----- | ----------- | ---- | --- | ------- | ----- | + | sname | varchar(20) | YES | | NULL | | + | regno | varchar(20) | YES | | NULL | | + | m1 | int(11) | YES | | NULL | | + | m2 | int(11) | YES | | NULL | | + +### For the connection to the database + +```py +from kamalsql import KamalSQL + +db = KamalSQL( + host='localhost', + user='username', + password='mypassword', + database='mydatabase' +) +``` + +When you establish a connection in the above way, the auto-commit +feature is disabled by default. If you would like to auto-commit +the transactions, you can establish the connection is the following +way: + +```py +from kamalsql import KamalSQL + +db = KamalSQL( + host='localhost', + user='username', + password='mypassword', + database='mydatabase', + autocommit=True +) +``` + +You could also check the connection status using the `status()` function: + +```py +print(db.status()) +``` + +If the connection is established, you will get this: + +``` +Connection Successful +``` + +If not, this: + +``` +Connection Unsuccessful +``` + +### List out the tables present in the database + +You can get the tables present in the database using the +`showTables()` function. + +```py +tables = db.showTables() +print(tables) +``` + +##### Output + +``` +['department', 'student'] +``` + +### Describing the Table + +There are a couple of ways you could do this: + +- using `describeTable()` +- using `fancyDescribeTable()` + +#### using `describeTable()` + +The `describeTable()` returns a list with the description in the form of +tuples. So, to make it more readable, one has to use a loop. + +```py +description = db.describeTable('department') +for info in description: + print(info) +``` + +##### Output + +``` +('Field', 'Type', 'Null', 'Key', 'Default', 'Extra') +('sname', 'varchar(20)', 'YES', '', None, '') +('regno', 'varchar(20)', 'YES', '', None, '') +('m1', 'int(11)', 'YES', '', None, '') +('m2', 'int(11)', 'YES', '', None, '') +``` + +#### using `fancyDescibeTable()` + +Here we are using the `tabulate` module to pretty-print the +table description. + +```py +description = db.fancyDescribeTable('department') +print(description) +``` + +##### Output + +``` +╒═════════╤═════════════╤════════╤═══════╤═══════════╤═════════╕ +│ Field │ Type │ Null │ Key │ Default │ Extra │ +╞═════════╪═════════════╪════════╪═══════╪═══════════╪═════════╡ +│ sname │ varchar(20) │ YES │ │ │ │ +├─────────┼─────────────┼────────┼───────┼───────────┼─────────┤ +│ regno │ varchar(20) │ YES │ │ │ │ +├─────────┼─────────────┼────────┼───────┼───────────┼─────────┤ +│ m1 │ int(11) │ YES │ │ │ │ +├─────────┼─────────────┼────────┼───────┼───────────┼─────────┤ +│ m2 │ int(11) │ YES │ │ │ │ +╘═════════╧═════════════╧════════╧═══════╧═══════════╧═════════╛ +``` + +### Inserting values to a table + +Now that we know how to establish connection, lets see how to insert +values into a table. + +```py +db.insert( + 'department', + { + 'sname': 'Akash', + 'regno': '391201', + 'm1': 95, + 'm2': 96 + } +) + +db.insert( + 'department', + { + 'sname': 'Anish', + 'regno': '391202', + 'm1': 92, + 'm2': 91 + } +) + +db.insert( + 'department', + { + 'sname': 'Bala', + 'regno': '391203', + 'm1': 91, + 'm2': 90 + } +) + +db.insert( + 'department', + { + 'sname': 'Dinesh', + 'regno': '391204', + 'm1': 65, + 'm2': 86 + } +) +``` + +If you have not enabled the auto-commit feature, then make sure to use +`db.commit()` to complete the transaction. + +### Viewing the table contents + +- We saw how to insert values. +- Now lets check if they have been inserted into the table. +- This can be done by invoking the `getAll()` function. +- `getAll()` returns a list with dictionary objects. + +```py +records = db.getAll('department') +for record in records: + print(record) +``` + +##### Output + +``` +{'sname': 'Akash', 'regno': '391201', 'm1': 95, 'm2': 96} +{'sname': 'Anish', 'regno': '391202', 'm1': 92, 'm2': 91} +{'sname': 'Bala', 'regno': '391203', 'm1': 91, 'm2': 90} +{'sname': 'Dinesh', 'regno': '391204', 'm1': 65, 'm2': 86} +``` + +- By default, if you pass just the table name, it will select all the + columns. +- If you wish to view the above output in a tabular format, then you + could use `tableFormatRows()` to do the same. + +```py +rows = db.getAll('department') +table = db.tableFormatRows(rows) +print(table) +``` + +##### Output + +``` +sname regno m1 m2 +------- ------- ---- ---- +Akash 391201 95 96 +Anish 391202 92 91 +Bala 391203 91 90 +Dinesh 391204 65 86 +``` + +- See, I know that the above statements can be combined to form a one-liner + like this: `print(db.tableFormatRows(db.getAll('department')))` but, + for the sake of simplicity and to make things more clearer, I am doing it + in that way. + +- If you would like to add a few more conditions, then you could invoke + the `getAll()` function in this way: + +```py +rows = db.getAll( + 'department', # Table to be selected + ['regno', 'sname'], # Columns to display + ("regno >= %s and regno <= %s", # WHERE clause + ['391201', '391204'] # values for the arguments used in WHERE + ), + ["regno", "asc"], # ORDER BY regno asc + [0, 2] # LIMIT 0, 2 +) + +for row in rows: + print(row) + +print('\nTabular Format: \n') +print(db.tableFormatRows(rows)) +``` + +##### Output + +``` +{'regno': '391201', 'sname': 'Akash'} +{'regno': '391202', 'sname': 'Anish'} + +Tabular Format: + + + regno sname +------- ------- + 391201 Akash + 391202 Anish +``` + +### Updating the values + +- We saw how to insert and the various ways to see the table's content. +- Now, lets see how to update existing values. +- Note: Don't forget to give the `WHERE` condition. If you don't provide + that, the update condition will get applied to the entire table. + +```py +db.update( + 'department', # The table + { # The new values + "sname": "Frank", + "regno": "391205" + }, + ("regno = %s", ['391204']) # the WHERE condition. +) + +rows = db.getAll('department') +print(db.tableFormatRows(rows)) +``` + +##### Output + +``` +sname regno m1 m2 +------- ------- ---- ---- +Akash 391201 95 96 +Anish 391202 92 91 +Bala 391203 91 90 +Frank 391205 65 86 +``` + +### Deleting record(s) + +- We saw how to insert, view and the various ways to see the table's content. +- Now, lets see how to remove record(s). +- Note: Don't forget to give the `WHERE` condition. If you don't provide + that, the `DELETE` condition will get applied to the entire table. + +```py +db.delete( + 'department', # Table involved + ("regno = %s", ['391205']) # the WHERE clause +) + +rows = db.getAll('department') +print(db.tableFormatRows(rows)) +``` + +``` +sname regno m1 m2 +------- ------- ---- ---- +Akash 391201 95 96 +Anish 391202 92 91 +Bala 391203 91 90 +``` diff --git a/kamalsql/kamalsql.py b/kamalsql/kamalsql.py index af48a68..7c14e5e 100644 --- a/kamalsql/kamalsql.py +++ b/kamalsql/kamalsql.py @@ -33,8 +33,8 @@ def connect(self) -> None: def status(self) -> str: if (self.connection): - return 'Connection Succesful' - return 'Connection Unsucessful' + return 'Connection Successful' + return 'Connection Unsuccessful' def query(self, sqlQuery, params=None): """ @@ -226,5 +226,5 @@ def end(self): self.cursor.close() self.connection.close() - def __exit__(self, type, value, traceback): + def __exit__(self): self.end() diff --git a/setup.py b/setup.py index c2ebbf8..3c8c37d 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ setup( name='kamalsql', packages=['kamalsql'], - version='0.0.3', + version='1.0.0', license='MIT', description='A simple Python wrapper for your MySQL needs.', long_description=file_content, @@ -25,8 +25,8 @@ 'Intended Audience :: Developers', 'Natural Language :: English', 'Topic :: Software Development :: Libraries :: Python Modules', - 'Topic :: Database', - 'Topic :: Software Development :: Libraries', + 'Topic :: Database', + 'Topic :: Software Development :: Libraries', 'License :: OSI Approved :: MIT License', 'Programming Language :: Python :: 3', ],