update documentation

This commit is contained in:
Fanani M. Ihsan 2018-12-29 08:48:32 +07:00
parent b9d4eb4f6a
commit ac5e543ee6
12 changed files with 251 additions and 153 deletions

View File

@ -18,7 +18,9 @@ import os
# If extensions (or modules to document with autodoc) are in another directory, # If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the # add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.')) DOC_DIR = os.path.dirname(__file__)
ROOT_DIR = os.path.dirname(DOC_DIR)
sys.path.insert(0, ROOT_DIR)
# -- General configuration ------------------------------------------------ # -- General configuration ------------------------------------------------

View File

@ -139,9 +139,6 @@ Technical Documentation
We open to everyone for contribute in this project. Please refer `Communication_protocol_manual_CMD.pdf <https://github.com/fananimi/pyzk/blob/master/docs/_static/Communication_protocol_manual_CMD.pdf>`_ before you starting write your code. We open to everyone for contribute in this project. Please refer `Communication_protocol_manual_CMD.pdf <https://github.com/fananimi/pyzk/blob/master/docs/_static/Communication_protocol_manual_CMD.pdf>`_ before you starting write your code.
.. toctree::
:maxdepth: 2
Indices and tables Indices and tables
################## ##################
@ -149,3 +146,4 @@ Indices and tables
* :ref:`genindex` * :ref:`genindex`
* :ref:`modindex` * :ref:`modindex`
* :ref:`search` * :ref:`search`

View File

@ -1,7 +0,0 @@
zk
==
.. toctree::
:maxdepth: 4
zk

View File

@ -1,38 +0,0 @@
zk package
==========
Submodules
----------
zk.base module
--------------
.. automodule:: zk.base
:members:
:undoc-members:
:show-inheritance:
zk.const module
---------------
.. automodule:: zk.const
:members:
:undoc-members:
:show-inheritance:
zk.user module
--------------
.. automodule:: zk.user
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: zk
:members:
:undoc-members:
:show-inheritance:

12
docs/zk_attendance.rst Normal file
View File

@ -0,0 +1,12 @@
zk attendance
=============
zk.attendance
-------------
.. automodule:: zk.attendance
:members:
:undoc-members:
:show-inheritance:

11
docs/zk_base.rst Normal file
View File

@ -0,0 +1,11 @@
zk base
=======
zk.base module
--------------
.. automodule:: zk.base
:members:
:undoc-members:
:show-inheritance:

12
docs/zk_const.rst Normal file
View File

@ -0,0 +1,12 @@
zk const
========
zk.const module
---------------
.. automodule:: zk.const
:members:
:undoc-members:
:show-inheritance:

11
docs/zk_exception.rst Normal file
View File

@ -0,0 +1,11 @@
zk exception
============
zk.exception
------------
.. automodule:: zk.exception
:members:
:undoc-members:
:show-inheritance:

12
docs/zk_finger.rst Normal file
View File

@ -0,0 +1,12 @@
zk finger
=========
zk.finger
---------
.. automodule:: zk.finger
:members:
:undoc-members:
:show-inheritance:

12
docs/zk_user.rst Normal file
View File

@ -0,0 +1,12 @@
zk user
=======
zk.user module
---------------
.. automodule:: zk.user
:members:
:undoc-members:
:show-inheritance:

View File

@ -3,4 +3,5 @@ from .base import ZK
VERSION = (0, 9) VERSION = (0, 9)
__all__ = ['ZK'] __all__ = ['ZK']

View File

