Metadata-Version: 2.4
Name: pyaccess
Version: 0.1.0a0
Summary: Python library for reading MS Access databases (.accdb/.mdb files) on Linux systems using mdbtools
Author-email: Lyralabs <developer@lyralabs.cloud>
Maintainer-email: Lyralabs <developer@lyralabs.cloud>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rizquuula/pyaccess
Project-URL: Repository, https://github.com/rizquuula/pyaccess.git
Keywords: access,database,ms-access,mdb,accdb,pandas,geological,mining,mdbtools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2.0.0
Requires-Dist: pip>=25.3
Requires-Dist: typing-extensions>=4.0.0

# 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

```bash
pip install -e .
```

### System Requirements

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

## Quick Start

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

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

```python
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()

```python
# 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:

```python
# 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

```python
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:

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

## Exporting Data

```python
# 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

```bash
# Install test dependencies
pip install pytest

# Run tests
pytest

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

## Development

### Setting up development environment

```bash
# 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](link-to-issues) or contact the maintainers.
