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)

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

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.