pyarchinit-mini 0.1.1__tar.gz

pyarchinit_mini-0.1.1/CLAUDE.md

@@ -0,0 +1,234 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PyArchInit-Mini is a lightweight archaeological data management system focused on core functionality without GIS dependencies. It provides multiple interfaces (REST API, Web UI, Desktop GUI, CLI) for managing archaeological sites, stratigraphic units (US), and material inventories.
+
+## Architecture
+
+### Layered Architecture
+The codebase follows a clean, service-oriented architecture:
+
+```
+pyarchinit_mini/
+├── models/          # SQLAlchemy ORM models (Site, US, InventarioMateriali, etc.)
+├── database/        # Connection management, migrations, DatabaseManager
+├── services/        # Business logic layer (SiteService, USService, etc.)
+├── dto/             # Data Transfer Objects for clean API boundaries
+├── api/             # FastAPI REST endpoints with Pydantic schemas
+├── utils/           # Validators, exceptions, utilities
+├── harris_matrix/   # Harris Matrix generation and visualization
+├── pdf_export/      # PDF report generation
+└── media_manager/   # Media file handling
+```
+
+### Key Design Patterns
+
+**Session Management**: All database operations use context managers via `DatabaseConnection.get_session()`. The session automatically commits on success and rolls back on errors. Never manually create sessions outside this pattern.
+
+**Service Layer**: Business logic lives in services (e.g., `SiteService`, `USService`). Services use `DatabaseManager` for CRUD operations and contain validation logic. API endpoints should be thin wrappers around service calls.
+
+**DTO Pattern**: Models are converted to DTOs before leaving the service layer to avoid SQLAlchemy lazy loading issues outside sessions. Use `SiteDTO.from_model(site)` while still in session context.
+
+**Multi-Database Support**: Code supports both PostgreSQL and SQLite. Database-specific logic is isolated in `DatabaseConnection`. Test with both databases when making schema changes.
+
+## Common Development Commands
+
+### Running the Application
+
+```bash
+# Start REST API server (FastAPI)
+python main.py
+# Access API docs at http://localhost:8000/docs
+
+# Start Web Interface (Flask)
+python web_interface/app.py
+# Access at http://localhost:5000
+
+# Start Desktop GUI (Tkinter)
+python desktop_gui/gui_app.py
+# OR
+python run_gui.py
+
+# Start CLI Interface
+python cli_interface/cli_app.py
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/unit/test_site_service.py
+
+# Run with coverage
+pytest --cov=pyarchinit_mini
+
+# Run with verbose output
+pytest -v
+```
+
+### Database Operations
+
+```bash
+# Run migrations (creates/updates schema)
+python -c "from pyarchinit_mini.database import DatabaseConnection, DatabaseManager; \
+           db = DatabaseConnection('sqlite:///./pyarchinit_mini.db'); \
+           DatabaseManager(db).run_migrations()"
+
+# Migrate existing database
+python migrate_database.py
+
+# Load sample data for testing
+python launch_with_sample_data.py
+python scripts/populate_sample_data.py
+```
+
+### Code Quality
+
+```bash
+# Format code with Black
+black pyarchinit_mini/
+
+# Sort imports
+isort pyarchinit_mini/
+
+# Lint with flake8
+flake8 pyarchinit_mini/
+
+# Type checking
+mypy pyarchinit_mini/
+```
+
+## Critical Implementation Details
+
+### Database Sessions
+
+**ALWAYS** use the session context manager pattern:
+
+```python
+# CORRECT
+with self.db_manager.connection.get_session() as session:
+    site = session.query(Site).filter(Site.id_sito == site_id).first()
+    dto = SiteDTO.from_model(site)  # Convert to DTO while in session
+    return dto
+
+# WRONG - Never do this
+session = self.db_manager.connection.SessionLocal()
+site = session.query(Site).get(site_id)
+# Missing rollback/commit handling, resource leak
+```
+
+### Service Methods
+
+Services have two patterns for CRUD operations:
+
+1. **Model-returning methods** (legacy): Return SQLAlchemy models
+2. **DTO-returning methods** (preferred): Return DTOs, suffix with `_dto`
+
+When adding new endpoints, prefer DTO-returning service methods to avoid detached instance errors.
+
+### Foreign Key Relationships
+
+SQLite requires explicit foreign key enforcement. This is configured in `DatabaseConnection`:
+
+```python
+@event.listens_for(self.engine, "connect")
+def set_sqlite_pragma(dbapi_connection, connection_record):
+    cursor.execute("PRAGMA foreign_keys=ON")
+```
+
+When defining relationships in models, ensure proper cascade settings for deletions.
+
+### Harris Matrix Generation
+
+The Harris Matrix system uses NetworkX for graph operations:
+
+```python
+from pyarchinit_mini.harris_matrix import HarrisMatrixGenerator, MatrixVisualizer
+
+generator = HarrisMatrixGenerator(db_manager)
+graph = generator.generate_matrix(site_name)  # Returns NetworkX DiGraph
+levels = generator.get_matrix_levels(graph)   # Topological ordering
+```
+
+US relationships are defined via `rapporti_stratigrafici` field (e.g., "Covers 1002, 1003").
+
+## Environment Configuration
+
+### Database Configuration
+
+```bash
+# SQLite (default)
+export DATABASE_URL="sqlite:///./pyarchinit_mini.db"
+
+# PostgreSQL
+export DATABASE_URL="postgresql://user:password@localhost:5432/pyarchinit"
+```
+
+### FastAPI Server Configuration
+
+```bash
+# Server settings
+export HOST="0.0.0.0"
+export PORT="8000"
+export RELOAD="true"  # Auto-reload on code changes
+```
+
+## Important Files
+
+- `main.py`: FastAPI application entry point
+- `pyarchinit_mini/__init__.py`: Package exports (DatabaseManager, services)
+- `pyarchinit_mini/database/manager.py`: Generic CRUD operations, query builder
+- `pyarchinit_mini/database/connection.py`: Session management, DB connection
+- `pyarchinit_mini/api/dependencies.py`: FastAPI dependency injection for DB
+- `requirements.txt`: Python dependencies
+- `pyproject.toml`: Project metadata, tool configuration (black, mypy, pytest)
+
+## Common Gotchas
+
+1. **Detached Instance Errors**: Always convert models to DTOs within session context before returning from services
+2. **Foreign Key Constraints**: Remember SQLite needs PRAGMA foreign_keys=ON (already configured)
+3. **Session Lifecycle**: Never store SQLAlchemy model instances beyond session scope
+4. **Relationship Loading**: Use eager loading (joinedload) for relationships accessed outside sessions
+5. **Database URL Format**: PostgreSQL uses `postgresql://` not `postgres://`
+
+## Adding New Features
+
+### Adding a New Model
+
+1. Create model in `pyarchinit_mini/models/your_model.py` extending `BaseModel`
+2. Add DTO in `pyarchinit_mini/dto/your_dto.py`
+3. Create service in `pyarchinit_mini/services/your_service.py`
+4. Add API router in `pyarchinit_mini/api/your_router.py`
+5. Register router in `pyarchinit_mini/api/__init__.py` `create_app()`
+6. Run migrations to create table
+7. Add tests in `tests/unit/test_your_service.py`
+
+### Adding a New API Endpoint
+
+1. Use dependency injection for database access:
+   ```python
+   from .dependencies import get_db_manager
+
+   @router.get("/")
+   async def list_items(db_manager: DatabaseManager = Depends(get_db_manager)):
+       service = YourService(db_manager)
+       return service.get_all_items_dto()
+   ```
+
+2. Use Pydantic schemas for request/response validation
+3. Follow REST conventions (GET for read, POST for create, PUT for update, DELETE for delete)
+4. Return DTOs, not raw SQLAlchemy models
+
+## Testing Guidelines
+
+- Use pytest fixtures from `tests/conftest.py` for database setup
+- Each test should use a fresh database session
+- Test both SQLite and PostgreSQL code paths for schema changes
+- Mock external dependencies (file system, network) in unit tests
+- Integration tests should test full service layer operations

