picopyn 0.2.0__tar.gz → 0.3.0.dev1__tar.gz

{picopyn-0.2.0 → picopyn-0.3.0.dev1}/LICENSE

@@ -1,6 +1,6 @@
 BSD 2-Clause License
 
-Copyright (c) 2025, Picodata
+Copyright (c) 2025-2026, Picodata
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

{picopyn-0.2.0/picopyn.egg-info → picopyn-0.3.0.dev1}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.4
 Name: picopyn
-Version: 0.2.0
-Summary: Async connector for working with the distributed Picodata database.
-Author-email: Asya Lomakina <a.lomakina@picodata.io>, Igor Kuznetsov <i.kuznetsov@picodata.io>, Dmitriy Кoltsov <dkoltsov@picodata.io>
-License: BSD-2-Clause
-Project-URL: Homepage, https://git.picodata.io/solution/picopyn
+Version: 0.3.0.dev1
+Summary: Python connector for working with the distributed Picodata database.
+Author-email: Asya Lomakina <a.lomakina@picodata.io>, Igor Kuznetsov <i.kuznetsov@picodata.io>, Dmitriy Кoltsov <dkoltsov@picodata.io>, Daniil Gorlyakov <d.gorlyakov@picodata.io>
+License-Expression: BSD-2-Clause
+Project-URL: Source, https://git.picodata.io/solution/picopyn
+Project-URL: Documentation, https://picopyn.readthedocs.io/en/stable/
+Project-URL: Changelog, https://git.picodata.io/core/drivers/picopyn/-/blob/main/CHANGELOG.md
 Keywords: database,picodata
 Classifier: Programming Language :: Python :: 3.10
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -20,9 +21,7 @@ License-File: AUTHORS.md
 Requires-Dist: async-timeout==5.0.1
 Requires-Dist: asyncpg==0.30.0
 Requires-Dist: typing_extensions==4.12.2; python_version == "3.10"
-Provides-Extra: gssauth
-Requires-Dist: gssapi; platform_system != "Windows" and extra == "gssauth"
-Requires-Dist: sspilib; platform_system == "Windows" and extra == "gssauth"
+Requires-Dist: psycopg[binary]==3.3.4
 Provides-Extra: test
 Requires-Dist: pytest==8.3.5; extra == "test"
 Requires-Dist: pytest-asyncio==0.25.3; extra == "test"
@@ -30,37 +29,56 @@ Requires-Dist: ruff==0.11.13; extra == "test"
 Requires-Dist: mypy==1.16.0; extra == "test"
 Requires-Dist: black==25.1.0; extra == "test"
 Provides-Extra: docs
-Requires-Dist: pdoc==15.0.4; extra == "docs"
-Requires-Dist: pyright==1.1.396; extra == "docs"
+Requires-Dist: mkdocs<2.0,>=1.0; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Provides-Extra: benchmark
+Requires-Dist: numpy==1.24.4; extra == "benchmark"
+Requires-Dist: matplotlib==3.8.4; extra == "benchmark"
+Requires-Dist: colorama==0.4.6; extra == "benchmark"
+Provides-Extra: publish
+Requires-Dist: pypi-cleanup; extra == "publish"
 Dynamic: license-file
 
