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 GS1Message 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'

HRI can also be parsed.

>>> GS1Message.parse_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'],
gln=None, gln_error=None, gtin=Gtin(value='07032069804988',
format=GtinFormat.GTIN_13, prefix=GS1Prefix(value='703', usage='GS1
Norway'), company_prefix=GS1CompanyPrefix(value='703206'),
payload='703206980498', check_digit=8, packaging_level=None),
gtin_error=None, sscc=None, sscc_error=None, date=None, datetime=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'], gln=None, gln_error=None, gtin=None,
gtin_error=None, sscc=None, sscc_error=None, date=datetime.date(2021, 5,
26), datetime=None, 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'], gln=None,
gln_error=None, gtin=None, gtin_error=None, sscc=None, sscc_error=None,
date=None, datetime=None, decimal=None, money=None)
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.

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.GS1CompanyPrefix(value)

Company prefix assigned by GS1.

The prefix assigned to a single company.

Example

>>> from biip.gs1 import GS1CompanyPrefix
>>> GS1CompanyPrefix.extract("7044610873466")
GS1CompanyPrefix(value='704461')
value: str

The company prefix itself.

classmethod extract(value)

Extract the GS1 Company Prefix from the given value.

Parameters:

value (str) – The string to extract a GS1 Company Prefix from. The value is typically a GLN, GTIN, or an SSCC.

Return type:

Optional[GS1CompanyPrefix]

Returns:

Metadata about the extracted prefix, or None if the prefix is unknown.

Raises:

ParseError – If the parsing fails.

class biip.gs1.GS1ElementString(ai, value, pattern_groups, gln=None, gln_error=None, gtin=None, gtin_error=None, sscc=None, sscc_error=None, date=None, datetime=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'], gln=None, gln_error=None,
gtin=Gtin(value='07032069804988', format=GtinFormat.GTIN_13,
prefix=GS1Prefix(value='703', usage='GS1 Norway'),
company_prefix=GS1CompanyPrefix(value='703206'), payload='703206980498',
check_digit=8, packaging_level=None), gtin_error=None, sscc=None,
sscc_error=None, date=None, datetime=None, decimal=None, money=None)
>>> element_string.as_hri()
'(01)07032069804988'
ai: 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.

gln: Optional[Gln] = None

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

gln_error: Optional[str] = None

The GLN parse error, if parsing as a GLN was attempted and failed.

gtin: Optional[Gtin] = None

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

gtin_error: Optional[str] = None

The GTIN parse error, if parsing as a GTIN was attempted and failed.

sscc: Optional[Sscc] = None

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

sscc_error: Optional[str] = None

The SSCC parse error, if parsing as an SSCC was attempted and failed.

date: Optional[date] = None

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

datetime: Optional[datetime] = None

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

decimal: Optional[Decimal] = None

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

money: Optional[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, rcn_verify_variable_measure=True, separator_chars=('\\x1d',))

Extract the first GS1 Element String from the given value.

If the element string contains a primitive data type, like a date, decimal number, or currency, it will be parsed and stored in the date, decimal, or money field respectively. If parsing of a primitive data type fails, a ParseError will be raised.

If the element string contains another supported format, like a GLN, GTIN, or SSCC, it will parsed and validated, and the result stored in the fields gln, gtin, or sscc respectively. If parsing or validation of an inner format fails, the gln_error, gtin_error, or sscc_error field will be set. No ParseError will be raised.

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.

  • rcn_verify_variable_measure (bool) – Whether to verify that the variable measure in a RCN matches its check digit, if present. Some companies use the variable measure check digit for other purposes, requiring this check to be disabled.

  • 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.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[GS1ElementString]

List of Element Strings found in the message.

classmethod parse(value, *, rcn_region=None, rcn_verify_variable_measure=True, 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.

  • rcn_verify_variable_measure (bool) – Whether to verify that the variable measure in a RCN matches its check digit, if present. Some companies use the variable measure check digit for other purposes, requiring this check to be disabled.

  • 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:
  • ValueError – If the separator_char isn’t exactly 1 character long.

  • ParseError – If the parsing fails.

classmethod parse_hri(value, *, rcn_region=None, rcn_verify_variable_measure=True)

Parse the GS1 string given in HRI (human readable interpretation) format.

Parameters:
  • value (str) – The HRI 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.

  • rcn_verify_variable_measure (bool) – Whether to verify that the variable measure in a RCN matches its check digit, if present. Some companies use the variable measure check digit for other purposes, requiring this check to be disabled.

Return type:

GS1Message

Returns:

A message object with one or more element strings.

Raises:

ParseError – If parsing of the data fails.

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

Optional[GS1Prefix]

Returns:

Metadata about the extracted prefix, or None if the prefix is unknown.

Raises:

ParseError – If the parsing fails.

class biip.gs1.GS1Symbology(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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]