investify-utils 2.0.0a10__tar.gz → 2.0.0a12__tar.gz

{investify_utils-2.0.0a10 → investify_utils-2.0.0a12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investify-utils
-Version: 2.0.0a10
+Version: 2.0.0a12
 Summary: Shared utilities for Investify services
 Author-Email: Investify <dev@investify.vn>
 License: MIT
@@ -24,6 +24,8 @@ Provides-Extra: kafka
 Requires-Dist: confluent-kafka[avro,schemaregistry]>=2.0; extra == "kafka"
 Provides-Extra: s3
 Requires-Dist: boto3>=1.34; extra == "s3"
+Provides-Extra: s3-async
+Requires-Dist: aioboto3>=15.0; extra == "s3-async"
 Provides-Extra: helpers
 Requires-Dist: pandas>=2.0; extra == "helpers"
 Requires-Dist: numpy>=2.0; extra == "helpers"

{investify_utils-2.0.0a10 → investify_utils-2.0.0a12}/investify_utils/__init__.py

@@ -5,7 +5,8 @@ Install with optional dependencies:
     pip install investify-utils[postgres]        # Sync PostgreSQL client
     pip install investify-utils[postgres-async]  # Async PostgreSQL client
     pip install investify-utils[kafka]           # Kafka Avro producer/consumer
-    pip install investify-utils[s3]              # S3 client
+    pip install investify-utils[s3]              # Sync S3 client
+    pip install investify-utils[s3-async]        # Async S3 client
     pip install investify-utils[helpers]         # Timestamp/SQL utilities
 
 Usage:
@@ -19,10 +20,10 @@ Usage:
     from investify_utils.kafka import AvroProducer, AvroConsumer
 
     # S3
-    from investify_utils.s3 import S3Client
+    from investify_utils.s3 import S3Client, AsyncS3Client
 
     # Helpers
     from investify_utils.helpers import convert_to_pd_timestamp, create_sql_in_filter
 """
 
-__version__ = "2.0.0a8"
+__version__ = "2.0.0a12"

{investify_utils-2.0.0a10 → investify_utils-2.0.0a12}/investify_utils/kafka/__init__.py

@@ -1,8 +1,11 @@
 """
-Kafka Avro producer and consumer clients (sync only).
+Kafka Avro producer and consumer clients.
 
-Usage:
+Sync (for Celery workers, scripts):
     from investify_utils.kafka import AvroProducer, AvroConsumer
+
+Async (for LangGraph, FastAPI):
+    from investify_utils.kafka import AsyncAvroProducer, AsyncAvroConsumer
 """
 
 
@@ -20,6 +23,14 @@ def __getattr__(name: str):
         from investify_utils.kafka.sync_consumer import OffsetTracker
 
         return OffsetTracker
+    if name == "AsyncAvroProducer":
+        from investify_utils.kafka.async_producer import AsyncAvroProducer
+
+        return AsyncAvroProducer
+    if name == "AsyncAvroConsumer":
+        from investify_utils.kafka.async_consumer import AsyncAvroConsumer
+
+        return AsyncAvroConsumer
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
@@ -27,4 +38,6 @@ __all__ = [
     "AvroProducer",
     "AvroConsumer",
     "OffsetTracker",
+    "AsyncAvroProducer",
+    "AsyncAvroConsumer",
 ]

investify_utils-2.0.0a12/investify_utils/kafka/async_consumer.py

@@ -0,0 +1,210 @@
+"""
+Asynchronous Avro consumer using confluent-kafka with asyncio.
+
+Features:
+- Non-blocking poll with async/await
+- Suitable for FastAPI websocket streaming
+- Background message fetching with queue
+
+Usage:
+    from investify_utils.kafka import AsyncAvroConsumer
+
+    consumer = AsyncAvroConsumer(
+        topic="my-topic",
+        subject="my-topic-value",
+        schema_registry_url="http://localhost:8081",
+        bootstrap_servers="localhost:9092",
+        group_id="my-consumer-group",
+    )
+
+    # In FastAPI websocket
+    @app.websocket("/ws")
+    async def websocket_endpoint(websocket: WebSocket):
+        await websocket.accept()
+        async for key, value in consumer:
+            await websocket.send_json(value)
+"""
+
+import asyncio
+import logging
+from typing import AsyncIterator
+
+from confluent_kafka import DeserializingConsumer, TopicPartition
+from confluent_kafka.schema_registry import SchemaRegistryClient
+from confluent_kafka.schema_registry.avro import AvroDeserializer
+from confluent_kafka.serialization import StringDeserializer
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncAvroConsumer:
+    """
+    Asynchronous Avro consumer for async frameworks.
+
+    Uses a background thread for polling (confluent-kafka is not async-native)
+    and an asyncio queue to bridge to async code.
+
+    Args:
+        topic: Kafka topic name or list of topics
+        subject: Schema Registry subject name
+        schema_registry_url: Schema Registry URL
+        bootstrap_servers: Kafka bootstrap servers
+        group_id: Consumer group ID
+        seek_to_end: Start from latest offset (default: False)
+        queue_size: Max messages to buffer (default: 100)
+        **kwargs: Additional Kafka consumer config
+    """
+
+    def __init__(
+        self,
+        topic: str | list[str],
+        subject: str,
+        schema_registry_url: str,
+        bootstrap_servers: str,
+        group_id: str,
+        seek_to_end: bool = False,
+        queue_size: int = 100,
+        **kwargs,
+    ):
+        self._schema_registry_url = schema_registry_url
+        self._bootstrap_servers = bootstrap_servers
+        self._subject = subject
+        self._group_id = group_id
+        self._topic = topic
+        self._seek_to_end = seek_to_end
+        self._queue_size = queue_size
+        self._kwargs = kwargs
+
+        self._consumer: DeserializingConsumer | None = None
+        self._queue: asyncio.Queue | None = None
+        self._poll_task: asyncio.Task | None = None
+        self._running = False
+
+    def _init_consumer(self) -> DeserializingConsumer:
+        """Initialize the consumer."""
+        schema_registry_client = SchemaRegistryClient({"url": self._schema_registry_url})
+        registered_schema = schema_registry_client.get_latest_version(self._subject)
+        schema_str = registered_schema.schema.schema_str
+
+        avro_deserializer = AvroDeserializer(schema_registry_client, schema_str)
+
+        consumer_config = {
+            "bootstrap.servers": self._bootstrap_servers,
+            "group.id": self._group_id,
+            "key.deserializer": StringDeserializer("utf_8"),
+            "value.deserializer": avro_deserializer,
+            **self._kwargs,
+        }
+        consumer = DeserializingConsumer(consumer_config)
+
+        topic_list = self._topic if isinstance(self._topic, list) else [self._topic]
+
+        if self._seek_to_end:
+
+            def seek_to_end_assign(c, partitions):
+                for p in partitions:
+                    high_offset = c.get_watermark_offsets(p)[1]
+                    p.offset = high_offset
+                c.assign(partitions)
+
+            consumer.subscribe(topic_list, on_assign=seek_to_end_assign)
+        else:
+            consumer.subscribe(topic_list)
+
+        return consumer
+
+    async def start(self) -> None:
+        """Start consuming messages in background."""
+        if self._running:
+            return
+
+        self._consumer = self._init_consumer()
+        self._queue = asyncio.Queue(maxsize=self._queue_size)
+        self._running = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def _poll_loop(self) -> None:
+        """Background task for polling messages."""
+        loop = asyncio.get_running_loop()
+
+        while self._running:
+            # Run blocking poll in thread executor
+            msg = await loop.run_in_executor(None, self._consumer.poll, 0.1)
+
+            if msg is None:
+                continue
+
+            if msg.error():
+                logger.error(f"Consumer error: {msg.error()}")
+                continue
+
+            # Put message in queue (blocks if full)
+            await self._queue.put((msg.key(), msg.value(), msg))
+
+    async def poll(self, timeout: float = 1.0) -> tuple[str | None, dict | None, object] | None:
+        """
+        Poll for a single message.
+
+        Args:
+            timeout: Maximum time to wait in seconds
+
+        Returns:
+            Tuple of (key, value, raw_msg) or None if timeout
+        """
+        if not self._running:
+            await self.start()
+
+        try:
+            return await asyncio.wait_for(self._queue.get(), timeout=timeout)
+        except asyncio.TimeoutError:
+            return None
+
+    async def __aiter__(self) -> AsyncIterator[tuple[str | None, dict | None]]:
+        """
+        Async iterator for consuming messages.
+
+        Yields:
+            Tuple of (key, value) for each message
+        """
+        if not self._running:
+            await self.start()
+
+        while self._running:
+            try:
+                key, value, _ = await asyncio.wait_for(self._queue.get(), timeout=1.0)
+                yield key, value
+            except asyncio.TimeoutError:
+                continue
+
+    def commit(self) -> None:
+        """Commit current offsets."""
+        if self._consumer:
+            self._consumer.commit()
+
+    def commit_offsets(self, offsets: list[TopicPartition]) -> None:
+        """Commit specific offsets."""
+        if self._consumer:
+            self._consumer.commit(offsets=offsets)
+
+    async def close(self) -> None:
+        """Stop consuming and close the consumer."""
+        self._running = False
+
+        if self._poll_task:
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+            self._poll_task = None
+
+        if self._consumer:
+            self._consumer.close()
+            self._consumer = None
+
+    async def __aenter__(self):
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

investify_utils-2.0.0a12/investify_utils/kafka/async_producer.py

@@ -0,0 +1,152 @@
+"""
+Asynchronous Avro producer using confluent-kafka with asyncio.
+
+Features:
+- Non-blocking produce with async/await
+- Background asyncio task for polling
+- Suitable for async frameworks (LangGraph, FastAPI)
+
+Usage:
+    from investify_utils.kafka import AsyncAvroProducer
+
+    producer = AsyncAvroProducer(
+        topic="my-topic",
+        subject="my-topic-value",
+        schema_registry_url="http://localhost:8081",
+        bootstrap_servers="localhost:9092",
+    )
+
+    # In async context
+    await producer.produce(key="key1", value={"field": "value"})
+    producer.close()
+"""
+
+import asyncio
+import logging
+from typing import Callable
+
+from confluent_kafka import KafkaException, SerializingProducer
+from confluent_kafka.schema_registry import SchemaRegistryClient, record_subject_name_strategy
+from confluent_kafka.schema_registry.avro import AvroSerializer
+from confluent_kafka.serialization import StringSerializer
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncAvroProducer:
+    """
+    Asynchronous Avro producer for async frameworks.
+
+    Args:
+        topic: Kafka topic name
+        subject: Schema Registry subject name
+        schema_registry_url: Schema Registry URL
+        bootstrap_servers: Kafka bootstrap servers
+        **kwargs: Additional Kafka producer config
+    """
+
+    def __init__(
+        self,
+        topic: str,
+        subject: str,
+        schema_registry_url: str,
+        bootstrap_servers: str,
+        **kwargs,
+    ):
+        self.topic = topic
+        self._schema_registry_url = schema_registry_url
+        self._bootstrap_servers = bootstrap_servers
+        self._subject = subject
+        self._kwargs = kwargs
+        self._producer: SerializingProducer | None = None
+        self._poll_task: asyncio.Task | None = None
+
+    @property
+    def producer(self) -> SerializingProducer:
+        """Lazy producer initialization."""
+        if self._producer is None:
+            schema_registry_client = SchemaRegistryClient({"url": self._schema_registry_url})
+            registered_schema = schema_registry_client.get_latest_version(self._subject)
+            schema_str = registered_schema.schema.schema_str
+
+            avro_serializer = AvroSerializer(
+                schema_registry_client,
+                schema_str,
+                conf={
+                    "auto.register.schemas": False,
+                    "subject.name.strategy": record_subject_name_strategy,
+                },
+            )
+
+            producer_config = {
+                "bootstrap.servers": self._bootstrap_servers,
+                "key.serializer": StringSerializer("utf_8"),
+                "value.serializer": avro_serializer,
+                **self._kwargs,
+            }
+            self._producer = SerializingProducer(producer_config)
+
+            # Start background polling task
+            self._poll_task = asyncio.create_task(self._poll_loop())
+
+        return self._producer
+
+    async def _poll_loop(self) -> None:
+        """Background task for polling delivery callbacks."""
+        while True:
+            self._producer.poll(0.1)
+            await asyncio.sleep(0.1)
+
+    async def produce(
+        self,
+        value: dict,
+        key: str | None = None,
+        on_delivery: Callable | None = None,
+    ) -> asyncio.Future:
+        """
+        Produce a message asynchronously.
+
+        Args:
+            value: Message value (dict matching Avro schema)
+            key: Optional message key
+            on_delivery: Optional callback(err, msg) for delivery confirmation
+
+        Returns:
+            Future that resolves to the delivered message
+        """
+        loop = asyncio.get_running_loop()
+        result = loop.create_future()
+
+        def ack(err, msg):
+            if err:
+                loop.call_soon_threadsafe(result.set_exception, KafkaException(err))
+            else:
+                loop.call_soon_threadsafe(result.set_result, msg)
+            if on_delivery:
+                loop.call_soon_threadsafe(on_delivery, err, msg)
+
+        self.producer.produce(self.topic, key=key, value=value, on_delivery=ack)
+        return await result
+
+    def flush(self, timeout: float = 10.0) -> int:
+        """
+        Wait for all messages to be delivered.
+
+        Args:
+            timeout: Maximum time to wait in seconds
+
+        Returns:
+            Number of messages still in queue
+        """
+        if self._producer:
+            return self._producer.flush(timeout)
+        return 0
+
+    def close(self) -> None:
+        """Cancel polling task and flush pending messages."""
+        if self._poll_task:
+            self._poll_task.cancel()
+            self._poll_task = None
+        if self._producer:
+            self._producer.flush()
+            self._producer = None

investify_utils-2.0.0a12/investify_utils/s3/__init__.py

@@ -0,0 +1,25 @@
+"""
+S3-compatible object storage client.
+
+Sync client (boto3):
+    from investify_utils.s3 import S3Client
+
+Async client (aioboto3):
+    from investify_utils.s3 import AsyncS3Client
+"""
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid loading boto3/aioboto3 if not needed."""
+    if name == "S3Client":
+        from investify_utils.s3.sync_client import S3Client
+
+        return S3Client
+    if name == "AsyncS3Client":
+        from investify_utils.s3.async_client import AsyncS3Client
+
+        return AsyncS3Client
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["S3Client", "AsyncS3Client"]

investify_utils-2.0.0a12/investify_utils/s3/async_client.py

@@ -0,0 +1,228 @@
+"""
+Async S3-compatible object storage client using aioboto3.
+
+Features:
+- Works with AWS S3, Ceph RGW, MinIO, and other S3-compatible services
+- Lazy session initialization
+- Same API as sync S3Client, all methods async
+
+Usage:
+    from investify_utils.s3 import AsyncS3Client
+
+    client = AsyncS3Client(
+        endpoint_url="https://s3.example.com",
+        access_key="access_key",
+        secret_key="secret_key",
+    )
+
+    # Get object as bytes
+    data = await client.get_object("my-bucket", "remote.pdf")
+
+    # Put object from bytes/string
+    await client.put_object("my-bucket", "file.txt", b"content", content_type="text/plain")
+"""
+
+import os
+from typing import IO
+
+import aioboto3
+from botocore.config import Config
+from botocore.exceptions import ClientError
+
+
+class AsyncS3Client:
+    """
+    Async S3-compatible object storage client.
+
+    Args:
+        endpoint_url: S3 endpoint URL (e.g., https://s3.amazonaws.com)
+        access_key: AWS access key ID
+        secret_key: AWS secret access key
+        region: AWS region (default: None)
+    """
+
+    def __init__(
+        self,
+        endpoint_url: str,
+        access_key: str,
+        secret_key: str,
+        region: str | None = None,
+    ):
+        self._endpoint_url = endpoint_url
+        self._access_key = access_key
+        self._secret_key = secret_key
+        self._region = region
+        self._session = None
+
+    @property
+    def session(self) -> aioboto3.Session:
+        """Lazy session initialization."""
+        if self._session is None:
+            self._session = aioboto3.Session(
+                aws_access_key_id=self._access_key,
+                aws_secret_access_key=self._secret_key,
+                region_name=self._region,
+            )
+        return self._session
+
+    def _client_ctx(self):
+        """Create an async context manager for the S3 client."""
+        return self.session.client(
+            "s3",
+            endpoint_url=self._endpoint_url,
+            config=Config(signature_version="s3v4"),
+        )
+
+    async def list_buckets(self) -> list[str]:
+        """List all buckets."""
+        async with self._client_ctx() as client:
+            response = await client.list_buckets()
+            return [bucket["Name"] for bucket in response["Buckets"]]
+
+    async def list_objects(
+        self,
+        bucket: str,
+        prefix: str = "",
+        max_keys: int | None = None,
+    ) -> list[dict]:
+        """
+        List objects in a bucket with optional prefix filter.
+
+        Args:
+            bucket: Bucket name
+            prefix: Filter objects by prefix (e.g., "folder/")
+            max_keys: Maximum number of objects to return (None = all)
+
+        Returns:
+            List of object metadata dicts with keys: Key, Size, LastModified
+        """
+        objects = []
+        async with self._client_ctx() as client:
+            paginator = client.get_paginator("list_objects_v2")
+            async for page in paginator.paginate(Bucket=bucket, Prefix=prefix):
+                for obj in page.get("Contents", []):
+                    objects.append(
+                        {
+                            "Key": obj["Key"],
+                            "Size": obj["Size"],
+                            "LastModified": obj["LastModified"],
+                        }
+                    )
+                    if max_keys and len(objects) >= max_keys:
+                        return objects
+        return objects
+
+    async def upload_file(self, file_path: str, bucket: str, key: str | None = None) -> None:
+        """
+        Upload a local file to S3.
+
+        Args:
+            file_path: Local file path
+            bucket: Bucket name
+            key: Object key (default: basename of file_path)
+        """
+        if key is None:
+            key = os.path.basename(file_path)
+        async with self._client_ctx() as client:
+            await client.upload_file(file_path, bucket, key)
+
+    async def download_file(self, bucket: str, key: str, file_path: str) -> None:
+        """
+        Download an object to a local file.
+
+        Args:
+            bucket: Bucket name
+            key: Object key
+            file_path: Local file path to save to
+        """
+        async with self._client_ctx() as client:
+            await client.download_file(bucket, key, file_path)
+
+    async def get_object(self, bucket: str, key: str) -> bytes:
+        """
+        Get object content as bytes.
+
+        Args:
+            bucket: Bucket name
+            key: Object key
+
+        Returns:
+            Object content as bytes
+        """
+        async with self._client_ctx() as client:
+            response = await client.get_object(Bucket=bucket, Key=key)
+            return await response["Body"].read()
+
+    async def put_object(
+        self,
+        bucket: str,
+        key: str,
+        data: str | bytes | IO[bytes],
+        content_type: str | None = None,
+        content_disposition: str | None = None,
+    ) -> None:
+        """
+        Upload data directly to S3.
+
+        Args:
+            bucket: Bucket name
+            key: Object key
+            data: Content as string, bytes, or file-like object
+            content_type: MIME type (e.g., "application/pdf")
+            content_disposition: Content-Disposition header value
+        """
+        params: dict = {"Bucket": bucket, "Key": key, "Body": data}
+        if content_type:
+            params["ContentType"] = content_type
+        if content_disposition:
+            params["ContentDisposition"] = content_disposition
+        async with self._client_ctx() as client:
+            await client.put_object(**params)
+
+    async def delete_object(self, bucket: str, key: str) -> None:
+        """Delete a single object."""
+        async with self._client_ctx() as client:
+            await client.delete_object(Bucket=bucket, Key=key)
+
+    async def delete_prefix(self, bucket: str, prefix: str) -> int:
+        """
+        Delete all objects with a given prefix.
+
+        Args:
+            bucket: Bucket name
+            prefix: Prefix to match (e.g., "folder/" deletes all in folder)
+
+        Returns:
+            Number of objects deleted
+        """
+        deleted_count = 0
+        async with self._client_ctx() as client:
+            paginator = client.get_paginator("list_objects_v2")
+            async for page in paginator.paginate(Bucket=bucket, Prefix=prefix):
+                contents = page.get("Contents", [])
+                if not contents:
+                    continue
+                delete_keys = [{"Key": obj["Key"]} for obj in contents]
+                await client.delete_objects(Bucket=bucket, Delete={"Objects": delete_keys})
+                deleted_count += len(delete_keys)
+        return deleted_count
+
+    async def exists(self, bucket: str, key: str) -> bool:
+        """
+        Check if an object exists.
+
+        Args:
+            bucket: Bucket name
+            key: Object key
+
+        Returns:
+            True if object exists, False otherwise
+        """
+        try:
+            async with self._client_ctx() as client:
+                await client.head_object(Bucket=bucket, Key=key)
+                return True
+        except ClientError as e:
+            if e.response["Error"]["Code"] == "404":
+                return False
+            raise

{investify_utils-2.0.0a10 → investify_utils-2.0.0a12}/investify_utils/s3/sync_client.py

@@ -103,11 +103,13 @@ class S3Client:
 
         for page in paginator.paginate(Bucket=bucket, Prefix=prefix):
             for obj in page.get("Contents", []):
-                objects.append({
-                    "Key": obj["Key"],
-                    "Size": obj["Size"],
-                    "LastModified": obj["LastModified"],
-                })
+                objects.append(
+                    {
+                        "Key": obj["Key"],
+                        "Size": obj["Size"],
+                        "LastModified": obj["LastModified"],
+                    }
+                )
                 if max_keys and len(objects) >= max_keys:
                     return objects
 
@@ -223,4 +225,3 @@ class S3Client:
             if e.response["Error"]["Code"] == "404":
                 return False
             raise
-

{investify_utils-2.0.0a10 → investify_utils-2.0.0a12}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "investify-utils"
-version = "2.0.0a10"
+version = "2.0.0a12"
 description = "Shared utilities for Investify services"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -46,6 +46,9 @@ kafka = [
 s3 = [
     "boto3>=1.34",
 ]
+s3-async = [
+    "aioboto3>=15.0",
+]
 helpers = [
     "pandas>=2.0",
     "numpy>=2.0",

investify_utils-2.0.0a10/investify_utils/s3/__init__.py

@@ -1,18 +0,0 @@
-"""
-S3-compatible object storage client.
-
-Usage:
-    from investify_utils.s3 import S3Client
-"""
-
-
-def __getattr__(name: str):
-    """Lazy import to avoid loading boto3 if not needed."""
-    if name == "S3Client":
-        from investify_utils.s3.sync_client import S3Client
-
-        return S3Client
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
-
-__all__ = ["S3Client"]