chore: restructured project, updated readme
This commit is contained in:
216
MIGRATION_GUIDE.md
Normal file
216
MIGRATION_GUIDE.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Migration Guide: New File Structure
|
||||
|
||||
## Overview
|
||||
|
||||
The codebase has been reorganized to improve clarity, maintainability, and separation of concerns. This guide shows how to update your imports.
|
||||
|
||||
## New Structure Summary
|
||||
|
||||
```
|
||||
src/
|
||||
├── core/ # Domain models & constants (formerly in logic/)
|
||||
├── database/ # Data persistence (formerly in backend/)
|
||||
├── services/ # External APIs (from backend/ and logic/)
|
||||
├── parsers/ # File parsing (formerly in logic/)
|
||||
├── documents/ # Document generation (formerly in utils/)
|
||||
├── background/ # Threading tasks (formerly in backend/)
|
||||
├── admin/ # Admin commands (formerly in backend/)
|
||||
├── shared/ # Cross-cutting concerns (logging, config)
|
||||
├── utils/ # Pure utilities
|
||||
├── ui/ # UI components (unchanged)
|
||||
└── errors/ # Custom exceptions (unchanged)
|
||||
```
|
||||
|
||||
## Import Changes
|
||||
|
||||
### Core Domain Models
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.logic import BookData, Prof, Semester, Apparat
|
||||
from src.logic.dataclass import BookData, Prof
|
||||
from src.logic.semester import Semester
|
||||
from src.logic.constants import APP_NRS, SEMAP_MEDIA_ACCOUNTS
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.core.models import BookData, Prof, Semester, Apparat, ApparatData
|
||||
from src.core import BookData, Prof, Semester # Can use shorthand
|
||||
from src.core.semester import Semester
|
||||
from src.core.constants import APP_NRS, SEMAP_MEDIA_ACCOUNTS
|
||||
```
|
||||
|
||||
### Database
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.backend import Database
|
||||
from src.backend.database import Database
|
||||
from src.backend.db import CREATE_TABLE_MEDIA
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.database import Database
|
||||
from src.database.connection import Database # If you need specific module
|
||||
from src.database.schemas import CREATE_TABLE_MEDIA
|
||||
```
|
||||
|
||||
### External Services & APIs
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.backend.catalogue import Catalogue
|
||||
from src.backend.webadis import get_book_medianr
|
||||
from src.logic.SRU import SWB
|
||||
from src.logic.lehmannsapi import LehmannsClient
|
||||
from src.logic.zotero import ZoteroController
|
||||
from src.logic.webrequest import BibTextTransformer, WebRequest
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.services import Catalogue, SWB, LehmannsClient, ZoteroController
|
||||
from src.services.catalogue import Catalogue
|
||||
from src.services.webadis import get_book_medianr
|
||||
from src.services.sru import SWB
|
||||
from src.services.lehmanns import LehmannsClient
|
||||
from src.services.zotero import ZoteroController
|
||||
from src.services.webrequest import BibTextTransformer, WebRequest
|
||||
```
|
||||
|
||||
### Parsers
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.logic import csv_to_list, word_to_semap
|
||||
from src.logic.csvparser import csv_to_list
|
||||
from src.logic.wordparser import word_to_semap
|
||||
from src.logic.pdfparser import pdf_to_text
|
||||
from src.logic.xmlparser import xml_to_dict
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.parsers import csv_to_list, word_to_semap # Lazy loading
|
||||
from src.parsers.csv_parser import csv_to_list
|
||||
from src.parsers.word_parser import word_to_semap
|
||||
from src.parsers.pdf_parser import pdf_to_text
|
||||
from src.parsers.xml_parser import xml_to_dict
|
||||
```
|
||||
|
||||
### Document Generation
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.utils.richtext import create_document, create_pdf
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.documents import create_document, create_pdf
|
||||
from src.documents.generators import create_document, create_pdf
|
||||
```
|
||||
|
||||
### Background Tasks
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.backend import AutoAdder, AvailChecker, BookGrabber
|
||||
from src.backend.threads_autoadder import AutoAdder
|
||||
from src.backend.threads_availchecker import AvailChecker
|
||||
from src.backend.thread_bookgrabber import BookGrabber
|
||||
from src.backend.thread_neweditions import NewEditionCheckerThread
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.background import AutoAdder, AvailChecker, BookGrabber, NewEditionCheckerThread
|
||||
from src.background.autoadder import AutoAdder
|
||||
from src.background.availability_checker import AvailChecker
|
||||
from src.background.book_grabber import BookGrabber
|
||||
from src.background.new_editions import NewEditionCheckerThread
|
||||
```
|
||||
|
||||
### Admin Commands
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.backend import AdminCommands
|
||||
from src.backend.admin_console import AdminCommands
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.admin import AdminCommands
|
||||
from src.admin.commands import AdminCommands
|
||||
```
|
||||
|
||||
### Configuration & Logging
|
||||
|
||||
**OLD:**
|
||||
```python
|
||||
from src.backend.settings import Settings
|
||||
from src.logic.settings import Settings
|
||||
from src.shared.logging import log # This stays the same
|
||||
```
|
||||
|
||||
**NEW:**
|
||||
```python
|
||||
from src.shared import Settings, load_config, log
|
||||
from src.shared.config import Settings, load_config
|
||||
from src.shared.logging import log
|
||||
```
|
||||
|
||||
## File Renames
|
||||
|
||||
| Old Path | New Path |
|
||||
|----------|----------|
|
||||
| `logic/dataclass.py` | `core/models.py` |
|
||||
| `logic/SRU.py` | `services/sru.py` |
|
||||
| `logic/lehmannsapi.py` | `services/lehmanns.py` |
|
||||
| `backend/database.py` | `database/connection.py` |
|
||||
| `backend/db.py` | `database/schemas.py` |
|
||||
| `backend/threads_autoadder.py` | `background/autoadder.py` |
|
||||
| `backend/threads_availchecker.py` | `background/availability_checker.py` |
|
||||
| `backend/thread_bookgrabber.py` | `background/book_grabber.py` |
|
||||
| `backend/thread_neweditions.py` | `background/new_editions.py` |
|
||||
| `backend/admin_console.py` | `admin/commands.py` |
|
||||
| `utils/richtext.py` | `documents/generators.py` |
|
||||
| `logic/csvparser.py` | `parsers/csv_parser.py` |
|
||||
| `logic/pdfparser.py` | `parsers/pdf_parser.py` |
|
||||
| `logic/wordparser.py` | `parsers/word_parser.py` |
|
||||
| `logic/xmlparser.py` | `parsers/xml_parser.py` |
|
||||
|
||||
## Quick Migration Checklist
|
||||
|
||||
1. ✅ Update all `from src.backend import Database` → `from src.database import Database`
|
||||
2. ✅ Update all `from src.logic import BookData` → `from src.core.models import BookData`
|
||||
3. ✅ Update all `from src.backend.catalogue` → `from src.services.catalogue`
|
||||
4. ✅ Update all `from src.logic.SRU` → `from src.services.sru`
|
||||
5. ✅ Update all `from src.backend.admin_console` → `from src.admin`
|
||||
6. ✅ Update threading imports from `src.backend.thread*` → `src.background.*`
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Clearer architecture**: Each folder has a specific, well-defined purpose
|
||||
- **Better dependency flow**: core → database/services → background → ui
|
||||
- **Reduced duplication**: Merged 3 duplicate files (pickles.py, settings.py)
|
||||
- **Easier navigation**: Intuitive folder names ("services" vs "logic")
|
||||
- **Scalability**: Clear extension points for new features
|
||||
|
||||
## Backwards Compatibility
|
||||
|
||||
The old `backend/` and `logic/` folders still exist with original files. They will be removed in a future cleanup phase after thorough testing.
|
||||
|
||||
## Questions?
|
||||
|
||||
If you encounter import errors:
|
||||
1. Check this guide for the new import path
|
||||
2. Search for the class/function name in the new structure
|
||||
3. Most moves follow the pattern: external APIs → `services/`, data models → `core/`, threads → `background/`
|
||||
|
||||
## Status
|
||||
|
||||
✅ **Migration Complete** - Application successfully starts and runs with new structure!
|
||||
Reference in New Issue
Block a user