biip.gs1

Support for barcode data with GS1 element strings.

The biip.gs1 module contains Biip’s support for parsing data consisting of GS1 Element Strings. Each Element String is identified by a GS1 Application Identifier (AI) prefix.

Data of this format is found in the following types of barcodes:

  • GS1-128

  • GS1 DataBar

  • GS1 DataMatrix

  • GS1 QR Code

If you only want to parse GS1 Messages, you can import the GS1 Message parser directly instead of using biip.parse().

>>> from biip.gs1 import GS1Message

If the parsing succeeds, it returns a GS1Message object.

>>> msg = GS1Message.parse("010703206980498815210526100329")

The has a raw value as well as an HRI, short for “human readable interpretation”. The HRI is the text usually printed below or next to the barcode.

>>> msg.value
'010703206980498815210526100329'
>>> msg.as_hri()
'(01)07032069804988(15)210526(10)0329'

A message can contain multiple element strings.

>>> len(msg.element_strings)
3

In this example, the first element string is a GTIN.

>>> msg.element_strings[0]
GS1ElementString(ai=GS1ApplicationIdentifier(ai='01', description='Global
Trade Item Number (GTIN)', data_title='GTIN', fnc1_required=False,
format='N2+N14'), value='07032069804988',
pattern_groups=['07032069804988'], gtin=Gtin(value='07032069804988',
format=GtinFormat.GTIN_13, prefix=GS1Prefix(value='703', usage='GS1
Norway'), payload='703206980498', check_digit=8, packaging_level=None),
sscc=None, date=None, decimal=None, money=None)

The message object has get() and filter() methods to lookup element strings either by the Application Identifier’s “data title” or its AI number.

>>> msg.get(data_title='BEST BY')
GS1ElementString(ai=GS1ApplicationIdentifier(ai='15', description='Best
before date (YYMMDD)', data_title='BEST BEFORE or BEST BY',
fnc1_required=False, format='N2+N6'), value='210526',
pattern_groups=['210526'], gtin=None, sscc=None, date=datetime.date(2021, 5, 26),
decimal=None, money=None)
>>> msg.get(ai="10")
GS1ElementString(ai=GS1ApplicationIdentifier(ai='10', description='Batch
or lot number', data_title='BATCH/LOT', fnc1_required=True,
format='N2+X..20'), value='0329', pattern_groups=['0329'], gtin=None,
sscc=None, date=None, decimal=None, money=None)
class biip.gs1.GS1Message(value, element_strings)

A GS1 message is the result of a single barcode scan.

It may contain one or more GS1 Element Strings.

Example

See biip.gs1 for a usage example.

value: str

Raw unprocessed value.

element_strings: List[biip.gs1._element_strings.GS1ElementString]

List of Element Strings found in the message.

classmethod parse(value, *, rcn_region=None, separator_chars=('\\x1d'))

Parse a string from a barcode scan as a GS1 message with AIs.

Parameters
  • value (str) – The string to parse.

  • rcn_region (Optional[RcnRegion]) – The geographical region whose rules should be used to interpret Restricted Circulation Numbers (RCN). Needed to extract e.g. variable weight/price from GTIN.

  • separator_chars (Iterable[str]) – Characters used in place of the FNC1 symbol. Defaults to <GS> (ASCII value 29). If variable-length fields in the middle of the message are not terminated with a separator character, the parser might greedily consume the rest of the message.

Return type

GS1Message

Returns

A message object with one or more element strings.

Raises

ParseError – If a fixed-length field ends with a separator character.

as_hri()

Render as a human readable interpretation (HRI).

The HRI is often printed directly below barcodes.

Return type

str

Returns

A human-readable string where the AIs are wrapped in parenthesis.

filter(*, ai=None, data_title=None)

Filter Element Strings by AI or data title.

Parameters
  • ai (Union[str, GS1ApplicationIdentifier, None]) – AI instance or string to match against the start of the Element String’s AI.

  • data_title (Optional[str]) – String to find anywhere in the Element String’s AI data title.

Return type

List[GS1ElementString]

Returns

All matching Element Strings in the message.

get(*, ai=None, data_title=None)

Get Element String by AI or data title.

Parameters
  • ai (Union[str, GS1ApplicationIdentifier, None]) – AI instance or string to match against the start of the Element String’s AI.

  • data_title (Optional[str]) – String to find anywhere in the Element String’s AI data title.

Return type

Optional[GS1ElementString]

Returns

The first matching Element String in the message.

class biip.gs1.GS1ElementString(ai, value, pattern_groups, gtin=None, sscc=None, date=None, decimal=None, money=None)

GS1 Element String.

An Element String consists of a GS1 Application Identifier (AI) and its data field.

A single barcode can contain multiple Element Strings. Together these are called a “message.”

Example

>>> from biip.gs1 import GS1ElementString
>>> element_string = GS1ElementString.extract("0107032069804988")
>>> element_string
GS1ElementString(ai=GS1ApplicationIdentifier(ai='01',
description='Global Trade Item Number (GTIN)', data_title='GTIN',
fnc1_required=False, format='N2+N14'), value='07032069804988',
pattern_groups=['07032069804988'], gtin=Gtin(value='07032069804988',
format=GtinFormat.GTIN_13, prefix=GS1Prefix(value='703', usage='GS1
Norway'), payload='703206980498', check_digit=8,
packaging_level=None), sscc=None, date=None, decimal=None, money=None)
>>> element_string.as_hri()
'(01)07032069804988'
ai: biip.gs1._application_identifiers.GS1ApplicationIdentifier

The element’s Application Identifier (AI).

value: str

Raw data field of the Element String. Does not include the AI.

pattern_groups: List[str]

List of pattern groups extracted from the Element String.

gtin: Optional[biip.gtin._gtin.Gtin] = None

A GTIN created from the element string, if the AI represents a GTIN.

sscc: Optional[biip.sscc.Sscc] = None

An SSCC created from the element string, if the AI represents a SSCC.

date: Optional[datetime.date] = None

A date created from the element string, if the AI represents a date.

decimal: Optional[decimal.Decimal] = None

A decimal value created from the element string, if the AI represents a number.

money: Optional[moneyed.classes.Money] = None

A Money value created from the element string, if the AI represents a currency and an amount. Only set if py-moneyed is installed.

classmethod extract(value, *, rcn_region=None, separator_chars=('\\x1d'))

Extract the first GS1 Element String from the given value.

Parameters
  • value (str) – The string to extract an Element String from. May contain more than one Element String.

  • rcn_region (Optional[RcnRegion]) – The geographical region whose rules should be used to interpret Restricted Circulation Numbers (RCN). Needed to extract e.g. variable weight/price from GTIN.

  • separator_chars (Iterable[str]) – Characters used in place of the FNC1 symbol. Defaults to <GS> (ASCII value 29). If variable-length fields are not terminated with a separator character, the parser might greedily consume later fields.

Return type

GS1ElementString

Returns

A data class with the Element String’s parts and data extracted from it.

Raises
  • ValueError – If the separator_char isn’t exactly 1 character long.

  • ParseError – If the parsing fails.

as_hri()

Render as a human readable interpretation (HRI).

The HRI is often printed directly below the barcode.

Return type

str

Returns

A human-readable string where the AI is wrapped in parenthesis.

class biip.gs1.GS1ApplicationIdentifier(ai, description, data_title, fnc1_required, format, pattern)

GS1 Application Identifier (AI).

AIs are data field prefixes used in several types of barcodes, including GS1-128. The AI defines what semantical meaning and format of the following data field.

AIs standardize how to include e.g. product weight, expiration dates, and lot numbers in barcodes.

References

https://www.gs1.org/standards/barcodes/application-identifiers

Example

>>> from biip.gs1 import GS1ApplicationIdentifier
>>> ai = GS1ApplicationIdentifier.extract("01")
>>> ai
GS1ApplicationIdentifier(ai='01', description='Global Trade Item
Number (GTIN)', data_title='GTIN', fnc1_required=False,
format='N2+N14')
>>> ai.pattern
'^01(\\d{14})$'
ai: str

The Application Identifier (AI) itself.

description: str

Description of the AIs use.

data_title: str

Commonly used label/abbreviation for the AI.

fnc1_required: bool

Whether a FNC1 character is required after element strings of this type. This is the case for all AIs that have a variable length.

format: str

Human readable format of the AIs element string.

pattern: str

Regular expression for parsing the AIs element string.

classmethod extract(value)

Extract the GS1 Application Identifier (AI) from the given value.

Parameters

value (str) – The string to extract an AI from.

Return type

GS1ApplicationIdentifier

Returns

Metadata about the extracted AI.

Raises

ParseError – If the parsing fails.

Example

>>> from biip.gs1 import GS1ApplicationIdentifier
>>> GS1ApplicationIdentifier.extract("010703206980498815210526100329")
GS1ApplicationIdentifier(ai='01', description='Global Trade Item
Number (GTIN)', data_title='GTIN', fnc1_required=False,
format='N2+N14')
class biip.gs1.GS1Prefix(value, usage)

Prefix assigned by GS1.

Used to split the allocation space of various number schemes, e.g. GTIN, among GS1 organizations worldwide.

The GS1 Prefix does not identify the origin of a product, only where the number was assigned to a GS1 member organization.

References

https://www.gs1.org/standards/id-keys/company-prefix

Example

>>> from biip.gs1 import GS1Prefix
>>> GS1Prefix.extract("978-1-492-05374-3")
GS1Prefix(value='978', usage='Bookland (ISBN)')
value: str

The prefix itself.

usage: str

Description of who is using the prefix.

classmethod extract(value)

Extract the GS1 Prefix from the given value.

Parameters

value (str) – The string to extract a GS1 Prefix from.

Return type

GS1Prefix

Returns

Metadata about the extracted prefix.

Raises

ParseError – If the parsing fails.

class biip.gs1.GS1Symbology(value)

Enum of Symbology Identifiers used in the GS1 system.

References

GS1 General Specifications, figure 5.1.2-2. ISO/IEC 15424:2008.

EAN_13 = 'E0'

EAN-13, UPC-A, or UPC-E.

EAN_TWO_DIGIT_ADD_ON = 'E1'

Two-digit add-on symbol for EAN-13.

EAN_FIVE_DIGIT_ADD_ON = 'E2'

Five-digit add-on symbol for EAN-13.

EAN_13_WITH_ADD_ON = 'E3'

EAN-13, UPC-A, or UPC-E with add-on symbol.

EAN_8 = 'E4'

EAN-8

ITF_14 = 'I1'

ITF-14

GS1_128 = 'C1'

GS1-128

GS1_DATABAR = 'e0'

GS1 DataBar

GS1_COMPOSITE_WITH_SEPARATOR_CHAR = 'e1'

GS1 Composite. Data packet follows an encoded symbol separator character.

GS1_COMPOSITE_WITH_ESCAPE_CHAR = 'e2'

GS1 Composite. Data packet follows an escape mechanism character.

GS1_DATAMATRIX = 'd2'

GS1 DataMatrix

GS1_QR_CODE = 'Q3'

GS1 QR Code

GS1_DOTCODE = 'J1'

GS1 DotCode

classmethod with_ai_element_strings()

Symbologies that may contain AI Element Strings.

Return type

Set[GS1Symbology]

classmethod with_gtin()

Symbologies that may contain GTINs.

Return type

Set[GS1Symbology]

biip.gs1.DEFAULT_SEPARATOR_CHARS: Tuple[str] = ('\x1d',)

The default separator character is <GS>, ASCII value 29.

References

GS1 General Specifications, section 7.8.3.