auditflowlog 0.0.1__tar.gz

auditflowlog-0.0.1/.gitignore

@@ -0,0 +1,147 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

auditflowlog-0.0.1/BUILD_AND_PUBLISH.md

@@ -0,0 +1,324 @@
+# Building and Publishing AuditFlow SDK
+
+## Prerequisites
+
+- Python 3.9+
+- pip
+- PyPI account (for publishing)
+
+## Local Development Setup
+
+```bash
+# Clone the repository
+cd auditflowlog-py
+
+# Create virtual environment (optional but recommended)
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+python -m pip install -r requirements.txt
+
+# Install package in editable mode
+python -m pip install -e .
+
+# Run tests
+python tests/test_models.py
+```
+
+## Building the Package
+
+### 1. Install Build Tools
+
+```bash
+python -m pip install build twine
+```
+
+### 2. Build Distribution Files
+
+```bash
+python -m build
+```
+
+This creates two files in `dist/`:
+- `auditflowlog-0.0.1-py3-none-any.whl` - Wheel distribution (binary)
+- `auditflowlog-0.0.1.tar.gz` - Source distribution
+
+### 3. Verify the Build
+
+```bash
+# List contents
+ls dist/
+
+# Check wheel contents
+unzip -l dist/auditflowlog-0.0.1-py3-none-any.whl
+
+# Verify package metadata
+python -m twine check dist/*
+```
+
+## Testing the Built Package
+
+### Test in a Clean Environment
+
+```bash
+# Create new virtual environment
+python -m venv test_env
+source test_env/bin/activate  # On Windows: test_env\Scripts\activate
+
+# Install from wheel
+pip install dist/auditflowlog-0.0.1-py3-none-any.whl
+
+# Test import
+python -c "from auditflowlog import AuditFlowClient, LogLevel; print('✓ Import successful')"
+
+# Run an example
+python examples/direct_client_example.py
+
+# Deactivate and clean up
+deactivate
+rm -rf test_env
+```
+
+## Publishing to PyPI
+
+### 1. Check Package Name Availability
+
+Visit https://pypi.org/project/auditflowlog/ to check if the name is available.
+
+If taken, update `pyproject.toml`:
+```toml
+[project]
+name = "auditflowlog-client"  # or another unique name
+```
+
+### 2. Create PyPI Account
+
+1. Go to https://pypi.org/account/register/
+2. Verify email
+3. Enable 2FA (recommended)
+
+### 3. Generate API Token
+
+1. Go to https://pypi.org/manage/account/token/
+2. Create token with scope: "Entire account" (first time) or "Project: auditflowlog" (after first upload)
+3. Copy the token (starts with `pypi-`)
+
+### 4. Configure Credentials
+
+**Option A: Use .pypirc file (recommended)**
+
+Create `~/.pypirc`:
+```ini
+[pypi]
+username = __token__
+password = pypi-AgEIcHlwaS5vcmcC...  # Your actual token
+```
+
+**Option B: Use environment variable**
+
+```bash
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmcC...
+```
+
+### 5. Upload to PyPI
+
+```bash
+# Upload to PyPI
+python -m twine upload dist/*
+
+# You'll see:
+# Uploading distributions to https://upload.pypi.org/legacy/
+# Uploading auditflowlog-0.0.1-py3-none-any.whl
+# Uploading auditflowlog-0.0.1.tar.gz
+```
+
+### 6. Verify on PyPI
+
+Visit https://pypi.org/project/auditflowlog/ to see your package!
+
+## Publishing to Test PyPI (Recommended First)
+
+Test on TestPyPI before publishing to real PyPI:
+
+### 1. Create TestPyPI Account
+
+https://test.pypi.org/account/register/
+
+### 2. Generate TestPyPI Token
+
+https://test.pypi.org/manage/account/token/
+
+### 3. Upload to TestPyPI
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+### 4. Test Installation
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ auditflowlog
+```
+
+### 5. If Successful, Upload to Real PyPI
+
+```bash
+python -m twine upload dist/*
+```
+
+## Version Management
+
+### Update Version Number
+
+Edit `pyproject.toml`:
+```toml
+[project]
+version = "0.2.0"  # Bump version
+```
+
+Also update:
+- `src/auditflowlog/__init__.py` - `__version__`
+- `CHANGELOG.md` - Add new version entry
+
+### Semantic Versioning
+
+Follow semver (https://semver.org/):
+
+- **MAJOR** (1.0.0): Breaking changes
+- **MINOR** (0.2.0): New features, backward compatible
+- **PATCH** (0.1.1): Bug fixes, backward compatible
+
+Examples:
+- `0.0.1` → `0.1.1`: Bug fix
+- `0.1.1` → `0.2.0`: New feature (streaming support)
+- `0.2.0` → `1.0.0`: Stable release, API guarantee
+
+## Release Checklist
+
+Before publishing a new version:
+
+- [ ] Update version in `pyproject.toml`
+- [ ] Update `__version__` in `src/auditflowlog/__init__.py`
+- [ ] Update `CHANGELOG.md` with changes
+- [ ] Run all tests: `python tests/test_models.py`
+- [ ] Test all examples work
+- [ ] Update documentation if needed
+- [ ] Clean dist folder: `rm -rf dist/`
+- [ ] Build: `python -m build`
+- [ ] Check build: `python -m twine check dist/*`
+- [ ] Test install in clean environment
+- [ ] Upload to TestPyPI first
+- [ ] Test TestPyPI install works
+- [ ] Upload to PyPI
+- [ ] Create git tag: `git tag v0.0.1`
+- [ ] Push tag: `git push origin v0.0.1`
+- [ ] Create GitHub release with changelog
+
+## CI/CD (Future)
+
+### GitHub Actions Workflow
+
+Create `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      
+      - name: Install dependencies
+        run: |
+          pip install build twine
+      
+      - name: Build
+        run: python -m build
+      
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+```
+
+Add `PYPI_API_TOKEN` to GitHub secrets.
+
+## Troubleshooting
+
+### "Package already exists"
+
+You've already uploaded this version. Bump version number and rebuild.
+
+### "Invalid authentication"
+
+Check your API token is correct and properly formatted in `.pypirc`.
+
+### "Filename already used"
+
+PyPI doesn't allow re-uploading same filename. Bump version and rebuild.
+
+### Import errors after install
+
+Make sure `pyproject.toml` has correct package path:
+```toml
+[tool.hatchling.build.targets.wheel]
+packages = ["src/auditflowlog"]
+```
+
+## Distribution Channels
+
+Once published to PyPI, users can install via:
+
+```bash
+# Standard install
+pip install auditflowlog
+
+# With extras
+pip install auditflowlog[loguru]
+pip install auditflowlog[streaming]
+pip install auditflowlog[all]
+
+# Specific version
+pip install auditflowlog==0.0.1
+
+# Upgrade
+pip install --upgrade auditflowlog
+```
+
+## Post-Publication
+
+After publishing:
+
+1. **Announce** on social media, forums, community
+2. **Monitor** GitHub issues for bug reports
+3. **Update** documentation if users find gaps
+4. **Plan** next version based on feedback
+5. **Maintain** changelog for transparency
+
+## Support After Release
+
+- Respond to GitHub issues promptly
+- Fix critical bugs quickly (patch release)
+- Consider user feature requests for minor releases
+- Maintain backward compatibility until 1.0.0
+- Document breaking changes clearly in CHANGELOG
+
+## Resources
+
+- [Python Packaging Guide](https://packaging.python.org/)
+- [PyPI Help](https://pypi.org/help/)
+- [Semantic Versioning](https://semver.org/)
+- [Keep a Changelog](https://keepachangelog.com/)

auditflowlog-0.0.1/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to the AuditFlow Python SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-07-18
+
+### Added
+
+#### Core Client
+- `AuditFlowClient` - Synchronous HTTP client for log ingestion
+- `AsyncAuditFlowClient` - Asynchronous HTTP client for log ingestion
+- Context manager support for both sync and async clients
+- Batch log sending capability
+- Proper error handling with custom exceptions
+
+#### Logging Framework Integrations
+- `AuditFlowSink` - Loguru sink for automatic log forwarding
+- `StdlibHandler` - Standard library logging handler
+- Automatic metadata extraction from log records
+- Exception tracking in metadata
+
+#### Real-time Streaming
+- `LogStream` - Async WebSocket client for real-time log streaming
+- `SyncLogStream` - Synchronous wrapper for blocking usage
+- Flexible filtering by bucket, level, time range, and metadata
+- Auto-reconnect on connection loss
+- Both callback-based and async iterator APIs
+
+#### Models and Types
+- `LogLevel` enum (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- `LogEntry` dataclass for structured log representation
+- `LogFilter` dataclass for query/stream filtering
+- Full type hints throughout the codebase
+
+#### Exceptions
+- `AuditFlowError` - Base exception class
+- `AuthenticationError` - Invalid API key
+- `RateLimitError` - Rate limit exceeded
+- `ConnectionError` - WebSocket connection failed
+- `StreamError` - Streaming error
+
+#### Documentation
+- Comprehensive README with examples
+- Getting Started guide
+- Architecture documentation
+- 5 complete working examples:
+  - Loguru integration
+  - Standard library logging
+  - Direct client usage
+  - Async client usage
+  - Real-time streaming
+
+#### Package Configuration
+- Optional dependencies for loguru and websockets
+- Proper package metadata and classifiers
+- MIT license
+
+### Dependencies
+- httpx >= 0.27.2 (required)
+- loguru >= 0.7.0 (optional, for loguru integration)
+- websockets >= 12.0 (optional, for streaming)
+
+## [Unreleased]
+
+### Planned Features
+- Buffered sending with automatic batch flushing
+- Circuit breaker pattern for backend failures
+- Local file fallback when backend is unavailable
+- Log compression for large batches
+- Built-in metrics and telemetry
+- Sampling support for high-volume scenarios
+- structlog integration
+- Django/Flask/FastAPI middleware integrations