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("5901234123457")
>>> gtin
Gtin(value='5901234123457', format=GtinFormat.GTIN_13,
prefix=GS1Prefix(value='590', usage='GS1 Poland'),
payload='590123412345', check_digit=7, 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()
'05901234123457'

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, payload, check_digit, packaging_level=None)

Data class containing a GTIN.

value: str

Raw unprocessed value.

May include leading zeros.

format: biip.gtin._enums.GtinFormat

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

Classification is done after stripping leading zeros.

prefix: Optional[biip.gs1._prefixes.GS1Prefix]

The GS1 prefix, indicating what GS1 country organization that assigned code range.

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)

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

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)

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

Length of a GTIN of the given format.

Return type

int

class biip.gtin.Rcn(value, format, prefix, payload, check_digit, packaging_level=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[biip.gtin._enums.RcnUsage] = None

Where the RCN can be circulated, in a geographical region or within a company.

region: Optional[biip.gtin._enums.RcnRegion] = None

The geographical region whose rules are used to interpret the contents of the RCN.

weight: Optional[decimal.Decimal] = None

A variable weight value extracted from the barcode, if indicated by prefix.

price: Optional[decimal.Decimal] = None

A variable weight price extracted from the barcode, if indicated by prefix.

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)

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)

Enum of geographical regions with custom RCN rules.

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

ESTONIA = 'ee'

Estonia

FINLAND = 'fi'

Finland

GREAT_BRITAIN = 'gb'

Great Britain

LATVIA = 'lv'

Latvia

LITHUANIA = 'lt'

Lithuania

NORWAY = 'no'

Norway

SWEDEN = 'se'

Sweden

classmethod from_iso_3166_1_numeric_code(code)

Get the region from an ISO 3166-1 numeric code.

Return type

Optional[RcnRegion]

get_currency_code()

Get the ISO-4217 currency code for the region.

Return type

Optional[str]