Metadata-Version: 2.1
Name: aiochsa
Version: 1.2.1
Summary: Clickhouse Python/asyncio library for use with SQLAlchemy core
Home-page: https://github.com/ods/aiochsa
Author: Denis Otkidach
Author-email: denis.otkidach@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.7
License-File: LICENSE
Requires-Dist: aiohttp (<4.0.0,>=3.7.2)
Requires-Dist: clickhouse-sqlalchemy (>=0.1.5)
Requires-Dist: lark-parser (>=0.11.2)
Requires-Dist: simplejson (>=3.16.0)
Requires-Dist: sqlalchemy (>=1.3.0)
Requires-Dist: backports.zoneinfo ; python_version < "3.9"
Provides-Extra: test
Requires-Dist: lovely-pytest-docker (>=0.1.0) ; extra == 'test'
Requires-Dist: pytest (>=6.2.0) ; extra == 'test'
Requires-Dist: pytest-asyncio (>=0.14.0) ; extra == 'test'
Requires-Dist: pytest-cov (>=2.11.1) ; extra == 'test'
Requires-Dist: six ; extra == 'test'

aiochsa
=======

Clickhouse Python/asyncio library for use with SQLAlchemy core


Example
-------

.. code-block:: python

    import aiochsa
    import sqlalchemy as sa

    table = sa.Table(
        'test', sa.MetaData(),
        sa.Column('id', sa.Integer),
        sa.Column('name', sa.String),
    )

    async with aiochsa.connect('clickhouse://127.0.0.1:8123') as conn:
        await conn.execute(
            table.insert(),
            [
                {'id': 1, 'name': 'Alice'},
                {'id': 2, 'name': 'Bob'},
            ],
        )
        rows = await conn.fetch(
            table.select()
        )


To add ``FINAL`` modifier use ``with_hint(table, 'FINAL')``
(see `SQLAlchemy docs for details <https://docs.sqlalchemy.org/en/13/core/selectable.html?highlight=with_hint#sqlalchemy.sql.expression.Select.with_hint>`_).

Configure logging to show SQL:

.. code-block:: python

    logging.getLogger('aiochsa.client.SQL').setLevel(logging.DEBUG)


Custom type converters
----------------------

Here is an example of installing converter for ClickHouse's ``DateTime`` type
that requires and returns timezone-aware Python's ``datetime`` object and
stores it as UTC:

.. code-block:: python

    from datetime import datetime
    import aiochsa
    from aiochsa.types import DateTimeUTCType, TypeRegistry

    types = TypeRegistry()
    types.register(DateTimeUTCType, ['DateTime'], datetime)
    conn = aiochsa.connect(dsn, types=types)


Change log
----------

See `CHANGELOG <https://github.com/ods/aiochsa/blob/master/CHANGELOG.rst>`_.


Development
-----------

Prerequizites: Python (use pyenv to manage multiple versions), pip, tox,
coverage, docker, docker-compose.

Running tests:

.. code-block:: shell

    # Run whole tests matrix:
    tox
    # Run test with specific Python version only:
    tox -e py38
    # Test with specific Clickhouse version:
    tox -e py38 -- --clickhouse-version=21.2.2.8
    # Run specified test(s):
    tox -e py38 -- tests/test_execute.py::test_aggregate_function