@ -59,9 +59,13 @@ def make_commkey(key, session_id, ticks=50):
class ZK_helper(object): class ZK_helper(object):
""" """
helper class ZK helper class
""" """
def __init__(self, ip, port=4370): def __init__(self, ip, port=4370):
"""
Construct a new 'ZK_helper' object.
"""
self.address = (ip, port) self.address = (ip, port)
self.ip = ip self.ip = ip
self.port = port self.port = port
@ -69,6 +73,8 @@ class ZK_helper(object):
def test_ping(self): def test_ping(self):
""" """
Returns True if host responds to a ping request Returns True if host responds to a ping request
:return: bool
""" """
import subprocess, platform import subprocess, platform
# Ping parameters as function of OS # Ping parameters as function of OS
@ -82,6 +88,10 @@ class ZK_helper(object):
shell=need_sh) == 0 shell=need_sh) == 0
def test_tcp(self): def test_tcp(self):
"""
test TCP connection
"""
self.client = socket(AF_INET, SOCK_STREAM) self.client = socket(AF_INET, SOCK_STREAM)
self.client.settimeout(10) self.client.settimeout(10)
res = self.client.connect_ex(self.address) res = self.client.connect_ex(self.address)
@ -89,6 +99,9 @@ class ZK_helper(object):
return res return res
def test_udp(self): def test_udp(self):
"""
test UDP connection
"""
self.client = socket(AF_INET, SOCK_DGRAM) self.client = socket(AF_INET, SOCK_DGRAM)
self.client.settimeout(10) self.client.settimeout(10)
@ -99,7 +112,16 @@ class ZK(object):
""" """
def __init__(self, ip, port=4370, timeout=60, password=0, force_udp=False, ommit_ping=False, verbose=False, encoding='UTF-8'): def __init__(self, ip, port=4370, timeout=60, password=0, force_udp=False, ommit_ping=False, verbose=False, encoding='UTF-8'):
""" """
initialize instance Construct a new 'ZK' object.
:param ip: machine's IP address
:param port: machine's port
:param timeout: timeout number
:param password: passint
:param force_udp: use UDP connection
:param omit_ping: check ip using ping before connect
:param verbose: showing log while run the commands
:param encoding: user encoding
""" """
User.encoding = encoding User.encoding = encoding
self.__address = (ip, port) self.__address = (ip, port)
@ -337,6 +359,8 @@ class ZK(object):
def connect(self): def connect(self):
""" """
connect to the device connect to the device
:return: bool
""" """
self.end_live_capture = False self.end_live_capture = False
if not self.ommit_ping and not self.helper.test_ping(): if not self.ommit_ping and not self.helper.test_ping():
@ -364,6 +388,8 @@ class ZK(object):
def disconnect(self): def disconnect(self):
""" """
diconnect from the connected device diconnect from the connected device
:return: bool
""" """
cmd_response = self.__send_command(const.CMD_EXIT) cmd_response = self.__send_command(const.CMD_EXIT)
if cmd_response.get('status'): if cmd_response.get('status'):
@ -377,6 +403,8 @@ class ZK(object):
def enable_device(self): def enable_device(self):
""" """
re-enable the connected device and allow user activity in device again re-enable the connected device and allow user activity in device again
:return: bool
""" """
cmd_response = self.__send_command(const.CMD_ENABLEDEVICE) cmd_response = self.__send_command(const.CMD_ENABLEDEVICE)
if cmd_response.get('status'): if cmd_response.get('status'):
@ -388,6 +416,8 @@ class ZK(object):
def disable_device(self): def disable_device(self):
""" """
disable (lock) device, to ensure no user activity in device while some process run disable (lock) device, to ensure no user activity in device while some process run
:return: bool
""" """
cmd_response = self.__send_command(const.CMD_DISABLEDEVICE) cmd_response = self.__send_command(const.CMD_DISABLEDEVICE)
if cmd_response.get('status'): if cmd_response.get('status'):
@ -398,7 +428,7 @@ class ZK(object):
def get_firmware_version(self): def get_firmware_version(self):
""" """
return the firmware version :return: the firmware version
""" """
cmd_response = self.__send_command(const.CMD_GET_VERSION,b'', 1024) cmd_response = self.__send_command(const.CMD_GET_VERSION,b'', 1024)
if cmd_response.get('status'): if cmd_response.get('status'):
@ -409,7 +439,7 @@ class ZK(object):
def get_serialnumber(self): def get_serialnumber(self):
""" """
return the serial number :return: the serial number
""" """
command = const.CMD_OPTIONS_RRQ command = const.CMD_OPTIONS_RRQ
command_string = b'~SerialNumber\x00' command_string = b'~SerialNumber\x00'
@ -424,7 +454,7 @@ class ZK(object):
def get_platform(self): def get_platform(self):
""" """
return the platform name :return: the platform name
""" """
command = const.CMD_OPTIONS_RRQ command = const.CMD_OPTIONS_RRQ
command_string = b'~Platform\x00' command_string = b'~Platform\x00'
@ -440,7 +470,7 @@ class ZK(object):
def get_mac(self): def get_mac(self):
""" """
return the mac :return: the machine's mac address
""" """
command = const.CMD_OPTIONS_RRQ command = const.CMD_OPTIONS_RRQ
command_string = b'MAC\x00' command_string = b'MAC\x00'
@ -456,6 +486,8 @@ class ZK(object):
def get_device_name(self): def get_device_name(self):
""" """
return the device name return the device name
:return: str
""" """
command = const.CMD_OPTIONS_RRQ command = const.CMD_OPTIONS_RRQ
command_string = b'~DeviceName\x00' command_string = b'~DeviceName\x00'
@ -470,7 +502,7 @@ class ZK(object):
def get_face_version(self): def get_face_version(self):
""" """
return the face version :return: the face version
""" """
command = const.CMD_OPTIONS_RRQ command = const.CMD_OPTIONS_RRQ
command_string = b'ZKFaceVersion\x00' command_string = b'ZKFaceVersion\x00'
@ -485,7 +517,7 @@ class ZK(object):
def get_fp_version(self): def get_fp_version(self):
""" """
return the fingerprint version :return: the fingerprint version
""" """
command = const.CMD_OPTIONS_RRQ command = const.CMD_OPTIONS_RRQ
command_string = b'~ZKFPVersion\x00' command_string = b'~ZKFPVersion\x00'
@ -573,6 +605,9 @@ class ZK(object):
return None return None
def get_network_params(self): def get_network_params(self):
"""
get network params
"""
ip = self.__address[0] ip = self.__address[0]
mask = b'' mask = b''
gate = b'' gate = b''
@ -589,7 +624,7 @@ class ZK(object):
def get_pin_width(self): def get_pin_width(self):
""" """
return the serial number :return: the PIN width
""" """
command = const.CMD_GET_PINWIDTH command = const.CMD_GET_PINWIDTH
command_string = b' P' command_string = b' P'
@ -604,6 +639,8 @@ class ZK(object):
def free_data(self): def free_data(self):
""" """
clear buffer clear buffer
:return: bool
""" """
command = const.CMD_FREE_DATA command = const.CMD_FREE_DATA
cmd_response = self.__send_command(command) cmd_response = self.__send_command(command)
@ -614,7 +651,7 @@ class ZK(object):
def read_sizes(self): def read_sizes(self):
""" """
read sizes read the memory ussage
""" """
command = const.CMD_GET_FREE_SIZES command = const.CMD_GET_FREE_SIZES
response_size = 1024 response_size = 1024
@ -646,9 +683,11 @@ class ZK(object):
def unlock(self, time=3): def unlock(self, time=3):
""" """
:param time: define time in seconds unlock the door\n
:return:
thanks to https://github.com/SoftwareHouseMerida/pyzk/ thanks to https://github.com/SoftwareHouseMerida/pyzk/
:param time: define delay in seconds
:return: bool
""" """
command = const.CMD_UNLOCK command = const.CMD_UNLOCK
command_string = pack("I",int(time)*10) command_string = pack("I",int(time)*10)
@ -673,6 +712,8 @@ class ZK(object):
def restart(self): def restart(self):
""" """
restart the device restart the device
:return: bool
""" """
command = const.CMD_RESTART command = const.CMD_RESTART
cmd_response = self.__send_command(command) cmd_response = self.__send_command(command)
@ -685,7 +726,7 @@ class ZK(object):
def get_time(self): def get_time(self):
""" """
get Device Time :return: the machine's time
""" """
command = const.CMD_GET_TIME command = const.CMD_GET_TIME
response_size = 1032 response_size = 1032
@ -698,6 +739,8 @@ class ZK(object):
def set_time(self, timestamp): def set_time(self, timestamp):
""" """
set Device time (pass datetime object) set Device time (pass datetime object)
:param timestamp: python datetime object
""" """
command = const.CMD_SET_TIME command = const.CMD_SET_TIME
command_string = pack(b'I', self.__encode_time(timestamp)) command_string = pack(b'I', self.__encode_time(timestamp))
@ -709,7 +752,7 @@ class ZK(object):
def poweroff(self): def poweroff(self):
""" """
shutdown the device shutdown the machine
""" """
command = const.CMD_POWEROFF command = const.CMD_POWEROFF
command_string = b'' command_string = b''
@ -723,9 +766,6 @@ class ZK(object):
raise ZKErrorResponse("can't poweroff") raise ZKErrorResponse("can't poweroff")
def refresh_data(self): def refresh_data(self):
"""
shutdown the device
"""
command = const.CMD_REFRESHDATA command = const.CMD_REFRESHDATA
cmd_response = self.__send_command(command) cmd_response = self.__send_command(command)
if cmd_response.get('status'): if cmd_response.get('status'):
@ -735,82 +775,77 @@ class ZK(object):
def test_voice(self, index=0): def test_voice(self, index=0):
""" """
play test voice: play test voice:\n
0 Thank You 0 Thank You\n
1 Incorrect Password 1 Incorrect Password\n
2 Access Denied 2 Access Denied\n
3 Invalid ID 3 Invalid ID\n
4 Please try again 4 Please try again\n
5 Re-enter ID 5 Re-enter ID\n
6 The clock is full 6 The clock is full\n
7 The clock is full 7 The clock is full\n
8 Duplicate finger 8 Duplicate finger\n
9 Accepted. Thank you 9 Accepted. Thank you\n
10 beep kuko 10 beep kuko\n
11 beep siren 11 beep siren\n
12 - 12 -\n
13 beep bell 13 beep bell\n
\t HELP! TRANSLATE TO ENGLISH THE FOLLOWING ITEMS\n
14 excedido tiempo p esta operacion\n
15 coloque su dedo de nuevo\n
16 coloque su dedo por ultima vez\n
17 ATN numero de tarjeta está repetida\n
18 proceso de registro correcto\n
19 borrado correcto\n
20 Numero de usuario / ponga la caja de ojos\n
21 ATN se ha llegado al max num usuarios\n
22 verificacion de usuarios\n
23 usuario no registrado\n
24 ATN se ha llegado al num max de registros\n
25 ATN la puerta no esta cerrada\n
26 registro de usuarios\n
27 borrado de usuarios\n
28 coloque su dedo\n
29 registre la tarjeta de administrador\n
30 0\n
31 1\n
32 2\n
33 3\n
34 4\n
35 5\n
36 6\n
37 7\n
38 8\n
39 9\n
40 PFV seleccione numero de usuario\n
41 registrar\n
42 operacion correcta\n
43 PFV acerque su tarjeta\n
43 la tarjeta ha sido registrada\n
45 error en operacion\n
46 PFV acerque tarjeta de administracion, p confirmacion\n
47 descarga de fichajes\n
48 descarga de usuarios\n
49 carga de usuarios\n
50 actualizan de firmware\n
51 ejeuctar ficheros de configuracion\n
52 confirmación de clave de acceso correcta\n
53 error en operacion de tclado\n
54 borrar todos los usuarios\n
55 restaurar terminal con configuracion por defecto\n
56 introduzca numero de usuario\n
57 teclado bloqueado\n
58 error en la gestión de la tarjeta\n
59 establezca una clave de acceso\n
60 pulse el teclado\n
61 zona de accceso invalida\n
62 acceso combinado invĺlido\n
63 verificación multiusuario\n
64 modo de verificación inválido\n
65 -\n
/* :param index: int sound index
** :return: bool
***
HELP! TRANSLATE TO ENGLISH THE FOLLOWING ITEMS
***
**
*
*/
14 excedido tiempo p esta operacion /-
15 coloque su dedo de nuevo /-
16 coloque su dedo por ultima vez /-
17 ATN numero de tarjeta está repetida /-
18 proceso de registro correcto * /-
19 borrado correcto /-
20 Numero de usuario / ponga la caja de ojos
21 ATN se ha llegado al max num usuarios /-
22 verificacion de usuarios /-
23 usuario no registrado /-
24 ATN se ha llegado al num max de registros /-
25 ATN la puerta no esta cerrada /-
26 registro de usuarios /-
27 borrado de usuarios /-
28 coloque su dedo /-
29 registre la tarjeta de administrador /-
30 0 /-
31 1 /-
32 2 /-
33 3 /-
34 4 /-
35 5 /-
36 6 /-
37 7 /-
38 8 /-
39 9 /-
40 PFV seleccione numero de usuario /-
41 registrar /-
42 operacion correcta /-
43 PFV acerque su tarjeta /-
43 la tarjeta ha sido registrada /-
45 error en operacion /-
46 PFV acerque tarjeta de administracion, p confirmacion /-
47 descarga de fichajes /-
48 descarga de usuarios /-
49 carga de usuarios /-
50 actualizan de firmware /-
51 ejeuctar ficheros de configuracion /-
52 confirmación de clave de acceso correcta /-
53 error en operacion de tclado /-
54 borrar todos los usuarios /-
55 restaurar terminal con configuracion por defecto /-
56 introduzca numero de usuario /-
57 teclado bloqueado /-
58 error en la gestión de la tarjeta /-
59 establezca una clave de acceso /-
60 pulse el teclado /-
61 zona de accceso invalida /-
62 acceso combinado invĺlido /-
63 verificación multiusuario /-
64 modo de verificación inválido /-
65 - /-
""" """
command = const.CMD_TESTVOICE command = const.CMD_TESTVOICE
command_string = pack("I", index) command_string = pack("I", index)
@ -823,6 +858,14 @@ class ZK(object):
def set_user(self, uid=None, name='', privilege=0, password='', group_id='', user_id='', card=0): def set_user(self, uid=None, name='', privilege=0, password='', group_id='', user_id='', card=0):
""" """
create or update user by uid create or update user by uid
:param name: name ot the user
:param privilege: check the const.py for reference
:param password: int password
:param group_id: group ID
:param user_id: your own user ID
:param card: card
:return: bool
""" """
command = const.CMD_USER_WRQ command = const.CMD_USER_WRQ
if uid is None: if uid is None:
@ -859,7 +902,12 @@ class ZK(object):
self.next_user_id = str(self.next_uid) self.next_user_id = str(self.next_uid)
def save_user_template(self, user, fingers=[]): def save_user_template(self, user, fingers=[]):
""" save user and template """ """
save user and template
:param user: user
:param fingers: list of finger. (The maximum index 0-9)
"""
if not isinstance(user, User): if not isinstance(user, User):
users = self.get_users() users = self.get_users()
tusers = list(filter(lambda x: x.uid==user, users)) tusers = list(filter(lambda x: x.uid==user, users))
@ -925,7 +973,10 @@ class ZK(object):
def delete_user_template(self, uid=0, temp_id=0, user_id=''): def delete_user_template(self, uid=0, temp_id=0, user_id=''):
""" """
Delete specific template Delete specific template
for tcp via user_id:
:param uid: user ID that are generated from device
:param user_id: your own user ID
:return: bool
""" """
if self.tcp and user_id: if self.tcp and user_id:
command = 134 command = 134
@ -952,6 +1003,10 @@ class ZK(object):
def delete_user(self, uid=0, user_id=''): def delete_user(self, uid=0, user_id=''):
""" """
delete specific user by uid or user_id delete specific user by uid or user_id
:param uid: user ID that are generated from device
:param user_id: your own user ID
:return: bool
""" """
if not uid: if not uid:
users = self.get_users() users = self.get_users()
@ -970,10 +1025,9 @@ class ZK(object):
def get_user_template(self, uid, temp_id=0, user_id=''): def get_user_template(self, uid, temp_id=0, user_id=''):
""" """
ZKFinger VX10.0 :param uid: user ID that are generated from device
for tcp: :param user_id: your own user ID
command = const.CMD_USERTEMP_RRQ (doesn't work always) :return: list Finger object of the selected user
command_string = pack('hb', uid, temp_id)
""" """
if not uid: if not uid:
users = self.get_users() users = self.get_users()
@ -999,7 +1053,7 @@ class ZK(object):
def get_templates(self): def get_templates(self):
""" """
return array of all fingers :return: list of Finger object
""" """
self.read_sizes() self.read_sizes()
if self.fingers == 0: if self.fingers == 0:
@ -1023,7 +1077,9 @@ class ZK(object):
return templates return templates
def get_users(self): def get_users(self):
""" return all user """ """
:return: list of User object
"""
self.read_sizes() self.read_sizes()
if self.users == 0: if self.users == 0:
self.next_uid = 1 self.next_uid = 1
@ -1083,6 +1139,8 @@ class ZK(object):
def cancel_capture(self): def cancel_capture(self):
""" """
cancel capturing finger cancel capturing finger
:return: bool
""" """
command = const.CMD_CANCELCAPTURE command = const.CMD_CANCELCAPTURE
cmd_response = self.__send_command(command) cmd_response = self.__send_command(command)
@ -1091,6 +1149,8 @@ class ZK(object):
def verify_user(self): def verify_user(self):
""" """
start verify finger mode (after capture) start verify finger mode (after capture)
:return: bool
""" """
command = const.CMD_STARTVERIFY command = const.CMD_STARTVERIFY
cmd_response = self.__send_command(command) cmd_response = self.__send_command(command)
@ -1120,7 +1180,11 @@ class ZK(object):
def enroll_user(self, uid=0, temp_id=0, user_id=''): def enroll_user(self, uid=0, temp_id=0, user_id=''):
""" """
start enroll user start enroll user
we need user_id (uid2)
:param uid: uid
:param temp_id: template id
:param user_id: user ID
:return: bool
""" """
command = const.CMD_STARTENROLL command = const.CMD_STARTENROLL
done = False done = False
@ -1209,7 +1273,9 @@ class ZK(object):
return done return done
def live_capture(self, new_timeout=10): def live_capture(self, new_timeout=10):
""" try live capture of events""" """
try live capture of events
"""
was_enabled = self.is_enabled was_enabled = self.is_enabled
users = self.get_users() users = self.get_users()
self.cancel_capture() self.cancel_capture()
@ -1277,7 +1343,9 @@ class ZK(object):
def clear_data(self): def clear_data(self):
""" """
clear all data (include: user, attendance report, finger database ) clear all data (included: user, attendance report, finger database)
:return: bool
""" """
command = const.CMD_CLEAR_DATA command = const.CMD_CLEAR_DATA
command_string = '' command_string = ''
@ -1484,6 +1552,8 @@ class ZK(object):
def get_attendance(self): def get_attendance(self):
""" """
return attendance record return attendance record
:return: List of Attendance object
""" """
self.read_sizes() self.read_sizes()
if self.records == 0: if self.records == 0:
@ -1548,6 +1618,8 @@ class ZK(object):
def clear_attendance(self): def clear_attendance(self):
""" """
clear all attendance record clear all attendance record
:return: bool
""" """
command = const.CMD_CLEAR_ATTLOG command = const.CMD_CLEAR_ATTLOG
cmd_response = self.__send_command(command) cmd_response = self.__send_command(command)