Parse GTINs (also known as UPC/EAN/JAN/ISBN)
Project description
gtin
A library and CLI for parsing and validating GTINs ("Global Trade Item Numbers"—also known as UPC/EAN/JAN/ISBN).
Installation
Basic Installation
pip3 install gtin
Development Installation
To install for development of this project:
git clone https://github.com/davebelais/gtin.git && \
cd gtin && \
make && \
source venv/bin/activate
Usage
This package can be used as a CLI (command-line-interface) or library.
CLI
gtin ccd | gtin calculate-check-digit
$ gtin ccd -h
usage: gtin calculate-check-digit [-h] GTIN
gtin ccd [-h] GTIN
positional arguments:
GTIN A GTIN without the check-digit
optional arguments:
-h, --help show this help message and exit
gtin acd | gtin append-check-digit
$ gtin acd -h
usage: gtin append-check-digit [-h] [-l LENGTH] GTIN
gtin acd [-h] [-l LENGTH] GTIN
positional arguments:
GTIN A GTIN without the check-digit
optional arguments:
-h, --help show this help message and exit
-l LENGTH, --length LENGTH
The length of GTIN to return
gtin vcd | gtin validate-check-digit
$ gtin vcd -h
usage: gtin validate-check-digit [-h] GTIN
gtin vcd [-h] GTIN
If the provided GTIN is *invalid*, this command will terminate with a non-zero
exit status.
positional arguments:
GTIN A GTIN *with* check-digit
optional arguments:
-h, --help show this help message and exit
gtin hvcd | gtin has-valid-check-digit
$ gtin hvcd -h
usage: gtin has-valid-check-digit [-h] GTIN
gtin hvcd [-h] GTIN
If the provided GTIN is *valid*, this command will return "YES". If the
provided GTIN is *valid*, this command will return "NO".
positional arguments:
GTIN A GTIN *with* check-digit
optional arguments:
-h, --help show this help message and exit
gtin gcp | gtin get-gcp
$ gtin gcp -h
usage: gtin get-gcp [-h] GTIN
gtin gcp [-h] GTIN
positional arguments:
GTIN A GTIN *with* check-digit
optional arguments:
-h, --help show this help message and exit
Library
gtin.calculate_check_digit
This function calculates and returns a check-digit for the provided GTIN.
Note: If the provided unchecked_gtin
is a str
, the returned value is a
str
. If the provided unchecked_gtin
is an int
, the returned value is an
int
.
Parameters:
- unchecked_gtin (str|int): A GTIN without check-digit
gtin.append_check_digit
This function calculates a check-digit and returns the provided GTIN with the check-digit appended.
Note: If the provided unchecked_gtin
is a str
, the returned value is a
str
. If the provided unchecked_gtin
is an int
, the returned value is an
int
.
Parameters:
- unchecked_gtin (str|int): A GTIN without check-digit
gtin.calculate_check_digit
This function accepts a GTIN without check-digit and returns the check-digit.
>>> from gtin import calculate_check_digit
... calculate_check_digit("02345678901289")
'4'
>>> calculate_check_digit(2345678901289)
4
gtin.append_check_digit
This function accepts a GTIN without check-digit and returns the same GTIN with a check-digit appended.
>>> from gtin import append_check_digit
... append_check_digit("02345678901289")
'023456789012894'
>>> append_check_digit(2345678901289)
23456789012894
gtin.has_valid_check_digit
This function accepts a GTIN with check-digit and returns True
if the
check-digit is valid, or False
if the check-digit is invalid.
>>> from gtin import has_valid_check_digit
... has_valid_check_digit("02345678901289")
True
>>> has_valid_check_digit(2345678901281)
False
23456789012894
gtin.validate_check_digit
This function accepts a GTIN with check-digit and raises a
gtin.CheckDigitError
if the provided GTIN's check-digit is invalid.
>>> from gtin import validate_check_digit
... validate_check_digit("02345678901289")
>>> validate_check_digit("02345678901281")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/Users/DBelai/Code/gtin/gtin/__init__.py", line 159, in validate_check_digit
raise CheckDigitError(gtin, check_digit)
gtin.CheckDigitError: "02345678901281" is not a valid GTIN, the last digit is "1", whereas the correct check-digit would be "9".
gtin.get_gcp
This function accepts a GTIN with check-digit and returns the GCP (GS1 Company Prefix).
>>> from gtin import get_gcp
... get_gcp("00332100000001")
'033210'
>>> get_gcp(332100000001)
'033210'
gtin.GTIN
This class represents a Global Trade Item Number, and can be used to:
- Identify a trade item's Indicator-Digit, GCP (GS1 Company Prefix), Item Reference, and Check-Digit.
- Validate a GTIN's check-digit.
- Calculate a check-digit from a raw GTIN.
Parameters:
-
gtin (str|int): A string or number representing a GTIN, including the check-digit.
- When the gtin parameter is provided, the last (rightmost) digit is used to validate the GTIN.
-
length (int):
The length of the GTIN.
- If no value is provided for length, and gtin is a str—length is inferred based on the character length of gtin.
- If no value is passed for length, gtin is None, and raw is a str—length is inferred based on the length of raw (adding 1, to account for the absent check-digit).
- If no length is passed, and none can be inferred from gtin or raw, length defaults to 14.
-
raw (str|int):
A string or number representing the GTIN, excluding the check-digit.
- If a value is provided for the parameter gtin, this parameter is not used, but is instead derived from gtin.
An instance of GTIN
has the following properties:
-
indicator_digit (str): This is the first (leftmost) digit of a GTIN-14.
- "0" indicates a base unit.
- "1" through "8" are used to define the packaging hierarchy of a product with the same item reference.
- "9" indicates a variable-measure trade item.
-
gcp (str): The GCP (GS1 Company Prefix) is a globally unique identifier assigned to an entity (usually a company) by GS1 Member Organizations, in order to create identifiers within the GS1 System. Company Prefixes, which vary in length, are comprised of a GS1 Member Organization Prefix followed by a company/entity-specific number.
-
item_reference (str): The item reference is the part of the GTIN that is allocated by a GS1 entity to identify a trade item. An item reference varies in length as a function of a GTIN's GCP length.
-
check_digit (str): The last digit in the GTIN when cast as a
str
, the check-digit is a mod-10 algorithm digit used to check for input errors. To understand how this digit is calculated, refer to: http://www.gs1.org/how-calculate-check-digit-manually. -
length (int): The number of characters comprising the GTIN (including the check-digit).
Examples
A GTIN initialized without any arguments:
>>> from gtin import GTIN
... print(repr(GTIN()))
gtin.GTIN("00000000000000")
Typical usage will require converting your GTIN to a str prior to use in your application.
>>> from gtin import GTIN
... print(str(GTIN()))
00000000000000
Given a raw GTIN, the check-digit is calculated and appended.
>>> from gtin import GTIN
... print(str(GTIN(raw="0978289450809")))
09782894508091
Given a valid GTIN str for gtin, the return value of str(GTIN(gtin)) is equal to gtin.
>>> from gtin import GTIN
... print(str(GTIN("04000101613600")))
04000101613600
Non-numeric characters are ignored/discarded.
>>> from gtin import GTIN
... print(str(GTIN("0-4000101-6136-00")))
04000101613600
Given a an int for the parameter raw, the length defaults to 14.
>>> from gtin import GTIN
... print(str(GTIN(raw=7447010150)))
00074470101505
>>> print(str(GTIN(74470101505)))
00074470101505
Given a GTIN, and a length:
>>> from gtin import GTIN
... print(str(GTIN(raw=7447010150,length=12)))
074470101505
>>> print(str(GTIN(74470101505,length=12)))
074470101505
>>> from gtin import GTIN
... print(str(GTIN("74470101505",length=14)))
00074470101505
Get the GCP of a GTIN:
>>> from gtin import GTIN
... print(GTIN("00041333704647").gcp)
0041333
>>> print(GTIN("00811068011972").gcp)
081106801
>>> from gtin import GTIN
... print(GTIN("00188781000171").gcp)
0188781000
Get the component parts of a GTIN instance as a tuple containing GTIN.indicator_digit, GTIN.gcp, GTIN.item_reference, and GTIN.check_digit:
>>> from gtin import GTIN
... print(tuple(GTIN(raw="0400010161360")))
("0", "4000101", "61360", "0")
Testing
Assuming you have already followed the
Development Installation instructions, you can
simply run make test
in the project directory.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for gtin-1.0.1631641032-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d401384a558e737df803cb0ba1975001ef86ff673173889e814b88012eed5a43 |
|
MD5 | 09096859706ee8dd2ed20c91a99442a8 |
|
BLAKE2b-256 | 721fe2fa986b4a5563f1d9c5e0f072ce1e43d03da7d0ede056c509ad93c8910d |