Skip to main content

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/enorganic/gtin.git && \
cd gtin && \
make && \
source venv/bin/activate

Usage

This package can be used as a CLI (command-line-interface) or library.

Please see the Notes Concerning GCP if calculating a correct GCP is important to your usage.

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 *invalid*, 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 accepts a GTIN without check-digit and returns the check-digit.

Parameters:

  • unchecked_gtin (str|int): A GTIN without check-digit

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.

Example:

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

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

Example:

>>> 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/David/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 strlength is inferred based on the character length of gtin.
    • If no value is passed for length, gtin is None, and raw is a strlength 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.

Notes Concerning GCP

If inferring a correct GCP (GS1 Company Prefix) is important for your usage, you should update this package periodically:

pip3 install --upgrade gtin

Why? Because GCP allocation is subject to change. When the GS1 (the organization which governs GCP allocation) publishes a new GCP Prefix Format List (an XML document specifying GCP lengths according to variable-length prefix blocks), a new distribution of this package is automatically packaged and distributed to pypi.org with the new GCP Prefix Format List. If you have the most recent version of this package, you will be calculating GCPs based on the most recent GCP Prefix Format List.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gtin-1.2.1631641032.tar.gz (277.2 kB view details)

Uploaded Source

Built Distribution

gtin-1.2.1631641032-py3-none-any.whl (614.6 kB view details)

Uploaded Python 3

File details

Details for the file gtin-1.2.1631641032.tar.gz.

File metadata

  • Download URL: gtin-1.2.1631641032.tar.gz
  • Upload date:
  • Size: 277.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.5.0 importlib_metadata/4.9.0 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.1

File hashes

Hashes for gtin-1.2.1631641032.tar.gz
Algorithm Hash digest
SHA256 be95e950395c5bcbdf846a72ffcd3afcf14c227af0fefb681464bdc92ba0dbf1
MD5 f89726e539f15b0a0c3ff3c36bf937fb
BLAKE2b-256 9d075e6c2929e7c86b9b8aa5556a59cd2121f881e8e0f519e4eb175eb66f43f4

See more details on using hashes here.

Provenance

File details

Details for the file gtin-1.2.1631641032-py3-none-any.whl.

File metadata

  • Download URL: gtin-1.2.1631641032-py3-none-any.whl
  • Upload date:
  • Size: 614.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.5.0 importlib_metadata/4.9.0 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.1

File hashes

Hashes for gtin-1.2.1631641032-py3-none-any.whl
Algorithm Hash digest
SHA256 a68d8af87afe1908c07b3b411333045d0afad8a97254da2759717b42730a52bd
MD5 4908eb78aa95ecc84ce6b971580ceec9
BLAKE2b-256 b6f4b24fc8a1cda4a43176ec28e1fe2ae65a1107613ad0d49cb0d8bb32623fc9

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page