ean-tools 0.1.0__tar.gz

ean_tools-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.3
+Name: ean-tools
+Version: 0.1.0
+Summary: Collection of tools for validating and getting information about EAN (UPC, GTIN) and ISBN barcodes.
+Home-page: https://github.com/ean-db/ean-tools
+License: MIT
+Keywords: barcode,ean,upc,isbn,gtin
+Author: EAN-DB
+Author-email: support@ean-db.com
+Requires-Python: >=3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: PyYaml (>=6)
+Requires-Dist: affix-tree (>=0.1.1)
+Project-URL: Repository, https://github.com/ean-db/ean-tools
+Description-Content-Type: text/markdown
+
+# ean-tools
+
+Collection of tools for validating and getting information about EAN (UPC, GTIN) and ISBN barcodes.
+
+## Installation
+
+```commandline
+pip install affix-tree
+```
+
+## Usage
+
+### Barcode normalization
+
+```pycon
+>>> from ean_tools.normalization import normalize_barcode
+
+>>> normalize_barcode('978-84865-4608-3')
+
+'9788486546083'
+```
+
+### Check digit validation
+
+```pycon
+>>> from ean_tools.check_digits import has_correct_check_digit
+
+>>> has_correct_check_digit('8510000076279')
+
+False
+```
+
+### Getting additional barcode information
+
+```pycon
+>>> from ean_tools.barcode_info import get_barcode_info, BarcodeType
+
+>>> get_barcode_info('4000000001140')
+
+BarcodeInfo(barcode_type=BarcodeType.REGULAR, description='GS1 Germany', country='de')
+```
+

ean_tools-0.1.0/README.md

@@ -0,0 +1,41 @@
+# ean-tools
+
+Collection of tools for validating and getting information about EAN (UPC, GTIN) and ISBN barcodes.
+
+## Installation
+
+```commandline
+pip install affix-tree
+```
+
+## Usage
+
+### Barcode normalization
+
+```pycon
+>>> from ean_tools.normalization import normalize_barcode
+
+>>> normalize_barcode('978-84865-4608-3')
+
+'9788486546083'
+```
+
+### Check digit validation
+
+```pycon
+>>> from ean_tools.check_digits import has_correct_check_digit
+
+>>> has_correct_check_digit('8510000076279')
+
+False
+```
+
+### Getting additional barcode information
+
+```pycon
+>>> from ean_tools.barcode_info import get_barcode_info, BarcodeType
+
+>>> get_barcode_info('4000000001140')
+
+BarcodeInfo(barcode_type=BarcodeType.REGULAR, description='GS1 Germany', country='de')
+```

ean_tools-0.1.0/ean_tools/barcode_info.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+from ean_tools.barcode_prefixes import get_raw_ean8_prefix_info, get_raw_ean13_prefix_info, get_raw_isbn_prefix_info
+
+
+class BarcodeType(Enum):
+    COUPON_ID = 'COUPON_ID'
+    DEMO = 'DEMO'
+    GENERAL_MANAGER_NUMBER = 'GENERAL_MANAGER_NUMBER'
+    REFUND_RECEIPT = 'REFUND_RECEIPT'
+    REGULAR = 'REGULAR'
+    RESERVED_FOR_FUTURE = 'RESERVED_FOR_FUTURE'
+    RESTRICTED_CIRCULATION = 'RESTRICTED_CIRCULATION'
+    UNUSED = 'UNUSED'
+
+
+@dataclass
+class BarcodeInfo:
+    barcode_type: BarcodeType
+    description: str
+    country: Optional[str]
+
+
+def get_barcode_info(normalized_barcode: str) -> BarcodeInfo:
+    """Retrieves information about a given barcode.
+
+    Args:
+        normalized_barcode (str): The normalized barcode string.
+
+    Returns:
+        BarcodeInfo: An object containing barcode information.
+    """
+    if len(normalized_barcode) == 13 and (normalized_barcode.startswith('978') or normalized_barcode.startswith('979')):
+        barcode_info = get_raw_isbn_prefix_info(normalized_barcode)
+        if not barcode_info:
+            return BarcodeInfo(BarcodeType.REGULAR, 'ISBN', None)
+
+        return BarcodeInfo(BarcodeType.REGULAR, barcode_info['description'], barcode_info.get('country'))
+
+    if len(normalized_barcode) == 8:
+        barcode_info = get_raw_ean8_prefix_info(normalized_barcode)
+    elif len(normalized_barcode) == 14:
+        barcode_info = get_raw_ean13_prefix_info(normalized_barcode[1:])
+    else:
+        barcode_info = get_raw_ean13_prefix_info(normalized_barcode)
+
+    if not barcode_info:
+        return BarcodeInfo(BarcodeType.RESERVED_FOR_FUTURE, 'Reserved for future use', None)
+
+    if 'type' in barcode_info:
+        barcode_type = BarcodeType[barcode_info['type']]
+    else:
+        barcode_type = BarcodeType.REGULAR
+
+    return BarcodeInfo(barcode_type, barcode_info['description'], barcode_info.get('country'))

