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/__init__.py +24 -0
- zotlib/backup.py +98 -0
- zotlib/cli.py +448 -0
- zotlib/config.py +184 -0
- zotlib/covers.py +113 -0
- zotlib/database.py +67 -0
- zotlib/exporters.py +601 -0
- zotlib/extractors.py +230 -0
- zotlib/formatters/__init__.py +5 -0
- zotlib/formatters/apa.py +86 -0
- zotlib/paths.py +43 -0
- zotlib/tables.py +828 -0
- zotlib-0.4.3.dist-info/METADATA +219 -0
- zotlib-0.4.3.dist-info/RECORD +16 -0
- zotlib-0.4.3.dist-info/WHEEL +4 -0
- zotlib-0.4.3.dist-info/entry_points.txt +2 -0
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)})
|