PyArchInit Import/Export

Added in version 1.2.17.

Overview

The PyArchInit Import/Export feature provides bidirectional data synchronization between PyArchInit (full version) and PyArchInit-Mini databases. This enables seamless data migration, collaboration workflows, and compatibility with the full PyArchInit ecosystem.

Key Capabilities

Bidirectional Sync: Import from and export to PyArchInit databases
Multi-Database Support: SQLite and PostgreSQL compatibility
Intelligent Relationship Mapping: Automatic conversion between PyArchInit’s rapporti field and PyArchInit-Mini’s relational structure
Selective Import/Export: Filter by site name and choose specific data tables
Multi-Interface: Available in CLI, Desktop GUI, and Web interface

Supported Data Types

Import

The following data types can be imported from PyArchInit:

Sites (site_table) - Archaeological site information
Stratigraphic Units (us_table) - US data with automatic relationship mapping
Inventario Materiali (inventario_materiali_table) - Artifact inventory
Periodizzazione (periodizzazione_table) - Chronological periods
Thesaurus (pyarchinit_thesaurus_sigle) - Terminology and abbreviations

Export

The following data types can be exported to PyArchInit:

Sites - Site data in PyArchInit format
US with Relationships - Stratigraphic units with automatic rapporti field generation

Relationship Mapping

One of the most important features is the intelligent mapping between PyArchInit’s rapporti field and PyArchInit-Mini’s relational database structure.

PyArchInit Format

PyArchInit stores US relationships in a TEXT field using Python list format:

rapporti = "[['Copre', '2'], ['Copre', '8'], ['Taglia', '5']]"

PyArchInit-Mini Format

PyArchInit-Mini uses a proper relational table us_relationships_table:

CREATE TABLE us_relationships_table (
    id INTEGER PRIMARY KEY,
    sito VARCHAR(350) NOT NULL,
    us_from VARCHAR(100) NOT NULL,
    us_to VARCHAR(100) NOT NULL,
    relationship_type VARCHAR(50) NOT NULL
);

Automatic Conversion

The import/export service automatically converts between these formats:

Import Process:

Parse rapporti string using ast.literal_eval()
Extract relationship type and target US number
Create individual records in us_relationships_table

Export Process:

Query all relationships for a US
Format as Python list of lists
Generate rapporti string for PyArchInit

Example:

# PyArchInit format
rapporti = "[['Copre', '2', '1', 'Pompei'], ['Taglia', '5', '1', 'Pompei']]"

# Imported to PyArchInit-Mini as:
# Record 1: sito='Pompei', us_from=1, us_to=2, relationship_type='Copre'
# Record 2: sito='Pompei', us_from=1, us_to=5, relationship_type='Taglia'

Command Line Interface

Installation

pip install pyarchinit-mini>=1.2.17

Import from PyArchInit

Import all data from a specific site:

pyarchinit-mini-import import-from-pyarchinit \
  --source-db "sqlite:////path/to/pyarchinit_db.sqlite" \
  --tables all \
  --sites "Scavo archeologico"

Import specific tables:

pyarchinit-mini-import import-from-pyarchinit \
  --source-db "postgresql://user:pass@localhost:5432/pyarchinit" \
  --tables sites \
  --tables us \
  --sites "Pompei" \
  --sites "Ercolano" \
  --import-relationships

Export to PyArchInit

Export sites and US to a PyArchInit database:

pyarchinit-mini-import export-to-pyarchinit \
  --target-db "sqlite:////path/to/target_db.sqlite" \
  --tables sites \
  --tables us \
  --sites "Project Alpha" \
  --export-relationships

List Available Sites

View sites in a PyArchInit database:

pyarchinit-mini-import list-sites \
  --source-db "sqlite:////path/to/pyarchinit_db.sqlite"

CLI Options

--source-db, -s <connection_string>: Source database connection string (required for import/list operations)

--target-db, -t <connection_string>: Target database connection string (required for export operations)

--tables, -T <table_name>: Tables to import/export. Can be specified multiple times. Valid values: sites, us, inventario, periodizzazione, thesaurus, all

--sites <site_name>: Filter by site name. Can be specified multiple times for multiple sites.

--import-relationships / --no-import-relationships: Import US relationships (default: yes)

--export-relationships / --no-export-relationships: Export US relationships (default: yes)

Desktop GUI Interface

Access

Launch PyArchInit-Mini Desktop GUI
Navigate to Tools → PyArchInit Import/Export

Import Workflow

Select Database Type: Choose SQLite or PostgreSQL
Enter Connection Details:
- SQLite: Browse to select database file
- PostgreSQL: Enter host, port, database, username, password
Test Connection: Verify connection and load available sites
Select Data: Check tables to import and optionally filter by sites
Import: Click “Import” and monitor progress in console

Export Workflow

Select Database Type: Choose target database type
Configure Connection: Enter target database details
Select Data: Choose tables and sites to export
Export: Start export and review results

Web Interface

Access

Navigate to Tools → PyArchInit Import/Export from the main menu.

Import Process

Select Import tab
Toggle database type (SQLite/PostgreSQL)
Enter connection details
Click Test Connection to verify
Select tables and filter options
Click Start Import
Monitor real-time progress and statistics

Export Process

Select Export tab
Configure target database
Choose export options
Click Start Export
Review export results

Connection String Formats

SQLite

sqlite:////absolute/path/to/database.db
sqlite:///~/Documents/database.db
sqlite:///relative/path/database.db

PostgreSQL

postgresql://username:password@hostname:port/database_name

Example:

postgresql://archaeologist:secret123@db.example.com:5432/pyarchinit

Technical Details

Field Mapping

The service maps over 50 US fields between PyArchInit and PyArchInit-Mini schemas:

