Metadata-Version: 2.4
Name: b62
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: General
Classifier: Typing :: Typed
License-File: LICENSE
Summary: A lightning-fast, zero-dependency Base62 encoder/decoder for Python
Keywords: base62,encoding,decoding,url-shortening,performance
Author-email: Maksim Smirnov <smirnoffmg@gmail.com>
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/smirnoffmg/b62
Project-URL: Documentation, https://github.com/smirnoffmg/b62#readme
Project-URL: Repository, https://github.com/smirnoffmg/b62.git
Project-URL: Issues, https://github.com/smirnoffmg/b62/issues

# b62

🎉 A lightning-fast, zero-dependency and friendly Base62 encoder/decoder for Python! Tame your data with style and a smile.

## Features

- ⚡ High-performance Base62 encode/decode for integers
- 🐍 Friendly Python interface backed by Rust
- 🔧 Seamless Rust-Python integration via PyO3
- 🛡️ Type-safe with comprehensive error handling
- 🧪 Thoroughly tested with property-based testing
- 📦 Zero runtime dependencies

## Installation

### From PyPI

```bash
pip install b62
```

## Usage


```python
import b62

# Encode an integer to Base62
encoded = b62.encode(123456789)
print(encoded)  # Output: "8M0kX"

# Decode a Base62 string back to integer
decoded = b62.decode("8M0kX")
print(decoded)  # Output: 123456789

# Error handling
try:
    b62.decode("invalid!")
except ValueError as e:
    print(f"Invalid Base62 string: {e}")

# Round-trip validation
original = 987654321
encoded = b62.encode(original)
decoded = b62.decode(encoded)
assert original == decoded  # Always True!
```

## Performance

b62 is built with Rust for maximum performance and delivers exceptional speed:

### Benchmark Results

**Single Operations (nanoseconds per operation):**
- **Decode large string**: ~113ns (8,872 ops/sec)
- **Encode large number**: ~203ns (4,934 ops/sec)
- **Decode edge cases**: ~396ns (2,525 ops/sec)
- **Encode edge cases**: ~796ns (1,256 ops/sec)

**Batch Operations (100,000 operations):**
- **Encoding**: ~0.014s (7.2M ops/sec)
- **Decoding**: ~0.020s (5.1M ops/sec)
- **Round-trip**: ~0.033s (3.0M ops/sec)

**Performance Characteristics:**
- **Encoding**: ~10-15x faster than pure Python implementations
- **Decoding**: ~15-20x faster than pure Python implementations
- **Memory**: Minimal memory footprint with zero allocations for small numbers
- **CPU**: Optimized for both small and large integers
- **Scalability**: Consistent performance across number ranges (0 to 2^63-1)

### Technical Implementation

The library uses a highly optimized Rust implementation with PyO3 bindings:

- **Character Set**: `0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`
- **Algorithm**: Efficient division/modulo operations with pre-allocated buffers
- **Error Handling**: Comprehensive validation with detailed error messages
- **Type Safety**: Full type annotations and runtime validation
- **Memory Management**: Zero-copy operations where possible

## API Reference

### `b62.encode(num: int) -> str`

Encodes an integer to Base62 string representation.

**Parameters:**

- `num` (int): Integer to encode (must be non-negative)

**Returns:**

- `str`: Base62 encoded string

**Raises:**

- `OverflowError`: If the integer is too large for u64

### `b62.decode(s: str) -> int`
Decodes a Base62 string back to an integer.

**Parameters:**

- `s` (str): Base62 string to decode

**Returns:**

- `int`: Decoded integer

**Raises:**

- `ValueError`: If the string contains invalid Base62 characters

## Development

### Running Tests

```bash
make test
```

### Code Quality

```bash
make ci
```

### Building

```bash
make build_package
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines

- Follow PEP 8 style guidelines
- Add tests for new functionality
- Update documentation as needed
- Ensure all tests pass before submitting

## License

MIT License - free and open for all! 🎉

## Why b62?

Keep your integer conversions speedy and stylish! Perfect for:

- URL shortening
- Database ID encoding
- Compact data serialization
- Performance-critical applications

🦀🐍💨

