zync-py 0.1.0__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.
- zync/__init__.py +23 -0
- zync/cli/__init__.py +1 -0
- zync/cli/app.py +183 -0
- zync/core/__init__.py +21 -0
- zync/core/attachments.py +57 -0
- zync/core/concurrency.py +22 -0
- zync/core/folders.py +184 -0
- zync/core/library.py +89 -0
- zync/core/patterns.py +86 -0
- zync/core/removals.py +57 -0
- zync/core/settings.py +27 -0
- zync/core/sync/__init__.py +2 -0
- zync/core/sync/additions.py +61 -0
- zync/core/sync/deletions.py +95 -0
- zync/core/sync/index.py +85 -0
- zync/core/sync/paths.py +7 -0
- zync/core/sync/report.py +37 -0
- zync/core/sync/zync.py +133 -0
- zync/infra/__init__.py +10 -0
- zync/infra/disk.py +30 -0
- zync/infra/zotero/__init__.py +11 -0
- zync/infra/zotero/credentials.py +33 -0
- zync/infra/zotero/library.py +278 -0
- zync/py.typed +0 -0
- zync_py-0.1.0.dist-info/METADATA +138 -0
- zync_py-0.1.0.dist-info/RECORD +29 -0
- zync_py-0.1.0.dist-info/WHEEL +4 -0
- zync_py-0.1.0.dist-info/entry_points.txt +2 -0
- zync_py-0.1.0.dist-info/licenses/LICENSE +21 -0
zync/__init__.py
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
from .cli import main as main
|
|
2
|
+
from .core import (
|
|
3
|
+
AttachedFiles as AttachedFiles,
|
|
4
|
+
Attachment as Attachment,
|
|
5
|
+
AttachmentMode as AttachmentMode,
|
|
6
|
+
CollectionPath as CollectionPath,
|
|
7
|
+
CollectionUpdate as CollectionUpdate,
|
|
8
|
+
FolderTree as FolderTree,
|
|
9
|
+
InvalidPatternError as InvalidPatternError,
|
|
10
|
+
LinkedFile as LinkedFile,
|
|
11
|
+
RemovalMode as RemovalMode,
|
|
12
|
+
StoredFile as StoredFile,
|
|
13
|
+
SyncReport as SyncReport,
|
|
14
|
+
SyncSettings as SyncSettings,
|
|
15
|
+
ZoteroLibrary as ZoteroLibrary,
|
|
16
|
+
Zync as Zync,
|
|
17
|
+
attachments as attachments,
|
|
18
|
+
removals as removals,
|
|
19
|
+
)
|
|
20
|
+
from .infra import (
|
|
21
|
+
LocalFolderTree as LocalFolderTree,
|
|
22
|
+
ZoteroDesktopLibrary as ZoteroDesktopLibrary,
|
|
23
|
+
)
|
zync/cli/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
from .app import main as main
|
zync/cli/app.py
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
from collections.abc import Iterator
|
|
2
|
+
from contextlib import contextmanager
|
|
3
|
+
from enum import StrEnum
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Annotated, NoReturn
|
|
6
|
+
|
|
7
|
+
from zync.core import (
|
|
8
|
+
CollectionUpdate,
|
|
9
|
+
InvalidPatternError,
|
|
10
|
+
SyncReport,
|
|
11
|
+
SyncSettings,
|
|
12
|
+
Zync,
|
|
13
|
+
attachments,
|
|
14
|
+
removals,
|
|
15
|
+
)
|
|
16
|
+
from zync.infra import (
|
|
17
|
+
LocalAuthorizationError,
|
|
18
|
+
LocalFolderTree,
|
|
19
|
+
MissingLocalApiKeyError,
|
|
20
|
+
ZoteroDesktopLibrary,
|
|
21
|
+
ZoteroWriteError,
|
|
22
|
+
authorize_local_api,
|
|
23
|
+
load_local_api_key,
|
|
24
|
+
save_local_api_key,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
import httpx2
|
|
28
|
+
import trio
|
|
29
|
+
import typer
|
|
30
|
+
from pyzotero import LocalAPIDeniedError
|
|
31
|
+
|
|
32
|
+
DEFAULT_SETTINGS = SyncSettings()
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class AttachmentModeName(StrEnum):
|
|
36
|
+
LINK = "link"
|
|
37
|
+
COPY = "copy"
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class RemovalModeName(StrEnum):
|
|
41
|
+
TRASH = "trash"
|
|
42
|
+
KEEP = "keep"
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
ATTACHMENT_MODES = {
|
|
46
|
+
AttachmentModeName.LINK: attachments.link,
|
|
47
|
+
AttachmentModeName.COPY: attachments.copy,
|
|
48
|
+
}
|
|
49
|
+
REMOVAL_MODES = {
|
|
50
|
+
RemovalModeName.TRASH: removals.trash,
|
|
51
|
+
RemovalModeName.KEEP: removals.keep,
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
app = typer.Typer(
|
|
55
|
+
help="Sync folders of PDFs into Zotero collections.",
|
|
56
|
+
no_args_is_help=True,
|
|
57
|
+
add_completion=False,
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def main() -> None:
|
|
62
|
+
"""Run the command line interface."""
|
|
63
|
+
app()
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@app.command()
|
|
67
|
+
def authorize() -> None:
|
|
68
|
+
"""Allow Zync to change your Zotero library.
|
|
69
|
+
|
|
70
|
+
Choose "Always Allow" when Zotero asks.
|
|
71
|
+
"""
|
|
72
|
+
with _reported_errors():
|
|
73
|
+
key_file = trio.run(_authorize)
|
|
74
|
+
typer.echo(
|
|
75
|
+
f"Zotero allowed Zync to change your library. The permission is saved in {key_file}"
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@app.command()
|
|
80
|
+
def sync(
|
|
81
|
+
root: Annotated[
|
|
82
|
+
Path,
|
|
83
|
+
typer.Argument(help="The root folder to search.", exists=True, file_okay=False),
|
|
84
|
+
] = Path(),
|
|
85
|
+
*,
|
|
86
|
+
folder_pattern: Annotated[
|
|
87
|
+
list[str],
|
|
88
|
+
typer.Option(
|
|
89
|
+
default_factory=lambda: list(DEFAULT_SETTINGS.folder_patterns),
|
|
90
|
+
help="A pattern for the folders to sync. Repeat it for several patterns.",
|
|
91
|
+
show_default="{*}/**/Literature",
|
|
92
|
+
),
|
|
93
|
+
],
|
|
94
|
+
skipped_folder: Annotated[
|
|
95
|
+
list[str],
|
|
96
|
+
typer.Option(
|
|
97
|
+
default_factory=lambda: sorted(DEFAULT_SETTINGS.skipped_folder_names),
|
|
98
|
+
help="A folder name that is not searched. Repeat it for several names.",
|
|
99
|
+
show_default=".git, .venv, node_modules",
|
|
100
|
+
),
|
|
101
|
+
],
|
|
102
|
+
file_extension: Annotated[
|
|
103
|
+
list[str],
|
|
104
|
+
typer.Option(
|
|
105
|
+
default_factory=lambda: sorted(DEFAULT_SETTINGS.file_extensions),
|
|
106
|
+
help="An extension of the files to add. Repeat it for several extensions.",
|
|
107
|
+
show_default=".pdf",
|
|
108
|
+
),
|
|
109
|
+
],
|
|
110
|
+
attachment_mode: Annotated[
|
|
111
|
+
AttachmentModeName,
|
|
112
|
+
typer.Option(
|
|
113
|
+
help="link: Zotero opens each file where it is. "
|
|
114
|
+
"copy: Zotero keeps its own copy."
|
|
115
|
+
),
|
|
116
|
+
] = AttachmentModeName.LINK,
|
|
117
|
+
removal_mode: Annotated[
|
|
118
|
+
RemovalModeName,
|
|
119
|
+
typer.Option(
|
|
120
|
+
help="What happens in Zotero when a file is deleted from a synced folder. "
|
|
121
|
+
"trash: Zotero moves it to the trash. keep: Zotero keeps it."
|
|
122
|
+
),
|
|
123
|
+
] = RemovalModeName.TRASH,
|
|
124
|
+
) -> None:
|
|
125
|
+
"""Add the files of every synced folder to Zotero."""
|
|
126
|
+
settings = SyncSettings(
|
|
127
|
+
folder_patterns=tuple(folder_pattern),
|
|
128
|
+
skipped_folder_names=frozenset(skipped_folder),
|
|
129
|
+
file_extensions=frozenset(file_extension),
|
|
130
|
+
attachment_mode=ATTACHMENT_MODES[attachment_mode](),
|
|
131
|
+
removal_mode=REMOVAL_MODES[removal_mode](),
|
|
132
|
+
)
|
|
133
|
+
with _reported_errors():
|
|
134
|
+
report = trio.run(_synchronize, root.resolve(), settings)
|
|
135
|
+
for update in report.collection_updates:
|
|
136
|
+
typer.echo(_describe(update))
|
|
137
|
+
for deleted_file in report.deleted_files:
|
|
138
|
+
typer.echo(f"Deleted from its synced folder: {deleted_file}")
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
async def _authorize() -> Path:
|
|
142
|
+
return await save_local_api_key(await authorize_local_api())
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
async def _synchronize(root: Path, settings: SyncSettings) -> SyncReport:
|
|
146
|
+
zync = Zync(
|
|
147
|
+
root=root,
|
|
148
|
+
folder_tree=LocalFolderTree(),
|
|
149
|
+
library=ZoteroDesktopLibrary(await load_local_api_key()),
|
|
150
|
+
settings=settings,
|
|
151
|
+
)
|
|
152
|
+
return await zync.synchronize()
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _describe(update: CollectionUpdate) -> str:
|
|
156
|
+
return (
|
|
157
|
+
f"{' / '.join(update.collection_path)}: "
|
|
158
|
+
f"attached {len(update.new_files)} new files, "
|
|
159
|
+
f"added {len(update.existing_files)} files that were already in Zotero"
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
@contextmanager
|
|
164
|
+
def _reported_errors() -> Iterator[None]:
|
|
165
|
+
try:
|
|
166
|
+
yield
|
|
167
|
+
except httpx2.ConnectError:
|
|
168
|
+
_fail(
|
|
169
|
+
"Zotero is not running: expected its local API on port 23119, found nothing."
|
|
170
|
+
)
|
|
171
|
+
except (
|
|
172
|
+
MissingLocalApiKeyError,
|
|
173
|
+
LocalAuthorizationError,
|
|
174
|
+
LocalAPIDeniedError,
|
|
175
|
+
ZoteroWriteError,
|
|
176
|
+
InvalidPatternError,
|
|
177
|
+
) as error:
|
|
178
|
+
_fail(str(error))
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def _fail(message: str) -> NoReturn:
|
|
182
|
+
typer.secho(message, err=True, fg=typer.colors.RED)
|
|
183
|
+
raise typer.Exit(code=1)
|
zync/core/__init__.py
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
from .attachments import (
|
|
2
|
+
AttachmentMode as AttachmentMode,
|
|
3
|
+
attachments as attachments,
|
|
4
|
+
)
|
|
5
|
+
from .folders import FolderTree as FolderTree
|
|
6
|
+
from .library import (
|
|
7
|
+
AttachedFiles as AttachedFiles,
|
|
8
|
+
Attachment as Attachment,
|
|
9
|
+
CollectionPath as CollectionPath,
|
|
10
|
+
LinkedFile as LinkedFile,
|
|
11
|
+
StoredFile as StoredFile,
|
|
12
|
+
ZoteroLibrary as ZoteroLibrary,
|
|
13
|
+
)
|
|
14
|
+
from .patterns import InvalidPatternError as InvalidPatternError
|
|
15
|
+
from .removals import RemovalMode as RemovalMode, removals as removals
|
|
16
|
+
from .settings import SyncSettings as SyncSettings
|
|
17
|
+
from .sync import (
|
|
18
|
+
CollectionUpdate as CollectionUpdate,
|
|
19
|
+
SyncReport as SyncReport,
|
|
20
|
+
Zync as Zync,
|
|
21
|
+
)
|
zync/core/attachments.py
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
from pathlib import Path
|
|
2
|
+
from typing import Protocol
|
|
3
|
+
|
|
4
|
+
from zync.core.library import CollectionPath, ZoteroLibrary
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class AttachmentMode(Protocol):
|
|
8
|
+
"""How new files are added to the library."""
|
|
9
|
+
|
|
10
|
+
async def attach(
|
|
11
|
+
self,
|
|
12
|
+
files: list[Path],
|
|
13
|
+
*,
|
|
14
|
+
library: ZoteroLibrary,
|
|
15
|
+
collection_path: CollectionPath,
|
|
16
|
+
) -> None:
|
|
17
|
+
"""Add the files to the collection as new attachments.
|
|
18
|
+
|
|
19
|
+
The collection must exist.
|
|
20
|
+
"""
|
|
21
|
+
...
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class _Link:
|
|
25
|
+
async def attach(
|
|
26
|
+
self,
|
|
27
|
+
files: list[Path],
|
|
28
|
+
*,
|
|
29
|
+
library: ZoteroLibrary,
|
|
30
|
+
collection_path: CollectionPath,
|
|
31
|
+
) -> None:
|
|
32
|
+
await library.link_files(files, collection_path)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class _Copy:
|
|
36
|
+
async def attach(
|
|
37
|
+
self,
|
|
38
|
+
files: list[Path],
|
|
39
|
+
*,
|
|
40
|
+
library: ZoteroLibrary,
|
|
41
|
+
collection_path: CollectionPath,
|
|
42
|
+
) -> None:
|
|
43
|
+
await library.store_files(files, collection_path)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class attachments:
|
|
47
|
+
"""The ways to add new files to the library."""
|
|
48
|
+
|
|
49
|
+
@staticmethod
|
|
50
|
+
def link() -> AttachmentMode:
|
|
51
|
+
"""Add each file as a linked file, which Zotero opens from its place on disk."""
|
|
52
|
+
return _Link()
|
|
53
|
+
|
|
54
|
+
@staticmethod
|
|
55
|
+
def copy() -> AttachmentMode:
|
|
56
|
+
"""Add a copy of each file to the library's own storage."""
|
|
57
|
+
return _Copy()
|
zync/core/concurrency.py
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
from collections.abc import Awaitable, Callable
|
|
2
|
+
|
|
3
|
+
import trio
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
async def map_concurrently[Item, Result](
|
|
7
|
+
function: Callable[[Item], Awaitable[Result]], items: list[Item]
|
|
8
|
+
) -> list[Result]:
|
|
9
|
+
"""Call the function on every item at the same time.
|
|
10
|
+
|
|
11
|
+
Returns:
|
|
12
|
+
The results in the order of the items.
|
|
13
|
+
"""
|
|
14
|
+
results: dict[int, Result] = {}
|
|
15
|
+
|
|
16
|
+
async def run(index: int, item: Item) -> None:
|
|
17
|
+
results[index] = await function(item)
|
|
18
|
+
|
|
19
|
+
async with trio.open_nursery() as nursery:
|
|
20
|
+
for index, item in enumerate(items):
|
|
21
|
+
nursery.start_soon(run, index, item)
|
|
22
|
+
return [results[index] for index in range(len(items))]
|
zync/core/folders.py
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
from dataclasses import dataclass
|
|
2
|
+
from pathlib import Path, PurePosixPath
|
|
3
|
+
from typing import Protocol
|
|
4
|
+
|
|
5
|
+
from zync.core.concurrency import map_concurrently
|
|
6
|
+
from zync.core.library import CollectionPath
|
|
7
|
+
from zync.core.patterns import FolderPattern
|
|
8
|
+
from zync.core.settings import SyncSettings
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class FolderTree(Protocol):
|
|
12
|
+
"""Read access to the folders and files below a root folder."""
|
|
13
|
+
|
|
14
|
+
async def subfolders(self, folder: Path) -> list[Path]:
|
|
15
|
+
"""Return the folders directly inside the folder, sorted by path."""
|
|
16
|
+
...
|
|
17
|
+
|
|
18
|
+
async def files(self, folder: Path) -> list[Path]:
|
|
19
|
+
"""Return the files directly inside the folder, sorted by path."""
|
|
20
|
+
...
|
|
21
|
+
|
|
22
|
+
async def md5(self, file: Path) -> str:
|
|
23
|
+
"""Return the MD5 hex digest of the file's content."""
|
|
24
|
+
...
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@dataclass(frozen=True)
|
|
28
|
+
class SyncedFile:
|
|
29
|
+
"""A file in a synced folder.
|
|
30
|
+
|
|
31
|
+
Attributes:
|
|
32
|
+
path: The path of the file, below the root folder.
|
|
33
|
+
collection_path: The names of the folders in curly braces in the
|
|
34
|
+
pattern that matched the synced folder, followed by the names of
|
|
35
|
+
the folders between the synced folder and the file.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
path: Path
|
|
39
|
+
collection_path: CollectionPath
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
async def find_synced_files(
|
|
43
|
+
*,
|
|
44
|
+
root: Path,
|
|
45
|
+
folder_tree: FolderTree,
|
|
46
|
+
patterns: list[FolderPattern],
|
|
47
|
+
settings: SyncSettings,
|
|
48
|
+
) -> list[SyncedFile]:
|
|
49
|
+
"""Return the files of every synced folder below the root.
|
|
50
|
+
|
|
51
|
+
A synced folder is a folder whose path relative to the root matches
|
|
52
|
+
one of the patterns. When several patterns match, the first one names the
|
|
53
|
+
collections. A synced folder inside another synced folder counts
|
|
54
|
+
as an ordinary subfolder of the outer one.
|
|
55
|
+
"""
|
|
56
|
+
return await _FolderSearch(
|
|
57
|
+
root=root, folder_tree=folder_tree, patterns=patterns, settings=settings
|
|
58
|
+
).files()
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def is_in_synced_folder(
|
|
62
|
+
file: Path,
|
|
63
|
+
*,
|
|
64
|
+
root: Path,
|
|
65
|
+
folder_tree: FolderTree,
|
|
66
|
+
patterns: list[FolderPattern],
|
|
67
|
+
settings: SyncSettings,
|
|
68
|
+
) -> bool:
|
|
69
|
+
"""Return whether the file would be synced if it existed.
|
|
70
|
+
|
|
71
|
+
The check uses only the path, so it also applies to files and folders
|
|
72
|
+
that were deleted.
|
|
73
|
+
"""
|
|
74
|
+
return _FolderSearch(
|
|
75
|
+
root=root, folder_tree=folder_tree, patterns=patterns, settings=settings
|
|
76
|
+
).is_in_synced_folder(file)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@dataclass(frozen=True)
|
|
80
|
+
class _SyncedFolder:
|
|
81
|
+
path: Path
|
|
82
|
+
collection_path: CollectionPath
|
|
83
|
+
|
|
84
|
+
def synced_file(self, file: Path) -> SyncedFile:
|
|
85
|
+
subfolder_names = file.parent.relative_to(self.path).parts
|
|
86
|
+
return SyncedFile(
|
|
87
|
+
path=file, collection_path=(*self.collection_path, *subfolder_names)
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
@dataclass(frozen=True)
|
|
92
|
+
class _FolderSearch:
|
|
93
|
+
root: Path
|
|
94
|
+
folder_tree: FolderTree
|
|
95
|
+
patterns: list[FolderPattern]
|
|
96
|
+
settings: SyncSettings
|
|
97
|
+
|
|
98
|
+
async def files(self) -> list[SyncedFile]:
|
|
99
|
+
synced_folders = await self._synced_folders_below(self.root)
|
|
100
|
+
return _flattened(await map_concurrently(self._synced_files_in, synced_folders))
|
|
101
|
+
|
|
102
|
+
def is_in_synced_folder(self, file: Path) -> bool:
|
|
103
|
+
return (
|
|
104
|
+
file.is_relative_to(self.root)
|
|
105
|
+
and self._has_synchronized_extension(file)
|
|
106
|
+
and not self._is_in_skipped_folder(file)
|
|
107
|
+
and any(
|
|
108
|
+
self._matching_patterns(folder) for folder in self._folders_above(file)
|
|
109
|
+
)
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
async def _synced_folders_below(self, folder: Path) -> list[_SyncedFolder]:
|
|
113
|
+
subfolders = await self._searched_subfolders(folder)
|
|
114
|
+
return _flattened(
|
|
115
|
+
await map_concurrently(self._synced_folders_at_or_below, subfolders)
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
async def _synced_folders_at_or_below(self, folder: Path) -> list[_SyncedFolder]:
|
|
119
|
+
matching_patterns = self._matching_patterns(folder)
|
|
120
|
+
if matching_patterns:
|
|
121
|
+
return [self._synced_folder(folder, matching_patterns[0])]
|
|
122
|
+
return await self._synced_folders_below(folder)
|
|
123
|
+
|
|
124
|
+
def _synced_folder(self, folder: Path, pattern: FolderPattern) -> _SyncedFolder:
|
|
125
|
+
return _SyncedFolder(
|
|
126
|
+
path=folder,
|
|
127
|
+
collection_path=pattern.collection_path(self._relative_path(folder)),
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
async def _synced_files_in(self, synced_folder: _SyncedFolder) -> list[SyncedFile]:
|
|
131
|
+
return [
|
|
132
|
+
synced_folder.synced_file(file)
|
|
133
|
+
for file in await self._synchronized_files_below(synced_folder.path)
|
|
134
|
+
]
|
|
135
|
+
|
|
136
|
+
async def _synchronized_files_below(self, folder: Path) -> list[Path]:
|
|
137
|
+
subfolders = await self._searched_subfolders(folder)
|
|
138
|
+
files_in_subfolders = await map_concurrently(
|
|
139
|
+
self._synchronized_files_below, subfolders
|
|
140
|
+
)
|
|
141
|
+
return await self._synchronized_files_in(folder) + _flattened(
|
|
142
|
+
files_in_subfolders
|
|
143
|
+
)
|
|
144
|
+
|
|
145
|
+
async def _synchronized_files_in(self, folder: Path) -> list[Path]:
|
|
146
|
+
return [
|
|
147
|
+
file
|
|
148
|
+
for file in await self.folder_tree.files(folder)
|
|
149
|
+
if self._has_synchronized_extension(file)
|
|
150
|
+
]
|
|
151
|
+
|
|
152
|
+
async def _searched_subfolders(self, folder: Path) -> list[Path]:
|
|
153
|
+
return [
|
|
154
|
+
subfolder
|
|
155
|
+
for subfolder in await self.folder_tree.subfolders(folder)
|
|
156
|
+
if not self._is_skipped(subfolder)
|
|
157
|
+
]
|
|
158
|
+
|
|
159
|
+
def _is_in_skipped_folder(self, file: Path) -> bool:
|
|
160
|
+
return any(self._is_skipped(folder) for folder in self._folders_above(file))
|
|
161
|
+
|
|
162
|
+
def _is_skipped(self, folder: Path) -> bool:
|
|
163
|
+
return folder.name in self.settings.skipped_folder_names
|
|
164
|
+
|
|
165
|
+
def _folders_above(self, file: Path) -> list[Path]:
|
|
166
|
+
relative_folders = file.relative_to(self.root).parents[:-1]
|
|
167
|
+
return [self.root / folder for folder in relative_folders]
|
|
168
|
+
|
|
169
|
+
def _matching_patterns(self, folder: Path) -> list[FolderPattern]:
|
|
170
|
+
relative_path = self._relative_path(folder)
|
|
171
|
+
return [pattern for pattern in self.patterns if pattern.matches(relative_path)]
|
|
172
|
+
|
|
173
|
+
def _relative_path(self, folder: Path) -> PurePosixPath:
|
|
174
|
+
# A POSIX path makes "/" the separator and matching case-sensitive on every platform.
|
|
175
|
+
return PurePosixPath(folder.relative_to(self.root).as_posix())
|
|
176
|
+
|
|
177
|
+
def _has_synchronized_extension(self, file: Path) -> bool:
|
|
178
|
+
return file.suffix.lower() in {
|
|
179
|
+
extension.lower() for extension in self.settings.file_extensions
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _flattened[Entry](lists: list[list[Entry]]) -> list[Entry]:
|
|
184
|
+
return [entry for entries in lists for entry in entries]
|
zync/core/library.py
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
from dataclasses import dataclass
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
from typing import Protocol
|
|
4
|
+
|
|
5
|
+
type CollectionPath = tuple[str, ...]
|
|
6
|
+
"""The names of a collection and its parent collections, starting at the top level."""
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass(frozen=True)
|
|
10
|
+
class Attachment:
|
|
11
|
+
"""An attachment in the library and the top-level item it belongs to.
|
|
12
|
+
|
|
13
|
+
Attributes:
|
|
14
|
+
key: The key of the attachment.
|
|
15
|
+
item_key: The key of the top-level item: the parent of the attachment,
|
|
16
|
+
or the attachment itself when it has no parent.
|
|
17
|
+
item_attachment_keys: The keys of all attachments of the top-level
|
|
18
|
+
item, this one included.
|
|
19
|
+
collection_paths: The collections that the top-level item is in.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
key: str
|
|
23
|
+
item_key: str
|
|
24
|
+
item_attachment_keys: frozenset[str]
|
|
25
|
+
collection_paths: frozenset[CollectionPath]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class LinkedFile:
|
|
30
|
+
"""A file on disk that a linked-file attachment in the library points to."""
|
|
31
|
+
|
|
32
|
+
path: Path
|
|
33
|
+
attachment: Attachment
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass(frozen=True)
|
|
37
|
+
class StoredFile:
|
|
38
|
+
"""A copy of a file that the library stores itself.
|
|
39
|
+
|
|
40
|
+
Attributes:
|
|
41
|
+
md5: The MD5 hex digest of the stored content.
|
|
42
|
+
title: The title of the attachment.
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
md5: str
|
|
46
|
+
title: str
|
|
47
|
+
attachment: Attachment
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
@dataclass(frozen=True)
|
|
51
|
+
class AttachedFiles:
|
|
52
|
+
"""The files that the attachments in the library hold."""
|
|
53
|
+
|
|
54
|
+
linked_files: list[LinkedFile]
|
|
55
|
+
stored_files: list[StoredFile]
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class ZoteroLibrary(Protocol):
|
|
59
|
+
"""The Zotero library that the sync writes to."""
|
|
60
|
+
|
|
61
|
+
async def ensure_collection(self, collection_path: CollectionPath) -> None:
|
|
62
|
+
"""Create the collection and its parent collections where they are missing."""
|
|
63
|
+
...
|
|
64
|
+
|
|
65
|
+
async def attached_files(self) -> AttachedFiles:
|
|
66
|
+
"""Return the files that the attachments outside the trash link to or store."""
|
|
67
|
+
...
|
|
68
|
+
|
|
69
|
+
async def add_to_collection(
|
|
70
|
+
self, item_key: str, collection_path: CollectionPath
|
|
71
|
+
) -> None:
|
|
72
|
+
"""Add the item to the collection, which must exist."""
|
|
73
|
+
...
|
|
74
|
+
|
|
75
|
+
async def link_files(
|
|
76
|
+
self, files: list[Path], collection_path: CollectionPath
|
|
77
|
+
) -> None:
|
|
78
|
+
"""Add one standalone linked-file attachment per file to the collection."""
|
|
79
|
+
...
|
|
80
|
+
|
|
81
|
+
async def store_files(
|
|
82
|
+
self, files: list[Path], collection_path: CollectionPath
|
|
83
|
+
) -> None:
|
|
84
|
+
"""Add one standalone attachment with a stored copy per file to the collection."""
|
|
85
|
+
...
|
|
86
|
+
|
|
87
|
+
async def trash(self, keys: list[str]) -> None:
|
|
88
|
+
"""Move the items or attachments with these keys to the trash."""
|
|
89
|
+
...
|
zync/core/patterns.py
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
from pathlib import PurePosixPath
|
|
2
|
+
|
|
3
|
+
from zync.core.library import CollectionPath
|
|
4
|
+
|
|
5
|
+
ANY_FOLDERS = "**"
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class InvalidPatternError(Exception):
|
|
9
|
+
"""A folder pattern cannot be used."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class FolderPattern:
|
|
13
|
+
"""A glob pattern for the path of a synced folder, relative to the root folder.
|
|
14
|
+
|
|
15
|
+
Segments are separated by "/", "*" matches any part of one folder name,
|
|
16
|
+
"**" matches any number of folders, and matching is case-sensitive. A
|
|
17
|
+
segment in curly braces, such as "{*}", matches like the glob inside them,
|
|
18
|
+
and the name of the folder it matches becomes a collection.
|
|
19
|
+
|
|
20
|
+
Raises:
|
|
21
|
+
InvalidPatternError: The pattern names no collection, it names a
|
|
22
|
+
collection after a segment between two "**" segments, or curly
|
|
23
|
+
braces enclose only part of a segment.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
def __init__(self, pattern: str) -> None:
|
|
27
|
+
segments = pattern.split("/")
|
|
28
|
+
for segment in segments:
|
|
29
|
+
_check_curly_braces(segment, pattern)
|
|
30
|
+
self._glob = "/".join(_glob_of(segment) for segment in segments)
|
|
31
|
+
self._collection_positions = _collection_positions(segments, pattern)
|
|
32
|
+
|
|
33
|
+
def matches(self, relative_path: PurePosixPath) -> bool:
|
|
34
|
+
return relative_path.full_match(self._glob)
|
|
35
|
+
|
|
36
|
+
def collection_path(self, relative_path: PurePosixPath) -> CollectionPath:
|
|
37
|
+
"""Return the names of the folders that name collections, for a path that `matches`."""
|
|
38
|
+
return tuple(
|
|
39
|
+
relative_path.parts[position] for position in self._collection_positions
|
|
40
|
+
)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _check_curly_braces(segment: str, pattern: str) -> None:
|
|
44
|
+
has_curly_braces = "{" in segment or "}" in segment
|
|
45
|
+
if has_curly_braces and not _names_collection(segment):
|
|
46
|
+
raise InvalidPatternError(
|
|
47
|
+
f'Pattern "{pattern}": expected curly braces around a whole folder name, '
|
|
48
|
+
f'found "{segment}".'
|
|
49
|
+
)
|
|
50
|
+
if _names_collection(segment) and _glob_of(segment) in {"", ANY_FOLDERS}:
|
|
51
|
+
raise InvalidPatternError(
|
|
52
|
+
f'Pattern "{pattern}": expected a glob for one folder name inside curly braces, '
|
|
53
|
+
f'found "{segment}".'
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _collection_positions(segments: list[str], pattern: str) -> list[int]:
|
|
58
|
+
collection_indices = [
|
|
59
|
+
index for index, segment in enumerate(segments) if _names_collection(segment)
|
|
60
|
+
]
|
|
61
|
+
if not collection_indices:
|
|
62
|
+
raise InvalidPatternError(
|
|
63
|
+
f'Pattern "{pattern}": expected at least one folder in curly braces to name a '
|
|
64
|
+
"collection, found none."
|
|
65
|
+
)
|
|
66
|
+
return [_position(index, segments, pattern) for index in collection_indices]
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _position(index: int, segments: list[str], pattern: str) -> int:
|
|
70
|
+
any_folders_before = ANY_FOLDERS in segments[:index]
|
|
71
|
+
any_folders_after = ANY_FOLDERS in segments[index + 1 :]
|
|
72
|
+
if any_folders_before and any_folders_after:
|
|
73
|
+
raise InvalidPatternError(
|
|
74
|
+
f'Pattern "{pattern}": expected "{segments[index]}" at a fixed distance from '
|
|
75
|
+
'the start or the end of the path, found "**" on both sides of it.'
|
|
76
|
+
)
|
|
77
|
+
# Behind a "**", the folder's position is only fixed when counted from the end.
|
|
78
|
+
return index - len(segments) if any_folders_before else index
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _names_collection(segment: str) -> bool:
|
|
82
|
+
return segment.startswith("{") and segment.endswith("}")
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _glob_of(segment: str) -> str:
|
|
86
|
+
return segment[1:-1] if _names_collection(segment) else segment
|