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. because lib7.Composer derives from lib7.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 exist
lib7.Composer.write_file(): write the created or modified file
lib7.Message: all the other methods inherited from Message
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: Node

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: Node

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 and Composer 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 or Composer 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: Meta

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: Message

parent¶

get the parent node

Returns the parent Node or Message.

Getter: depending on parent type, usually Node is returned. however the top most parent is always Message
Return type: Node or Message

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: 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 address
lib7.Message.meta(): hl7 metadata such as separators, see: lib7.Meta
lib7.Message.children: a list of segments in this Message
lib7.Node.data: the nodes data if it has no children ( num_children is 0)
lib7.Node.addr: string representation of the current node’s address
lib7.Node.parent: the parent Node, None if there is no parent
lib7.Node.children: a list of child ndoes
lib7.Node.next_sibling: the next sibling of this ndoe
lib7.Node.previous_sibling: the last sibling of this node
lib7.Node.first_child: gets the first child Node
lib7.Node.last_child: gets the last child Node
lib7.Node.child_at(): get a specific child at position N
lib7.Node.num_children: how many child ndoes are there ?
lib7.Node.num_siblings: how many siblings are there ?
lib7.Node.type: returns the type lib7.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: Node

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: Node

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 and Composer 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 or Composer 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: Meta

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: Message

parent¶

get the parent node

Returns the parent Node or Message.

Getter: depending on parent type, usually Node is returned. however the top most parent is always Message
Return type: Node or Message

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: 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 in Message.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: MetaSeparator

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: Node

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: Node

first_sibling¶

Get a reference to the first sibling of this Node

Getter: returns first sibling
Return type: Node

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: Node

last_sibling¶

Get a reference to the last sibling of this Node

Getter: returns last sibling
Return type: Node

next_sibling¶

Get a reference to the next sibling node (to the right)

Getter: returns sibling or raises IndexError
Return type: Node

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

Returns the parent Node or Message.

Getter: depending on parent type, usually Node is returned. however the top most parent is always Message
Return type: Node or Message

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: Node

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: 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.

API Documentation¶

Indices and tables¶

lib7

Navigation

Related Topics