pyarchinit_mini-0.1.1/MANIFEST.in

@@ -0,0 +1,39 @@
+# MANIFEST.in - Specifies additional files to include in the distribution
+
+# Include documentation
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CLAUDE.md
+
+# Include configuration files
+include pyproject.toml
+include setup.py
+include requirements.txt
+
+# Include data files
+recursive-include data *.db *.sql
+recursive-include pyarchinit_mini/data *.db *.sql
+
+# Include web interface templates and static files
+recursive-include web_interface/templates *.html
+recursive-include web_interface/static *.css *.js *.png *.jpg *.ico
+
+# Include desktop GUI assets
+recursive-include desktop_gui *.png *.ico *.gif
+
+# Include CLI configurations
+recursive-include cli_interface *.json *.yaml
+
+# Include package configs
+recursive-include pyarchinit_mini *.yaml *.yml *.json
+
+# Exclude unnecessary files
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store
+recursive-exclude tests *
+recursive-exclude docs *
+recursive-exclude examples *
+recursive-exclude .venv *
+recursive-exclude .git *

pyarchinit_mini-0.1.1/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: pyarchinit-mini
+Version: 0.1.1
+Summary: Lightweight archaeological data management system with REST API, Web UI, Desktop GUI, and CLI
+Home-page: https://github.com/pyarchinit/pyarchinit-mini
+Author: PyArchInit Team
+Author-email: PyArchInit Team <enzo.ccc@gmail.com>
+License: GPL-2.0
+Project-URL: Homepage, https://github.com/pyarchinit/pyarchinit-mini
+Project-URL: Documentation, https://pyarchinit-mini.readthedocs.io/
+Project-URL: Repository, https://github.com/pyarchinit/pyarchinit-mini
+Project-URL: Bug Tracker, https://github.com/pyarchinit/pyarchinit-mini/issues
+Keywords: archaeology,archaeological data,heritage,cultural heritage,database,api,stratigraphy,excavation,harris matrix,finds inventory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: alembic>=1.12.0
+Requires-Dist: networkx>=3.0.0
+Requires-Dist: reportlab>=4.0.0
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: cli
+Requires-Dist: click>=8.1.0; extra == "cli"
+Requires-Dist: rich>=13.0.0; extra == "cli"
+Requires-Dist: inquirer>=3.0.0; extra == "cli"
+Provides-Extra: web
+Requires-Dist: flask>=3.0.0; extra == "web"
+Requires-Dist: flask-wtf>=1.2.0; extra == "web"
+Requires-Dist: wtforms>=3.1.0; extra == "web"
+Requires-Dist: jinja2>=3.1.0; extra == "web"
+Provides-Extra: gui
+Requires-Dist: pillow>=10.0.0; extra == "gui"
+Provides-Extra: harris
+Requires-Dist: matplotlib>=3.7.0; extra == "harris"
+Requires-Dist: graphviz>=0.20.0; extra == "harris"
+Provides-Extra: pdf
+Requires-Dist: weasyprint>=60.0.0; extra == "pdf"
+Provides-Extra: media
+Requires-Dist: python-magic>=0.4.0; extra == "media"
+Requires-Dist: moviepy>=1.0.0; extra == "media"
+Provides-Extra: all
+Requires-Dist: click>=8.1.0; extra == "all"
+Requires-Dist: rich>=13.0.0; extra == "all"
+Requires-Dist: inquirer>=3.0.0; extra == "all"
+Requires-Dist: flask>=3.0.0; extra == "all"
+Requires-Dist: flask-wtf>=1.2.0; extra == "all"
+Requires-Dist: wtforms>=3.1.0; extra == "all"
+Requires-Dist: jinja2>=3.1.0; extra == "all"
+Requires-Dist: matplotlib>=3.7.0; extra == "all"
+Requires-Dist: graphviz>=0.20.0; extra == "all"
+Requires-Dist: weasyprint>=60.0.0; extra == "all"
+Requires-Dist: python-magic>=0.4.0; extra == "all"
+Requires-Dist: moviepy>=1.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
+Requires-Dist: myst-parser>=1.0.0; extra == "docs"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# PyArchInit-Mini
+
+**Lightweight Archaeological Data Management System**
+
+PyArchInit-Mini is a standalone, modular version of PyArchInit focused on core archaeological data management functionality without GIS dependencies. It provides multiple interfaces and a clean, scalable API for managing archaeological sites, stratigraphic units, and material inventories.
+
+## Features
+
+### Core Data Management
+- 🏛️ **Site Management**: Complete CRUD operations for archaeological sites
+- 📋 **Stratigraphic Units (US)**: Manage stratigraphic contexts and excavation data  
+- 📦 **Material Inventory**: Track and catalog archaeological finds
+- 🗄️ **Multi-Database Support**: Works with both PostgreSQL and SQLite
+
+### Advanced Archaeological Tools
+- 🔗 **Harris Matrix**: Generate and visualize stratigraphic relationships
+- 📄 **PDF Export**: Create comprehensive archaeological reports
+- 🖼️ **Media Management**: Handle images, documents, and multimedia files
+- 📊 **Statistics & Reports**: Comprehensive data analysis and reporting
+
+### Multiple User Interfaces
+- 🌐 **Web Interface**: Modern Flask-based web application with Bootstrap UI
+- 🖥️ **Desktop GUI**: Complete Tkinter desktop application
+- 💻 **CLI Interface**: Rich-based interactive command-line interface
+- 🚀 **REST API**: FastAPI-based scalable API with automatic documentation
+
+### Technical Features
+- 📊 **Data Validation**: Comprehensive validation using Pydantic schemas
+- 🔍 **Search & Filtering**: Advanced search and filtering capabilities
+- 📖 **Auto Documentation**: Interactive API docs via Swagger/OpenAPI
+- 🔄 **Session Management**: Proper database session handling and connection pooling
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install pyarchinit-mini
+```
+
+### Interface Options
+
+PyArchInit-Mini provides multiple ways to interact with your archaeological data:
+
+#### 1. Web Interface (Flask)
+Modern web application with responsive Bootstrap UI:
+
+```bash
+cd pyarchinit-mini
+python web_interface/app.py
+```
+
+Visit `http://localhost:5000` to access the web interface.
+
+#### 2. Desktop GUI (Tkinter)
+Complete desktop application with rich interface:
+
+```bash
+cd pyarchinit-mini
+python desktop_gui/gui_app.py
+# OR use the quick launcher:
+python run_gui.py
+```
+
+#### 3. CLI Interface (Rich)
+Interactive command-line interface:
+
+```bash
+cd pyarchinit-mini
+python cli_interface/cli_app.py
+```
+
+#### 4. REST API Server (FastAPI)
+Scalable API server with automatic documentation:
+
+```bash
+cd pyarchinit-mini
+python main.py
+```
+
+Visit `http://localhost:8000/docs` for interactive API documentation.
+
+### Basic Usage
+
+#### As a Python Library
+
+```python
+from pyarchinit_mini import DatabaseManager, SiteService
+from pyarchinit_mini.database import DatabaseConnection
+
+# Connect to database
+db_conn = DatabaseConnection.sqlite("archaeological_data.db")
+db_manager = DatabaseManager(db_conn)
+
+# Use services
+site_service = SiteService(db_manager)
+
+# Create a new site
+site_data = {
+    "sito": "Pompei",
+    "nazione": "Italia",
+    "regione": "Campania", 
+    "comune": "Pompei",
+    "provincia": "NA",
+    "descrizione": "Ancient Roman city"
+}
+
+site = site_service.create_site(site_data)
+print(f"Created site: {site.display_name}")
+```
+
+#### Database Configuration
+
+All interfaces support both SQLite and PostgreSQL. Configure via environment variable:
+
+```bash
+# SQLite (default)
+export DATABASE_URL="sqlite:///./pyarchinit_mini.db"
+
+# PostgreSQL
+export DATABASE_URL="postgresql://user:password@localhost:5432/pyarchinit"
+```
+
+## API Endpoints
+
+### Sites
+- `GET /api/v1/sites/` - List sites with pagination and filtering
+- `POST /api/v1/sites/` - Create new site
+- `GET /api/v1/sites/{site_id}` - Get site by ID
+- `PUT /api/v1/sites/{site_id}` - Update site
+- `DELETE /api/v1/sites/{site_id}` - Delete site
+
+### Stratigraphic Units (US)
+- `GET /api/v1/us/` - List stratigraphic units
+- `POST /api/v1/us/` - Create new US
+- `GET /api/v1/us/{us_id}` - Get US by ID
+- `PUT /api/v1/us/{us_id}` - Update US
+- `DELETE /api/v1/us/{us_id}` - Delete US
+
+### Material Inventory
+- `GET /api/v1/inventario/` - List inventory items
+- `POST /api/v1/inventario/` - Create new inventory item
+- `GET /api/v1/inventario/{item_id}` - Get item by ID
+- `PUT /api/v1/inventario/{item_id}` - Update item
+- `DELETE /api/v1/inventario/{item_id}` - Delete item
+
+## Special Features
+
+### Harris Matrix Generation
+PyArchInit-Mini includes advanced Harris Matrix functionality:
+
+```python
+from pyarchinit_mini.harris_matrix import HarrisMatrixGenerator, MatrixVisualizer
+
+# Generate Harris Matrix for a site
+matrix_generator = HarrisMatrixGenerator(db_manager)
+graph = matrix_generator.generate_matrix("Pompei")
+levels = matrix_generator.get_matrix_levels(graph)
+stats = matrix_generator.get_matrix_statistics(graph)
+
+# Visualize and export
+visualizer = MatrixVisualizer()
+exports = visualizer.export_to_formats(graph, levels, "pompei_matrix")
+```
+
+### PDF Report Generation
+Create comprehensive archaeological reports:
+
+```python
+from pyarchinit_mini.pdf_export import PDFGenerator
+
+pdf_generator = PDFGenerator()
+site_data = site_service.get_site_by_id(1).to_dict()
+us_data = [us.to_dict() for us in us_service.get_us_by_site("Pompei")]
+inventory_data = [inv.to_dict() for inv in inventario_service.get_inventario_by_site("Pompei")]
+
+pdf_bytes = pdf_generator.generate_site_report(site_data, us_data, inventory_data)
+
+with open("site_report.pdf", "wb") as f:
+    f.write(pdf_bytes)
+```
+
+### Media Management
+Handle multimedia files with automatic organization:
+
+```python
+from pyarchinit_mini.media_manager import MediaHandler
+
+media_handler = MediaHandler()
+metadata = media_handler.store_file(
+    "/path/to/photo.jpg",
+    "site",
+    1,  # site ID
+    "Excavation photo of area A"
+)
+```
+
+## Database Support
+
+### SQLite (Default)
+```python
+from pyarchinit_mini.database import DatabaseConnection
+
+db_conn = DatabaseConnection.sqlite("path/to/database.db")
+```
+
+### PostgreSQL
+```python
+from pyarchinit_mini.database import DatabaseConnection
+
+db_conn = DatabaseConnection.postgresql(
+    host="localhost",
+    port=5432, 
+    database="pyarchinit",
+    username="user",
+    password="password"
+)
+```
+
+## Data Models
+
+### Site
+Core information about archaeological sites including location, description, and metadata.
+
+### Stratigraphic Unit (US) 
+Represents stratigraphic contexts with excavation data, relationships, measurements, and dating information.
+
+### Material Inventory
+Catalog of archaeological finds with classification, measurements, conservation data, and contextual information.
+
+## Architecture
+
+PyArchInit-Mini follows a clean, modular architecture:
+
+- **Models**: SQLAlchemy entities defining database structure
+- **Services**: Business logic layer with validation and operations
+- **API**: FastAPI REST endpoints with Pydantic schemas
+- **Database**: Connection management and query abstractions
+
+## Development
+
+### Setup Development Environment
+
+```bash
+git clone https://github.com/pyarchinit/pyarchinit-mini.git
+cd pyarchinit-mini
+pip install -e ".[dev]"
+```
+
+### Run Tests
+
+```bash
+pytest
+```
+
+### Code Quality
+
+```bash
+black pyarchinit_mini/
+flake8 pyarchinit_mini/
+mypy pyarchinit_mini/
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main repository.
+
+## License
+
+PyArchInit-Mini is licensed under the GNU General Public License v2.0. See [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- [PyArchInit](https://github.com/pyarchinit/pyarchinit3) - Full QGIS plugin version
+- [PyArchInit Documentation](https://pyarchinit.github.io/pyarchinit_doc/)
+
+## Support
+
+- 📧 Email: enzo.ccc@gmail.com
+- 🐛 Issue Tracker: [GitHub Issues](https://github.com/pyarchinit/pyarchinit-mini/issues)
+- 📖 Documentation: [Read the Docs](https://pyarchinit-mini.readthedocs.io/)
+
+---
+
+Made with ❤️ by the PyArchInit Team