python-hl7(1)

1PYTHON-HL7(1)                     python-hl7                     PYTHON-HL7(1)
2
3
4

NAME

6       python-hl7 - python-hl7 Documentation
7
8       python-hl7  is  a simple library for parsing messages of Health Level 7
9       (HL7) version 2.x into Python objects.
10
11       HL7 is a communication protocol and  message  format  for  health  care
12       data.  It is the de-facto standard for transmitting data between clini‐
13       cal information systems and between clinical devices.  The version  2.x
14       series, which is often is a pipe delimited format is currently the most
15       widely accepted version of HL7 (version 3.0 is an XML-based format).
16
17       python-hl7 currently only parses HL7 version 2.x messages into an  easy
18       to  access  data  structure.  The  current implementation does not com‐
19       pletely follow the HL7 specification, but is good enough to  parse  the
20       most  commonly  seen HL7 messages. The library could potentially evolve
21       into being fully complainant with the spec.  The library could  eventu‐
22       ally also contain the ability to create HL7 v2.x messages.
23
24       python-hl7  parses  HL7 into a series of wrapped hl7.Container objects.
25       The there are specific subclasses of  hl7.Container  depending  on  the
26       part of the HL7 message. The hl7.Container message itself is a subclass
27       of a Python list, thus we can easily  access  the  HL7  message  as  an
28       n-dimensional  list.  Specifically, the subclasses of hl7.Container, in
29       order, are hl7.Message, hl7.Segment, and hl7.Field.   Eventually  addi‐
30       tional containers will be added to fully support the HL7 specification.
31

USAGE

33       As an example, let's create a HL7 message:
34
35       >>> message = 'MSH|^~\&|GHH LAB|ELAB-3|GHH OE|BLDG4|200202150930||ORU^R01|CNTRL-3456|P|2.4\r'
36       >>> message += 'PID|||555-44-4444||EVERYWOMAN^EVE^E^^^^L|JONES|196203520|F|||153 FERNWOOD DR.^^STATESVILLE^OH^35292||(206)3345232|(206)752-121||||AC555444444||67-A4335^OH^20030520\r'
37       >>> message += 'OBR|1|845439^GHH OE|1045813^GHH LAB|1554-5^GLUCOSE|||200202150730||||||||555-55-5555^PRIMARY^PATRICIA P^^^^MD^^LEVEL SEVEN HEALTHCARE, INC.|||||||||F||||||444-44-4444^HIPPOCRATES^HOWARD H^^^^MD\r'
38       >>> message += 'OBX|1|SN|1554-5^GLUCOSE^POST 12H CFST:MCNC:PT:SER/PLAS:QN||^182|mg/dl|70_105|H|||F'
39
40       We call the hl7.parse() command with string message:
41
42       >>> import hl7
43       >>> h = hl7.parse(message)
44
45       We get a hl7.Message object, wrapping a series of hl7.Segment objects:
46
47       >>> type(h)
48       <class 'hl7.Message'>
49
50       We can always get the HL7 message back:
51
52       >>> unicode(h) == message
53       True
54
55       Interestingly, hl7.Message can be accessed as a list:
56
57       >>> isinstance(h, list)
58       True
59
60       There were 4 segments (MSH, PID, OBR, OBX):
61
62       >>> len(h)
63       4
64
65       We can extract the hl7.Segment from the hl7.Message instance:
66
67       >>> h[3]
68       [[u'OBX'], [u'1'], [u'SN'], [u'1554-5', u'GLUCOSE', u'POST 12H CFST:MCNC:PT:SER/PLAS:QN'], [u''], [u'', u'182'], [u'mg/dl'], [u'70_105'], [u'H'], [u''], [u''], [u'F']]
69
70       We  can  easily reconstitute this segment as HL7, using the appropriate
71       separators:
72
73       >>> unicode(h[3])
74       u'OBX|1|SN|1554-5^GLUCOSE^POST 12H CFST:MCNC:PT:SER/PLAS:QN||^182|mg/dl|70_105|H|||F'
75
76       We can extract individual elements of the message:
77
78       >>> h[3][3][1]
79       u'GLUCOSE'
80       >>> h[3][5][1]
81       u'182'
82
83       We can look up segments by the segment identifier, either via  hl7.Mes‐
84       sage.segments() or via the traditional dictionary syntax:
85
86       >>> h.segments('OBX')[0][3][1]
87       u'GLUCOSE'
88       >>> h['OBX'][0][3][1]
89       u'GLUCOSE'
90
91       Since many many types of segments only have a single instance in a mes‐
92       sage (e.g. PID or MSH), hl7.Message.segment()  provides  a  convienance
93       wrapper  around  hl7.Message.segments() that returns the first matching
94       hl7.Segment:
95
96       >>> h.segment('PID')[3][0]
97       u'555-44-4444'
98

