Metadata-Version: 2.4
Name: ifscfinder
Version: 0.1.0
Summary: High-performance IFSC code lookup utilities backed by SQLite.
Author-email: Akshat Kotpalliwar <akshatkot@gmail.com>
Maintainer-email: Akshat Kotpalliwar <akshatkot@gmail.com>
License-Expression: LGPL-2.1
Project-URL: Homepage, https://github.com/IntegerAlex/IFSCFinder
Project-URL: Repository, https://github.com/IntegerAlex/IFSCFinder
Project-URL: Documentation, https://github.com/IntegerAlex/IFSCFinder/wiki
Project-URL: Bug Reports, https://github.com/IntegerAlex/IFSCFinder/issues
Keywords: ifsc,banking,lookup,sqlite,finance,indian-banks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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 :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.68.0; extra == "fastapi"
Requires-Dist: starlette>=0.14.0; extra == "fastapi"
Provides-Extra: flask
Requires-Dist: flask>=1.0.0; extra == "flask"
Provides-Extra: django
Requires-Dist: django>=3.0.0; extra == "django"
Provides-Extra: web
Requires-Dist: fastapi>=0.68.0; extra == "web"
Requires-Dist: starlette>=0.14.0; extra == "web"
Requires-Dist: flask>=1.0.0; extra == "web"
Requires-Dist: django>=3.0.0; extra == "web"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: flake8>=3.8.0; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: pre-commit>=2.15.0; extra == "dev"
Requires-Dist: build>=0.8.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: performance
Requires-Dist: orjson>=3.8.0; extra == "performance"
Requires-Dist: uvloop>=0.17.0; sys_platform != "win32" and extra == "performance"
Provides-Extra: all
Requires-Dist: fastapi>=0.68.0; extra == "all"
Requires-Dist: starlette>=0.14.0; extra == "all"
Requires-Dist: flask>=1.0.0; extra == "all"
Requires-Dist: django>=3.0.0; extra == "all"
Requires-Dist: orjson>=3.8.0; extra == "all"
Requires-Dist: uvloop>=0.17.0; sys_platform != "win32" and extra == "all"

IFSCFinder (Python)
===================

IFSCFinder is a high-performance Python package that provides lightning-fast IFSC code lookups through an embedded SQLite database. With sub-millisecond query times and 40x cache acceleration, it's optimized for banking automation, fintech analytics, and high-throughput microservice architectures.

**Performance Metrics:**
- **Average lookup time**: 0.01ms per query
- **Throughput**: 136,845 lookups/second (uncached), 5.5M/second (cached)
- **Cache speedup**: 40x faster for repeated queries
- **Database size**: 42MB compressed SQLite with full Indian banking network coverage
- **Memory footprint**: Minimal with configurable caching

Installation
------------

```bash
pip install git+https://github.com/IntegerAlex/IFSCFinder.git#subdirectory=python
```

For local development:

```bash
cd /home/akshat/projects/ifsc/python
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Usage
-----

```python
from ifscfinder import ifsc_to_details, ifsc_to_bank

details = ifsc_to_details("SBIN0000001")
bank_name = ifsc_to_bank("SBIN0000001")
```

- `ifsc_to_details(code)` returns a dictionary with `BANK`, `BRANCH`, `ADDRESS`, `CITY1`, `CITY2`, `STATE`, and `STD_CODE` keys.
- Field-specific helpers (`ifsc_to_bank`, `ifsc_to_branch`, `ifsc_to_state`, etc.) offer ergonomic access.
- `clear_lookup_cache()` invalidates the in-memory cache when the database changes.
- `get_database(db_path=None)` returns the underlying `IFSCDatabase` singleton if you need lower-level control.

Data Source
-----------

The packaged SQLite database lives under `ifscfinder/data/ifsc.db`. Replace this file with an updated dataset to refresh lookups. The package automatically validates the presence of the database and raises a descriptive `FileNotFoundError` if it is missing.

Testing & Quality
-----------------

- Run `python3 -m compileall src/ifscfinder` to sanity check syntax.
- Upcoming automated tests will live under `python/tests` and be executed via `pytest`.
- The code uses strict IFSC normalization and structured logging to aid production diagnostics.

Roadmap
-------

- Publish the package to PyPI with automated GitHub Actions builds.
- Provide a JSON export pipeline to feed JavaScript, Go, and Rust ports.
- Synchronize API contracts across the forthcoming TypeScript client and other language bindings.

Contributing
------------

1. Fork the repository and create a feature branch.
2. Run sanity checks before submitting a pull request.
3. Document any API changes in this README and sync cross-language specs.

License
-------

LGPL-2.1 License. See `LICENSE` in the project root.

**Copyright Notice:**
Copyright (c) 2024 Akshat Kotpalliwar. All rights reserved.

This package is distributed under the GNU Lesser General Public License v2.1.
See the LICENSE file for full copyright information and license terms.