Core stratigraphic data (descrizione, interpretazione, etc.)
Chronological periods (periodo_iniziale, fase_iniziale, etc.)
Physical characteristics (colore, consistenza, struttura, etc.)
Excavation metadata (schedatore, data_schedatura, etc.)
Measurements (quota, lunghezza, profondita, etc.)

Date Handling

Date fields are automatically converted:

String dates (YYYY-MM-DD, DD/MM/YYYY, etc.) → Python date objects
Handles multiple common date formats
Invalid dates are set to NULL

ID Generation

PyArchInit-Mini uses VARCHAR primary keys (id_us) with sequential numbering:

Automatically generates next available ID during import
Queries MAX(id_us) and increments
Ensures no conflicts with existing records

Error Handling

Per-record error handling without stopping entire import
Detailed error messages with site/US identification
Transaction safety with individual commits
Statistics tracking for all operations

API Reference

Python API

from pyarchinit_mini.services.import_export_service import ImportExportService

# Initialize service
service = ImportExportService(
    mini_db_connection="sqlite:///./pyarchinit_mini.db",
    source_db_connection="sqlite:////path/to/pyarchinit_db.sqlite"
)

# Import sites
stats = service.import_sites(sito_filter=['Pompei'])
print(f"Imported: {stats['imported']}, Updated: {stats['updated']}")

# Import US with relationships
stats = service.import_us(
    sito_filter=['Pompei'],
    import_relationships=True
)
print(f"Imported: {stats['imported']}, Relationships: {stats['relationships_created']}")

# Export to PyArchInit
stats = service.export_us(
    target_db_connection="sqlite:////path/to/target.sqlite",
    sito_filter=['Pompei'],
    export_relationships=True
)

Available Methods

class ImportExportService

import_sites(sito_filter: List[str] | None = None) → Dict[str, Any]

Import site data from PyArchInit database.

Parameters:: sito_filter – Optional list of site names to import
Returns:: Dictionary with import statistics

import_us(sito_filter: List[str] | None = None, import_relationships: bool = True) → Dict[str, Any]

Import stratigraphic units from PyArchInit database.

Parameters:

sito_filter – Optional list of site names to import
import_relationships – Whether to import US relationships

Returns:

Dictionary with import statistics

import_inventario(sito_filter: List[str] | None = None) → Dict[str, Any]: Import artifact inventory from PyArchInit database.

import_periodizzazione(sito_filter: List[str] | None = None) → Dict[str, Any]: Import chronological periods from PyArchInit database.

import_thesaurus() → Dict[str, Any]: Import thesaurus/terminology from PyArchInit database.

export_sites(target_db_connection: str, sito_filter: List[str] | None = None) → Dict[str, Any]: Export sites to PyArchInit format.

export_us(target_db_connection: str, sito_filter: List[str] | None = None, export_relationships: bool = True) → Dict[str, Any]: Export US to PyArchInit format with automatic rapporti generation.

get_available_sites_in_source() → List[str]: List available sites in source database.

validate_database_connection(connection_string: str) → bool: Test database connection validity.

Use Cases

Scenario 1: Migrate Complete Site

Import all data from a PyArchInit database for a specific excavation:

pyarchinit-mini-import import-from-pyarchinit \
  --source-db "sqlite:////path/to/pyarchinit_db.sqlite" \
  --tables all \
  --sites "Scavo 2024 - Area A"

Result:

1 site imported
150 US imported
487 relationships created
320 inventory items imported
12 chronological periods imported

Scenario 2: Collaborate with Team

Export data to a shared PostgreSQL database:

pyarchinit-mini-import export-to-pyarchinit \
  --target-db "postgresql://team:pass@server:5432/pyarchinit" \
  --tables sites \
  --tables us \
  --sites "Project Alpha" \
  --export-relationships

Scenario 3: Desktop Workflow

Open PyArchInit Import/Export dialog
Select PyArchInit database
Test connection → 3 sites found
Select all tables
Filter: “Scavo 2023”
Import complete: 85 US, 234 relationships

Troubleshooting

Connection Issues

Problem: “Database file not found”

Solution:

Verify absolute path to database file
Use forward slashes: /Users/name/db.sqlite
Expand user home: ~/Documents/db.sqlite

Problem: “Failed to connect to PostgreSQL”

Solution:

Check credentials, host, and port
Verify PostgreSQL is running
Check firewall settings

Import Errors

Problem: “Date parsing failed”

Solution: Invalid date formats are automatically converted to NULL

Problem: “Referenced US not found”

Solution:

Import US before relationships
Use --import-relationships flag
Ensure target US exists

Performance

Typical Import Times

100 US records: ~5-10 seconds
1000 US records: ~30-60 seconds
Large datasets (10,000+): 5-10 minutes

Optimization Tips

Use site filtering for selective imports
Import multiple tables in one operation
PostgreSQL is faster than SQLite for large datasets
Use local databases when possible

PyArchInit Import/Export

Overview

Key Capabilities

Supported Data Types

Import

Export

Relationship Mapping

PyArchInit Format

PyArchInit-Mini Format

Automatic Conversion

Command Line Interface

Installation

Import from PyArchInit

Export to PyArchInit

List Available Sites

CLI Options

Desktop GUI Interface

Access

Import Workflow

Export Workflow

Web Interface

Access

Import Process

Export Process

Connection String Formats

SQLite

PostgreSQL

Technical Details

Field Mapping

Date Handling

ID Generation

Error Handling

API Reference

Python API

Available Methods

Use Cases

Scenario 1: Migrate Complete Site

Scenario 2: Collaborate with Team

Scenario 3: Desktop Workflow

Troubleshooting

Connection Issues

Import Errors

Performance

Typical Import Times

Optimization Tips

See Also