1
2
3
4
5
6
7
8
9 """
10 B{Overview}
11
12 The Python API is a I{ctypes} representation of the C API. It has slightly
13 different functionality that the C API, however its usage is very similar.
14
15 Instead of function in a module it has been implimented as a class therefore
16 taking advantage of private and protected objects to give a cleaner interface.
17
18 B{Installation}
19
20 It is simple to install the Python egg::
21
22 $ sudo easy_install linklist-2.0.0.tar.gz
23
24 or
25
26 $ cd linklist-2.0.0
27 $ make egg
28 $ sudo easy_install dist/DLinklist*.egg
29
30 B{Usage}
31
32 The first thing that needs to be done is to create your C{Info} class. There
33 are two ways to do this.
34
35 1. Use the class that is already created::
36 from dlinklist import Info
37
38 Info._fields_.append(('field01', c_char * 100))
39 Info._fields_.append(('field02', c_char * 100))
40
41 2. Make a new class::
42 from ctypes import Structure
43
44 class Info(Structure):
45 _fields_ = (
46 ('field01', c_char * 100),
47 ('field02', c_char * 100),
48 )
49
50 Note: If you need to make a reference to the C{Info} class itself it will
51 need to be done as in number 1 above, even if you create your own class.
52
53 The next thing that needs to be done is to create the C{List} object. We
54 actually will not be creating a C{List} object as we did with the C{Info} class,
55 this will be done within the library itself.
56
57 Instantiate the C{DLinklist} class and create the C{List} object::
58 from dlinklist import *
59 from ctypes import sizeof
60
61 dll = DLinklist()
62 dll.create(sizeof(Info))
63
64 And you are done, just call any method in the C{DLinklist} class on the
65 C{dll} object.
66
67 @note: All the C{pFun} objects in the API need to return C{< 0}, C{0}, and
68 C{> 0} as in the Python I{cmp} function. The C{compare} method in the
69 API is very basic, so you will probably need to write your own. However,
70 use the C{compare} method in the source code as an example of how it
71 should be written.
72 """
73
74 __all__ = ('linklist',)
75
76 import pkg_resources as _res
77
78 _res.declare_namespace(__name__)
79 _RES_PATH = _res.resource_filename(__name__, "libdll.so")
80
81 from linklist import Return, SrchOrigin, SrchDir, InsertDir, Info, DLinklist
82
83
85 """
86 The base exception for all Dlinklist exceptions.
87 """
88 __DEFAULT_MESSAGE = "Error: No message given."
89
91 """
92 Call the standard Python Exception constructor and sets the default
93 message if no message provided.
94
95 @keyword msg: The message to return when raised.
96 @type msg: C{str}
97 """
98 super(BaseLinklistException, self).__init__(msg)
99 if not msg: msg = self.__DEFAULT_MESSAGE
100 self.__message = str(msg)
101
103 return self.__message
104
105
107 """
108 Raised if the C{C} link list library is not found.
109 """
110
112 """
113 Call the C{BaseLinklistException} constructor.
114
115 @param msg: The message to return when raised.
116 @type msg: C{str}
117 """
118 super(LibraryNotFoundException, self).__init__(msg)
119
120
122 """
123 Raised if the C{Return.NORMAL} value is not returned by a C{C} function.
124 """
125
127 """
128 Call the C{BaseLinklistException} constructor and sets the C{Return}
129 value. The default is C{Return.NORMAL} if no return value is provided.
130
131 @param msg: The message to return when raised.
132 @type msg: C{str}
133 @keyword retval: One of the enumerated objects from the C{Return} class.
134 @type retval: C{int}
135 """
136 super(FunctionException, self).__init__(msg)
137 self._retval = retval
138
140 """
141 Get the C{Return} value.
142
143 @return: An enumerated object from the C{Return} class.
144 @rtype: C{int}
145 """
146 return self._retval
147
149 """
150 Raised if the low level C{C} functions encounter an error.
151 """
152
154 """
155 Call the C{BaseLinklistException} constructor.
156
157 @param msg: The message to return when raised.
158 @type msg: C{str}
159 """
160 super(APIException, self).__init__(msg)
161