Base datatypes

Warning

The HL7 versions can have different implementation of base datatypes; for example the ST base datatype of HL7 v2.6 is different from the v2.5 one. This module contains reference classes for all base datatypes but you should not import them directly from here. If you need an implementation for a particular version use the get_base_datatypes() function from a specific version’s module For example if you’re using version 2.4 and you need an FT base datatype do the following:

>>> from hl7apy.v2_4 import FT
>>> f = FT('some useful information')
class hl7apy.base_datatypes.BaseDataType(value, max_length=None, validation_level=None)

Generic datatype base class. It handles the value of the data type and its maximum length. It is meant to be extended and it should not be used directly

Parameters:
  • value – the value of the data type
  • max_length (int) – The maximum length of the value. Default to None
  • validation_level (int) – It must be a value from class VALIDATION_LEVEL If it is STRICT it checks that value doesn’t exceed the attr:max_length
Raise:

MaxLengthReached When the value’s length is greater than the max_length. Only if validation_level is STRICT

classname

The name of the class

to_er7(encoding_chars=None)

Encode to ER7 format


class hl7apy.base_datatypes.TextualDataType(value, max_length=32, highlights=None, validation_level=None)

Base class for textual data types. It is meant to be extended and it should not be used directly

Parameters:
  • value (str) – the value of the data type
  • max_length (int) – the max length of the value (default to 32)
  • highlights (tuple, list) – a list of ranges indicating the part of the value to be highlighted. e.g. ((0,5), (6,7)) The highlights cannot overlap, if they do an HL7Exception will be thrown when to_er7 method is called
  • validation_level (int) – It has the same meaning as in BaseDatatype
Raise:

MaxLengthReached When the value’s length is greater than max_length

Classes representing textual datatypes are:

class hl7apy.base_datatypes.ST(value, highlights=None, validation_level=None)

Class for ST datatype. It extends hl7apy.base_datatypes.TextualDatatype and the parameters are the same of the superclass

max_length is 199

class hl7apy.base_datatypes.FT(value, highlights=None, validation_level=None)

Class for FT datatype. It extends hl7apy.base_datatypes.TextualDataType and the parameters are the same of the superclass

max_length is 65536

class hl7apy.base_datatypes.ID(value, highlights=None, validation_level=None)

Class for ID datatype. It extends hl7apy.base_datatypes.TextualDataType and the parameters are the same of the superclass

max_length None

class hl7apy.base_datatypes.IS(value, highlights=None, validation_level=None)

Class for IS datatype. It extends hl7apy.base_datatypes.TextualDataType and the parameters are the same of the superclass

max_length is 20

class hl7apy.base_datatypes.TX(value, highlights=None, validation_level=None)

Class for TX datatype. It extends hl7apy.base_datatypes.TextualDataType and the parameters are the same of the superclass

max_length is 65536

class hl7apy.base_datatypes.GTS(value, highlights=None, validation_level=None)

Class for GTS datatype. It extends hl7apy.base_datatypes.TextualDataType and the parameters are the same of the superclass

max_length is 199

class hl7apy.base_datatypes.WD(value, highlights=None, validation_level=None)

Datatype class for withdraw fields. They are fields that has been withdrawn from specification and should not be used. It is implemented as a hl7apy.base_datatypes.TextualDatatype with max_length 0.

max_length is 0


class hl7apy.base_datatypes.NumericDataType(value=None, max_length=16, validation_level=None)

Base class for numeric data types. It is meant to be extended and it should not be used directly

Parameters:
  • value – the value of the data type. Default is None
  • max_length (int) – The maximum number of digit in the value. Default is 16
  • validation_level (int) – It has the same meaning as in hl7apy.base_datatypes.BaseDataType
Raise:

hl7apy.exceptions.MaxLengthReached When the value’s length is greater than max_length

Classes representing numeric datatypes are:

class hl7apy.base_datatypes.NM(value=None, validation_level=None)

Class for NM datatype. It extends hl7apy.base_datatypes.NumericDatatype and the parameters are the same of the superclass

max_length is 16.

The type of value must be decimal.Decimal or Real

Raise:ValueError raised when the value is not of one of the correct type
class hl7apy.base_datatypes.SI(value=None, validation_level=None)

Class for NM datatype. It extends NumericDatatype and the parameters are the same of the superclass

max_length is 4.

The type of value must be int or numbers.Integral

Raise:ValueError raised when the value is not of one of the correct type

class hl7apy.base_datatypes.DateTimeDataType(value=None, out_format='')

Base class for datetime data types. It is meant to be extended and it should not be used directly. Children classes should at least override the allowed_formats tuple

Parameters:
  • value – a datetime date object. Default is None
  • out_format (str) – the format that will be used converting the object to string. It must be an item of the allowed_formats tuple
Raise:

:exc:InvalidDateFormat <hl7apy.exceptions.InvalidDateFormat>` if the ``format is not in the allowed_formats member

Classes representing datetime datatypes are:

class hl7apy.base_datatypes.DT(value=None, out_format='%Y%m%d')

Class for DT base datatype. It extends DatetimeDatatype and it represents a time value with year, month and day. Parameters are the same of the superclass.

The allowed_formats tuple is ('%Y', '%Y%m', '%Y%m%d')

class hl7apy.base_datatypes.TM(value=None, out_format='%H%M%S.%f', offset='', microsec_precision=4)

Class for TM base datatype. It extends DateTimeDatatype and it represents a time value with hours, minutes, seconds and microseconds. Parameters are the same of the superclass plus offset. Since HL7 supports only four digits for microseconds, and Python datetime uses 6 digits, the wanted precision must be specified.

The allowed_formats tuple is ('%H', '%H%M', '%H%M%S', '%H%M%S.%f'). It needs also the offset parameter which represents the UTC offset

Parameters:
  • offset (str) – the UTC offset. By default it is ‘’. It must be in the form '+/-HHMM'
  • microsec_precision (int) – Number of digit of the microseconds part of the value. It must be between 1 and 4
class hl7apy.base_datatypes.DTM(value=None, out_format='%Y%m%d%H%M%S.%f', offset='', microsec_precision=4)

Class for DTM base datatype. It extends TM and it represents classes DT and DTM combined. Thus it represents year, month, day, hours, minutes, seconds and microseconds. Parameters are the same of the superclass.

The allowed_formats tuple is ('%Y', '%Y%m', '%Y%m%d', '%Y%m%d%H', '%Y%m%d%H%M', '%Y%m%d%H%M%S', '%Y%m%d%H%M%S.%f')