Quickstart

Basic Usage

After installing the package, you can use the gpc command-line tool to import GS1 GPC data into a database.

Basic Import

gpc import-gpc

This will:

Look for the latest cached XML file in the imports directory
If none found, use the fallback file
Import the data into the default SQLite database

Download Latest Data

gpc import-gpc --download

This will:

Download the latest GPC data from the GS1 API
Save it to the imports directory with standard naming convention: {language_code}-{version}.xml
Import the data into the default SQLite database

Specify Language

gpc import-gpc --download --language fr

This will download and import the French version of the GPC data.

Custom Files

gpc import-gpc --xml-file ./my_custom_file.xml --db-file ./my_database.sqlite3

Export Database to SQL

gpc import-gpc --dump-sql

This will:

Import data as usual
Export all GPC tables to a SQL file in the exports directory
The SQL file will follow the naming convention: {language_code}-v{date}.sql

Export Only (No Import)

gpc export-sql --db-file ./data/instances/gpc_data_xml.sqlite3

PostgreSQL Support

gpc import-gpc --db-type postgresql --db-file "postgresql://user:password@localhost/dbname"

Python API Usage

You can also use the package as a Python library. The library now provides a class-based API:

from gs1_gpc.db import DatabaseConnection, setup_database
from gs1_gpc.parser import GPCParser
from gs1_gpc.downloader import GPCDownloader

# Create a downloader instance
downloader = GPCDownloader(download_dir="/path/to/downloads", language_code="en")

# Find the latest XML file
xml_file = downloader.find_latest_xml_file()

# Create database connection
db_connection = DatabaseConnection("my_database.sqlite3")

# Setup database
setup_database(db_connection)

# Create parser and process XML file
parser = GPCParser(db_connection)
parser.process_xml(xml_file)

# Close database connection
db_connection.close()

Basic Example

The package includes a basic example that demonstrates how to import GPC data:

#!/usr/bin/env python3
"""
Example script demonstrating basic usage of the gs1_gpc package.
"""

import os
import logging
from gs1_gpc.db import DatabaseConnection, setup_database
from gs1_gpc.parser import GPCParser
from gs1_gpc.downloader import GPCDownloader

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

# Get script directory
SCRIPT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Define paths
GPC_DOWNLOAD_DIR = os.path.join(SCRIPT_DIR, 'imports')
DB_FILE = os.path.join(SCRIPT_DIR, 'instances', 'example_import.sqlite3')

def main():
    """Main function to demonstrate basic import."""
    # Create a downloader instance
    downloader = GPCDownloader(download_dir=GPC_DOWNLOAD_DIR)
    
    # Find the latest XML file
    xml_file = downloader.find_latest_xml_file()
    if not xml_file:
        logging.error("No XML files found in %s", GPC_DOWNLOAD_DIR)
        return
    
    # Create database connection
    db_connection = DatabaseConnection(DB_FILE)
    
    # Setup database
    if not setup_database(db_connection):
        logging.error("Failed to setup database")
        return
    
    # Create parser and process XML file
    parser = GPCParser(db_connection)
    parser.process_xml(xml_file)
    
    # Close database connection
    db_connection.close()
    
    logging.info("Import completed successfully")

if __name__ == "__main__":
    main()