nippy-decoder 0.1.0__tar.gz

nippy_decoder-0.1.0/.crush/.gitignore

@@ -0,0 +1 @@
+*

nippy_decoder-0.1.0/.crush/logs/crush.log

@@ -0,0 +1,16 @@
+{"time":"2026-02-26T21:41:18.667496+05:30","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/config.Load","file":"github.com/charmbracelet/crush/internal/config/load.go","line":58},"msg":"No git repository detected in working directory, will limit file walk operations","depth":2,"items":100}
+{"time":"2026-02-26T21:41:18.669777+05:30","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/config.Load","file":"github.com/charmbracelet/crush/internal/config/load.go","line":66},"msg":"Detected Apple Terminal, enabling transparent mode"}
+{"time":"2026-02-26T21:41:18.675466+05:30","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":55},"msg":"Fetching providers from Catwalk"}
+{"time":"2026-02-26T21:41:19.065506+05:30","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":63},"msg":"Catwalk providers not modified"}
+{"time":"2026-02-26T21:41:19.087574+05:30","level":"INFO","msg":"OK   20250424200609_initial.sql (1.16ms)"}
+{"time":"2026-02-26T21:41:19.087836+05:30","level":"INFO","msg":"OK   20250515105448_add_summary_message_id.sql (191.29µs)"}
+{"time":"2026-02-26T21:41:19.08802+05:30","level":"INFO","msg":"OK   20250624000000_add_created_at_indexes.sql (170.54µs)"}
+{"time":"2026-02-26T21:41:19.088202+05:30","level":"INFO","msg":"OK   20250627000000_add_provider_to_messages.sql (172.38µs)"}
+{"time":"2026-02-26T21:41:19.088547+05:30","level":"INFO","msg":"OK   20250810000000_add_is_summary_message.sql (174.96µs)"}
+{"time":"2026-02-26T21:41:19.088777+05:30","level":"INFO","msg":"OK   20250812000000_add_todos_to_sessions.sql (210.38µs)"}
+{"time":"2026-02-26T21:41:19.089194+05:30","level":"INFO","msg":"OK   20260127000000_add_read_files_table.sql (395.96µs)"}
+{"time":"2026-02-26T21:41:19.0892+05:30","level":"INFO","msg":"goose: successfully migrated database to version: 20260127000000"}
+{"time":"2026-02-26T21:41:19.091067+05:30","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent/tools/mcp.Initialize","file":"github.com/charmbracelet/crush/internal/agent/tools/mcp/init.go","line":153},"msg":"Initializing MCP clients"}
+{"time":"2026-02-26T21:41:26.184106+05:30","level":"ERROR","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":812},"msg":"Error generating title with small model; trying big model","err":"Post \"https://bedrock-runtime..amazonaws.com/model/us.anthropic.claude-haiku-4-5-20251001-v1%3A0/invoke-with-response-stream\": dial tcp: lookup bedrock-runtime..amazonaws.com: no such host"}
+{"time":"2026-02-27T09:16:51.594865+05:30","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*Config).RefreshOAuthToken","file":"github.com/charmbracelet/crush/internal/config/config.go","line":564},"msg":"Successfully refreshed OAuth token","provider":"copilot"}
+{"time":"2026-02-27T09:47:01.79407+05:30","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*Config).RefreshOAuthToken","file":"github.com/charmbracelet/crush/internal/config/config.go","line":564},"msg":"Successfully refreshed OAuth token","provider":"copilot"}

nippy_decoder-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__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
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

nippy_decoder-0.1.0/AGENTS.md

