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

company_prefix: Optional[biip.gs1._prefixes.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 (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

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=None, *, 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.

Return type

int

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=None, *, 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=None, *, 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]