{"id":31921117,"url":"https://github.com/ohdearquant/pynector","last_synced_at":"2025-10-13T22:32:00.184Z","repository":{"id":291696263,"uuid":"977586057","full_name":"ohdearquant/pynector","owner":"ohdearquant","description":"connect anywhere","archived":false,"fork":false,"pushed_at":"2025-07-25T18:53:02.000Z","size":1255,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-26T01:18:36.407Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohdearquant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-04T14:47:08.000Z","updated_at":"2025-07-25T18:32:55.000Z","dependencies_parsed_at":"2025-05-06T04:40:19.445Z","dependency_job_id":null,"html_url":"https://github.com/ohdearquant/pynector","commit_stats":null,"previous_names":["ohdearquant/pynector"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ohdearquant/pynector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearquant%2Fpynector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearquant%2Fpynector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearquant%2Fpynector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearquant%2Fpynector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohdearquant","download_url":"https://codeload.github.com/ohdearquant/pynector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohdearquant%2Fpynector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017160,"owners_count":26085983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-13T22:30:35.498Z","updated_at":"2025-10-13T22:32:00.176Z","avatar_url":"https://github.com/ohdearquant.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pynector\n\nPynector is a Python library that provides a flexible, maintainable, and\ntype-safe interface for network communication with optional observability\nfeatures and structured concurrency.\n\n## Core Pynector Client\n\nThe `Pynector` class is the main entry point for using the library. It\nintegrates the Transport Abstraction Layer, Structured Concurrency, and Optional\nObservability components into a cohesive, user-friendly API.\n\n### Key Features\n\n- **Flexible Transport Integration**: Works with both built-in and custom\n  transports\n- **Efficient Batch Processing**: Parallel request processing with concurrency\n  limits\n- **Optional Observability**: Integrated tracing and logging with no-op\n  fallbacks\n- **Resource Safety**: Proper async resource management with context managers\n- **Robust Error Handling**: Specific exception types and retry mechanisms\n\n### Usage\n\n```python\nfrom pynector import Pynector\n\n# Create a client with HTTP transport\nasync with Pynector(\n    transport_type=\"http\",\n    base_url=\"https://api.example.com\",\n    headers={\"Content-Type\": \"application/json\"}\n) as client:\n    # Make a request\n    response = await client.request({\"path\": \"/users\", \"method\": \"GET\"})\n\n    # Make multiple requests in parallel\n    requests = [\n        ({\"path\": \"/users/1\", \"method\": \"GET\"}, {}),\n        ({\"path\": \"/users/2\", \"method\": \"GET\"}, {}),\n        ({\"path\": \"/users/3\", \"method\": \"GET\"}, {})\n    ]\n    responses = await client.batch_request(requests, max_concurrency=2)\n```\n\nFor more detailed documentation, see the\n[Core Client Documentation](docs/client.md).\n\n## Structured Concurrency\n\nThe Structured Concurrency module is a core component of Pynector that provides\na robust foundation for managing concurrent operations in Python. It leverages\nAnyIO to provide a consistent interface for structured concurrency across both\nasyncio and trio backends.\n\n### Key Features\n\n- **Structured Concurrency Pattern**: Ensures that concurrent operations have\n  well-defined lifetimes that are bound to a scope.\n- **AnyIO Integration**: Provides a consistent interface for both asyncio and\n  trio backends.\n- **Task Groups**: Manage multiple concurrent tasks with proper cleanup and\n  error propagation.\n- **Cancellation Scopes**: Fine-grained control over task cancellation and\n  timeouts.\n- **Resource Management Primitives**: Synchronization mechanisms like locks,\n  semaphores, and events.\n- **Concurrency Patterns**: Common patterns like connection pools, parallel\n  requests, and worker pools.\n\n### Components\n\nThe Structured Concurrency module consists of the following components:\n\n1. **Task Groups**: Provide a way to spawn and manage multiple concurrent tasks\n   while ensuring proper cleanup and error propagation.\n\n2. **Cancellation Scopes**: Provide fine-grained control over task cancellation\n   and timeouts.\n\n3. **Resource Management Primitives**: Implement synchronization mechanisms for\n   coordinating access to shared resources.\n\n4. **Error Handling**: Utilities for handling cancellation and shielding tasks\n   from cancellation.\n\n5. **Concurrency Patterns**: Implement common patterns like connection pools,\n   parallel requests, and worker pools.\n\n### Usage\n\nHere's a simple example of how to use the Structured Concurrency module:\n\n```python\nimport asyncio\nfrom pynector.concurrency import create_task_group\n\nasync def task1():\n    print(\"Task 1 started\")\n    await asyncio.sleep(1)\n    print(\"Task 1 completed\")\n\nasync def task2():\n    print(\"Task 2 started\")\n    await asyncio.sleep(2)\n    print(\"Task 2 completed\")\n\nasync def main():\n    async with create_task_group() as tg:\n        await tg.start_soon(task1)\n        await tg.start_soon(task2)\n        print(\"All tasks started\")\n\n    print(\"All tasks completed\")\n\nasyncio.run(main())\n```\n\nFor more detailed documentation, see the\n[Structured Concurrency Documentation](docs/concurrency.md).\n\n## Transport Abstraction Layer\n\nThe Transport Abstraction Layer is a core component of Pynector that provides a\nflexible and maintainable interface for network communication. It follows the\nsans-I/O pattern, which separates I/O concerns from protocol logic, making it\neasier to test, maintain, and extend.\n\n### Key Features\n\n- **Protocol-Based Design**: Uses Python's Protocol classes for interface\n  definitions, enabling static type checking.\n- **Sans-I/O Pattern**: Separates I/O concerns from protocol logic for better\n  testability and maintainability.\n- **Async Context Management**: Proper implementation of async context managers\n  for resource handling.\n- **Comprehensive Error Hierarchy**: Well-structured error hierarchy with\n  specific exception types.\n- **Message Protocols**: Flexible message serialization and deserialization with\n  support for different formats.\n- **Factory Pattern**: Factory method pattern for creating transport instances.\n- **HTTP Transport**: Complete HTTP client implementation using httpx with\n  connection pooling, retry mechanism, and comprehensive error handling.\n- **SDK Transport**: Unified interface for interacting with AI model provider\n  SDKs (OpenAI and Anthropic) with adapter pattern, error translation, and\n  streaming support.\n\n### Components\n\nThe Transport Abstraction Layer consists of the following components:\n\n1. **Transport Protocol**: Defines the interface for all transport\n   implementations with async methods for connect, disconnect, send, and receive\n   operations.\n\n2. **Message Protocol**: Defines the interface for message serialization and\n   deserialization.\n\n3. **Error Hierarchy**: Implements a comprehensive error hierarchy for\n   transport-related errors.\n\n4. **Message Implementations**:\n   - `JsonMessage`: Implements JSON serialization/deserialization.\n   - `BinaryMessage`: Implements binary message format with headers and payload.\n   - `HttpMessage`: Implements HTTP-specific message format with support for\n     headers, query parameters, JSON data, form data, and file uploads.\n\n5. **Transport Factory**: Implements the Factory Method pattern for creating\n   transport instances.\n\n6. **Transport Factory Registry**: Provides a registry for transport factories.\n\n7. **HTTP Transport Implementation**:\n   - `HTTPTransport`: Implements the Transport Protocol for HTTP communication\n     using httpx.\n   - `HTTPTransportFactory`: Creates and configures HTTP transport instances.\n   - HTTP-specific error hierarchy for detailed error handling.\n\n8. **SDK Transport Implementation**:\n   - `SdkTransport`: Implements the Transport Protocol for AI model provider\n     SDKs.\n   - `SDKAdapter`: Abstract base class for SDK-specific adapters.\n   - `OpenAIAdapter` and `AnthropicAdapter`: Concrete adapters for specific\n     SDKs.\n   - `SdkTransportFactory`: Creates and configures SDK transport instances.\n   - SDK-specific error hierarchy for detailed error handling.\n\n### Usage\n\nHere's a simple example of how to use the Transport Abstraction Layer with the\nHTTP transport:\n\n```python\nfrom pynector.transport import TransportFactoryRegistry\nfrom pynector.transport.http import HttpMessage, HTTPTransportFactory\n\n# Set up registry\nregistry = TransportFactoryRegistry()\nregistry.register(\n    \"http\",\n    HTTPTransportFactory(\n        base_url=\"https://api.example.com\",\n        message_type=HttpMessage,\n    ),\n)\n\n# Create a transport\ntransport = registry.create_transport(\"http\")\n\n# Use the transport with async context manager\nasync with transport as t:\n    # Create a GET request message\n    message = HttpMessage(\n        method=\"GET\",\n        url=\"/users\",\n        params={\"limit\": 10},\n    )\n\n    # Send the message\n    await t.send(message)\n\n    # Receive the response\n    async for response in t.receive():\n        data = response.get_payload()[\"data\"]\n        print(f\"Received {len(data)} users\")\n```\n\nFor more detailed documentation, see the\n[Transport Abstraction Layer Documentation](docs/transport.md) and the\n[HTTP Transport Documentation](docs/http_transport.md) or\n[SDK Transport Documentation](docs/sdk_transport.md).\n\n## Optional Observability\n\nThe Optional Observability module provides telemetry features for tracing and\nlogging with minimal dependencies. It follows a design that makes OpenTelemetry\nand structlog optional dependencies with no-op fallbacks.\n\n### Key Features\n\n- **Optional Dependencies**: Works with or without OpenTelemetry and structlog.\n- **No-op Fallbacks**: Graceful degradation when dependencies are not available.\n- **Context Propagation**: Maintains trace context across async boundaries.\n- **Flexible Configuration**: Configure via environment variables or API.\n- **Unified API**: Consistent interface regardless of dependency availability.\n\n### Components\n\n1. **Telemetry Facade**: Unified interface for tracing and logging operations.\n2. **No-op Implementations**: Fallbacks when dependencies are missing.\n3. **Context Propagation**: Maintains trace context in async code.\n4. **Configuration**: Flexible options for telemetry setup.\n5. **Dependency Detection**: Auto-detects available dependencies.\n\n### Usage\n\n```python\nfrom pynector.telemetry import get_telemetry, configure_telemetry\n\n# Configure telemetry (optional)\nconfigure_telemetry(service_name=\"my-service\")\n\n# Get tracer and logger\ntracer, logger = get_telemetry(\"my_component\")\n\n# Use the logger\nlogger.info(\"Operation started\", operation=\"process_data\")\n\n# Use the tracer\nwith tracer.start_as_current_span(\"process_data\") as span:\n    span.set_attribute(\"data.size\", 100)\n    logger.info(\"Processing data\", items=100)\n```\n\nFor more detailed documentation, see the\n[Optional Observability Documentation](docs/observability.md).\n\n## Installation\n\n```bash\n# Basic installation\npip install pynector\n\n# With observability features\npip install pynector[observability]\n```\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohdearquant%2Fpynector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohdearquant%2Fpynector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohdearquant%2Fpynector/lists"}