biip

Biip interprets the data in barcodes.

>>> import biip

An ambiguous value may be interpreted as different formats. In the following example, the value can be interpreted as either a GTIN or a GS1 Message.

>>> result = biip.parse("96385074")
>>> result.gtin
Gtin(value='96385074', format=GtinFormat.GTIN_8,
prefix=GS1Prefix(value='00009', usage='GS1 US'),
company_prefix=GS1CompanyPrefix(value='0000963'), payload='9638507',
check_digit=4, packaging_level=None)
>>> result.gs1_message
GS1Message(value='96385074',
element_strings=[GS1ElementString(ai=GS1ApplicationIdentifier(ai='96',
description='Company internal information', data_title='INTERNAL',
fnc1_required=True, format='N2+X..90'), value='385074',
pattern_groups=['385074'], gln=None, gln_error=None, gtin=None,
gtin_error=None, sscc=None, sscc_error=None, date=None, datetime=None,
decimal=None, money=None)])

In the next example, the value is only valid as a GS1 Message and the GTIN parser returns an error explaining why the value cannot be interpreted as a GTIN. If a format includes check digits, Biip always control them and fail if the check digits are incorrect.

>>> result = biip.parse("15210527")
>>> result.gtin
None
>>> result.gtin_error
"Invalid GTIN check digit for '15210527': Expected 4, got 7."
>>> result.gs1_message
GS1Message(value='15210527',
element_strings=[GS1ElementString(ai=GS1ApplicationIdentifier(ai='15',
description='Best before date (YYMMDD)', data_title='BEST BEFORE or BEST
BY', fnc1_required=False, format='N2+N6'), value='210527',
pattern_groups=['210527'], gln=None, gln_error=None, gtin=None,
gtin_error=None, sscc=None, sscc_error=None, date=datetime.date(2021, 5,
27), datetime=None, decimal=None, money=None)])

If a value cannot be interpreted as any supported format, an exception is raised with a reason from each parser.

>>> biip.parse("123")
Traceback (most recent call last):
    ...
biip._exceptions.ParseError: Failed to parse '123':
- GTIN: Failed to parse '123' as GTIN: Expected 8, 12, 13, or 14 digits, got 3.
- UPC: Failed to parse '123' as UPC: Expected 6, 7, 8, or 12 digits, got 3.
- SSCC: Failed to parse '123' as SSCC: Expected 18 digits, got 3.
- GS1: Failed to match '123' with GS1 AI (12) pattern '^12(\d{2}(?:0\d|1[0-2])(?:[0-2]\d|3[01]))$'.
biip.parse(value, *, rcn_region=None, rcn_verify_variable_measure=True, separator_chars=('\\x1d',))

Identify data format and parse data.

The current strategy is:

  1. If Symbology Identifier prefix indicates a GTIN or GS1 Message, attempt to parse and validate as that.

  2. Else, if not Symbology Identifier, attempt to parse with all parsers.

Parameters:

  • value (str) – The data to classify and 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:

ParseResult

Returns:

A data class depending upon what type of data is parsed.

Raises:

ParseError – If parsing of the data fails.

class biip.ParseResult(value, symbology_identifier=None, gtin=None, gtin_error=None, upc=None, upc_error=None, sscc=None, sscc_error=None, gs1_message=None, gs1_message_error=None)

Results from a successful barcode parsing.

value: str

The raw value. Only stripped of surrounding whitespace.

symbology_identifier: Optional[SymbologyIdentifier] = None

The Symbology Identifier, if any.

gtin: Optional[Gtin] = None

The extracted GTIN, if any. Is also set if a GS1 Message containing a GTIN was successfully parsed.

gtin_error: Optional[str] = None

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

upc: Optional[Upc] = None

The extracted UPC, if any.

upc_error: Optional[str] = None

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

sscc: Optional[Sscc] = None

The extracted SSCC, if any. Is also set if a GS1 Message containing an SSCC was successfully parsed.

sscc_error: Optional[str] = None

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

gs1_message: Optional[GS1Message] = None

The extracted GS1 Message, if any.

gs1_message_error: Optional[str] = None

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

exception biip.BiipException

Base class for all custom exceptions raised by the library.

exception biip.EncodeError

Error raised if encoding of a value fails.

exception biip.ParseError

Error raised if parsing of barcode data fails.