pyaccess 0.1.0a1

Python library for reading MS Access databases (.accdb/.mdb files) on Linux systems using mdbtools

PyAccess

A Python library for reading Microsoft Access databases (.accdb/.mdb files) on Linux systems using mdbtools.

Features

• Cross-platform Access database reading - Works on Linux using mdbtools
• Pandas integration - Query results returned as pandas DataFrames
• Geological database support - Specialized classes for mining/geological data
• Type safety - Full type hints and error handling
• Context manager support - Clean resource management
• Export capabilities - Export data to CSV files

Installation

pip install -e .

System Requirements

• Linux operating system
• mdbtools (install with apt install mdbtools on Debian/Ubuntu)
• Python 3.13+

Quick Start

from pyaccess import GeologicalDatabase
from pathlib import Path

# Open your Access database
db_path = Path("path/to/your/database.accdb")
with GeologicalDatabase(db_path) as db:
    print(f"Tables: {db.get_tables()}")

    # Get all drill hole collar data
    collars = db.collar.get_all_holes()
    print(f"Found {len(collars)} drill holes")

    # Get data for a specific hole
    hole_id = "DH001"
    hole_data = db.get_complete_hole_data(hole_id)
    print(f"Hole {hole_id} has {len(hole_data['survey'])} survey points")

API Reference

AccessDatabase

The base class for accessing any MS Access database.

from pyaccess import AccessDatabase

# Basic usage
db = AccessDatabase("database.accdb")

# Get table list
tables = db.get_tables()

# Get table schema
table_info = db.get_table_info("my_table")

# Query data
df = db.query_table("my_table", columns=["col1", "col2"], where="col1 > 100", limit=10)

# Export to CSV
db.export_table_to_csv("my_table", "output.csv")

GeologicalDatabase

Specialized class for geological/mining databases with convenient access to common tables.

from pyaccess import GeologicalDatabase

db = GeologicalDatabase("geological.accdb")

# Collar data access
all_holes = db.collar.get_all_holes()
specific_hole = db.collar.get_hole_by_id("DH001")
holes_in_block = db.collar.get_holes_in_block("Block_A")

# Survey data
survey_data = db.survey.get_survey_for_hole("DH001")

# Lithology data
litho_data = db.lithology.get_lithology_for_hole("DH001")
litho_by_code = db.lithology.get_lithology_by_code("QTZ")

# Get complete hole data (collar + survey + lithology)
complete_data = db.get_complete_hole_data("DH001")

# Export hole data to CSV files
db.export_hole_to_csv("DH001", "output_directory/")

Query Methods

query_table()

# Basic query
df = db.query_table("table_name")

# With column selection
df = db.query_table("table_name", columns=["col1", "col2"])

# With filtering (pandas query syntax)
df = db.query_table("table_name", where="col1 > 100 and col2 == 'value'")

# With limit
df = db.query_table("table_name", limit=100)

WHERE Clause Syntax

The where parameter uses pandas query syntax:

# String matching
where="hole_id == 'DH001'"

# Numeric comparisons
where="depth > 100 and depth < 200"

# Multiple conditions
where="block == 'A' and max_depth > 50"

Geological Data Structure

The library is designed to work with typical geological database schemas:

• collar: Drill hole location and metadata (hole_id, x, y, z, max_depth, etc.)
• survey: Drill hole survey data (azimuth, dip, depth)
• litho: Lithology intervals (depth_from, depth_to, lith_code, etc.)
• alteration: Alteration data
• styles: Visualization styling
• translation: Code translations

Error Handling

from pyaccess import (
    AccessDatabaseError,
    DatabaseConnectionError,
    TableNotFoundError
)

try:
    db = GeologicalDatabase("database.accdb")
    data = db.query_table("nonexistent_table")
except DatabaseConnectionError:
    print("Database file not found or corrupted")
except TableNotFoundError:
    print("Table does not exist")
except AccessDatabaseError as e:
    print(f"Database error: {e}")

Context Manager

Use the context manager for automatic resource management:

with GeologicalDatabase("database.accdb") as db:
    data = db.collar.get_all_holes()
    # Database connection automatically closed

Exporting Data

# Export table to CSV
db.export_table_to_csv("collar", "collar_data.csv")

# Export with filtering
db.export_table_to_csv(
    "survey",
    "survey_data.csv",
    where="hole_id == 'DH001'",
    columns=["hole_id", "depth", "azimuth", "dip"]
)

# Export complete hole data
db.export_hole_to_csv("DH001", "hole_data/")
# Creates: DH001_collar.csv, DH001_survey.csv, DH001_lithology.csv

Running Tests

# Install test dependencies
pip install pytest

# Run tests
pytest

# Run with coverage
pytest --cov=pyaccess --cov-report=html

Development

Setting up development environment

# Clone repository
git clone <repository-url>
cd pyaccess

# Install in development mode
pip install -e .

# Install development dependencies
pip install pytest pandas ruff

# Run linting
ruff check .

# Run tests
pytest

Project Structure

pyaccess/
├── src/
│   ├── pyaccess.py     # Main library code
│   └── main.py         # Example usage
├── tests/
│   └── test_pyaccess.py # Test suite
├── resources/          # Test data (Access databases)
├── pyproject.toml      # Project configuration
└── README.md          # This file

Dependencies

• pandas: Data manipulation and analysis
• typing-extensions: Enhanced type hints for older Python versions
• mdbtools (system): Command-line tools for reading MS Access databases

License

[Add your license here]

Contributing

[Add contribution guidelines]

Support

For issues and questions, please create an issue or contact the maintainers.