v0.2.5

- Added in-built functions to query postgres tables.
- Added ChangeLog to docs.
- Improve documentation using sphinx-toolbox.

docs/conf.py

@@ -6,14 +6,15 @@
     "sphinx_copybutton",
     "sphinx_rtd_theme",
     "sphinx_rtd_dark_mode",
-    # "sphinx_toolbox.confval",
+    "sphinx_toolbox.confval",
     # "sphinx_toolbox.github",
     # "sphinx_toolbox.sidebar_links",
     # "myst_parser"
 ]
 templates_path = ['templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 html_theme = 'sphinx_rtd_theme'
+# html_theme = "pydata_sphinx_theme"
 html_favicon = 'favicon.ico'
 copybutton_prompt_text = "$ "
 default_dark_mode = False

docs/index.rst

@@ -14,7 +14,7 @@ Not convinced to use PyStark? Try it out first, using few small steps given in t
 .. hlist::
     :columns: 1
 
-    - :doc:`Quick Start <introduction/quickstart>`: Overview to get you started quickly.
+    - :doc:`Quick Start <introduction/quickstart>` - Overview to get you started quickly.
 
 
 How the Documentation is Organized
@@ -23,20 +23,31 @@ How the Documentation is Organized
 .. hlist::
     :columns: 1
 
-    - :doc:`Installation <introduction/install>`: Overview to get you started quickly.
-    - :doc:`Boilerplate <topics/boilerplate>`: Generate a boilerplate
-    - :doc:`Mandatory Variables <topics/variables>`: Setup the needed variables for bot
-    - :doc:`Customization <topics/customization>`: Easily customize your bot.
-    - :doc:`Creating Plugins <topics/plugins>`: Code your own plugins
-    - :doc:`Run Bot <topics/run>`: Run your bot locally
-    - :doc:`Using Databases <topics/databases>`: Use various databases with pystark
+    - :doc:`Installation <introduction/install>` - Overview to get you started quickly.
+    - :doc:`Boilerplate <topics/boilerplate>` - Generate a boilerplate.
+    - :doc:`Mandatory Variables <topics/variables>` -  Setup the needed variables for bot.
+    - :doc:`Customization <topics/customization>` - Easily customize your bot.
+    - :doc:`Creating Plugins <topics/plugins>` - Code your own plugins
+    - :doc:`Run Bot <topics/run>` - Run your bot locally.
+    - :doc:`Using Databases <topics/database>` - Use various databases with PyStark.
 
 
 Easy mantra to use this documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Just tap on ``Next`` button below every page, keep reading while following the steps whenever necessary. That's it.
 
+
+Meta
+^^^^
+
+.. hlist::
+    :columns: 1
+
+    - :doc:`PyStark FAQs <meta/faqs>` - Answer to common PyStark questions.
+    - :doc:`ChangeLog <meta/changelog>` - ChangeLog for PyStark releases.
+
+
 .. toctree::
     :hidden:
     :caption: Introduction
@@ -53,10 +64,11 @@ Just tap on ``Next`` button below every page, keep reading while following the s
     topics/plugins
     topics/customization
     topics/run
-    topics/databases
+    topics/database
 
 .. toctree::
     :hidden:
     :caption: Meta
 
-    topics/faqs
+    meta/faqs
+    meta/changelog

docs/meta/changelog.rst

@@ -0,0 +1,17 @@
+ChangeLog
+=========
+
+Latest Version - ``v0.2.5``
+
+------------------
+
+.. confval:: v0.2.5
+
+- Added in-built functions to query postgres tables - :ref:`Read More <default-functions>`
+- Added ChangeLog to docs (this webpage)
+- Improve documentation using sphinx-toolbox
+
+
+.. confval:: v0.2.4
+
+- This Documentation was created

docs/requirements.txt

@@ -1,4 +1,4 @@
 sphinx-rtd-theme
 sphinx-copybutton
 sphinx-rtd-dark-mode
-# sphinx-toolbox
+sphinx-toolbox

docs/topics/databases.rst → docs/topics/database.rst

@@ -6,7 +6,7 @@ By following this guide, you will have a basic understanding of how to use them.
 
 .. note::
 
-    This feature is still in beta. There are a lot of things to do like adding global functions, default classes, alembic support for sqlalchemy, etc and this is just a pre-release.
+    This feature is still in beta. There are a lot of things to add like alembic support for sqlalchemy, etc and this is just a pre-release.
 
 .. contents:: Contents
     :backlinks: none
@@ -40,7 +40,7 @@ Below is a code example for a table named ``users`` with 3 columns named ``user_
     class Users(Base):
         __tablename__ = "users"
         __table_args__ = {'extend_existing': True}
-        user_id = Column(Integer, primary_key=True)  # sql pk
+        user_id = Column(Integer, primary_key=True)  # sql primary key (pk)
         name = Column(String)
         aim = Column(String)
 
@@ -53,43 +53,17 @@ Below is a code example for a table named ``users`` with 3 columns named ``user_
     # Create Table
     Users.__table__.create(checkfirst=True)
 
-- **Querying Tables** - You can query tables using ``Session`` object.
+- **Querying Tables** - You can query tables using ``Session`` object or the in-built pystark functions.
 
-.. code-block:: python
-
-    # import 'Session' object
-    from pystark.database.postgres import Session
-    # import Python class for respective table
-    # let's say it is in 'users_sql.py' inside 'database' folder.
-    from database.users_sql import Users
-
-
-    # This function gives total 'rows', that is total user ids in 'users' table.
-    def num_users():
-        users = Session.query(Users).count()
-        # close session after all queries are made.
-        Session.close()
-        return users
-
-
-    # This function returns 'name' and 'aim' for users by using 'user_id'
-    def get_name_and_aim(user_id):
-        query = Session.query(Users).get(user_id)
-        name = query.name  # get name
-        aim = query.aim  # get aim
-        Session.close()
-        return (name, aim)
+    - :ref:`Using Session object <session-object>`
+    - :ref:`Using in-built functions <default-functions>`
 
 
-    # This function sets name and aim for users by using 'user_id'
-    def set_name_and_aim(user_id, name, aim):
-        query = Session.query(Users).get(user_id)
-        query.name = name  # set name
-        query.aim = aim  # set aim
-        Session.commit()  # use this after setting anything.
-        # Now you don't need to 'Session.close()' as you used 'Session.commit()' already.
+.. toctree::
+    :hidden:
+    :caption: database
 
-    # Etc
+    postgres
 
 --------
 

docs/topics/postgres.rst

@@ -0,0 +1,165 @@
+Querying Postgres Tables
+========================
+
+In this guide, you will learn how to query using postgres tables while using PyStark
+
+.. note::
+
+    This feature is still in beta. There are a lot of things to add like default classes, alembic support, etc and this is just a pre-release.
+
+.. contents:: Contents
+    :backlinks: none
+    :depth: 1
+    :local:
+
+--------
+
+.. _default-functions:
+
+Using the in-built functions
+----------------------------
+
+PyStark provides some default functions to query postgres tables. These functions allow you to query tables using table name (``__tablename__`` attribute), that is, a string instead of a class. Therefore, you do not need to import classes.
+
+.. note::
+
+    All the in-built functions are asynchronous.
+
+.. list-table:: In-built Functions
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Name
+     - Function
+   * - **all_db**
+     - :ref:`Get All Rows <all_db>`
+   * - **get_db**
+     - :ref:`Get a Particular Row <get_db>`
+   * - **count_db**
+     - :ref:`Get Number of Rows <count_db>`
+   * - **set_db**
+     - :ref:`Set/Update value of a key in a Row <set_db>`
+   * - **delete_db**
+     - :ref:`Delete a Row <delete_db>`
+
+.. _all_db:
+
+- **Get All Rows**
+
+.. code-block:: python
+
+    from pystark.database.postgres import all_db
+
+
+    # Get all rows from "users" table as dicts.
+    async def get_users():
+        all_data = await all_db("users")
+        print(all_data)
+
+.. _get_db:
+
+- **Get a Particular Row**
+
+.. code-block:: python
+
+    from pystark.database.postgres import get_db
+
+
+    # Get row using primary key from "users" table.
+    async def get_user():
+        user_id = 500123456  # primary key
+        get_data = await get_db("users", user_id)
+        print(get_data)
+
+.. _count_db:
+
+- **Get Number of Rows**
+
+.. code-block:: python
+
+    from pystark.database.postgres import count_db
+
+
+    # Get number of rows in "users" table.
+    async def user_count():
+        count = await count_db("users")
+        print(count)
+
+
+.. _set_db:
+
+- **Set/Update value of a key in a Row**
+
+.. code-block:: python
+
+    from pystark.database.postgres import set_db
+
+
+    # set/update key, value pairs in "users" table.
+    async def set_data():
+        user_id = 500123456  # primary key
+        key_to_change = "aim"
+        new_value = "programmer"
+        set_data = await set_db("users", user_id, key_to_change, new_value)
+        print("Set")
+
+.. _delete_db:
+
+- **Delete a Row**
+
+.. code-block:: python
+
+    from pystark.database.postgres import delete_db
+
+
+    # Delete a row using primary key from "users" table.
+    async def delete_user():
+        user_id = 500123456
+        delete_data = await delete_db("users", user_id)
+        print("Deleted")
+
+--------
+
+.. _session-object:
+
+Using the Regular Way (Session object)
+--------------------------------------
+
+You can query tables using the ``Session`` object which is the regular way in sqlalchemy.
+
+
+.. code-block:: python
+
+    # import 'Session' object
+    from pystark.database.postgres import Session
+    # import Python class for respective table
+    # let's say it is in 'users_sql.py' inside 'database' folder.
+    from database.users_sql import Users
+
+
+    # This function gives total 'rows', that is total user ids in 'users' table.
+    def num_users():
+        users = Session.query(Users).count()
+        # close session after all queries are made.
+        Session.close()
+        return users
+
+
+    # This function returns 'name' and 'aim' for users by using 'user_id'
+    def get_name_and_aim(user_id):
+        query = Session.query(Users).get(user_id)
+        name = query.name  # get name
+        aim = query.aim  # get aim
+        Session.close()
+        return (name, aim)
+
+
+    # This function sets name and aim for users by using 'user_id'
+    def set_name_and_aim(user_id, name, aim):
+        query = Session.query(Users).get(user_id)
+        query.name = name  # set name
+        query.aim = aim  # set aim
+        Session.commit()  # use this after setting anything.
+        # Now you don't need to 'Session.close()' as you used 'Session.commit()' already.
+
+    # Etc