zotlib 0.4.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
zotlib/config.py ADDED
@@ -0,0 +1,184 @@
1
+ """Configuration management for zotlib."""
2
+
3
+ import os
4
+ from pathlib import Path
5
+
6
+ CONFIG_FILE = "zotlib.toml"
7
+
8
+
9
+ def load_config() -> dict:
10
+ """Load configuration from zotlib.toml if it exists.
11
+
12
+ Returns a dict with keys like 'database', 'pdfs_dir' or empty dict.
13
+ """
14
+ config_path = Path(CONFIG_FILE)
15
+ if not config_path.exists():
16
+ return {}
17
+
18
+ try:
19
+ import tomllib
20
+ except ModuleNotFoundError:
21
+ import tomli as tomllib
22
+
23
+ text = config_path.read_text()
24
+ data = tomllib.loads(text)
25
+ return data.get("zotlib", {})
26
+
27
+
28
+ def discover_zotero_database() -> Path | None:
29
+ """Attempt to auto-discover Zotero database location.
30
+
31
+ Checks common locations across different platforms.
32
+ """
33
+ user = os.environ.get("USER", "")
34
+
35
+ candidates = [
36
+ # Linux (native)
37
+ Path.home() / "Zotero" / "zotero.sqlite",
38
+ # WSL accessing Windows
39
+ Path(f"/mnt/c/Users/{user}/Zotero/zotero.sqlite"),
40
+ # macOS
41
+ Path.home() / "Library" / "Zotero" / "zotero.sqlite",
42
+ ]
43
+
44
+ # Windows (if APPDATA exists)
45
+ appdata = os.environ.get("APPDATA")
46
+ if appdata:
47
+ candidates.append(Path(appdata) / "Zotero" / "Zotero" / "zotero.sqlite")
48
+
49
+ for candidate in candidates:
50
+ if candidate.exists():
51
+ return candidate
52
+
53
+ return None
54
+
55
+
56
+ def _windows_to_wsl_path(win_path: str) -> Path:
57
+ """Convert a Windows path to a WSL /mnt/ path."""
58
+ from pathlib import PureWindowsPath
59
+
60
+ p = PureWindowsPath(win_path)
61
+ drive = p.drive.rstrip(":").lower()
62
+ return Path(f"/mnt/{drive}") / p.relative_to(p.anchor)
63
+
64
+
65
+ def discover_pdfs_dir(check_exists: bool = True) -> Path | None:
66
+ """Discover the linked attachments directory from Zotero preferences.
67
+
68
+ Reads baseAttachmentPath from prefs.js in the Zotero profile directory.
69
+ Set check_exists=False to return the path even if not currently accessible.
70
+ """
71
+ user = os.environ.get("USER", "")
72
+
73
+ profile_dirs = [
74
+ # WSL
75
+ Path(f"/mnt/c/Users/{user}/AppData/Roaming/Zotero/Zotero/Profiles"),
76
+ # Linux
77
+ Path.home() / ".zotero" / "zotero" / "Profiles",
78
+ # macOS
79
+ Path.home() / "Library" / "Application Support" / "Zotero" / "Profiles",
80
+ ]
81
+
82
+ for profile_dir in profile_dirs:
83
+ if not profile_dir.exists():
84
+ continue
85
+ for prefs_file in profile_dir.glob("*/prefs.js"):
86
+ for line in prefs_file.read_text(errors="ignore").splitlines():
87
+ if "extensions.zotero.baseAttachmentPath" in line and "better-bibtex" not in line:
88
+ # Extract value from: user_pref("...", "value");
89
+ value = line.split('"')[-2]
90
+ # Convert Windows path if needed
91
+ if "\\" in value or (len(value) > 1 and value[1] == ":"):
92
+ path = _windows_to_wsl_path(value)
93
+ else:
94
+ path = Path(value)
95
+ if not check_exists or path.exists():
96
+ return path
97
+
98
+ return None
99
+
100
+
101
+ def get_database_path(explicit_path: Path | str | None = None) -> Path:
102
+ """Get the Zotero database path.
103
+
104
+ Priority order:
105
+ 1. Explicit path argument (CLI flag)
106
+ 2. ZOTERO_DATABASE environment variable
107
+ 3. zotlib.toml config file
108
+ 4. Auto-discovery
109
+
110
+ Raises:
111
+ FileNotFoundError: If no database can be found.
112
+ """
113
+ # Check explicit path
114
+ if explicit_path:
115
+ path = Path(explicit_path)
116
+ if path.exists():
117
+ return path
118
+ raise FileNotFoundError(f"Zotero database not found at: {path}")
119
+
120
+ # Check environment variable
121
+ env_path = os.environ.get("ZOTERO_DATABASE")
122
+ if env_path:
123
+ path = Path(env_path)
124
+ if path.exists():
125
+ return path
126
+ raise FileNotFoundError(f"ZOTERO_DATABASE path does not exist: {path}")
127
+
128
+ # Check config file
129
+ config = load_config()
130
+ if "database" in config:
131
+ path = Path(config["database"])
132
+ if path.exists():
133
+ return path
134
+
135
+ # Try auto-discovery
136
+ discovered = discover_zotero_database()
137
+ if discovered:
138
+ return discovered
139
+
140
+ raise FileNotFoundError(
141
+ "Could not find Zotero database. "
142
+ "Run 'zotlib init', set ZOTERO_DATABASE, or use --database flag."
143
+ )
144
+
145
+
146
+ def get_pdfs_dir(explicit_path: Path | str | None = None) -> Path | None:
147
+ """Get the linked PDFs directory.
148
+
149
+ Priority order:
150
+ 1. Explicit path argument (CLI flag)
151
+ 2. zotlib.toml config file
152
+ 3. Auto-discovery from Zotero preferences
153
+
154
+ Returns None if no directory can be found.
155
+ """
156
+ if explicit_path:
157
+ path = Path(explicit_path)
158
+ if path.exists():
159
+ return path
160
+ return None
161
+
162
+ # Check config file
163
+ config = load_config()
164
+ if "pdfs_dir" in config:
165
+ path = Path(config["pdfs_dir"])
166
+ if path.exists():
167
+ return path
168
+
169
+ # Try auto-discovery
170
+ return discover_pdfs_dir()
171
+
172
+
173
+ def write_config(database: Path, pdfs_dir: Path | None = None) -> Path:
174
+ """Write configuration to zotlib.toml.
175
+
176
+ Returns the path to the config file.
177
+ """
178
+ config_path = Path(CONFIG_FILE)
179
+ lines = ["[zotlib]", f'database = "{database}"']
180
+ if pdfs_dir:
181
+ lines.append(f'pdfs_dir = "{pdfs_dir}"')
182
+ lines.append("") # trailing newline
183
+ config_path.write_text("\n".join(lines))
184
+ return config_path
zotlib/covers.py ADDED
@@ -0,0 +1,113 @@
1
+ """Generate cover images from first page of PDFs in a Zotero collection."""
2
+
3
+ from pathlib import Path
4
+
5
+ import fitz
6
+ import polars as pl
7
+
8
+ from zotlib.database import ZoteroDatabase
9
+ from zotlib.extractors import extract_attachments, extract_collections, extract_items
10
+ from zotlib.paths import resolve_pdf_path
11
+
12
+
13
+ def render_first_page(pdf_path: Path, output_path: Path, dpi: int = 300) -> None:
14
+ """Render the first page of a PDF as a PNG image."""
15
+ doc = fitz.open(pdf_path)
16
+ page = doc[0]
17
+ zoom = dpi / 72
18
+ matrix = fitz.Matrix(zoom, zoom)
19
+ pixmap = page.get_pixmap(matrix=matrix)
20
+ pixmap.save(str(output_path))
21
+ doc.close()
22
+
23
+
24
+ def generate_thumbnails(
25
+ input_dir: Path,
26
+ output_dir: Path,
27
+ width: int = 400,
28
+ ) -> int:
29
+ """Resize cover images to thumbnail size.
30
+
31
+ Args:
32
+ input_dir: Directory containing full-size cover PNGs.
33
+ output_dir: Directory to write thumbnails.
34
+ width: Target width in pixels (height scales proportionally).
35
+
36
+ Returns:
37
+ Number of thumbnails generated.
38
+ """
39
+ from PIL import Image
40
+
41
+ output_dir.mkdir(parents=True, exist_ok=True)
42
+ count = 0
43
+
44
+ for png_path in sorted(input_dir.glob("*-cover.png")):
45
+ img = Image.open(png_path)
46
+ scale = width / img.width
47
+ height = int(img.height * scale)
48
+ thumb = img.resize((width, height), Image.Resampling.LANCZOS)
49
+
50
+ thumb_name = png_path.stem.replace("-cover", "-thumb") + ".png"
51
+ thumb.save(output_dir / thumb_name)
52
+ count += 1
53
+
54
+ return count
55
+
56
+
57
+ def generate_covers(
58
+ db: ZoteroDatabase,
59
+ collection_name: str,
60
+ output_dir: Path,
61
+ dpi: int = 300,
62
+ pdfs_dir: Path | None = None,
63
+ ) -> tuple[dict[int, Path], list[str]]:
64
+ """Generate first-page cover images for all PDFs in a collection.
65
+
66
+ Returns:
67
+ Tuple of (dict mapping parentItemID to cover image path,
68
+ list of skipped item descriptions).
69
+ """
70
+ storage_dir = db.database_path.parent / "storage"
71
+
72
+ # Get items in the collection
73
+ collections = extract_collections(db)
74
+ collection_items = collections.filter(pl.col("collectionName") == collection_name)
75
+ if len(collection_items) == 0:
76
+ raise ValueError(f"Collection not found: {collection_name}")
77
+
78
+ item_ids = set(collection_items["itemID"].to_list())
79
+
80
+ # Get all items for titles
81
+ items = extract_items(db)
82
+ items_in_collection = items.filter(pl.col("itemID").is_in(list(item_ids)))
83
+ title_map = dict(
84
+ zip(
85
+ items_in_collection["itemID"].to_list(),
86
+ items_in_collection["title"].to_list(),
87
+ )
88
+ )
89
+
90
+ # Get PDF attachments
91
+ attachments = extract_attachments(db)
92
+ attachments = attachments.filter(pl.col("parentItemID").is_in(list(item_ids)))
93
+
94
+ output_dir.mkdir(parents=True, exist_ok=True)
95
+
96
+ cover_paths: dict[int, Path] = {}
97
+ skipped = []
98
+
99
+ for row in attachments.iter_rows(named=True):
100
+ parent_id = row["parentItemID"]
101
+ title = title_map.get(parent_id, f"item_{parent_id}")
102
+
103
+ pdf_path = resolve_pdf_path(storage_dir, row["key"], row["path"], pdfs_dir=pdfs_dir)
104
+ if not pdf_path.exists():
105
+ skipped.append(f"{title} ({pdf_path})")
106
+ continue
107
+
108
+ bibkey = pdf_path.stem
109
+ output_path = output_dir / f"{bibkey}-cover.png"
110
+ render_first_page(pdf_path, output_path, dpi=dpi)
111
+ cover_paths[parent_id] = output_path
112
+
113
+ return cover_paths, skipped
zotlib/database.py ADDED
@@ -0,0 +1,67 @@
1
+ """Database connection and query utilities for Zotero SQLite."""
2
+
3
+ import sqlite3
4
+ from collections.abc import Iterator
5
+ from contextlib import contextmanager
6
+ from pathlib import Path
7
+
8
+ import polars as pl
9
+
10
+
11
+ class ZoteroDatabase:
12
+ """Read-only interface to Zotero SQLite database."""
13
+
14
+ def __init__(self, database_path: Path | str):
15
+ """Initialize database connection.
16
+
17
+ Args:
18
+ database_path: Path to zotero.sqlite file.
19
+
20
+ Raises:
21
+ FileNotFoundError: If database file doesn't exist.
22
+ """
23
+ self.database_path = Path(database_path)
24
+ if not self.database_path.exists():
25
+ raise FileNotFoundError(f"Zotero database not found: {self.database_path}")
26
+
27
+ @contextmanager
28
+ def connection(self) -> Iterator[sqlite3.Connection]:
29
+ """Context manager for read-only database connection."""
30
+ # Use file URI with mode=ro for read-only access
31
+ uri = f"file:{self.database_path}?mode=ro"
32
+ conn = sqlite3.connect(uri, uri=True)
33
+ try:
34
+ yield conn
35
+ finally:
36
+ conn.close()
37
+
38
+ def get_table_names(self) -> list[str]:
39
+ """Get all table names in the database."""
40
+ with self.connection() as conn:
41
+ cursor = conn.cursor()
42
+ cursor.execute("SELECT name FROM sqlite_master WHERE type='table';")
43
+ return [row[0] for row in cursor.fetchall()]
44
+
45
+ def get_column_names(self, table_name: str) -> list[str]:
46
+ """Get column names for a table."""
47
+ with self.connection() as conn:
48
+ cursor = conn.cursor()
49
+ cursor.execute(f"SELECT * FROM {table_name} LIMIT 0")
50
+ return [desc[0] for desc in cursor.description]
51
+
52
+ def query(self, sql: str, params: list | tuple | None = None) -> pl.DataFrame:
53
+ """Execute a query and return results as DataFrame.
54
+
55
+ Args:
56
+ sql: SQL query string.
57
+ params: Optional query parameters for ? placeholders.
58
+
59
+ Returns:
60
+ DataFrame with query results.
61
+ """
62
+ with self.connection() as conn:
63
+ cursor = conn.cursor()
64
+ cursor.execute(sql, params or [])
65
+ columns = [desc[0] for desc in cursor.description]
66
+ rows = cursor.fetchall()
67
+ return pl.DataFrame({col: [row[i] for row in rows] for i, col in enumerate(columns)})