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:
- 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:
- Returns:
A GTIN instance with zeros in the variable measure places.
- Raises:
EncodeError – If the rules for variable measures in the region are unknown.
-
value:
- 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:
- 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.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
]