-# Picopyn - Picodata python driver
+[![Version](https://img.shields.io/pypi/v/picopyn.svg?maxAge=86400)](https://pypi.org/project/picopyn/)
+[![Supported Versions](https://img.shields.io/pypi/pyversions/picopyn.svg)](https://pypi.org/project/picopyn)
+[![Documentation](https://readthedocs.org/projects/picopyn/badge/?version=stable)](https://picopyn.readthedocs.io)
 
-**Picopyn** is a Python package for working with the distributed Picodata database. It's built on top of the [asyncpg](https://github.com/MagicStack/asyncpg) package.
+# Picopyn - Picodata Python driver
+
+**Picopyn** is a Python package for working with the distributed [Picodata](https://picodata.io/en/) database.
 
 ## Features
 * Connection pooling with configurable pool size
 * Optional automatic node discovery
 * Pluggable load-balancing strategies
-* Fully asynchronous API
+* Provides both asynchronous API (based on [asyncpg](https://github.com/MagicStack/asyncpg)) and synchronous API (based on [psycopg](https://www.psycopg.org/))
 
 ## Navigation
-* [Installation](#install-driver)
-* [Quickstart](#simple-start)
-* [Development](#dev)
-* [Benchmark](#bench)
-
-## <a name="install-driver"></a>Install
+* [Installation](#installation)
+* [Quickstart](#quickstart)
+* [Development](#development)
+    * [Docs](#documentation)
+    * [Lint](#how-to-write-code)
+    * [Test](#how-to-test)
+    * [Debug](#how-to-debug)
+* [Benchmark](#benchmark)
+
+## Installation
+
+```sh
+pip install picopyn
+```
 
-Install from source:
+Or from source:
 
-``` sh
+```sh
 git clone https://git.picodata.io/solution/picopyn.git
 cd picopyn
-make install
+pip install -e .
 ```
 
-## <a name="simple-start"></a>Quickstart
+## Quickstart
 
 ```python
 import asyncio
@@ -86,22 +104,31 @@ async def main():
 asyncio.run(main())
 ```
 
-## <a name="dev"></a>Development
+## Development
+For development we use [uv](https://docs.astral.sh/uv/getting-started/installation/) as package manager and [docker compose](https://docs.docker.com/compose/install/) for test environment.
 
-Install development dependencies
+To install development dependencies:
 ```bash
-pip install -r requirements-dev.txt
+uv sync --extra test
 ```
 
-### Documentation
-
-To update documentation:
+Inside the test container, run the same command to keep dependencies up to date if the image is outdated:
 ```bash
-make gen-doc
+make shell
+# inside the container:
+make install
 ```
 
-To view documentation:
+### Documentation
+
+The documentation is written in Markdown and built with [MkDocs](https://www.mkdocs.org/) using the [Material theme](https://squidfunk.github.io/mkdocs-material/). API reference is generated automatically from docstrings via [mkdocstrings](https://mkdocstrings.github.io/).
+
+Published documentation is available at **[picopyn.readthedocs.io](https://picopyn.readthedocs.io/en/stable/)**.
+
+Source files are located in the `docs/` directory. To work on docs locally, install the docs dependencies and start the live-reload server:
+
 ```bash
+uv sync --extra docs
 make doc
 ```
 
@@ -115,7 +142,7 @@ We use several tools to ensure code style and type safety.
 To check code style and static types:
 ```bash
 make lint
-````
+```
 
 To automatically fix formatting and style issues:
 
@@ -124,6 +151,7 @@ make fmt
 ```
 
 ### How to test
+We use [docker compose](https://docs.docker.com/compose/install/) for test environment.
 
 Run the general test suite:
 
@@ -145,8 +173,7 @@ This will:
 
 
 ### How to debug
-
-Do not forget run environment via `make env`
+Do not forget to run the environment via `make env`
 
 For debugging purposes:
 
@@ -165,8 +192,9 @@ python -m asyncio
 3. To connect directly to Picodata:
 
 ```bash
-picodata admin tmp/picodata-1-1/admin.sock
+picodata admin tmp/data/picodata-1-1/admin.sock
 ```
-## <a name="bench"></a>Benchmark
+
+## Benchmark
 
 Benchmark instructions and usage examples are available [here](benchmark/README.md).

picopyn-0.3.0.dev1/README.md

@@ -0,0 +1,158 @@
+[![Version](https://img.shields.io/pypi/v/picopyn.svg?maxAge=86400)](https://pypi.org/project/picopyn/)
+[![Supported Versions](https://img.shields.io/pypi/pyversions/picopyn.svg)](https://pypi.org/project/picopyn)
+[![Documentation](https://readthedocs.org/projects/picopyn/badge/?version=stable)](https://picopyn.readthedocs.io)
+
+# Picopyn - Picodata Python driver
+
+**Picopyn** is a Python package for working with the distributed [Picodata](https://picodata.io/en/) database.
+
+## Features
+* Connection pooling with configurable pool size
+* Optional automatic node discovery
+* Pluggable load-balancing strategies
+* Provides both asynchronous API (based on [asyncpg](https://github.com/MagicStack/asyncpg)) and synchronous API (based on [psycopg](https://www.psycopg.org/))
+
+## Navigation
+* [Installation](#installation)
+* [Quickstart](#quickstart)
+* [Development](#development)
+    * [Docs](#documentation)
+    * [Lint](#how-to-write-code)
+    * [Test](#how-to-test)
+    * [Debug](#how-to-debug)
+* [Benchmark](#benchmark)
+
+## Installation
+
+```sh
+pip install picopyn
+```
+
+Or from source:
+
+```sh
+git clone https://git.picodata.io/solution/picopyn.git
+cd picopyn
+pip install -e .
+```
+
+## Quickstart
+
+```python
+import asyncio
+from picopyn import Client
+
+async def main():
+    # create and connect client to the picodata cluster
+    client = Client(dsn="postgresql://admin:pass@localhost:5432")
+    await client.connect()
+
+    # execute DDL operations
+    await client.execute('''
+        CREATE TABLE "warehouse" (id INTEGER NOT NULL, item TEXT NOT NULL, PRIMARY KEY (id)) USING memtx DISTRIBUTED BY (id) OPTION (TIMEOUT = 3.0);
+    ''')
+
+    # execute DML operations
+    await client.execute('INSERT INTO \"warehouse\" VALUES ($1::int, $2::varchar)', 1, "test")
+    rows = await client.fetch('SELECT * FROM \"warehouse\"')
+    print(rows)
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Development
+For development we use [uv](https://docs.astral.sh/uv/getting-started/installation/) as package manager and [docker compose](https://docs.docker.com/compose/install/) for test environment.
+
+To install development dependencies:
+```bash
+uv sync --extra test
+```
+
+Inside the test container, run the same command to keep dependencies up to date if the image is outdated:
+```bash
+make shell
+# inside the container:
+make install
+```
+
+### Documentation
+
+The documentation is written in Markdown and built with [MkDocs](https://www.mkdocs.org/) using the [Material theme](https://squidfunk.github.io/mkdocs-material/). API reference is generated automatically from docstrings via [mkdocstrings](https://mkdocstrings.github.io/).
+
+Published documentation is available at **[picopyn.readthedocs.io](https://picopyn.readthedocs.io/en/stable/)**.
+
+Source files are located in the `docs/` directory. To work on docs locally, install the docs dependencies and start the live-reload server:
+
+```bash
+uv sync --extra docs
+make doc
+```
+
+### How to write code
+
+We use several tools to ensure code style and type safety.
+* ruff — code style, lint checks and automatic lint fixing
+* mypy — static type checking
+* black — code formatting
+
+To check code style and static types:
+```bash
+make lint
+```
+
+To automatically fix formatting and style issues:
+
+```bash
+make fmt
+```
+
+### How to test
+We use [docker compose](https://docs.docker.com/compose/install/) for test environment.
+
+Run the general test suite:
+
+```bash
+make test
+```
+
+or run SSL tests:
+
+```bash
+make test-ssl
+```
+
+This will:
+
+1. Start required test containers (Picodata cluster and test-runner) using Docker Compose
+
+2. Execute tests using pytest
+
+
+### How to debug
+Do not forget to run the environment via `make env`
+
+For debugging purposes:
+
+1. Open a bash shell in the test container:
+
+```bash
+make shell
+```
+
+2. For interactive Python (with asyncio support) run inside of container:
+
+```bash
+python -m asyncio
+```
+
+3. To connect directly to Picodata:
+
+```bash
+picodata admin tmp/data/picodata-1-1/admin.sock
+```
+
+## Benchmark
+
+Benchmark instructions and usage examples are available [here](benchmark/README.md).

{picopyn-0.2.0 → picopyn-0.3.0.dev1}/benchmark/README.md

@@ -26,21 +26,18 @@ This directory contains a benchmark tool for measuring Picopyn insert performanc
 ## <a name="prerequisites"></a>Prerequisites
 
 - Python 3.10+
-- Install project dependencies (including `picopyn` and deps from `./requirements.txt`):
 
-Attention! It's recommended to use out test-runner container. All commands below are for the docker container! To enter to container execute in console:
+All commands below are for the test-runner container. To enter it:
 
 ```bash
-# root dir
+# from project root
 make shell
+cd benchmark
 ```
 
-To install deps:
+Sync dependencies (in case the image is outdated):
 ```bash
-make install
-cd benchmark
-# not necessary for docker container
-pip install -r requirements.txt
+uv sync --extra test --extra benchmark
 ```
 
 ## <a name="csv"></a>CSV Input Format
@@ -211,7 +208,7 @@ For a big dataset you may need to inscrease Picodata memory. Use:
 
 ```bash
 # connect to picodata instance
-picodata admin tmp/data/picodata-1-1/admin.sock
+picodata admin ../tmp/data/picodata-1-1/admin.sock
 # inside picodata console switch to LUA
 (admin) sql> \lua
 Language switched to lua

picopyn-0.3.0.dev1/docs/async.md

@@ -0,0 +1,3 @@
+# Async
+
+::: picopyn.asynchronous

picopyn-0.3.0.dev1/docs/explain.md

@@ -0,0 +1,11 @@
+# Explain
+
+::: picopyn.explain
+    options:
+      members: false
+      show_root_heading: false
+      show_source: false
+
+::: picopyn.explain.ExplainPlan
+
+::: picopyn.explain.ExplainRawPlan

picopyn-0.3.0.dev1/docs/index.md

@@ -0,0 +1,41 @@
+# picopyn
+
+**picopyn** is a Python connector for working with the distributed [Picodata](https://picodata.io/en/) database.
+
+## Features
+
+- Connection pooling with configurable pool size
+- Optional automatic node discovery
+- Pluggable load-balancing strategies
+- Asynchronous API based on [asyncpg](https://github.com/MagicStack/asyncpg)
+- Synchronous API based on [psycopg](https://www.psycopg.org/)
+
+## Quick start
+
+```sh
+pip install picopyn
+```
+
+```python
+import asyncio
+from picopyn import Client
+
+async def main():
+    client = Client(dsn="postgresql://admin:pass@localhost:5432")
+    await client.connect()
+
+    await client.execute('''
+        CREATE TABLE "warehouse" (id INTEGER NOT NULL, item TEXT NOT NULL, PRIMARY KEY (id))
+        USING memtx DISTRIBUTED BY (id) OPTION (TIMEOUT = 3.0);
+    ''')
+
+    await client.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
+    rows = await client.fetch('SELECT * FROM "warehouse"')
+    print(rows)
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+See [Installation](installation.md) for all install options.

picopyn-0.3.0.dev1/docs/installation.md

@@ -0,0 +1,19 @@
+# Installation
+
+## Requirements
+
+- Python 3.10+
+
+## Install from PyPI
+
+```sh
+pip install picopyn
+```
+
+## Install from source
+
+```sh
+git clone https://git.picodata.io/solution/picopyn.git
+cd picopyn
+pip install -e .
+```

picopyn-0.3.0.dev1/docs/sync.md

@@ -0,0 +1,3 @@
+# Sync
+
+::: picopyn.synchronous

picopyn-0.3.0.dev1/picopyn/__init__.py

@@ -0,0 +1,50 @@
+"""Picopyn is a Python driver for working with the Picodata database.
+
+It provides both [asynchronous](async.md) and [synchronous](sync.md) APIs for connecting to a Picodata cluster, executing queries and working with connection pools.
+
+See [picodata docs](https://docs.picodata.io/picodata/devel/).
+
+## Logging
+
+The library uses standard Python logging under the `picopyn` logger name. No handlers are configured by default — it is up to the application to configure logging. You can do it in several ways:
+
+- configure format and output via root logger (the simplest approach):
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG, format="%(levelname)-8s %(name)s — %(message)s")
+logging.getLogger("picopyn").setLevel(logging.DEBUG)
+```
+
+- add a handler directly to the `picopyn` logger without affecting the root logger:
+```python
+import logging
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter("%(levelname)-8s %(name)s — %(message)s"))
+logging.getLogger("picopyn").addHandler(handler)
+logging.getLogger("picopyn").setLevel(logging.DEBUG)
+```
+
+- if a handler is already configured elsewhere in the application, just set the level:
+```python
+logging.getLogger("picopyn").setLevel(logging.DEBUG)
+```
+
+- set log level for a specific module:
+```python
+logging.getLogger("picopyn.asynchronous.pool").setLevel(logging.DEBUG)
+```
+"""
+
+import logging
+
+from .asynchronous import Client, Connection, ExplainPlan, ExplainRawPlan, Pool
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "Client",
+    "Connection",
+    "ExplainPlan",
+    "ExplainRawPlan",
+    "Pool",
+]

{picopyn-0.2.0/picopyn → picopyn-0.3.0.dev1/picopyn/asynchronous}/__init__.py

@@ -1,6 +1,9 @@
+"""Async API based on asyncpg for connection management, pools, and client classes."""
+
+from picopyn.explain import ExplainPlan, ExplainRawPlan
+
 from .client import Client
 from .connection import Connection
-from .explain import ExplainPlan, ExplainRawPlan
 from .pool import Pool
 
 __all__ = [