networkpype 0.1.0__tar.gz

networkpype-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gianluca Pagliara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

networkpype-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.1
+Name: networkpype
+Version: 0.1.0
+Summary: 
+Author: Gianluca Pagliara
+Author-email: pagliara.gianluca@gmail.com
+Requires-Python: >=3.13,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (<3.10.0)
+Requires-Dist: aioresponses (>=0.7.8,<0.8.0)
+Requires-Dist: numpy (>=2.2.2,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Network Pypeline
+
+[![PyPI version](https://badge.fury.io/py/networkpype.svg)](https://badge.fury.io/py/networkpype)
+[![Python](https://img.shields.io/pypi/pyversions/networkpype.svg?style=plastic)](https://badge.fury.io/py/networkpype)
+[![Documentation Status](https://readthedocs.org/projects/networkpype/badge/?version=latest)](https://networkpype.readthedocs.io/en/latest/?badge=latest)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A powerful Python library for building efficient network communication pipelines, supporting both REST and WebSocket protocols with built-in rate limiting and time synchronization.
+
+## Features
+
+- 🔄 **Dual Protocol Support**: Seamlessly handle both REST and WebSocket communications
+- 🚦 **Rate Limiting**: Built-in throttling mechanism to respect API rate limits
+- ⏰ **Time Synchronization**: Automatic time synchronization for accurate API interactions
+- 🏭 **Factory Pattern**: Easy-to-use factory for creating and managing connections
+- 🔌 **Modular Design**: Extensible processor architecture for custom request/response handling
+- 🛡️ **Type Safety**: Full type hinting support for better development experience
+
+## Installation
+
+Install using pip:
+
+```bash
+pip install networkpype
+```
+
+Or with Poetry:
+
+```bash
+poetry add networkpype
+```
+
+## Quick Start
+
+### REST Example
+
+```python
+from networkpype.factory import ConnectionFactory
+from networkpype.rest.method import Method
+
+# Create a REST connection
+factory = ConnectionFactory()
+connection = factory.create_rest_connection(
+    base_url="https://api.example.com",
+    rate_limit=100  # requests per minute
+)
+
+# Make a request
+response = connection.request(
+    method=Method.GET,
+    endpoint="/users",
+    params={"page": 1}
+)
+```
+
+### WebSocket Example
+
+```python
+from networkpype.factory import ConnectionFactory
+
+# Create a WebSocket connection
+factory = ConnectionFactory()
+connection = factory.create_websocket_connection(
+    url="wss://ws.example.com"
+)
+
+# Subscribe to updates
+connection.subscribe(
+    channel="market.btcusdt.trade",
+    callback=lambda msg: print(f"Received: {msg}")
+)
+```
+
+## Documentation
+
+For detailed documentation, please visit [networkpype.readthedocs.io](https://networkpype.readthedocs.io/).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

networkpype-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Network Pypeline
+
+[![PyPI version](https://badge.fury.io/py/networkpype.svg)](https://badge.fury.io/py/networkpype)
+[![Python](https://img.shields.io/pypi/pyversions/networkpype.svg?style=plastic)](https://badge.fury.io/py/networkpype)
+[![Documentation Status](https://readthedocs.org/projects/networkpype/badge/?version=latest)](https://networkpype.readthedocs.io/en/latest/?badge=latest)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A powerful Python library for building efficient network communication pipelines, supporting both REST and WebSocket protocols with built-in rate limiting and time synchronization.
+
+## Features
+
+- 🔄 **Dual Protocol Support**: Seamlessly handle both REST and WebSocket communications
+- 🚦 **Rate Limiting**: Built-in throttling mechanism to respect API rate limits
+- ⏰ **Time Synchronization**: Automatic time synchronization for accurate API interactions
+- 🏭 **Factory Pattern**: Easy-to-use factory for creating and managing connections
+- 🔌 **Modular Design**: Extensible processor architecture for custom request/response handling
+- 🛡️ **Type Safety**: Full type hinting support for better development experience
+
+## Installation
+
+Install using pip:
+
+```bash
+pip install networkpype
+```
+
+Or with Poetry:
+
+```bash
+poetry add networkpype
+```
+
+## Quick Start
+
+### REST Example
+
+```python
+from networkpype.factory import ConnectionFactory
+from networkpype.rest.method import Method
+
+# Create a REST connection
+factory = ConnectionFactory()
+connection = factory.create_rest_connection(
+    base_url="https://api.example.com",
+    rate_limit=100  # requests per minute
+)
+
+# Make a request
+response = connection.request(
+    method=Method.GET,
+    endpoint="/users",
+    params={"page": 1}
+)
+```
+
+### WebSocket Example
+
+```python
+from networkpype.factory import ConnectionFactory
+
+# Create a WebSocket connection
+factory = ConnectionFactory()
+connection = factory.create_websocket_connection(
+    url="wss://ws.example.com"
+)
+
+# Subscribe to updates
+connection.subscribe(
+    channel="market.btcusdt.trade",
+    callback=lambda msg: print(f"Received: {msg}")
+)
+```
+
+## Documentation
+
+For detailed documentation, please visit [networkpype.readthedocs.io](https://networkpype.readthedocs.io/).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

networkpype-0.1.0/networkpype/auth.py

@@ -0,0 +1,89 @@
+"""Authentication module for REST and WebSocket requests.
+
+This module provides the base authentication class that can be used to implement
+various authentication schemes for both REST and WebSocket connections. It supports
+time-synchronized authentication methods and can be extended to implement specific
+authentication protocols.
+
+Classes:
+    Auth: Abstract base class for implementing authentication schemes.
+"""
+
+from abc import abstractmethod
+
+from networkpype.rest.request import RESTRequest
+from networkpype.time_synchronizer import TimeSynchronizer
+from networkpype.websocket.request import WebSocketRequest
+
+
+class Auth:
+    """Abstract base class for authentication objects used by ConnectionManagersFactory.
+
+    This class provides the foundation for implementing various authentication schemes.
+    It can be used to authenticate both REST and WebSocket requests, and supports
+    time-synchronized authentication methods.
+
+    The class can be extended to implement specific authentication protocols such as:
+    - API Key authentication
+    - OAuth
+    - JWT
+    - HMAC signatures
+    - Custom authentication schemes
+
+    Attributes:
+        time_provider (TimeSynchronizer): Component for handling time synchronization
+            in authentication operations.
+
+    Note:
+        If the authentication requires a simple REST request to acquire information from the
+        server that is required in the message signature, this class can be passed a
+        `RESTConnection` object that it can use to that end.
+    """
+
+    def __init__(
+        self,
+        time_provider: TimeSynchronizer | None = None,
+    ):
+        """Initialize the Auth instance with an optional time synchronizer.
+
+        Args:
+            time_provider (TimeSynchronizer | None): Component for handling time
+                synchronization. If None, a new TimeSynchronizer instance will be created.
+        """
+        self.time_provider = time_provider or TimeSynchronizer()
+
+    @abstractmethod
+    async def rest_authenticate(self, request: RESTRequest) -> RESTRequest:
+        """Authenticate a REST request.
+
+        This method should be implemented by subclasses to add authentication
+        information to REST requests (e.g., headers, query parameters, etc.).
+
+        Args:
+            request (RESTRequest): The REST request to authenticate.
+
+        Returns:
+            RESTRequest: The authenticated request with added authentication information.
+
+        Raises:
+            NotImplementedError: If the subclass does not implement this method.
+        """
+        ...
+
+    @abstractmethod
+    async def ws_authenticate(self, request: WebSocketRequest) -> WebSocketRequest:
+        """Authenticate a WebSocket request.
+
+        This method should be implemented by subclasses to add authentication
+        information to WebSocket requests (e.g., connection parameters, headers, etc.).
+
+        Args:
+            request (WebSocketRequest): The WebSocket request to authenticate.
+
+        Returns:
+            WebSocketRequest: The authenticated request with added authentication information.
+
+        Raises:
+            NotImplementedError: If the subclass does not implement this method.
+        """
+        ...

networkpype-0.1.0/networkpype/factory.py

@@ -0,0 +1,217 @@
+"""Network communication factory module for REST and WebSocket connections.
+
+This module provides factory classes for creating and managing network connections,
+both for REST and WebSocket protocols. It abstracts the underlying network library
+(aiohttp) and provides a clean interface for connection management.
+
+Classes:
+    ConnectionsFactory: Creates and manages low-level network connections.
+    ConnectionManagersFactory: Creates and manages high-level connection managers with additional features.
+"""
+
+import aiohttp
+
+from networkpype.auth import Auth
+from networkpype.rest.connection import RESTConnection
+from networkpype.rest.manager import RESTManager
+from networkpype.rest.processor.base import RESTPostProcessor, RESTPreProcessor
+from networkpype.throttler.throttler import AsyncThrottler
+from networkpype.time_synchronizer import TimeSynchronizer
+from networkpype.websocket.connection import WebSocketConnection
+from networkpype.websocket.manager import WebSocketManager
+from networkpype.websocket.processor.base import (
+    WebSocketPostProcessor,
+    WebSocketPreProcessor,
+)
+
+
+class ConnectionsFactory:
+    """Factory class for creating and managing network connections.
+
+    This class is a thin wrapper around the underlying REST and WebSocket third-party library.
+    It isolates the general `connection_manager` infrastructure from the underlying library
+    (in this case, `aiohttp`) to enable dependency change with minimal refactoring of the code.
+
+    Attributes:
+        _shared_client (aiohttp.ClientSession | None): Shared HTTP client session for all connections.
+    """
+
+    def __init__(self):
+        """Initialize the ConnectionsFactory with no active client session."""
+        self._shared_client: aiohttp.ClientSession | None = None
+
+    async def get_rest_connection(self) -> RESTConnection:
+        """Create or retrieve a REST connection using the shared client session.
+
+        Returns:
+            RESTConnection: A connection object for making REST API calls.
+        """
+        shared_client = await self._get_shared_client()
+        connection = RESTConnection(aiohttp_client_session=shared_client)
+        return connection
+
+    async def get_ws_connection(self, **kwargs) -> WebSocketConnection:
+        """Create or retrieve a WebSocket connection using the shared client session.
+
+        Args:
+            **kwargs: Additional arguments to pass to the client session.
+
+        Returns:
+            WebSocketConnection: A connection object for WebSocket communication.
+        """
+        shared_client = await self._get_shared_client(**kwargs)
+        connection = WebSocketConnection(aiohttp_client_session=shared_client)
+        return connection
+
+    async def _get_shared_client(self, **kwargs) -> aiohttp.ClientSession:
+        """Get or create a shared aiohttp client session.
+
+        Args:
+            **kwargs: Additional arguments to pass to ClientSession constructor.
+
+        Returns:
+            aiohttp.ClientSession: The shared client session.
+        """
+        self._shared_client = self._shared_client or aiohttp.ClientSession(**kwargs)
+        return self._shared_client
+
+    async def update_cookies(self, cookies):
+        """Update the cookies in the shared client session.
+
+        Args:
+            cookies: Cookie data to update in the session.
+        """
+        shared_client = await self._get_shared_client()
+        shared_client.cookie_jar.update_cookies(cookies)
+
+    async def close(self):
+        """Close the shared client session and clean up resources."""
+        if self._shared_client:
+            await self._shared_client.close()
+            self._shared_client = None
+
+
+class ConnectionManagersFactory:
+    """Factory class for creating and managing high-level connection managers.
+
+    This class creates connection managers that handle authentication, rate limiting,
+    request/response processing, and time synchronization for both REST and WebSocket
+    connections.
+
+    Attributes:
+        _connections_factory (ConnectionsFactory): Factory for creating base connections.
+        _rest_pre_processors (list[RESTPreProcessor]): Processors to run before REST requests.
+        _rest_post_processors (list[RESTPostProcessor]): Processors to run after REST responses.
+        _ws_pre_processors (list[WebSocketPreProcessor]): Processors to run before WS messages.
+        _ws_post_processors (list[WebSocketPostProcessor]): Processors to run after WS messages.
+        _auth (Auth | None): Authentication handler.
+        _throttler (AsyncThrottler): Rate limiting handler.
+        _time_synchronizer (TimeSynchronizer | None): Time synchronization handler.
+    """
+
+    def __init__(
+        self,
+        throttler: AsyncThrottler,
+        auth: Auth | None = None,
+        rest_pre_processors: list[RESTPreProcessor] | None = None,
+        rest_post_processors: list[RESTPostProcessor] | None = None,
+        ws_pre_processors: list[WebSocketPreProcessor] | None = None,
+        ws_post_processors: list[WebSocketPostProcessor] | None = None,
+        time_synchronizer: TimeSynchronizer | None = None,
+    ):
+        """Initialize the ConnectionManagersFactory with the specified components.
+
+        Args:
+            throttler (AsyncThrottler): Rate limiting component for API requests.
+            auth (Auth | None): Authentication handler for requests. Defaults to None.
+            rest_pre_processors (list[RESTPreProcessor] | None): List of processors to run before REST requests.
+                Defaults to None.
+            rest_post_processors (list[RESTPostProcessor] | None): List of processors to run after REST responses.
+                Defaults to None.
+            ws_pre_processors (list[WebSocketPreProcessor] | None): List of processors to run before WebSocket messages.
+                Defaults to None.
+            ws_post_processors (list[WebSocketPostProcessor] | None): List of processors to run after WebSocket messages.
+                Defaults to None.
+            time_synchronizer (TimeSynchronizer | None): Component for handling time synchronization.
+                Defaults to None.
+        """
+        self._connections_factory = ConnectionsFactory()
+        self._rest_pre_processors = rest_pre_processors or []
+        self._rest_post_processors = rest_post_processors or []
+        self._ws_pre_processors = ws_pre_processors or []
+        self._ws_post_processors = ws_post_processors or []
+        self._auth = auth
+        self._throttler = throttler
+        self._time_synchronizer = time_synchronizer
+
+    @property
+    def throttler(self) -> AsyncThrottler:
+        """Get the rate limiting throttler.
+
+        Returns:
+            AsyncThrottler: The throttler instance used for rate limiting.
+        """
+        return self._throttler
+
+    @property
+    def time_synchronizer(self) -> TimeSynchronizer | None:
+        """Get the time synchronization component.
+
+        Returns:
+            TimeSynchronizer | None: The time synchronizer instance if configured, None otherwise.
+        """
+        return self._time_synchronizer
+
+    @property
+    def auth(self) -> Auth | None:
+        """Get the authentication handler.
+
+        Returns:
+            Auth | None: The authentication instance if configured, None otherwise.
+        """
+        return self._auth
+
+    async def get_rest_manager(self) -> RESTManager:
+        """Create a new REST connection manager with all configured components.
+
+        Returns:
+            RESTManager: A fully configured REST connection manager with authentication,
+                rate limiting, and request/response processing capabilities.
+        """
+        connection = await self._connections_factory.get_rest_connection()
+        assistant = RESTManager(
+            connection=connection,
+            throttler=self._throttler,
+            rest_pre_processors=self._rest_pre_processors,
+            rest_post_processors=self._rest_post_processors,
+            auth=self._auth,
+        )
+        return assistant
+
+    async def get_ws_manager(self, **kwargs) -> WebSocketManager:
+        """Create a new WebSocket connection manager with all configured components.
+
+        Args:
+            **kwargs: Additional arguments to pass to the WebSocket connection.
+
+        Returns:
+            WebSocketManager: A fully configured WebSocket connection manager with
+                authentication and message processing capabilities.
+        """
+        connection = await self._connections_factory.get_ws_connection(**kwargs)
+        assistant = WebSocketManager(
+            connection, self._ws_pre_processors, self._ws_post_processors, self._auth
+        )
+        return assistant
+
+    async def update_cookies(self, cookies):
+        """Update the cookies in the shared client session.
+
+        Args:
+            cookies: Cookie data to update in the session.
+        """
+        await self._connections_factory.update_cookies(cookies)
+
+    async def close(self):
+        """Close all connections and clean up resources."""
+        await self._connections_factory.close()

networkpype-0.1.0/networkpype/rest/__init__.py

@@ -0,0 +1,40 @@
+"""REST API client implementation for NetworkPype.
+
+This module provides a complete solution for making HTTP requests with features
+like rate limiting, request/response processing, and connection management. It
+uses aiohttp for making asynchronous HTTP requests and supports customization
+through processors.
+
+Key Components:
+    RESTManager: High-level interface for making HTTP requests.
+    RESTConnection: Low-level HTTP connection handler.
+    RESTRequest: Request data container with validation.
+    RESTResponse: Response data container with validation.
+    RESTPreProcessor: Base class for request pre-processors.
+    RESTPostProcessor: Base class for response post-processors.
+
+Example:
+    ```python
+    from networkpype.rest import RESTManager, RESTConnection
+    from networkpype.rest.processor import JSONProcessor
+
+    # Create a REST client with JSON processing
+    connection = RESTConnection()
+    manager = RESTManager(
+        connection=connection,
+        post_processors=[JSONProcessor()]
+    )
+
+    # Make HTTP requests
+    async with manager.session():
+        # GET request with automatic JSON parsing
+        response = await manager.get("https://api.example.com/data")
+        data = response.data  # Parsed JSON data
+
+        # POST request with automatic JSON serialization
+        response = await manager.post(
+            "https://api.example.com/items",
+            data={"name": "test"}
+        )
+    ```
+"""

networkpype-0.1.0/networkpype/rest/connection.py

@@ -0,0 +1,105 @@
+"""REST connection module for low-level HTTP communication.
+
+This module provides a low-level interface for making HTTP requests using the aiohttp
+library. It handles the direct communication with HTTP servers while providing a clean
+abstraction over the underlying HTTP client library.
+
+The module is designed to work with the RESTRequest and RESTResponse classes to provide
+a consistent interface for HTTP communication, regardless of the underlying HTTP client
+implementation.
+
+Classes:
+    RESTConnection: Low-level HTTP connection handler.
+"""
+
+import aiohttp
+from yarl import URL
+
+from networkpype.rest.request import RESTRequest
+from networkpype.rest.response import RESTResponse
+
+
+class RESTConnection:
+    """Low-level HTTP connection handler.
+
+    This class provides direct access to HTTP communication functionality, wrapping
+    an aiohttp client session. It handles the conversion between the networkpype
+    request/response types and the underlying aiohttp types.
+
+    The connection is designed to be reused across multiple requests to take advantage
+    of connection pooling and other HTTP/1.1 and HTTP/2 optimizations.
+
+    Attributes:
+        _client_session (aiohttp.ClientSession): The underlying aiohttp client session.
+
+    Example:
+        ```python
+        async with aiohttp.ClientSession() as session:
+            connection = RESTConnection(session)
+            request = RESTRequest(
+                method=RESTMethod.GET,
+                url="https://api.example.com/data"
+            )
+            response = await connection.call(request)
+            data = await response.json()
+        ```
+    """
+
+    def __init__(self, aiohttp_client_session: aiohttp.ClientSession):
+        """Initialize the RESTConnection with an aiohttp client session.
+
+        Args:
+            aiohttp_client_session (aiohttp.ClientSession): The aiohttp client session
+                to use for making HTTP requests.
+        """
+        self._client_session = aiohttp_client_session
+
+    async def call(
+        self, request: RESTRequest, encoded: bool = False, **kwargs
+    ) -> RESTResponse:
+        """Execute an HTTP request.
+
+        This method converts the networkpype request into an aiohttp request,
+        executes it, and wraps the response in a networkpype response object.
+
+        Args:
+            request (RESTRequest): The request to execute.
+            encoded (bool): Whether the URL is already percent-encoded. If True,
+                no additional encoding will be performed. Defaults to False.
+            **kwargs: Additional arguments to pass to aiohttp.ClientSession.request().
+
+        Returns:
+            RESTResponse: The response from the server.
+
+        Raises:
+            aiohttp.ClientError: If there is an error making the request.
+            asyncio.TimeoutError: If the request times out.
+            ValueError: If the request URL is None.
+        """
+        if request.url is None:
+            raise ValueError("Request URL cannot be None")
+
+        aiohttp_resp = await self._client_session.request(
+            method=request.method.value,
+            url=URL(request.url, encoded=encoded),
+            params=request.params,
+            data=request.data,
+            headers=request.headers,
+            **kwargs,
+        )
+
+        resp = await self._build_resp(aiohttp_resp)
+        return resp
+
+    @staticmethod
+    async def _build_resp(aiohttp_resp: aiohttp.ClientResponse) -> RESTResponse:
+        """Build a networkpype response from an aiohttp response.
+
+        Args:
+            aiohttp_resp (aiohttp.ClientResponse): The aiohttp response to wrap.
+
+        Returns:
+            RESTResponse: The wrapped response.
+        """
+        resp = RESTResponse(aiohttp_resp)
+        return resp