Metadata-Version: 2.4
Name: smartbindb
Version: 4.16.1
Summary: A powerful Asynchronous Python library for getting bins database by country name or bank name, also supports bin lookup, supporting bots, MTProto API frameworks, and Python scripts
Author-email: "@ISmartCoder" <abirxdhackz.info.me@gmail.com>
License: Proprietary
Project-URL: Homepage, https://github.com/abirxdhack
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pycountry
Requires-Dist: pycountry-convert
Requires-Dist: asyncio

# SmartBinDB

![Python Version](https://img.shields.io/badge/Python-3.8%2B-blue)
![Version](https://img.shields.io/badge/Version-4.16.1-green)
![Performance](https://img.shields.io/badge/Performance-Lightning%20Fast-red)

A **lightning-fast** asynchronous Python library for retrieving Bank Identification Number (BIN) database information, supporting lookups by country name, bank name, and individual BINs. Ideal for bots, MTProto API frameworks, and Python scripts. **This is a closed-source project, and the source code is not available for public distribution.**

## ⚡ What's New in v4.16.1

### 🚀 Massive Performance Improvements
- **Lightning-fast BIN lookups**: Now instant with O(1) hash table access
- **Ultra-fast startup**: Binary database caching reduces startup time from 6+ seconds to 10-50ms
- **Memory-optimized loading**: Smart caching system with automatic rebuild detection
- **Parallel processing**: Multi-threaded file loading for maximum performance
- **Pre-cached country data**: Zero-delay country information lookups

### 🔧 Technical Enhancements
- **Binary Database Format**: Optimized `.db` file format for instant loading
- **Smart Cache Management**: Automatic cache invalidation when source data changes
- **Memory-Mapped File Access**: Direct memory access for JSON files when needed
- **Thread-Safe Operations**: Concurrent operations with proper locking mechanisms
- **Optimized Data Structures**: Enhanced indexing for faster search operations

### 📊 Performance Benchmarks
- **BIN Lookups**: ~1000x faster (microseconds vs seconds)
- **Startup Time**: ~100x faster (milliseconds vs seconds) 
- **Memory Usage**: 50% reduction with optimized caching
- **Search Operations**: 5-10x faster with enhanced algorithms

## Features
- **Asynchronous operations** using `asyncio` for high-performance data retrieval
- **Flexible lookups** by country code, bank name, or specific BIN number
- **Optional limit support** for bank and country-based searches
- **Compatible** with Python 3.8 and all future versions
- **Seamless integration** for developers working with bots, APIs, and scripts
- **Lightning-fast performance** with intelligent caching and optimization
- **Memory-efficient** binary database format
- **Auto-updating cache** system for maximum performance

## Installation
Install SmartBinDB via pip:

```bash
pip install smartbindb
```

## Usage

### Basic Asyncio Example
```python
import asyncio
from smartbindb import SmartBinDB

async def main():
    smartdb = SmartBinDB()
    print("What would you like to do?")
    print("1. BIN lookup")
    print("2. Bank based search")
    print("3. Country based search")
    choice = input("Enter your choice (1, 2, or 3): ")

    if choice == "1":
        bin_number = input("Enter BIN number: ")
        result = await smartdb.get_bin_info(bin_number)
        print("BIN info:", result)
    elif choice == "2":
        bank_name = input("Enter bank name: ")
        use_limit = input("Do you want to use a limit? (yes/no): ").lower()
        limit = None
        if use_limit == "yes":
            limit = int(input("Enter limit: "))
        result = await smartdb.get_bins_by_bank(bank_name, limit)
        print("Bank results:", result)
    elif choice == "3":
        country_code = input("Enter country code: ").upper()
        use_limit = input("Do you want to use a limit? (yes/no): ").lower()
        limit = None
        if use_limit == "yes":
            limit = int(input("Enter limit: "))
        result = await smartdb.get_bins_by_country(country_code, limit)
        print("Country results:", result)
    else:
        print("Invalid choice. Please select 1, 2, or 3.")

if __name__ == "__main__":
    asyncio.run(main())
```

### Advanced Performance Example
```python
import asyncio
import time
from smartbindb import SmartBinDB

async def performance_test():
    smartdb = SmartBinDB()
    
    # Test lightning-fast BIN lookup
    start = time.time()
    result = await smartdb.get_bin_info("424242")
    end = time.time()
    print(f"BIN lookup completed in {(end-start)*1000:.2f}ms")
    print("Result:", result)
    
    # Test fast bank search
    start = time.time()
    bank_results = await smartdb.get_bins_by_bank("Chase", limit=100)
    end = time.time()
    print(f"Bank search completed in {(end-start)*1000:.2f}ms")
    print(f"Found {bank_results.get('count', 0)} results")

if __name__ == "__main__":
    asyncio.run(performance_test())
```

## Performance Notes

### First Run
On the first run, SmartBinDB will build an optimized binary database from your JSON data files. This one-time process takes 1-2 seconds but creates a highly optimized `.db` file.

### Subsequent Runs  
After the initial setup, SmartBinDB loads in milliseconds and provides instant BIN lookups. The binary cache automatically rebuilds only when your source data changes.

### Memory Efficiency
The new caching system uses 50% less memory while providing dramatically faster performance through intelligent data structures and optimized algorithms.

## API Reference

### `SmartBinDB()`
Creates a new SmartBinDB instance with lightning-fast performance optimizations.

### `await get_bin_info(bin: str)`
Performs instant BIN lookup with O(1) hash table access.

### `await get_bins_by_bank(bank: str, limit: Optional[int] = None)`
Fast bank-based search with optional result limiting.

### `await get_bins_by_country(country: str, limit: Optional[int] = None)`
Optimized country-based search with enhanced performance.

## Contributing
This is a closed-source project, and contributions are not accepted at this time.

## License
This project is proprietary and not licensed for open-source use.

## Contact
- **Author**: @ISmartCoder
- **Email**: abirxdhackz.info.me@gmail.com

## Changelog

### v4.16.1 (Latest)
- 🚀 **MAJOR**: Lightning-fast BIN lookups with O(1) hash access
- ⚡ **MAJOR**: Ultra-fast startup with binary database caching
- 🔧 **IMPROVED**: Memory-optimized data structures
- 🔧 **IMPROVED**: Multi-threaded parallel file loading
- 🔧 **IMPROVED**: Smart cache management with auto-rebuild
- 🔧 **IMPROVED**: Pre-cached country information
- 📊 **PERFORMANCE**: 1000x faster BIN lookups
- 📊 **PERFORMANCE**: 100x faster startup times
- 📊 **PERFORMANCE**: 50% memory usage reduction

