Metadata-Version: 2.4
Name: biometric-fetch
Version: 0.1.0
Summary: Fetch data from any biometric device easily
Author: Rishabh & Shreya
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyzk
Requires-Dist: pandas
Requires-Dist: requests
Requires-Dist: openpyxl
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<h1 align="center">Biometric Fetch 🚀</h1>

<p align="center">
  <strong>The ultimate universal wrapper for fetching attendance & user data from 50+ biometric devices.</strong><br>
  <em>(ZKTeco, eSSL, SecureEye, Hikvision, Suprema, IDEMIA, Nitgen, and more!)</em>
</p>

---

## What is Biometric Fetch?
Historically, interacting with biometric machines requires downloading confusing vendor SDKs, dealing with messy `DLL` segmentation faults, studying raw `Socket` connections, or writing massive API XML wrappers.

**`biometric-fetch`** solves this by acting as a universal "Factory Pattern". You write **3 lines of Python code** using one standard interface, and we automatically handle the underlying protocol (TCP/IP, REST API, or SDK Binding) securely under the hood.

We even natively convert all raw device logs directly into beautiful **Pandas DataFrames**! 📊

## ⚙️ Installation

Install effortlessly via PyPI:
```bash
pip install biometric-fetch
```

*(This automatically installs our dependencies: `pyzk`, `pandas`, `requests`, and `openpyxl`)*

---

## ⚡ Quick Start

### 1. Connecting via TCP/IP (ZKTeco, eSSL, Secureye, etc)
The most common biometric devices run on port `4370`.
```python
from biometric_fetch import BiometricDevice

# The factory seamlessly invokes the TCP/IP backend
device = BiometricDevice(brand="zkteco", ip="192.168.1.201")
device.connect()

# Fetch array of User Objects
users = device.get_users()
print(users)
```

### 2. Outputting as Pandas DataFrames! 🐼
Stop looping through messy strings. Enable `as_dataframe=True` to immediately deploy data analytics.
```python
df = device.get_attendance(as_dataframe=True)

# You now have a clean, formatted table of all punches
print(df.head())
# df.to_csv("attendance_logs.csv") # One-line export!
```

---

## 🔌 Advanced Protocols Supported

The wrapper natively understands completely different networking protocols under the exact same class commands!

### Accessing REST APIs (Hikvision, Suprema)
Many modern IP access control panels require complex HTTP Digest Auth and Token sessions. We map that directly:
```python
# Hikvision uses ISAPI JSON structures under the hood
hik_device = BiometricDevice(brand="hikvision", ip="192.168.1.100", api_key="admin_password123!")
hik_device.connect()

attendance_df = hik_device.get_attendance(as_dataframe=True)
```

### Accessing C-SDK DLLs (Nitgen, IDEMIA)
Requires physical `.dll` loading? We use `ctypes.WinDLL` to bind memory safely without Segment Faulting your Python instance.
```python
# Natively looks for C:\Windows\System32\NBioBSP.dll or SecuAPI.dll
sdk_device = BiometricDevice(brand="nitgen", ip="192.168.1.50")
```

---

## 💾 Offline USB Extraction
If a network cable breaks, staff pull the data via Pen Drive. `biometric-fetch` parses raw machine outputs natively:
```python
from biometric_fetch import usb

# Point it to your USB folder. It automatically hunts for .csv and .dat logs!
usb_logs = usb.read_usb("D:/Biometric_Exports", as_dataframe=True)
print(usb_logs)
```

---

## Enterprise Ready (Zero-Crash Guarantee)
This library is built for stable deployment in HR environments.
- **Fail-Safe**: If a device IP unexpectedly goes offline, your application won't suffer a stack-trace crash. The library safely catches the timeout and returns a standard Empty DataFrame!
- **Semantic Logging**: No messy `print()` statements. Customize the silent `logging` module so you can record device drops behind the scenes.

## 🤝 Supported Brands Roadmap
| Protocol Architecture | Tested Brands |
| :--- | :--- |
| **TCP/IP (pyzk wrapper)** | ZKTeco, eSSL, SecureEye, Realtime, BioMax, FingerTec |
| **HTTP/REST APIs** | Hikvision (ISAPI), Suprema (BioStar), Matrix, HID, Anviz |
| **C/C++ SDK Bindings** | IDEMIA, Nitgen, Fujitsu, Cogent |

---
**License**: MIT 
**Authors**: Rishabh & Shreya
