From f9a993c39406ed68855b8078d4404aa55fc26ee9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ege=20Emir=20=C3=96zkan?= Date: Sun, 16 Aug 2020 23:11:54 +0300 Subject: [PATCH] Add more readme --- docs/datalite.rst | 2 +- docs/decorator.rst | 79 +++++++++++++++++++++++++++++++++++++++++++ docs/fetch.rst | 32 ++++++++++++++++++ docs/index.rst | 15 +++++--- docs/installation.rst | 23 +++++++++++++ docs/migration.rst | 6 ++++ 6 files changed, 152 insertions(+), 5 deletions(-) create mode 100644 docs/decorator.rst create mode 100644 docs/fetch.rst create mode 100644 docs/installation.rst create mode 100644 docs/migration.rst diff --git a/docs/datalite.rst b/docs/datalite.rst index 5c6c468..66a1f24 100644 --- a/docs/datalite.rst +++ b/docs/datalite.rst @@ -1,4 +1,4 @@ -datalite package +API Reference ================ datalite Module diff --git a/docs/decorator.rst b/docs/decorator.rst new file mode 100644 index 0000000..ee3f3e2 --- /dev/null +++ b/docs/decorator.rst @@ -0,0 +1,79 @@ +Basic Decorator Operations +========================== + +Creating a datalite class +------------------------- + +A datalite class is a special dataclass. It is created by using a decorator ``@datalite.datalite``, +members of this class are, from Python's perspective, just normal classes. However, they have +additional methods and attributes. ``@datalite`` decorator needs a database path to be provided. +This database is the database the table for the dataclass will be created. + +.. code-block:: python + + from datalite import datalite + @datalite(db_path='db.db') + @dataclass + class Student: + student_id: int = 1 + student_name: str = "Kurt Gödel" + student_gpa: float = 3.9 + +Here, ``datalite`` will create a table called ``student`` in the database file ``db.db``, this +file will include all the fields of the dataclass as columns. Default value of these columns +are same as the default value of the dataclass. + +Special Methods +--------------- + +Each object initialised from a dataclass decorated with the ``@dataclass`` decorator automatically +gains access to three special methods. It should be noted, due to the nature of the library, extensions +such as ``mypy`` and IDEs such as PyCharm will not be able to see these methods and may raise exceptions. + +With this in mind, let us create a new object and run the methods over this objects. + +.. code-block:: python + + new_student = Student(0, "Albert Einstein", 4.0) + +Creating an Entry +################## + +First special method is ``.create_entry()`` when called on an object of a class decorated with the +``@datalite`` decorator, this method creates an entry in the table of the bound database of the class, +in this case, table named ``student`` in the ``db.db``. Therefore, to create the entry of Albert Einstein +in the table: + +.. code-block:: python + + new_student.create_entry() + +This also modifies the object in an intresting way, it adds a new attribute ``obj_id``, this is a unique, +autoincremented value in the database. It can be accessed by ``new_student.obj_id``. + +Updating an Entry +################## + +Second special method is ``.update_entry()``. If an object's attribute is changed, to update its +record in the database, this method must be called. + +.. code-block:: python + + new_student.student_gpa = 5.0 # He is Einstein, after all. + new_student.update_entry() + + +Deleting an Entry +################## + +To delete an entry from the record, the third and last special method, ``.remove_entry()`` should +be used. + +.. code-block:: python + + new_student.remove_entry() + +.. warning:: + + It should be noted that, if the ``new_student.obj_id`` attribute is modified, ``.update_entry()`` + and ``.remove_entry()`` may have unexpected results. diff --git a/docs/fetch.rst b/docs/fetch.rst new file mode 100644 index 0000000..1dc40ec --- /dev/null +++ b/docs/fetch.rst @@ -0,0 +1,32 @@ +Fetching Functions +=================== + +A database is hardly useful if data does not persist between program runs. In ``datalite`` +one can use ``datalite.fetch`` module to fetch data back from the database. + +There are different sorts of fetching. One can fetch all the objects of a class +using ``fetch_all(class_)``, or an object with a specific object id using ``fetch_from(class_, obj_id)``. +There are more functions for plural conditional fetching (``fetch_if``, ``fetch_where``) where +all objects fitting a condition will be returned, as well as singular conditional fetching that returns +the first object that fits a condition (``fetch_equals``). + +Pagination +########## + +Pagination is a feature that allows a portion of the results to be returned. Since ``datalite`` +is built to work with databases that may include large amounts of data, many systems using large +portions of data also make use of pagination. By building pagination inside the system, we hope to +allow easier usage. + +* ``fetch_where`` +* ``fetch_if`` +* ``fetch_all`` + +Supports pagination, in general, pagination is controlled via two arguments ``page`` and ``element_count``, +``page`` argument specifies which page to be returned and ``element_count`` specifies how many elements +each page has. When ``page`` is set to 0, all results are returned irregardless of the value of the +``element_count``. + +.. important:: + + More information regarding the ``datalite.fetch`` functions can be found in the API reference. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 07036cf..236e845 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,25 +3,32 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. + Welcome to Datalite's documentation! ==================================== Datalite is a simple to use Python library that can bind a dataclass to an sqlite3 database. -Contents -======================== +Documentation +============= .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: - + + installation + decorator + fetch + migration datalite + Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` + diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..18d6cf5 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,23 @@ +Getting Started +================= + +Welcome to the documentation of datalite. Datalite provides a simple, intuitive way to bind dataclasses +to sqlite3 databases. In its current version, it provides implicit support for conversion between +``int``, ``float``, ``str``, ``bytes`` classes and their ``sqlite3`` counterparts, default values, +basic schema migration and fetching functions. + +Installation +############ + +Simply write: + +.. code-block:: bash + + pip install datalite + +In the shell. And then, whenever you want to use it in Python, you can use: + +.. code-block:: python + + import datalite + diff --git a/docs/migration.rst b/docs/migration.rst new file mode 100644 index 0000000..e08058f --- /dev/null +++ b/docs/migration.rst @@ -0,0 +1,6 @@ +Schema Migrations +================== + +Datalite provides a module, ``datalite.migrations`` that handles schema migrations. When a class +definition is modified, ``datalite.migrations.basic_migration`` can be called to automatically +transfer records to a table fitting the new definitions.