Release v1.0.1

Author: sborsje

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## Description
+
+<!-- Describe what this PR does -->
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123, Closes #456 -->
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] I have read the [CONTRIBUTING](../CONTRIBUTING.md) guidelines
+- [ ] My code follows PEP 8 style guidelines
+- [ ] I have added tests for my changes (if applicable)
+- [ ] All tests pass locally (`pytest`)
+- [ ] I have updated documentation (if applicable)
+
+---
+
+> **Note:** This repository is a read-only mirror of our internal monorepo. If your PR is accepted, we will manually port your changes and credit you as a co-author. Your changes will appear with the next release. Thank you for contributing!
+

.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+ENV/
+env/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.DS_Store
+

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2025-11-27
+
+- Initial release
+

CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to Klime Python SDK
+
+Thank you for your interest in contributing to the Klime Python SDK!
+
+## Important: Repository Structure
+
+This repository is a **read-only mirror** of our internal monorepo. We develop and maintain the SDK internally, then mirror releases to this public repository.
+
+### What This Means for Contributors
+
+- **Pull requests are welcome** and will be reviewed by our team
+- If accepted, we'll **manually port your changes** to our internal monorepo
+- Your changes will appear in this repository with the **next release**
+- You'll be credited as a co-author in the commit
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. Check if the bug has already been reported in [Issues](../../issues)
+2. If not, create a new issue with:
+   - A clear, descriptive title
+   - Steps to reproduce the bug
+   - Expected vs actual behavior
+   - Your environment (Python version, OS, etc.)
+   - Any relevant code snippets or error messages
+
+### Suggesting Features
+
+1. Check if the feature has already been suggested in [Issues](../../issues)
+2. Create a new issue describing:
+   - The problem you're trying to solve
+   - Your proposed solution
+   - Any alternatives you've considered
+
+### Submitting Code Changes
+
+1. Fork this repository
+2. Create a feature branch (`git checkout -b feat/amazing-feature`)
+3. Make your changes
+4. Write or update tests as needed
+5. Ensure all tests pass (`pytest`)
+6. Commit using [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   feat: add new tracking method
+   fix: handle edge case in batch processing
+   docs: update README examples
+   ```
+7. Push to your fork and open a Pull Request
+
+### Pull Request Guidelines
+
+- Provide a clear description of what the PR does
+- Reference any related issues
+- Include tests for new functionality
+- Update documentation if needed
+- Keep PRs focused - one feature or fix per PR
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/klime-python.git
+cd klime-python
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+## Project Structure
+
+```
+klime-python/
+├── klime/
+│   ├── __init__.py
+│   ├── client.py      # Main client implementation
+│   └── types.py       # Type definitions
+├── tests/
+├── pyproject.toml     # Project configuration
+└── README.md
+```
+
+## Code Style
+
+- We follow [PEP 8](https://pep8.org/) style guidelines
+- Use type hints for all function signatures
+- Use meaningful variable and function names
+- Add docstrings for public APIs
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=klime
+
+# Run specific test file
+pytest tests/test_client.py
+```
+
+## Questions?
+
+If you have questions about contributing, feel free to open an issue and we'll be happy to help!
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+

README.md

@@ -0,0 +1,207 @@
+# klime-analytics
+
+Klime Analytics SDK for Python.
+
+## Installation
+
+```bash
+pip install klime-analytics
+```
+
+## Quick Start
+
+```python
+from klime import KlimeClient
+
+client = KlimeClient(
+    write_key='your-write-key'
+)
+
+# Track an event
+client.track('Button Clicked', {
+    'button_name': 'Sign up',
+    'plan': 'pro'
+})
+
+# Identify a user
+client.identify('user_123', {
+    'email': 'user@example.com',
+    'name': 'Stefan'
+})
+
+# Group a user with an organization
+client.group('org_456', {
+    'name': 'Acme Inc',
+    'plan': 'enterprise'
+}, user_id='user_123')
+
+# Shutdown gracefully
+client.shutdown()
+```
+
+## API Reference
+
+### Constructor
+
+```python
+KlimeClient(
+    write_key: str,                    # Required: Your Klime write key
+    endpoint: Optional[str] = None,    # Optional: API endpoint (default: https://ingest.klime.com)
+    flush_interval: Optional[int] = None,      # Optional: Milliseconds between flushes (default: 2000)
+    max_batch_size: Optional[int] = None,     # Optional: Max events per batch (default: 20, max: 100)
+    max_queue_size: Optional[int] = None,      # Optional: Max queued events (default: 1000)
+    retry_max_attempts: Optional[int] = None, # Optional: Max retry attempts (default: 5)
+    retry_initial_delay: Optional[int] = None, # Optional: Initial retry delay in ms (default: 1000)
+    flush_on_shutdown: Optional[bool] = None   # Optional: Auto-flush on exit (default: True)
+)
+```
+
+### Methods
+
+#### `track(event: str, properties: Optional[Dict] = None, user_id: Optional[str] = None, group_id: Optional[str] = None, ip: Optional[str] = None) -> None`
+
+Track a user event.
+
+```python
+# Simple usage
+client.track('Button Clicked', {
+    'button_name': 'Sign up',
+    'plan': 'pro'
+})
+
+# With user context and IP
+client.track('Button Clicked', {
+    'button_name': 'Sign up',
+    'plan': 'pro'
+}, user_id='user_123', group_id='org_456', ip='192.168.1.1')
+```
+
+#### `identify(user_id: str, traits: Optional[Dict] = None, ip: Optional[str] = None) -> None`
+
+Identify a user with traits.
+
+```python
+client.identify('user_123', {
+    'email': 'user@example.com',
+    'name': 'Stefan'
+}, ip='192.168.1.1')
+```
+
+#### `group(group_id: str, traits: Optional[Dict] = None, user_id: Optional[str] = None, ip: Optional[str] = None) -> None`
+
+Associate a user with a group and set group traits.
+
+```python
+# Simple usage
+client.group('org_456', {
+    'name': 'Acme Inc',
+    'plan': 'enterprise'
+})
+
+# With user ID and IP
+client.group('org_456', {
+    'name': 'Acme Inc',
+    'plan': 'enterprise'
+}, user_id='user_123', ip='192.168.1.1')
+```
+
+#### `flush() -> None`
+
+Manually flush queued events immediately.
+
+```python
+client.flush()
+```
+
+#### `shutdown() -> None`
+
+Gracefully shutdown the client, flushing remaining events.
+
+```python
+client.shutdown()
+```
+
+## Features
+
+- **Automatic Batching**: Events are automatically batched and sent every 2 seconds or when the batch size reaches 20 events
+- **Automatic Retries**: Failed requests are automatically retried with exponential backoff
+- **Thread-Safe**: Safe to use from multiple threads
+- **Process Exit Handling**: Automatically flushes events on process exit (via `atexit`)
+- **Zero Dependencies**: Uses only Python standard library
+
+## Configuration
+
+### Default Values
+
+- `flush_interval`: 2000ms
+- `max_batch_size`: 20 events
+- `max_queue_size`: 1000 events
+- `retry_max_attempts`: 5 attempts
+- `retry_initial_delay`: 1000ms
+- `flush_on_shutdown`: True
+
+## Error Handling
+
+The SDK automatically handles:
+
+- **Transient errors** (429, 503, network failures): Retries with exponential backoff
+- **Permanent errors** (400, 401): Logs error and drops event
+- **Rate limiting**: Respects `Retry-After` header
+
+## Size Limits
+
+- Maximum event size: 200KB
+- Maximum batch size: 10MB
+- Maximum events per batch: 100
+
+Events exceeding these limits are rejected and logged.
+
+## Flask Example
+
+```python
+from flask import Flask, request
+from klime import KlimeClient
+
+app = Flask(__name__)
+client = KlimeClient(write_key='your-write-key')
+
+@app.route('/api/button-clicked', methods=['POST'])
+def button_clicked():
+    client.track('Button Clicked', {
+        'button_name': request.json.get('buttonName')
+    }, user_id=request.json.get('userId'), ip=request.remote_addr)
+    
+    return {'success': True}
+
+# Graceful shutdown
+import atexit
+atexit.register(client.shutdown)
+```
+
+## Django Example
+
+```python
+from django.http import JsonResponse
+from django.views import View
+from klime import KlimeClient
+
+client = KlimeClient(write_key='your-write-key')
+
+class ButtonClickView(View):
+    def post(self, request):
+        client.track('Button Clicked', {
+            'button_name': request.POST.get('buttonName')
+        }, user_id=str(request.user.id), ip=request.META.get('REMOTE_ADDR'))
+        
+        return JsonResponse({'success': True})
+```
+
+## Requirements
+
+- Python 3.7 or higher
+- No external dependencies (uses only standard library)
+
+## License
+
+MIT
+