Conversation
Spec artifacts: - research.md: feasibility analysis and codebase exploration - requirements.md: user stories and acceptance criteria - design.md: architecture and technical decisions - tasks.md: POC-first implementation plan (22 tasks) Ready for implementation.
- Create pyproject.toml with hatch build, httpx dependency - Add src/logwell/__init__.py with __version__ - Add py.typed marker for type checking - Add minimal README.md for hatchling build
Add types.py module with TypedDict definitions: - LogLevel: Literal type for log severity levels - LogEntry: Log entry with level, message, timestamp, metadata - LogwellConfig: Client configuration with api_key, endpoint, callbacks - IngestResponse: API response with accepted/rejected counts Implements FR-1 (log methods), NFR-6 (type hints throughout).
- Add DEFAULT_CONFIG with batch_size, flush_interval, max_queue_size, max_retries, capture_source_location defaults - Add API_KEY_REGEX pattern: lw_[32 alphanumeric chars] - Add validate_api_key_format() function - Add validate_config() that validates required fields, API key format, endpoint URL, numeric bounds, and merges with defaults
Implement HttpTransport class with: - POST to /v1/ingest endpoint with Bearer auth header - Exponential backoff with jitter (min(base * 2^attempt, 10s) + 30% jitter) - Error classification by HTTP status: - 401 → UNAUTHORIZED (non-retryable) - 400 → VALIDATION_ERROR (non-retryable) - 429 → RATE_LIMITED (retryable) - 5xx → SERVER_ERROR (retryable) - TransportConfig from LogwellConfig helper - Async httpx client with lazy initialization Requirements: FR-10, AC-5.2, AC-5.3, AC-5.4
Implements BatchQueue class with: - Automatic flush on batch_size threshold - Timer-based flush using threading.Timer - Queue overflow protection (drops oldest) - Re-queue on send failure - Graceful shutdown with final flush - Thread-safe operations with threading.Lock
Implement source_location module with: - SourceLocation dataclass (frozen, slots) - capture_source_location() function using inspect.stack() - Supports skip_frames parameter to skip SDK internals - Returns None when stack depth exceeded Satisfies: FR-11, AC-6.1, AC-6.2, AC-6.3
Main entry point for the Python SDK that provides: - All log level methods (debug, info, warn, error, fatal) - Generic log() method for custom entries - Automatic timestamp generation - Source location capture when enabled - Metadata merging with parent context - Child logger creation with shared queue - Graceful shutdown with flush The client validates config on init, creates transport and queue, and routes logs through the batch queue for efficient delivery.
Export Logwell, LogwellError, LogwellErrorCode, and all types from the package's __init__.py for clean imports: from logwell import Logwell, LogwellError, LogwellErrorCode Task: 1.9 Spec: python-sdk
POC E2E verification complete: - Client instantiation works - All log levels (debug, info, warn, error, fatal) - Metadata attachment - Child loggers with inherited metadata - Flush and shutdown operations - Type check (mypy) passes - Error handling validated Minor fix: removed slots=True from SourceLocation dataclass for mypy compatibility.
- Verify thread safety already implemented in POC (threading.Lock on all ops) - Fix lint issues: TC001 - move type imports to TYPE_CHECKING blocks - Fix lint issues: UP035 - use collections.abc for Awaitable/Callable - All queue/timer operations protected by self._lock
- Config errors: Include example usage and explain what's missing/wrong - API key validation: Mask key in error, explain format requirements - Endpoint validation: Show invalid URL, provide correct examples - Numeric config: Show invalid value, explain purpose of each setting - Transport errors: Include endpoint URL and timeout info - HTTP errors: Explain what each status code means and what to do - Queue overflow: Show max size, explain why it happened and fixes Each error now answers: What failed? Why? How to fix it?
Verified mypy --strict passes on all source files. Type hints were comprehensive from initial implementation.
Add pytest fixtures for SDK testing: - Valid/invalid configuration fixtures - Mock HTTP response fixtures (success, error, rate limit) - Sample log entry fixtures - Callback capture helpers for testing events - Factory fixtures for creating test data
- Add tests/unit/__init__.py and tests/unit/test_config.py - 78 tests covering validate_api_key_format and validate_config - 100% code coverage of config.py module - Test cases for: - Valid API keys (lowercase, uppercase, mixed case, numbers, hyphens, underscores) - Invalid API keys (wrong prefix, length, invalid chars, empty, None, wrong types) - Missing/empty required fields (api_key, endpoint) - Invalid endpoint URLs (no scheme, relative paths) - Numeric bounds (batch_size, flush_interval, max_queue_size, max_retries) - Default value merging - Optional fields (service, on_error, on_flush, capture_source_location) - Edge cases and validation order
47 tests covering: - QueueConfig: construction, from_logwell_config - BatchQueue: add, flush, size, shutdown methods - Auto-flush on batch_size threshold - Timer-based flush after flush_interval - Queue overflow handling (drop oldest, on_error callback) - Concurrent add/flush operations (thread safety) - Edge cases (error recovery, entries during flush)
36 tests for source_location.py covering: - SourceLocation dataclass: attributes, frozen/immutable, equality, repr - capture_source_location: basic functionality, frame depths 0/1/2 - Invalid frame depths returning None - Edge cases: lambda, list comprehension, nested calls - Exception handling and graceful failure - Integration-style tests for typical logging patterns Requirements: AC-6.1, AC-6.2, AC-6.3
Add 67 comprehensive unit tests for client.py covering: - Logwell construction with valid/invalid configs - All log methods (debug, info, warn, error, fatal) - Logging with metadata (none, empty, complex) - Automatic UTC timestamp generation - Service name handling (config, override, inheritance) - queue_size property - flush() method delegation and response handling - shutdown() method (stops new logs, queue lifecycle) - child() method (shares queue, inherits config, merges metadata) - Nested children with accumulated metadata - Source location capture when enabled - _merge_metadata internal method - Integration-style workflow tests
Add 22 integration tests using respx for HTTP mocking: - Full flow tests (instantiate -> log -> flush -> verify) - All log levels (debug, info, warn, error, fatal) - Batching behavior and auto-flush on batch_size - Retry on 5xx server errors and 429 rate limits - Non-retryable error handling (401, 400) - Shutdown behavior (flush remaining, idempotent, reject after) - Child logger tests (same endpoint, metadata inheritance) - Nested children metadata accumulation - on_flush callback verification - Source location capture when enabled - Complex metadata serialization
- Fix E501 line too long errors in queue.py and transport.py - All quality checks now pass: - mypy --strict: no issues - ruff check: all checks passed - pytest: 308 tests, 98% coverage
|
| GitGuardian id | GitGuardian status | Secret | Commit | Filename | |
|---|---|---|---|---|---|
| 25015375 | Triggered | Generic High Entropy Secret | ae134b3 | sdks/python/tests/unit/test_config.py | View secret |
🛠 Guidelines to remediate hardcoded secrets
- Understand the implications of revoking this secret by investigating where it is used in your code.
- Replace and store your secret safely. Learn here the best practices.
- Revoke and rotate this secret.
- If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.
To avoid such incidents in the future consider
- following these best practices for managing and storing secrets including API keys and other credentials
- install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.
🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive production-ready Python SDK for the Logwell logging platform, mirroring the functionality of the existing TypeScript SDK with Python-specific implementations.
Changes:
- Complete Python SDK implementation with sync/async support, automatic batching, retry logic, and comprehensive error handling
- Full test suite with 100+ unit tests and 22 integration tests achieving >90% coverage
- Documentation including README, API reference, and usage examples
Reviewed changes
Copilot reviewed 28 out of 30 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| specs/python-sdk/*.md | Specification documents for SDK development phases (research, requirements, design, tasks) |
| sdks/python/src/logwell/*.py | Core SDK implementation (client, config, queue, transport, errors, types, source_location) |
| sdks/python/tests/**/*.py | Comprehensive test suite with unit and integration tests |
| sdks/python/pyproject.toml | Python package configuration with dependencies and build settings |
| sdks/python/README.md | User documentation with examples and API reference |
| sdks/python/LICENSE | MIT license |
| sdks/python/.gitignore | Python-specific ignore patterns |
| .gitignore | Added Python artifacts to root gitignore |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
All 22 tasks completed: - Phase 1: POC implementation - Phase 2: Refactoring (thread safety, type hints, docs) - Phase 3: Testing (unit + integration) - Phase 4: Quality gates + PR PR: #11
- Remove unused asyncio import from test_client.py - Remove unused Any import from test_e2e.py
- Add lint job: ruff check/format, mypy --strict - Add unit tests across Python 3.10-3.13 - Add integration tests with respx mocking - Add coverage report with 90% threshold - Add build verification with twine - Add PyPI publish via trusted publisher (OIDC) - Auto-publish on main when version changes - Add coverage[toml] to dev dependencies
- Remove unused Callable and IngestResponse imports from test_client.py - Remove unused Callable import from test_config.py - Move IngestResponse and LogEntry to TYPE_CHECKING block in test_queue.py - Remove empty TYPE_CHECKING block from test_source_location.py - Run ruff format to fix import sorting
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a production-ready Python SDK for sending logs to Logwell with automatic batching, async/sync support, and comprehensive error handling.
Key Features
LogwellClient) and async (AsyncLogwellClient) clientsLogwellHandlerfor seamlessloggingmodule integrationpy.typedmarker for static analysisFiles Added
sdks/python/src/logwell/- Core SDK implementationclient.py- Main sync/async client classesconfig.py- Configuration with validationqueue.py- Thread-safe batching queuetransport.py- HTTP transport with retry logicerrors.py- Custom exception hierarchytypes.py- TypedDict definitionssource_location.py- Call stack introspectionsdks/python/tests/- Comprehensive test suitesdks/python/README.md- Usage documentationsdks/python/pyproject.toml- Package configurationTest Coverage
Test Plan
pytest tests/unit/ -vpytest tests/integration/ -vmypy src/ruff check src/ tests/python -m build