source/projects/anosql/README.rst

anosql
======

**NOTICE**: This project is now deprecated in favor of `aiosql`_.

Unfortunately, I no longer have the time to devote to this project, and aiosql
is now a lot more popular.  I don't think it makes sense to maintain both.
Open source ftw!  Thanks for your hard work, `Will`_!

.. _aiosql: https://github.com/nackjicholson/aiosql
.. _Will: https://github.com/nackjicholson

.. image:: https://badge.fury.io/py/anosql.svg
    :target: https://badge.fury.io/py/anosql
    :alt: pypi package version

.. image:: http://readthedocs.org/projects/anosql/badge/?version=latest
    :target: http://anosql.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://travis-ci.org/honza/anosql.svg?branch=master
    :target: https://travis-ci.org/honza/anosql
    :alt: Travid build status

A Python library for using SQL

Inspired by the excellent `Yesql`_ library by Kris Jenkins.  In my mother
tongue, *ano* means *yes*.

If you are on python3.6+ or need ``anosql`` to work with ``asyncio``-based database drivers, see the related project, `aiosql <https://github.com/nackjicholson/aiosql>`_.

Complete documentation is available at `Read The Docs <https://anosql.readthedocs.io/en/latest/>`_.

Installation
------------

::

  $ pip install anosql

Usage
-----

Basics
******

Given a ``queries.sql`` file:

.. code-block:: sql

  -- name: get-all-greetings
  -- Get all the greetings in the database
  SELECT * FROM greetings;

  -- name: select-users
  -- Get all the users from the database,
  -- and return it as a dict
  SELECT * FROM USERS;

We can issue SQL queries, like so:

.. code-block:: python

    import anosql
    import psycopg2
    import sqlite3

    # PostgreSQL
    conn = psycopg2.connect('...')
    queries = anosql.from_path('queries.sql', 'psycopg2')

    # Or, Sqlite3...
    conn = sqlite3.connect('cool.db')
    queries = anosql.from_path('queries.sql', 'sqlite3')

    queries.get_all_greetings(conn)
    # => [(1, 'en', 'Hi')]

    queries.get_all_greetings.__doc__
    # => Get all the greetings in the database

    queries.get_all_greetings.sql
    # => SELECT * FROM greetings;

    queries.available_queries
    # => ['get_all_greetings']


Parameters
**********

Often, you want to change parts of the query dynamically, particularly values in
the ``WHERE`` clause.  You can use parameters to do this:

.. code-block:: sql

  -- name: get-greetings-for-language
  -- Get all the greetings in the database for given language
  SELECT *
  FROM greetings
  WHERE lang = %s;

And they become positional parameters:

.. code-block:: python

  visitor_language = "en"
  queries.get_greetings_for_language(conn, visitor_language)
  # => [(1, 'en', 'Hi')]


One Row Query
*************

Often, you would expect at most one row from a query, so that getting a list
is not convenient. Appending ``?`` to the query name makes it return either one
tuple if it returned one row, or ``None`` in other cases.

.. code-block:: sql

  -- name: get-a-greeting?
  -- Get a greeting based on its id
  SELECT *
  FROM greetings
  WHERE id = %s;

Then a tuple is returned:

.. code-block:: python

  queries.get_a_greeting(conn, 1)
  # => (1, 'en', 'Hi')


Named Parameters
****************

To make queries with many parameters more understandable and maintainable, you
can give the parameters names:

.. code-block:: sql

  -- name: get-greetings-for-language-and-length
  -- Get all the greetings in the database for given language and length
  SELECT *
  FROM greetings
  WHERE lang = :lang
  AND len(greeting) <= :length_limit;

If you were writing a Postgresql query, you could also format the parameters as
``%s(lang)`` and ``%s(length_limit)``.

Then, call your queries like you would any Python function with named
parameters:

.. code-block:: python

  visitor_language = "en"

  greetings_for_texting = queries.get_greetings_for_language_and_length(
                conn, lang=visitor_language, length_limit=140)

Update/Insert/Delete
********************

In order to run ``UPDATE``, ``INSERT``, or ``DELETE`` statements, you need to
add ``!`` to the end of your query name.  Anosql will then execute it properly.
It will also return the number of affected rows.

Insert queries returning autogenerated values
*********************************************

If you want the auto-generated primary key to be returned after you run an
insert query, you can add ``<!`` to the end of your query name.

.. code-block:: sql

  -- name: create-user<!
  INSERT INTO person (name) VALUES (:name)

Adding custom query loaders.
****************************

Out of the box, ``anosql`` supports SQLite and PostgreSQL via the stdlib ``sqlite3`` database driver
and ``psycopg2``. If you would like to extend ``anosql`` to communicate with other types of databases,
you may create a driver adapter class and register it with ``anosql.core.register_driver_adapter()``.

Driver adapters are duck-typed classes which adhere to the below interface. Looking at ``anosql/adapters`` package
is a good place to get started by looking at how the ``psycopg2`` and ``sqlite3`` adapters work.

To register a new loader::

    import anosql
    import anosql.core

    class MyDbAdapter():
        def process_sql(self, name, op_type, sql):
            pass

        def select(self, conn, sql, parameters):
            pass

        @contextmanager
        def select_cursor(self, conn, sql, parameters):
            pass

        def insert_update_delete(self, conn, sql, parameters):
            pass

        def insert_update_delete_many(self, conn, sql, parameters):
            pass

        def insert_returning(self, conn, sql, parameters):
            pass

        def execute_script(self, conn, sql):
            pass


    anosql.core.register_driver_adapter("mydb", MyDbAdapter)

    # To use make a connection to your db, and pass "mydb" as the db_type:
    import mydbdriver
    conn = mydbriver.connect("...")

    anosql.load_queries("path/to/sql/", "mydb")
    greetings = anosql.get_greetings(conn)

    conn.close()

If your adapter constructor takes arguments, you can register a function which can build
your adapter instance::

    def adapter_factory():
        return MyDbAdapter("foo", 42)

    anosql.register_driver_adapter("mydb", adapter_factory)

Tests
-----

::

   $ pip install tox
   $ tox

License
-------

BSD, short and sweet

.. _Yesql: https://github.com/krisajenkins/yesql/