ean_tools-0.1.0/ean_tools/barcode_prefixes.py

@@ -0,0 +1,61 @@
+import os
+from typing import Optional
+
+import yaml
+
+from affix_tree import AffixTree
+
+_CURRENT_DIR = os.path.dirname(__file__)
+
+
+def init_gs1_prefixes() -> AffixTree[dict]:
+    with open(os.path.join(_CURRENT_DIR, 'data/gs1-prefixes.yaml')) as gs1_prefixes_file:
+        _gs1_prefixes = yaml.load(gs1_prefixes_file.read(), yaml.CBaseLoader)
+
+    gs1_prefixes = AffixTree()
+    for prefix_group in _gs1_prefixes:
+        for p in prefix_group.pop('prefixes'):
+            gs1_prefixes.add(p, prefix_group)
+
+    return gs1_prefixes
+
+
+def init_gs1_8_prefixes() -> AffixTree[dict]:
+    with open(os.path.join(_CURRENT_DIR, 'data/gs1-8-prefixes.yaml')) as gs1_8_prefixes_file:
+        _gs1_8_prefixes = yaml.load(gs1_8_prefixes_file.read(), yaml.CBaseLoader)
+
+    gs1_8_prefixes = AffixTree()
+    for prefix_group in _gs1_8_prefixes:
+        for p in prefix_group.pop('prefixes'):
+            gs1_8_prefixes.add(p, prefix_group)
+
+    return gs1_8_prefixes
+
+
+def init_isbn_prefixes() -> AffixTree[dict]:
+    with open(os.path.join(_CURRENT_DIR, 'data/isbn-prefixes.yaml')) as isbn_prefixes_file:
+        _isbn_prefixes = yaml.load(isbn_prefixes_file.read(), yaml.CBaseLoader)
+
+    isbn_prefixes = AffixTree()
+    for prefix_group in _isbn_prefixes:
+        for p in prefix_group.pop('prefixes'):
+            isbn_prefixes.add(p, prefix_group)
+
+    return isbn_prefixes
+
+
+_GS1_8_PREFIXES: AffixTree[dict] = init_gs1_8_prefixes()
+_GS1_PREFIXES: AffixTree[dict] = init_gs1_prefixes()
+_ISBN_PREFIXES: AffixTree[dict] = init_isbn_prefixes()
+
+
+def get_raw_ean8_prefix_info(barcode: str) -> Optional[dict]:
+    return _GS1_8_PREFIXES.find(barcode)
+
+
+def get_raw_ean13_prefix_info(barcode: str) -> Optional[dict]:
+    return _GS1_PREFIXES.find(barcode)
+
+
+def get_raw_isbn_prefix_info(barcode: str) -> Optional[dict]:
+    return _ISBN_PREFIXES.find(barcode)

ean_tools-0.1.0/ean_tools/check_digits.py

@@ -0,0 +1,44 @@
+def has_correct_check_digit(normalized_barcode: str) -> bool:
+    """Checks if the given barcode has the correct check digit.
+
+    Args:
+        normalized_barcode (str): Normalized barcode string.
+
+    Returns:
+        bool: True if the check digit is correct, False otherwise.
+    """
+    return get_correct_check_digit(normalized_barcode) == normalized_barcode[-1]
+
+
+def get_correct_check_digit(normalized_barcode: str) -> str:
+    """Calculates the correct check digit for a barcode.
+
+    Args:
+        normalized_barcode (str): Normalized barcode string.
+
+    Returns:
+        str: The correct check digit.
+    """
+    check_digit = 0
+    barcode_length = len(normalized_barcode)
+
+    i = barcode_length - 2
+    while i >= 0:
+        weight = 3 if (barcode_length - i) % 2 == 0 else 1
+        check_digit += int(normalized_barcode[i]) * weight
+        i -= 1
+
+    return str((10 - (check_digit % 10)) % 10)
+
+
+def isbn10_has_correct_check_digit(isbn10: str) -> bool:
+    """Checks if an ISBN-10 barcode has the correct check digit.
+
+    Args:
+        isbn10 (str): The ISBN-10 barcode string.
+
+    Returns:
+        bool: True if the check digit is correct, False otherwise.
+    """
+    s = sum((10 - i) * int(c) for i, c in enumerate(isbn10))
+    return s % 11 == 0

ean_tools-0.1.0/ean_tools/data/gs1-8-prefixes.yaml

@@ -0,0 +1,28 @@
+- description: Used to issue Restricted Circulation Numbers within a company
+  type: RESTRICTED_CIRCULATION
+  prefixes:
+  - '0'
+  - '2'
+- description: Used to issue GTIN-8s
+  prefixes:
+  - '1'
+  - '3'
+  - '4'
+  - '5'
+  - '6'
+  - '7'
+  - '8'
+  - '90'
+  - '91'
+  - '92'
+  - '93'
+  - '94'
+  - '95'
+  - '96'
+  - '970'
+  - '971'
+  - '972'
+  - '973'
+  - '974'
+  - '975'
+  - '976'