100   python-hl7 API
101       hl7.parse(line)
102
103              Returns a instance of the hl7.Message that allows indexed access
104              to the data elements.
105
106       Note   HL7  usually  contains  only  ASCII, but can use other character
107              sets  (HL7  Standards  Document,  Section   1.7.1).   Therefore,
108              python-hl7  works  on  Python  unicode strings. hl7.parse() will
109              accept ASCII-only strings and automatically  convert  them  into
110              unicode.  However, if the message contains non-ASCII characters,
111              it is the responsibility of the caller of hl7.parse()  to  prop‐
112              erly convert the message string to unicode first.
113
114       >>> h = hl7.parse(message)
115
116              Return type
117                     hl7.Message
118
119       hl7.ishl7(line)
120
121              Determines  whether  a  line  looks  like  an HL7 message.  This
122              method only does a cursory check and does not fully validate the
123              message.
124
125              Return type
126                     bool
127
128   Data Types
129       class hl7.Container(separator, sequence=[])
130
131              Abstract root class for the parts of the HL7 message.
132
133              __unicode__()
134
135                     Join  a  the child containers into a single string, sepa‐
136                     rated by the self.separator.   This  method  acts  recur‐
137                     sively,  calling the children's __unicode__ method.  Thus
138                     unicode()  is  the  approriate  method  for  turning  the
139                     python-hl7 representation of HL7 into a standard string.
140
141                     >>> unicode(h) == message
142                     True
143
144       class hl7.Message(separator, sequence=[])
145
146              Representation of an HL7 message. It contains a list of hl7.Seg‐
147              ment instances.
148
149              segments(segment_id)
150
151                     Returns the requested segments from  the  parsed  message
152                     that  are  identified  by  the segment_id (e.g. OBR, MSH,
153                     ORC, OBX).
154
155                     >>> h.segments('OBX')
156                     [[[u'OBX'], [u'1'], ...]]
157
158                     Return type
159                            list of hl7.Segment
160
161              segment(segment_id)
162
163                     Gets the first  segment  with  the  segment_id  from  the
164                     parsed message.
165
166                     >>> h.segment('PID')
167                     [[u'PID'], ...]
168
169                     Return type
170                            hl7.Segment
171
172              __getitem__(key)
173
174                     Index or segment-based lookup.
175
176                     If  key  is  an  integer,  __getitem__  acts list a list,
177                     returning the hl7.Segment held at that index:
178
179                     >>> h[1]
180                     [[u'PID'], ...]
181
182                     If the key is a string, __getitem__ acts like  a  dictio‐
183                     nary,  returning  all  segments  whose  segment_id is key
184                     (alias of hl7.Message.segments()).
185
186                     >>> h['OBX']
187                     [[[u'OBX'], [u'1'], ...]]
188
189                     Return type
190                            hl7.Segment or list of hl7.Segment
191
192       class hl7.Segment(separator, sequence=[])
193
194              Second level of an HL7 message, which represents an HL7 Segment.
195              Traditionally  this is a line of a message that ends with a car‐
196              riage return and is separated by pipes. It contains  a  list  of
197              hl7.Field instances.
198
199       class hl7.Field(separator, sequence=[])
200
201              Third  level of an HL7 message, that traditionally is surrounded
202              by pipes and separated by carets. It contains a list of strings.
203
204   Contributing
205       The         source         code         is         available         at
206       http://github.com/johnpaulett/python-hl7
207
208       The test suite is located in tests/ and can be run via setup.py:
209
210       $ python setup.py test
211       ...
212       ----------------------------------------------------------------------
213       Ran 17 tests in 0.005s
214
215       OK
216
217       Make sure the documentation is still valid:
218
219       $ pushd docs && make html && make doctest && popd
220       ...
221       Doctest summary
222       ===============
223          23 tests
224           0 failures in tests
225           0 failures in setup code
226       ...
227
228   Change Log
229   v0.2.0 - 2011-06-12
230       · Converted hl7.segment and hl7.segments into methods on hl7.Message.
231
232       · Support  dict-syntax  for  getting Segments from a Message (e.g. mes‐
233         sage['OBX'])
234
235       · Use unicode throughout python-hl7 since the HL7 spec allows non-ASCII
236         characters.   It  is  up  to  the  caller  of  hl7.parse() to convert
237         non-ASCII messages into unicode.
238
239       · Refactored from single hl7.py file into the hl7 module.
240
241       · Added Sphinx documentation.  Moved project to github.
242
243   v0.1.1 - 2009-06-27
244       · Apply Python 3 trove classifier
245
246   v0.1.0 - 2009-03-13
247       · Support message-defined separation characters
248
249       · Message, Segment, Field classes
250
251   v0.0.3 - 2009-01-09
252       · Initial release
253
254   License
255       Copyright (C) 2009-2011 John Paulett (john -at- paulett.org)
256       All rights reserved.
257
258       Redistribution and use in source and binary forms, with or without
259       modification, are permitted provided that the following conditions
260       are met:
261
262        1. Redistributions of source code must retain the above copyright
263           notice, this list of conditions and the following disclaimer.
264        2. Redistributions in binary form must reproduce the above copyright
265           notice, this list of conditions and the following disclaimer in
266           the documentation and/or other materials provided with the
267           distribution.
268        3. The name of the author may not be used to endorse or promote
269           products derived from this software without specific prior
270           written permission.
271
272       THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
273       OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
274       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
275       ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
276       DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
277       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
278       GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
279       INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
280       IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
281       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
282       IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
283
284

LINKS

286       · Documentation: http://python-hl7.readthedocs.org
287
288       · Source Code: http://github.com/johnpaulett/python-hl7
289
290       · PyPi: http://pypi.python.org/pypi/hl7
291
292       HL7 References:
293
294       · Health Level 7 - Wikipedia
295
296       · nule.org's Introduction to HL7
297
298       · hl7.org
299
300       · OpenMRS's HL7 documentation
301

AUTHOR

303       John Paulett
304

COPYRIGHT

306       2011, John Paulett
307
308
309
310
3110.2.0                            July 25, 2011                   PYTHON-HL7(1)

NAME

USAGE

CONTENTS

LINKS

AUTHOR

COPYRIGHT