@@ -0,0 +1,363 @@
+# AGENTS.md
+
+## Project Overview
+
+**nippy-decoder** is a pure Python decoder for Clojure Nippy-encoded data. This is a library project focused on decoding serialized data from Clojure/Java services that use the Nippy format.
+
+- **Language**: Python 3.8+
+- **Dependencies**: Zero external dependencies (stdlib only)
+- **Purpose**: Decode Nippy-encoded bytes from databases (Postgres, SQLite), APIs, Kafka, Redis, etc.
+- **Status**: Beta (v0.1.0)
+- **License**: MIT
+
+## Essential Commands
+
+### Installation & Setup
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Install for use
+pip install nippy-decoder
+```
+
+### Running Examples
+
+```bash
+# Run examples (use PYTHONPATH to add src/)
+PYTHONPATH=src python examples/basic_usage.py
+PYTHONPATH=src python examples/database_example.py
+
+# Or after installing in dev mode
+python examples/basic_usage.py
+python examples/database_example.py
+```
+
+### Testing
+
+```bash
+# Install test dependency
+pip install pytest
+
+# Run all tests with verbose output
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_primitives.py -v
+pytest tests/test_collections.py -v
+pytest tests/test_uuid.py -v
+
+# Run with coverage (if coverage installed)
+pip install pytest-cov
+pytest tests/ --cov=nippy_decoder --cov-report=html
+```
+
+### Building & Publishing
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build package
+python -m build
+
+# Upload to test PyPI
+twine upload --repository testpypi dist/*
+
+# Upload to production PyPI
+twine upload dist/*
+```
+
+## Code Organization
+
+```
+nippy-decoder/
+├── src/nippy_decoder/          # Main package
+│   ├── __init__.py            # Package exports: NippyDecoder, __version__
+│   └── decoder.py             # Core decoder logic (~200 lines)
+├── tests/                      # pytest test suite
+│   ├── test_primitives.py     # Tests for basic types (null, bool, int, float, string, keyword)
+│   ├── test_collections.py    # Tests for vectors, maps, sets, lists
+│   └── test_uuid.py           # Tests for UUID decoding
+├── examples/                   # Usage examples
+│   ├── basic_usage.py         # Simple decoding examples
+│   └── database_example.py    # Database integration examples
+├── pyproject.toml             # Package metadata & build config (hatchling)
+├── README.md                  # User-facing documentation
+├── SETUP.md                   # Developer setup guide
+├── CHANGELOG.md               # Version history
+├── LICENSE                    # MIT license
+└── .gitignore                 # Standard Python gitignore
+```
+
+### Key Files
+
+- **`src/nippy_decoder/decoder.py`**: The entire decoder implementation (~200 lines)
+  - `NippyDecoder` class with `decode()` method
+  - Private methods for reading each type (`_read()`, `_read_str()`, `_read_vec()`, `_read_map()`, etc.)
+  - No external dependencies - uses only `struct`, `uuid`, `json`, `io` from stdlib
+
+- **`src/nippy_decoder/__init__.py`**: Simple package export
+  - Exports `NippyDecoder` class
+  - Defines `__version__` = "0.1.0"
+
+## Code Patterns & Conventions
+
+### Code Style
+
+- **Simple, readable code**: No complex abstractions
+- **Type hints**: Used for public API (`decode()` method signature)
+- **Docstrings**: Present for public methods and module
+- **No formatters/linters configured**: Use standard Python conventions
+- **Line length**: Reasonable (~80-100 chars, not strictly enforced)
+
+### Naming Conventions
+
+- **Classes**: PascalCase (`NippyDecoder`)
+- **Methods**: snake_case (`decode()`, `_read_str()`)
+- **Private methods**: Prefix with underscore (`_read()`, `_read_vec()`)
+- **Constants**: UPPER_SNAKE_CASE (`MAGIC_HEADER`, `VERSION`)
+- **Variables**: snake_case (`type_code`, `result`)
+
+### Error Handling
+
+- **Raises `ValueError`** for all decode errors:
+  - Invalid header: `"invalid nippy header"`
+  - Unsupported version: `"unsupported nippy version: X"`
+  - Unsupported type: `"unsupported type: X"`
+  - Unexpected EOF: `"unexpected end of stream"`
+
+- **Return `None`** for empty/missing data (not an error)
+
+### Data Type Conversions
+
+**Clojure → Python mappings:**
+- `nil` → `None`
+- `true`/`false` → `True`/`False`
+- integers → `int`
+- floats/doubles → `float`
+- strings → `str`
+- **keywords** (`:status`) → `str` (`"status"` without colon)
+- vectors → `list`
+- maps → `dict`
+- sets → `set`
+- byte arrays → `bytes` (or `dict`/`list` if auto-parsed as JSON)
+- UUID → `str` (UUID string representation)
+
+**Important**: Clojure keywords lose their `:` prefix when decoded to Python strings.
+
+### Key Implementation Details
+
+1. **Big-endian encoding**: All multi-byte integers use big-endian (`>` in struct format)
+
+2. **Type codes**: Each value is prefixed with a type byte (0-127)
+   - 0-3: Primitives (zero, true, false, nil)
+   - 4-8, 40-43: Integers (various sizes)
+   - 9-10: Floats (f32, f64)
+   - 11-14, 105: Strings
+   - 15-18: Byte arrays
+   - 19-23: Vectors
+   - 24-26, 112: Maps
+   - 27-29: Sets
+   - 30-32: Lists
+   - 33-35, 106: Keywords
+   - 36: UUID
+   - 37: Metadata (skip and read next)
+   - 44-127: Legacy collection types (treated as vectors)
+
+3. **Length prefixes**: Collections and strings use 1, 2, or 4-byte length prefixes
+   - Type determines prefix size
+   - Lengths are unsigned big-endian integers
+
+4. **UUID encoding**: Stored as two signed 64-bit longs (MSB, LSB)
+   - Conversion handles signed→unsigned for Python UUID construction
+
+5. **Map keys**: Unhashable keys (list, dict, set) converted to strings
+
+6. **Byte array special case**: If starts with `{` or `[`, attempts JSON parse
+
+7. **Metadata handling**: Type 37 skips metadata and returns the actual value
+
+## Testing Approach
+
+### Test Structure
+
+- **pytest** framework
+- Tests organized by type category:
+  - `test_primitives.py`: Basic types
+  - `test_collections.py`: Vectors, maps, sets
+  - `test_uuid.py`: UUID handling
+- Each test manually constructs Nippy bytes and validates decoded result
+
+### Test Patterns
+
+```python
+# Standard test pattern
+def test_something():
+    decoder = NippyDecoder()
+    
+    # Manually construct Nippy bytes
+    data = b'NPY\x00' + [type byte] + [payload]
+    
+    # Decode and assert
+    result = decoder.decode(data)
+    assert result == expected_value
+```
+
+### Key Test Scenarios Covered
+
+- All primitive types (null, bool, int, float)
+- String encoding (empty, short, medium)
+- Keywords (converted to strings)
+- Collections (vectors, maps, sets, lists)
+- Empty collections
+- Nested structures
+- Mixed-type collections
+- UUID encoding/decoding
+- Error cases (invalid header, unsupported version)
+- Edge cases (unhashable map keys)
+
+### Running Tests
+
+Always run tests after changes to decoder logic:
+```bash
+pytest tests/ -v
+```
+
+## Development Workflow
+
+### Making Changes
+
+1. **Read first**: Always read `decoder.py` before making changes
+2. **Understand context**: This decoder is validated against official Clojure Nippy - don't break compatibility
+3. **Test immediately**: Run tests after every change
+4. **Keep it simple**: The whole decoder is ~200 lines - maintain this simplicity
+
+### Adding New Type Support
+
+If adding support for a new Nippy type code:
+
+1. Find the type code in Nippy spec/source
+2. Add handler in `_read()` method (follow existing pattern)
+3. Create helper method if needed (e.g., `_read_new_type()`)
+4. Add test case in appropriate test file
+5. Update README type mapping table
+6. Update docstring in `decoder.py`
+
+### Common Tasks
+
+**Add a new type handler:**
+```python
+# In decoder.py _read() method
+if type_code == XX: return self._read_new_type(stream)
+```
+
+**Add a helper method:**
+```python
+def _read_new_type(self, stream: BytesIO) -> SomeType:
+    """Read new type with description."""
+    # Implementation
+    return result
+```
+
+**Update version:**
+1. Edit `pyproject.toml` version
+2. Edit `src/nippy_decoder/__init__.py` __version__
+3. Add entry to `CHANGELOG.md`
+
+## Important Gotchas
+
+### 1. Nippy Version Lock
+
+**Only Nippy v0 is supported** (the standard format since 2014). The decoder explicitly checks version byte and rejects anything other than 0.
+
+### 2. Keyword Transformation
+
+Clojure keywords like `:status` become Python strings `"status"`. The colon is not preserved. This is by design but can surprise users.
+
+### 3. JSON Auto-parsing in Byte Arrays
+
+Byte arrays that start with `{` or `[` are automatically parsed as JSON and returned as dict/list. This can fail silently (returns raw bytes on JSON parse error). This is intentional but worth knowing.
+
+### 4. Map Key Conversion
+
+Unhashable Python objects (list, dict, set) used as map keys are automatically converted to strings via `str()`. This prevents crashes but loses type information.
+
+### 5. Zero Dependencies Constraint
+
+**Never add external dependencies.** This is a core feature of the library. Use only Python stdlib.
+
+### 6. PYTHONPATH for Examples
+
+Examples must be run with `PYTHONPATH=src` unless package is installed in dev mode (`pip install -e .`).
+
+### 7. Struct Format Strings
+
+All struct unpacking uses big-endian (`>`):
+- `'>h'`: signed 16-bit
+- `'>i'`: signed 32-bit  
+- `'>q'`: signed 64-bit
+- `'>H'`: unsigned 16-bit
+- `'>I'`: unsigned 32-bit
+- `'>f'`: 32-bit float
+- `'>d'`: 64-bit double
+
+### 8. BytesIO Position
+
+The decoder uses `BytesIO.read()` which advances position automatically. Be careful when adding new read methods.
+
+### 9. No Encoding Support
+
+This is a **decoder-only** library. Encoding is not supported and should not be added. Users needing encoding should use official Clojure Nippy.
+
+## Project-Specific Context
+
+### Purpose & Use Cases
+
+This library solves a specific problem: **Python services need to read data serialized by Clojure services using Nippy format.**
+
+Common scenarios:
+- Reading Nippy-encoded columns from Postgres/SQLite databases
+- Consuming Nippy-encoded messages from Kafka
+- Reading Nippy values from Redis
+- Processing API responses with Nippy payloads
+
+### Design Philosophy
+
+1. **Simplicity**: ~200 lines total, easy to understand and debug
+2. **Zero dependencies**: No external deps, easy to install anywhere
+3. **Decode-only**: Focused on one problem, does it well
+4. **Stdlib only**: Uses only Python built-in modules
+5. **Type fidelity**: Maps Clojure types to natural Python equivalents
+
+### Not Supported (by design)
+
+- **Encoding**: Use official Clojure Nippy for encoding
+- **Nippy v1+**: Only v0 (the standard) is supported
+- **Custom extensions**: Custom Nippy types not implemented
+- **Types > 127**: Reserved/future types not implemented
+- **Streaming**: Decodes complete byte arrays, not streaming
+
+### Validation
+
+The decoder has been validated against official `taoensso/nippy` Clojure implementation. When making changes, ensure compatibility is maintained.
+
+## References
+
+- **Official Nippy**: https://github.com/taoensso/nippy
+- **Type codes**: See `decoder.py` comments or README.md type mapping table
+- **Build backend**: Uses `hatchling` (specified in `pyproject.toml`)
+
+## Tips for Agents
+
+1. **Always test after changes**: `pytest tests/ -v`
+2. **Keep decoder simple**: Resist urge to refactor into complex abstractions
+3. **Preserve zero dependencies**: Don't add external packages
+4. **Match existing patterns**: Follow the type handler pattern in `_read()`
+5. **Update docs together**: If changing decoder, update README type table
+6. **Test with real Nippy data**: If possible, validate against Clojure-generated bytes
+7. **Use exact whitespace**: Code has 4-space indentation consistently
+8. **Preserve type conversion logic**: Keyword→string, unhashable keys→string, etc.
+9. **Don't break backward compatibility**: This is a library, breaking changes affect users
+10. **Read SETUP.md and README.md**: They contain additional context and user docs

nippy_decoder-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-02-26
+
+### Added
+- Initial release
+- Pure Python Nippy decoder implementation
+- Support for all standard Nippy types:
+  - Primitives (null, bool, int, float)
+  - Strings and keywords
+  - Collections (vector, map, set, list)
+  - UUIDs
+  - Byte arrays with auto-JSON parsing
+- Zero external dependencies
+- Python 3.8+ support
+- Comprehensive test suite
+- Usage examples

nippy_decoder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nippy-decoder contributors
+
+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.