API Documentation¶
- class lib7.Composer(file=None)¶
Bases:
lib7.Message
Compose HL7 files
With
lib7.Composer
you get access to writing and creating hl7 files. becauselib7.Composer
derives fromlib7.Message
, all the above methods described in `Reading HL7 Files`_ are applicable.import lib7 # open an existing file for modifying msg = lib7.compose("path/to/some/file.hl7") # will create segment: "XYZ|^&mydata\r" msg.set("XYZ(1)-1.2.3, "mydata") # now write the changed data msg.write_file("path/to/some/other.hl7") # if you do bulk editing over many files, it is a good # idea to free memory like so: del(msg) # create an empty message. msg = lib7.compose() # this message will already contain an MSH segment, always, # it's really needed # # now you can start adding stuff msg.set("PID-3(1), "patientnumber") del(msg)
See also:
lib7.Composer.set()
: set a node by address, it will be created if it doesn’t existlib7.Composer.write_file()
: write the created or modified filelib7.Message
: all the other methods inherited from Messagelib7.Node
: every child of Message is a Node
- child_at(self, int pos) → Node¶
get the Nth child at pos.
Returns None if the child does not exist.
pos starts at 0 in contrast to HL7 adressing. Example: - MSH-2 will be at pos 1 - MSH-2.1 will be at position 0
- Parameters
pos (int) – position index starting at 0 or raises IndexError
- Return type
- children¶
get a list of child nodes
This property returns a list of child nodes. If you want to check or read child often
Node.__iter__
is to be preferred.Node.__iter__ is faster than getting a full list of all child nodes when you know you might not need them all.
- Getter
get a list of all child nodes
- Return type
list Nodes
- dump(self)¶
Dump the structure to stdout.
This method is primarely used for debugging and testing.
- first_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- get(self, addr) → Node¶
get a reference to a Node by a string address
This is a conveniecne way to access Nodes in a HL7 Structure. See Understanding Addressing for details on the address syntax.
Example:
msg = lib7.read("file.hl7") msh9 = msg.get("MSH-9.1") # first FIELD in MSH-9
- Getter
returns node or raises Hl7StructureException if the Node does not exist
- Return type
- id¶
Unique node ID
Internally generated node id. This id is used to compare to nodes if they are equal. This id is managed b the C Code and is read only.
- Getter
returns id
- Return type
int
- is_root¶
checks if this is the root node
On the message level this is always true,
Message
andComposer
cannot have a parent.- Return type
Bool
- last_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- meta¶
Metadata of the HL7 message
lets you read and set all the delimiters of the message. When a hl7 file is opened by
Message
orComposer
the underlying C library is autodetecting all separators in the file.You may change these by setting different separators before writing out a file. Access delimiters trough self.meta.separator.
Example:
msg = lib7.read("file.hl7") # will return a Message object msg.meta.separator.segment # should be "\r" by default. # set to windows CRLF msg.meta.sparator.segment = "\r\n" msg.meta.sparator.crlf # is now set to `True` # indicating that we have a 2 byte segment separator
see:
MetaSeparator
for all properties in self.meta.separator- Return type
- next_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- num_children¶
number of children of this Node
If num_children is 0, then this is typically a data node. Check the data property for the content. This does not apply for node_type SEGMENT where data always contains the segment name (no matter how many children it has).
Node provides and iterator to loop over all children.
message = lib7.read(...) node = message.get("PID-9.1") for n in node: print node
see also:
Node.children
,Node.__iter__()
- Getter
get number of children
- Return type
int
- num_siblings¶
Message has no siblings
This is here for compatibility reasons with Node
- Return type
int always 0
- open_file(self, unicode file)¶
Open a HL7 file
This Method will return a Message object which is iteratable. Iterating over it will return all Segments (of type Node) which will contain sub-nodes (if there are any) which are alos iteratable.
- Parameters
file (str) – file name pointing to the hl7 file or raises IOError or Hl7ParseException
- Return type
- parent¶
get the parent node
- previous_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- set(self, unicode addr: str, unicode data: str, hl7_escape=False)¶
Set a data of a Node (create Node if it doesn’t exist)
FIXME: hl7_escape here does not make sense. Either decode while reading from file or while writing to file
- Parameters
addr (str) – HL7 Node address as String. see `Understanding Addressing`_ for details.
data (str) – Raw data to write to the node. This data will be stored as bytearray a C unsigned char *
hl7_escape (bool) – hl7 escape all characters such as (
\n
to\.b\
etc.)
- type¶
Node type
Depending on where a node is located in the hirarchy, it has a different type. See also `Understanding Addressing`_
- Getter
node type
- Return type
- write_file(self, unicode file: str)¶
Write current data to file
If you would like to use different delimiters than the original file (in case you opened one) or the defaults, use Message.meta to change them before writing the file to disk.
- Parameters
file (str) – File name pointing to the HL7 file
- class lib7.Message(file=None)¶
Bases:
lib7._AbstractNode
This is the main class for parsing hl7 files
It will contain a list of Segments (lines) of a hl7 file. It can be iterated and will return top-level nodes of type SEGMENT.
Every segment may contain 0-N children which are also iterable.
Example:
import lib7 msg = lib7.open("path/to/some/file.hl7") # check what sort of message type this is, defined in MsH-9.1 msh91 = None msh92 = None try: msh91 = msg.get("MSH-9.1") print(msh91) # should print the content of the FIELD except Hl7StructureException: print("MSH-9.1 Not found) try: msh92 = msh91.next_sibling except Hl7StructureException: print("MSH-9.2 Not found) root = msh92 while root.parent: root = root.parent # we have now found the top most node which is of type MESSAGE # This node contains N segments in children print(root.type) # prints: Type.MESSAGE print("%r" % root) # prints: <MESSAGE (children: 2)> print(root.num_children) # prints: 2 assert(root == msg) # same same but different (variable name) # every node in the structure is an iterator which will # iterate over all child nodes. # # This is the preferred way, because it is faster than first # fetching all nodes via `n.children` and then looping over them. for seg in root: print("%r" % seg) # prints: <SEGMENT MSH(1) (children: 18), MSH> # <SEGMENT PID(1) (children: 1), PID> print(seg.addr) # prints: MSH(1) # PID(1) # or you may fetch a list of child ndoes like this: children = root.children # print the segment names for c in children: print(c.data) # prints: MSH, PID, ...
See also:
lib7.Message.get()
: get a node by addresslib7.Message.meta()
: hl7 metadata such as separators, see:lib7.Meta
lib7.Message.children
: a list of segments in this Messagelib7.Node.data
: the nodes data if it has no children ( num_children is 0)lib7.Node.addr
: string representation of the current node’s addresslib7.Node.parent
: the parent Node, None if there is no parentlib7.Node.children
: a list of child ndoeslib7.Node.next_sibling
: the next sibling of this ndoelib7.Node.previous_sibling
: the last sibling of this nodelib7.Node.first_child
: gets the first child Nodelib7.Node.last_child
: gets the last child Nodelib7.Node.child_at()
: get a specific child at position Nlib7.Node.num_children
: how many child ndoes are there ?lib7.Node.num_siblings
: how many siblings are there ?lib7.Node.type
: returns the typelib7.Type
lib7.Node
: every child of Message is a Node
- child_at(self, int pos) → Node¶
get the Nth child at pos.
Returns None if the child does not exist.
pos starts at 0 in contrast to HL7 adressing. Example: - MSH-2 will be at pos 1 - MSH-2.1 will be at position 0
- Parameters
pos (int) – position index starting at 0 or raises IndexError
- Return type
- children¶
get a list of child nodes
This property returns a list of child nodes. If you want to check or read child often
Node.__iter__
is to be preferred.Node.__iter__ is faster than getting a full list of all child nodes when you know you might not need them all.
- Getter
get a list of all child nodes
- Return type
list Nodes
- dump(self)¶
Dump the structure to stdout.
This method is primarely used for debugging and testing.
- first_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- get(self, addr) → Node¶
get a reference to a Node by a string address
This is a conveniecne way to access Nodes in a HL7 Structure. See Understanding Addressing for details on the address syntax.
Example:
msg = lib7.read("file.hl7") msh9 = msg.get("MSH-9.1") # first FIELD in MSH-9
- Getter
returns node or raises Hl7StructureException if the Node does not exist
- Return type
- id¶
Unique node ID
Internally generated node id. This id is used to compare to nodes if they are equal. This id is managed b the C Code and is read only.
- Getter
returns id
- Return type
int
- is_root¶
checks if this is the root node
On the message level this is always true,
Message
andComposer
cannot have a parent.- Return type
Bool
- last_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- meta¶
Metadata of the HL7 message
lets you read and set all the delimiters of the message. When a hl7 file is opened by
Message
orComposer
the underlying C library is autodetecting all separators in the file.You may change these by setting different separators before writing out a file. Access delimiters trough self.meta.separator.
Example:
msg = lib7.read("file.hl7") # will return a Message object msg.meta.separator.segment # should be "\r" by default. # set to windows CRLF msg.meta.sparator.segment = "\r\n" msg.meta.sparator.crlf # is now set to `True` # indicating that we have a 2 byte segment separator
see:
MetaSeparator
for all properties in self.meta.separator- Return type
- next_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- num_children¶
number of children of this Node
If num_children is 0, then this is typically a data node. Check the data property for the content. This does not apply for node_type SEGMENT where data always contains the segment name (no matter how many children it has).
Node provides and iterator to loop over all children.
message = lib7.read(...) node = message.get("PID-9.1") for n in node: print node
see also:
Node.children
,Node.__iter__()
- Getter
get number of children
- Return type
int
- num_siblings¶
Message has no siblings
This is here for compatibility reasons with Node
- Return type
int always 0
- open_file(self, unicode file)¶
Open a HL7 file
This Method will return a Message object which is iteratable. Iterating over it will return all Segments (of type Node) which will contain sub-nodes (if there are any) which are alos iteratable.
- Parameters
file (str) – file name pointing to the hl7 file or raises IOError or Hl7ParseException
- Return type
- parent¶
get the parent node
- previous_sibling¶
Message has no siblings
This is here for compatibility reasons with Node
will always raise IndexError
- type¶
Node type
Depending on where a node is located in the hirarchy, it has a different type. See also `Understanding Addressing`_
- Getter
node type
- Return type
- class lib7.Meta¶
Bases:
object
Access class to the metadata stored in Message._c_meta
This object pythonifies the access to all meta properties of a
Message
object.- crlf¶
True if the segment separator is CRLF
… otherwise False. If this property is true, the Segment separator is 2 characters long (0x13 0x10), otherwise it’s 1.
When
Meta.separator.segment
is set to \r\n (CRLF) then this property is set to True, else False.- Setter
set segment separator to 1 or 2 bytes.
- Getter
inidicates if segment separator is 2 or 1 byte.
- Return type
Bool
- separator¶
Change meta data of
Message
. This class is used inMessage.meta
to pythonify the acces to the underlying meta_t C object.- Getter
returns hl7 meta separator
- Setter
sets new meta separators through the properties of
MetaSeparator
- Return type
- class lib7.MetaSeparator¶
Bases:
object
This object holds all delimiters for Meta
It should always be used together with
Meta
and is used as accessor to the C Meta object seperator properties char meta_t->sep_*.NOTE: this is a private class.
- comp¶
The component separator, typically ^
- Getter
returns the current component spearation character
- Setter
sets a new component separation character
- Return type
char
- escape¶
The escape character, typically \
- Getter
returns the current escape character
- Setter
sets a new escape character
- Return type
char
- field¶
The field separator, typically |
- Getter
returns the current field spearation character
- Setter
sets a new field separation character
- Return type
char
- rep¶
The repetition separator, typically ~
- Getter
returns the current repetition spearation character
- Setter
sets a new repetition separation character
- Return type
char
- segment¶
The segment separator, typically \r
If this value is set to 0x10 0x13 then
Meta.crlf
is set to True, otherwise it is set to False.- Getter
returns the current segment spearation character
- Setter
sets a new segment separation character
- Return type
char (2 char if CRLF)
- subcmp¶
The sub-component separator, typically &
- Getter
returns the current sub-component spearation character
- Setter
sets a new sub-component separation character
- Return type
char
- class lib7.Node¶
Bases:
lib7._AbstractNode
Node class is the python implementation for typedef struct node_t
This class provides structural access to parent/siblings and children as well as holds the actual RAW data that may be stored in a node.
Every Node can technically have childeren, however, the HL7 definition does not support children below the SUB-COMPONENT (typically delimited by &) type. Children below SUB-COMPOINENT therefore cannot be serialized and are forbidden.
- addr¶
String representation of this Ndoes address
See chapter Understanding Addressing for a detailed description how addresses work. This method is costly and should not be used exessively (for exampe for traversing).
Use the internal node structure with __iter__ or sibling attributes to traverse the structure.
This method is mainly intended to create user readable addresses for error messages and print()
- Getter
returns a string representation of the Node’s address
- Return type
String
- child_at(self, int pos) → Node¶
get the Nth child at pos.
Returns None if the child does not exist.
pos starts at 0 in contrast to HL7 adressing. Example: - MSH-2 will be at pos 1 - MSH-2.1 will be at position 0
- Parameters
pos (int) – position index starting at 0 or raises IndexError
- Return type
- children¶
get a list of child nodes
This property returns a list of child nodes. If you want to check or read child often
Node.__iter__
is to be preferred.Node.__iter__ is faster than getting a full list of all child nodes when you know you might not need them all.
- Getter
get a list of all child nodes
- Return type
list Nodes
- data¶
this property holds the raw data
every LEAF node has data (nodes without children), this property holds the raw of the node’s content.
Data will be converted to UTF-8 before it is returned.
No scaping is done when a file is parsed. This attribute may hold hl7 escaped data such as \.br\ for newlines. However, proper decoding can only be done by using the separator characters from
Message.meta
.If the node has no allocated memory in the C struct, None will be returned.
- Getter
get raw data as UTF-8
- Return type
String
- Type
unsigned char
- data_length¶
length of the data
if 0, then there is no data. otherwise it will contain the number of bytes of the raw data stored in
Node.data
including the.- Return type
int
- first_child¶
Get a reference to the first child of this Node’s children
convenience method for
node.child_at(0)
- Getter
returns first child or raises IndexError
- Return type
- first_sibling¶
Get a reference to the first sibling of this Node
- Getter
returns first sibling
- Return type
- id¶
Unique node ID
Internally generated node id. This id is used to compare to nodes if they are equal. This id is managed b the C Code and is read only.
- Getter
returns id
- Return type
int
- is_root¶
checks if this is the root node
- Getter
returns True if there is no parent False otherwise.
- Return type
bool
- last_child¶
Get a reference to the last child of this Node’s children
convenience method for
node.child_at(node.num_children-1)
- Getter
returns last child or raises IndexError
- Return type
- last_sibling¶
Get a reference to the last sibling of this Node
- Getter
returns last sibling
- Return type
- next_sibling¶
Get a reference to the next sibling node (to the right)
- Getter
returns sibling or raises IndexError
- Return type
- num_children¶
number of children of this Node
If num_children is 0, then this is typically a data node. Check the data property for the content. This does not apply for node_type SEGMENT where data always contains the segment name (no matter how many children it has).
Node provides and iterator to loop over all children.
message = lib7.read(...) node = message.get("PID-9.1") for n in node: print node
see also:
Node.children
,Node.__iter__()
- Getter
get number of children
- Return type
int
- num_siblings¶
Number of siblings on this Node hirarchy level
- Getter
returns number of siblings
- Return type
int
- parent¶
get the parent node
- pos_in_parent¶
index in the parents children list
This value is useful to directly address the N`th element after the current `Node.
For example:
# this is usually more efficient than looping # through all siblings msh3 = msg.get("MSH-3") msh5 = msh3.parent.child_at(msh3.pos_in_parent + 2)
- Getter
get index in parent’s children list
- Return type
int position in Node.parent.children array
- previous_sibling¶
Get a reference to the previous sibling node (to the left)
- Getter
returns sibling or raises IndexError
- Return type
- type¶
Node type
Depending on where a node is located in the hirarchy, it has a different type. See also `Understanding Addressing`_
- Getter
node type
- Return type
- class lib7.Type(value)¶
Bases:
enum.Enum
Node types
Every Node has a type. The type tells you at which hirarchy level the node is stored. The lwoer the value, the higher in the hirarchy.
MESSAGE is generally the root element. However, it ispossible to have detatched nodes which have no parent (this happens during creation or when the structure is not properly managed).
LEAF is a relic and is never used.
- UNKNOWN = 0¶
- MESSAGE = 1¶
- SEGMENT = 2¶
- FIELDLIST = 4¶
- FIELD = 8¶
- COMP = 16¶
- SUBCOMP = 32¶
- LEAF = 64¶
- lib7.compose(unicode file: str = None) → Composer¶
compose an empty message (file=None) or parse a hl7 file
This method returns a composer. The composer is able to manipulate a message with self.set(…).
if (file == None) then a boilerplate MSH segment is created.
See also:
lib7.Composer.set()
: set a node by address, it will be created if it doesn’t existlib7.Composer.write_file()
: write the created or modified filelib7.Message
: all the other methods inherited from Messagelib7.Node
: every child of Message is a Node
- lib7.search_file(unicode file: str, unicode search_term: str)¶
fast search of data in Nodes
NOTE: this interface is royall broken and should not yet be used. It will probably segfault.