biip.gtin

Support for Global Trade Item Number (GTIN).

The biip.gtin module contains Biip’s support for parsing GTIN formats.

A GTIN is a number that uniquely identifies a trade item.

This class can interpet the following GTIN formats:

GTIN-8, found in EAN-8 barcodes.
GTIN-12, found in UPC-A and UPC-E barcodes.
GTIN-13, found in EAN-13 barcodes.
GTIN-14, found in ITF-14 barcodes, as well as a data field in GS1 barcodes.

If you only want to parse GTINs, you can import the GTIN parser directly instead of using biip.parse().

>>> from biip.gtin import Gtin

If parsing succeeds, it returns a Gtin object.

>>> gtin = Gtin.parse("7032069804988")
>>> gtin
Gtin(value='7032069804988', format=GtinFormat.GTIN_13,
prefix=GS1Prefix(value='703', usage='GS1 Norway'),
company_prefix=GS1CompanyPrefix(value='703206'), payload='703206980498',
check_digit=8, packaging_level=None)

A GTIN can be converted to any other GTIN format, as long as the target format is longer.

>>> gtin.as_gtin_14()
'07032069804988'

As all GTINs can be converted to GTIN-14, it is the recommended format to use when storing or comparing GTINs. For example, when looking up a product associated with a GTIN, the GTIN should first be expanded to a GTIN-14 before using it to query the product catalog.

class biip.gtin.Gtin(value, format, prefix, company_prefix, payload, check_digit, packaging_level=None)

Data class containing a GTIN.

value: str

Raw unprocessed value.

May include leading zeros.

format: GtinFormat

GTIN format, either GTIN-8, GTIN-12, GTIN-13, or GTIN-14.

Classification is done after stripping leading zeros.

prefix: Optional[GS1Prefix]: The GS1 Prefix, indicating what GS1 country organization that assigned code range.

company_prefix: Optional[GS1CompanyPrefix]: The GS1 Company Prefix, identifying the company that issued the GTIN.

payload: str: The actual payload, including packaging level if any, company prefix, and item reference. Excludes the check digit.

check_digit: int: Check digit used to check if the GTIN as a whole is valid.

packaging_level: Optional[int] = None

Packaging level is the first digit in GTIN-14 codes.

This digit is used for wholesale shipments, e.g. the GTIN-14 product identifier in GS1-128 barcodes, but not in the GTIN-13 barcodes used for retail products.

classmethod parse(value, *, rcn_region=None, rcn_verify_variable_measure=True)

Parse the given value into a Gtin object.

Both GTIN-8, GTIN-12, GTIN-13, and GTIN-14 are supported.

Parameters:

value (str) – The value to parse.
rcn_region (Union[RcnRegion, str, None]) – 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:

Gtin

Returns:

GTIN data structure with the successfully extracted data. The checksum is guaranteed to be valid if a GTIN object is returned.

Raises:

ParseError – If the parsing fails.

as_gtin_8()

Format as a GTIN-8.

Return type:: str

as_gtin_12()

Format as a GTIN-12.

Return type:: str

as_gtin_13()

Format as a GTIN-13.

Return type:: str

as_gtin_14()

Format as a GTIN-14.

Return type:: str

without_variable_measure()

Create a new GTIN where the variable measure is zeroed out.

This method is a no-op for proper GTINs. For RCNs, see the method on the Rcn subclass.

Return type:: Gtin
Returns:: A GTIN instance with zeros in the variable measure places.
Raises:: EncodeError – If the rules for variable measures in the region are unknown.

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

Enum of GTIN formats.

GTIN_8 = 8: GTIN-8

GTIN_12 = 12: GTIN-12

GTIN_13 = 13: GTIN-13

GTIN_14 = 14: GTIN-14

property length: int: Length of a GTIN of the given format.

class biip.gtin.Rcn(value, format, prefix, company_prefix, payload, check_digit, packaging_level=None, usage=None, region=None, weight=None, count=None, price=None, money=None)

Restricted Circulation Number (RCN) is a subset of GTIN.

Both RCN-8, RCN-12, and RCN-13 are supported. There is no 14 digit version of RCN.

RCN-12 with prefix 2 and RCN-13 with prefix 02 or 20-29 have the same semantics across a geographic region, defined by the local GS1 Member Organization.

RCN-8 with prefix 0 or 2, RCN-12 with prefix 4, and RCN-13 with prefix 04 or 40-49 have semantics that are only defined within a single company.

Use biip.gtin.Gtin.parse() to parse potential RCNs. This subclass is returned if the GS1 Prefix signifies that the value is an RCN.

References

GS1 General Specifications, section 2.1.11-2.1.12

usage: Optional[RcnUsage] = None: Where the RCN can be circulated, in a geographical region or within a company.

region: Optional[RcnRegion] = None: The geographical region whose rules are used to interpret the contents of the RCN.

weight: Optional[Decimal] = None: A variable weight value extracted from the GTIN.

count: Optional[int] = None: A variable count extracted from the GTIN.

price: Optional[Decimal] = None: A variable weight price extracted from the GTIN.

money: Optional['moneyed.Money'] = None: A Money value created from the variable weight price. Only set if py-moneyed is installed and the currency is known.

without_variable_measure()

Create a new RCN where the variable measure is zeroed out.

This provides us with a number which still includes the item reference, but does not vary with weight/price, and can thus be used to lookup the relevant trade item in a database or similar.

This has no effect on RCNs intended for use within a company, as the semantics of those numbers vary from company to company.

Return type:: Gtin
Returns:: A RCN instance with zeros in the variable measure places.
Raises:: EncodeError – If the rules for variable measures in the region are unknown.

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

Enum of RCN usage restrictions.

GEOGRAPHICAL = 'geo': Usage of RCN restricted to geopgraphical area.

COMPANY = 'company': Usage of RCN restricted to internally in a company.

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

Enum of geographical regions with custom RCN rules.

The value of the enum is the lowercase ISO 3166-1 Alpha-2 code.

DENMARK = 'dk': Denmark

ESTONIA = 'ee': Estonia

FINLAND = 'fi': Finland

GERMANY = 'de': Germany

GREAT_BRITAIN = 'gb': Great Britain

LATVIA = 'lv': Latvia

LITHUANIA = 'lt': Lithuania

NORWAY = 'no': Norway

SWEDEN = 'se': Sweden

get_currency_code()

Get the ISO-4217 currency code for the region.

Return type:: Optional[str]