ai-zkt 0.1.2

Python SDK for integrating with ZKTeco biometric devices (TCP/IP support)

ai-zkt

Python SDK for integrating with ZKTeco biometric devices via TCP/IP.

Features

• Device Communication: Connect to ZKTeco devices via TCP/IP
• Data Import: Import attendance data from Excel, CSV files, or directly from devices
• Data Processing: Built-in deduplication and aggregation capabilities
• Flexible Parsing: Support for various date/time formats and column structures
• Error Handling: Comprehensive exception handling for robust op``````erations
• Utilities: Date/time utilities and helper functions
• Clean API: Simple and intuitive interface for common operations

Installation

Standard Installation

pip install ai-zkt

Quick Start

Excel Upload Function - Step by Step Guide

The Excel upload function supports three different Excel formats for attendance data. Follow these steps to import your Excel file:

Step 1: Prepare Your Excel File

Ensure your Excel file matches one of these supported formats:

Format 1: User ID, Verify Mode, In/Out, Date, Time

User ID | Verify Mode | In/Out   | Date       | Time
101     | 0           | Check In | 2026-04-15 | 08:55:12
101     | 0           | Check Out| 2026-04-15 | 17:02:30

Format 2: User ID, DateTime, Status

User ID | DateTime           | Status
101     | 2026-04-15 08:55:12| Check In
101     | 2026-04-15 17:02:30| Check Out

Format 3: Emp Code, Name, Date, Check In, Check Out, Work Time

Emp Code | Name   | Date       | Check In | Check Out | Work Time
101      | Ahmed  | 2026-04-15 | 08:55    | 17:02    | 08:07
102      | Mohamed| 2026-04-15 | 09:15    | 18:30    | 09:15

Step 2: Use the ImportService

from ai_zkt import ImportService

# Create import service instance
service = ImportService()

# Import Excel file
logs = service.import_from_excel("your_attendance_file.xlsx")

# Get summary statistics
summary = service.get_import_summary(logs)
print(f"Total records: {summary['total_records']}")
print(f"Unique users: {summary['unique_users']}")

Step 3: Process the Imported Data

# Remove duplicates if needed
clean_logs = service.deduplicate_logs(logs)

# Export to different format if needed
service.export_to_excel(clean_logs, "cleaned_attendance.xlsx")
service.export_to_csv(clean_logs, "cleaned_attendance.csv")

# Aggregate data for reporting
aggregated = service.aggregate_logs(clean_logs, group_by="user_id")

Step 4: Command Line Usage

You can also use the main script directly:

python main.py your_attendance_file.xlsx

Step 5: Error Handling

from ai_zkt import ZKTecoError, DataError, ParseError

try:
    logs = service.import_from_excel("attendance.xlsx")
except ParseError as e:
    print(f"Excel parsing failed: {e}")
except DataError as e:
    print(f"Data processing failed: {e}")
except ZKTecoError as e:
    print(f"General error: {e}")

Supported Column Variations

The system automatically recognizes these column name variations:

• User ID: User ID, UserID, Employee ID, Emp ID, Emp Code
• Date/Time: Date, Time, DateTime, Date/Time, Timestamp
• Status: Status, Check Type, Type, In/Out
• Check Times: Check In, Check Out, Check-In, Check-Out

Date Format Support

The system automatically handles different date formats:

• YYYY-MM-DD HH:MM:SS (e.g., 2026-04-15 08:55:12)
• DD/MM/YYYY HH:MM (e.g., 15/04/2026 08:55)
• MM/DD/YYYY HH:MM (e.g., 04/15/2026 08:55)
• And many more variations

``

Basic Device Connection

from ai_zkt import ZKTecoDevice

# Connect to a ZKTeco device
device = ZKTecoDevice("192.168.1.100")

try:
    device.connect()
    
    # Get attendance logs
    logs = device.get_attendance_logs()
    print(f"Fetched {len(logs)} attendance records")
    
    # Get device information
    info = device.get_device_info()
    print(f"Device: {info['model']} v{info['firmware_version']}")
    
finally:
    device.disconnect()

Using Context Manager

from ai_zkt import ZKTecoDevice

# Automatic connection management
with ZKTecoDevice("192.168.1.100") as device:
    logs = device.get_attendance_logs()
    for log in logs:
        print(f"User {log.user_id}: {log.timestamp} - {log.status}")

Import Service

from ai_zkt import ImportService

service = ImportService()

# Import from Excel file
logs = service.import_from_excel("attendance_data.xlsx")

# Import from CSV file
logs = service.import_from_csv("attendance_data.csv")

# Import directly from device
logs = service.import_from_device("192.168.1.100")

# Remove duplicates
clean_logs = service.deduplicate_logs(logs)

# Get summary statistics
summary = service.get_import_summary(clean_logs)
print(f"Total records: {summary['total_records']}")
print(f"Unique users: {summary['unique_users']}")

API Reference

ZKTecoDevice

Main class for communicating with ZKTeco devices.

class ZKTecoDevice:
    def __init__(self, host: str, port: int = None, **kwargs)
    def connect(self) -> bool
    def disconnect(self)
    def is_connected(self) -> bool
    def get_attendance_logs(self) -> List[AttendanceLog]
    def get_device_info(self) -> Dict[str, Any]

ImportService

Service for importing and processing attendance data.

class ImportService:
    def import_from_excel(self, file_path: str, **kwargs) -> List[AttendanceLog]
    def import_from_csv(self, file_path: str, **kwargs) -> List[AttendanceLog]
    def import_from_device(self, device_host: str, device_port: int = None) -> List[AttendanceLog]
    def deduplicate_logs(self, logs: List[AttendanceLog]) -> List[AttendanceLog]
    def aggregate_logs(self, logs: List[AttendanceLog], **kwargs) -> Dict[str, Any]
    def export_to_excel(self, logs: List[AttendanceLog], output_path: str, **kwargs)
    def export_to_csv(self, logs: List[AttendanceLog], output_path: str, **kwargs)
    def get_import_summary(self, logs: List[AttendanceLog]) -> Dict[str, Any]

Configuration

Default Settings

The library uses sensible defaults for device communication:

from ai_zkt.config import get_zkteco_config

config = get_zkteco_config()
print(config)
# {
#     "timeout": 30,
#     "port": 4370,
#     "retries": 3,
#     "retry_delay": 1,
#     "encoding": "utf-8"
# }

Error Handling

The library provides specific exceptions for different error scenarios:

from ai_zkt import ZKTecoError, ConnectionError, DataError, ParseError

try:
    logs = service.import_from_excel("data.xlsx")
except ConnectionError as e:
    print(f"Connection failed: {e}")
except ParseError as e:
    print(f"Data parsing failed: {e}")
except DataError as e:
    print(f"Data processing failed: {e}")
except ZKTecoError as e:
    print(f"General ZKTeco error: {e}")

Development

Setup Development Environment

git clone https://github.com/ahmadibrahim/ai-zkt.git
cd ai-zkt
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Running Tests

pytest

License

This project is licensed under the MIT License.

Changelog

Version 0.1.1

• Initial release
• Basic ZKTeco device communication
• Excel/CSV data import
• Data processing and aggregation
• Comprehensive error handling
• Date/time utilities