zync-py 0.1.0__tar.gz

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.
@@ -0,0 +1,26 @@
1
+ # Python-generated files
2
+ __pycache__/
3
+ *.py[oc]
4
+ build/
5
+ dist/
6
+ wheels/
7
+ *.egg-info
8
+ .coverage
9
+
10
+ # Environment files
11
+ .env
12
+ .env.*
13
+
14
+ # Virtual environments, caches, and IDE settings
15
+ .venv
16
+ .vscode
17
+ .pytest_cache
18
+ .ruff_cache
19
+ .zed
20
+
21
+ # Documentation build
22
+ site/
23
+
24
+ # Agent Files
25
+ CLAUDE.md
26
+ .claude/
zync_py-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zurab Mujirishvili
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
zync_py-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,138 @@
1
+ Metadata-Version: 2.5
2
+ Name: zync-py
3
+ Version: 0.1.0
4
+ Summary: Sync folders of PDFs into Zotero collections.
5
+ Project-URL: Homepage, https://gitlab.com/zurabm/zync
6
+ Project-URL: Repository, https://gitlab.com/zurabm/zync
7
+ Project-URL: Bug Tracker, https://gitlab.com/zurabm/zync/-/issues
8
+ Project-URL: Changelog, https://gitlab.com/zurabm/zync/-/blob/main/CHANGELOG.md
9
+ Author-email: Zurab Mujirishvili <zurab.mu@gmail.com>
10
+ License-File: LICENSE
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Typing :: Typed
18
+ Requires-Python: >=3.13
19
+ Requires-Dist: httpx2>=2.12.0
20
+ Requires-Dist: platformdirs>=4.3.0
21
+ Requires-Dist: pyzotero>=1.16.0
22
+ Requires-Dist: trio>=0.35.0
23
+ Requires-Dist: typer>=0.29.1
24
+ Description-Content-Type: text/markdown
25
+
26
+ # Zync
27
+
28
+ Sync folders of PDFs into Zotero [collections](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#collection).
29
+
30
+ Zync adds the PDFs you keep in folders to Zotero and sorts them into collections that match your folders.
31
+
32
+ ```text
33
+ Root/ Zotero
34
+ ├── Topics/ ├── Topics
35
+ │ └── Literature/ │ ├── paper-a.pdf
36
+ │ ├── paper-a.pdf │ └── Humanoids
37
+ │ └── Humanoids/ │ └── paper-b.pdf
38
+ │ └── paper-b.pdf └── Thesis
39
+ └── Thesis/ └── paper-c.pdf
40
+ └── Proposal/
41
+ └── Literature/
42
+ └── paper-c.pdf
43
+ ```
44
+
45
+ ## Installation
46
+
47
+ Python 3.13+ and the Zotero 10 desktop app are required. Zotero must be running during a sync.
48
+
49
+ ```bash
50
+ uv tool install zync-py
51
+ ```
52
+
53
+ Or run it without installing, with `uvx --from zync-py zync ...`. The package is named `zync-py` on PyPI, and the command is `zync`.
54
+
55
+ ## Usage
56
+
57
+ Zotero has to allow Zync to change your library. Run this once, and choose "Always Allow" when Zotero asks:
58
+
59
+ ```bash
60
+ zync authorize
61
+ ```
62
+
63
+ Then synchronize a [root folder](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#root-folder):
64
+
65
+ ```bash
66
+ zync sync path/to/root
67
+ ```
68
+
69
+ | Option | Default | Meaning |
70
+ | ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
71
+ | `--folder-pattern` | `{*}/**/Literature` | Where the [synced folders](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#synced-folder) are, see [Folder patterns](#folder-patterns) |
72
+ | `--skipped-folder` | `.git`, `.venv`, `node_modules` | A folder name that Zync does not search |
73
+ | `--file-extension` | `.pdf` | An extension of the files to add |
74
+ | `--attachment-mode` | `link` | `link` or `copy`, see [How the sync works](#how-the-sync-works) |
75
+ | `--removal-mode` | `trash` | `trash` or `keep`, see [How the sync works](#how-the-sync-works) |
76
+
77
+ The first three options can be given several times.
78
+
79
+ ### How the sync works
80
+
81
+ Zync syncs the folders that match a [pattern](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#folder-pattern), by default every folder named `Literature`. Each synced folder gets a collection, named after the folder directly below the root folder that contains it. Subfolders become subcollections. [Folder patterns](#folder-patterns) shows how to choose other folders and names.
82
+
83
+ New files are added in one of two ways:
84
+
85
+ - `link` (the default): Zotero adds a [linked file](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#linked-file) and opens the file where it is. There is no second copy.
86
+ - `copy`: Zotero keeps its own [stored copy](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#stored-copy).
87
+
88
+ When you delete a file from a synced folder, Zync moves its [item](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#item) to the Zotero trash, where you can still restore it. If the item has other files, only the deleted file goes to the trash. With `--removal-mode keep`, Zync does not remove Zotero items when files are deleted.
89
+
90
+ Synchronizing with Zync is [idempotent](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#idempotent). If a file is already in Zotero, Zync puts the existing item into the collection instead of adding the file again. In copy mode, a file that changed replaces its old copy.
91
+
92
+ ### Folder patterns
93
+
94
+ A pattern describes where your synced folders are, as a path below the root folder. `*` stands for any folder name, and `**` for any number of folders. Put a folder in curly braces, `{ }`, to name a collection after it.
95
+
96
+ The default, `{*}/**/Literature`, finds every `Literature` folder and names its collection after the top folder it is in. Some other patterns:
97
+
98
+ ```bash
99
+ zync sync . --folder-pattern "{*}/**/Literature" --folder-pattern "{*}/**/References" # also References folders
100
+ zync sync . --folder-pattern "{Topics}/**/Literature" # only below Topics
101
+ zync sync . --folder-pattern "{*}/{*}/Literature" # a collection with a subcollection
102
+ zync sync . --folder-pattern "**/{*}/Literature" # named after the folder that holds Literature
103
+ zync sync . --folder-pattern "Topics/{*}" # every folder in Topics
104
+ ```
105
+
106
+ Every pattern needs at least one folder in curly braces.
107
+
108
+ ### Running it on a schedule
109
+
110
+ On Windows, this registers a task that synchronizes every 10 minutes without opening a console window:
111
+
112
+ ```powershell
113
+ Register-ScheduledTask -TaskName "Zync" `
114
+ -Action (New-ScheduledTaskAction -Execute (Get-Command uvw).Source -Argument 'tool run --from zync-py zync sync "C:\path\to\root"') `
115
+ -Trigger (New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes 10)) `
116
+ -Settings (New-ScheduledTaskSettingsSet -StartWhenAvailable -MultipleInstances IgnoreNew)
117
+ ```
118
+
119
+ ## Development
120
+
121
+ Get set up:
122
+
123
+ ```bash
124
+ git clone https://gitlab.com/zurabm/zync.git
125
+ cd zync
126
+ uv sync
127
+ uv run pre-commit install
128
+ ```
129
+
130
+ Run all checks (lint, format, type-check, import layers, tests):
131
+
132
+ ```bash
133
+ just check
134
+ ```
135
+
136
+ ## License
137
+
138
+ MIT
@@ -0,0 +1,113 @@
1
+ # Zync
2
+
3
+ Sync folders of PDFs into Zotero [collections](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#collection).
4
+
5
+ Zync adds the PDFs you keep in folders to Zotero and sorts them into collections that match your folders.
6
+
7
+ ```text
8
+ Root/ Zotero
9
+ ├── Topics/ ├── Topics
10
+ │ └── Literature/ │ ├── paper-a.pdf
11
+ │ ├── paper-a.pdf │ └── Humanoids
12
+ │ └── Humanoids/ │ └── paper-b.pdf
13
+ │ └── paper-b.pdf └── Thesis
14
+ └── Thesis/ └── paper-c.pdf
15
+ └── Proposal/
16
+ └── Literature/
17
+ └── paper-c.pdf
18
+ ```
19
+
20
+ ## Installation
21
+
22
+ Python 3.13+ and the Zotero 10 desktop app are required. Zotero must be running during a sync.
23
+
24
+ ```bash
25
+ uv tool install zync-py
26
+ ```
27
+
28
+ Or run it without installing, with `uvx --from zync-py zync ...`. The package is named `zync-py` on PyPI, and the command is `zync`.
29
+
30
+ ## Usage
31
+
32
+ Zotero has to allow Zync to change your library. Run this once, and choose "Always Allow" when Zotero asks:
33
+
34
+ ```bash
35
+ zync authorize
36
+ ```
37
+
38
+ Then synchronize a [root folder](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#root-folder):
39
+
40
+ ```bash
41
+ zync sync path/to/root
42
+ ```
43
+
44
+ | Option | Default | Meaning |
45
+ | ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
46
+ | `--folder-pattern` | `{*}/**/Literature` | Where the [synced folders](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#synced-folder) are, see [Folder patterns](#folder-patterns) |
47
+ | `--skipped-folder` | `.git`, `.venv`, `node_modules` | A folder name that Zync does not search |
48
+ | `--file-extension` | `.pdf` | An extension of the files to add |
49
+ | `--attachment-mode` | `link` | `link` or `copy`, see [How the sync works](#how-the-sync-works) |
50
+ | `--removal-mode` | `trash` | `trash` or `keep`, see [How the sync works](#how-the-sync-works) |
51
+
52
+ The first three options can be given several times.
53
+
54
+ ### How the sync works
55
+
56
+ Zync syncs the folders that match a [pattern](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#folder-pattern), by default every folder named `Literature`. Each synced folder gets a collection, named after the folder directly below the root folder that contains it. Subfolders become subcollections. [Folder patterns](#folder-patterns) shows how to choose other folders and names.
57
+
58
+ New files are added in one of two ways:
59
+
60
+ - `link` (the default): Zotero adds a [linked file](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#linked-file) and opens the file where it is. There is no second copy.
61
+ - `copy`: Zotero keeps its own [stored copy](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#stored-copy).
62
+
63
+ When you delete a file from a synced folder, Zync moves its [item](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#item) to the Zotero trash, where you can still restore it. If the item has other files, only the deleted file goes to the trash. With `--removal-mode keep`, Zync does not remove Zotero items when files are deleted.
64
+
65
+ Synchronizing with Zync is [idempotent](https://gitlab.com/zurabm/zync/-/blob/main/GLOSSARY.md#idempotent). If a file is already in Zotero, Zync puts the existing item into the collection instead of adding the file again. In copy mode, a file that changed replaces its old copy.
66
+
67
+ ### Folder patterns
68
+
69
+ A pattern describes where your synced folders are, as a path below the root folder. `*` stands for any folder name, and `**` for any number of folders. Put a folder in curly braces, `{ }`, to name a collection after it.
70
+
71
+ The default, `{*}/**/Literature`, finds every `Literature` folder and names its collection after the top folder it is in. Some other patterns:
72
+
73
+ ```bash
74
+ zync sync . --folder-pattern "{*}/**/Literature" --folder-pattern "{*}/**/References" # also References folders
75
+ zync sync . --folder-pattern "{Topics}/**/Literature" # only below Topics
76
+ zync sync . --folder-pattern "{*}/{*}/Literature" # a collection with a subcollection
77
+ zync sync . --folder-pattern "**/{*}/Literature" # named after the folder that holds Literature
78
+ zync sync . --folder-pattern "Topics/{*}" # every folder in Topics
79
+ ```
80
+
81
+ Every pattern needs at least one folder in curly braces.
82
+
83
+ ### Running it on a schedule
84
+
85
+ On Windows, this registers a task that synchronizes every 10 minutes without opening a console window:
86
+
87
+ ```powershell
88
+ Register-ScheduledTask -TaskName "Zync" `
89
+ -Action (New-ScheduledTaskAction -Execute (Get-Command uvw).Source -Argument 'tool run --from zync-py zync sync "C:\path\to\root"') `
90
+ -Trigger (New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes 10)) `
91
+ -Settings (New-ScheduledTaskSettingsSet -StartWhenAvailable -MultipleInstances IgnoreNew)
92
+ ```
93
+
94
+ ## Development
95
+
96
+ Get set up:
97
+
98
+ ```bash
99
+ git clone https://gitlab.com/zurabm/zync.git
100
+ cd zync
101
+ uv sync
102
+ uv run pre-commit install
103
+ ```
104
+
105
+ Run all checks (lint, format, type-check, import layers, tests):
106
+
107
+ ```bash
108
+ just check
109
+ ```
110
+
111
+ ## License
112
+
113
+ MIT
@@ -0,0 +1,114 @@
1
+ [project]
2
+ name = "zync-py"
3
+ dynamic = ["version"]
4
+ description = "Sync folders of PDFs into Zotero collections."
5
+ authors = [{ name = "Zurab Mujirishvili", email = "zurab.mu@gmail.com" }]
6
+ readme = "README.md"
7
+ requires-python = ">=3.13"
8
+ license-files = ["LICEN[CS]E*"]
9
+ classifiers = [
10
+ "Development Status :: 3 - Alpha",
11
+ "Environment :: Console",
12
+ "License :: OSI Approved :: MIT License",
13
+ "Programming Language :: Python :: 3",
14
+ "Programming Language :: Python :: 3.13",
15
+ "Programming Language :: Python :: 3.14",
16
+ "Typing :: Typed",
17
+ ]
18
+ dependencies = [
19
+ "httpx2>=2.12.0",
20
+ "platformdirs>=4.3.0",
21
+ "pyzotero>=1.16.0",
22
+ "trio>=0.35.0",
23
+ "typer>=0.29.1",
24
+ ]
25
+
26
+ [project.scripts]
27
+ zync = "zync:main"
28
+
29
+ [project.urls]
30
+ Homepage = "https://gitlab.com/zurabm/zync"
31
+ Repository = "https://gitlab.com/zurabm/zync"
32
+ "Bug Tracker" = "https://gitlab.com/zurabm/zync/-/issues"
33
+ Changelog = "https://gitlab.com/zurabm/zync/-/blob/main/CHANGELOG.md"
34
+
35
+ [dependency-groups]
36
+ dev = [
37
+ "pyright>=1.1.409",
38
+ "ruff>=0.15.4",
39
+ "pre-commit>=4.5.1",
40
+ "import-linter>=2.16",
41
+ ]
42
+ test = [
43
+ "pytest>=9.0.3",
44
+ "pytest-cov>=7.1.0",
45
+ "pytest-trio>=0.8.0",
46
+ "pytest-watcher>=0.6.3",
47
+ ]
48
+
49
+ [tool.uv]
50
+ default-groups = ["dev", "test"]
51
+
52
+ [build-system]
53
+ requires = ["hatchling", "hatch-vcs"]
54
+ build-backend = "hatchling.build"
55
+
56
+ [tool.hatch.version]
57
+ source = "vcs"
58
+
59
+ [tool.hatch.version.raw-options]
60
+ local_scheme = "no-local-version"
61
+ fallback_version = "0.0.0"
62
+
63
+ [tool.hatch.build.targets.sdist]
64
+ include = [
65
+ "/zync/",
66
+ "/LICENSE",
67
+ "/README.md",
68
+ "/pyproject.toml",
69
+ ]
70
+
71
+ [tool.hatch.build.targets.wheel]
72
+ packages = ["zync"]
73
+
74
+ [tool.pytest.ini_options]
75
+ testpaths = ["tests"]
76
+ pythonpath = ["."]
77
+ trio_mode = true
78
+
79
+ [tool.pyright]
80
+ include = ["zync", "tests"]
81
+
82
+ [tool.ruff.lint]
83
+ extend-select = ["I", "RUF018", "D"]
84
+
85
+ [tool.ruff.lint.per-file-ignores]
86
+ "*" = [
87
+ "D10", "D205", "D418"
88
+ ]
89
+ "tests/**" = [
90
+ "F841"
91
+ ]
92
+
93
+ [tool.ruff.lint.isort]
94
+ combine-as-imports = true
95
+ known-first-party = ["zync"]
96
+ known-local-folder = ["tests"]
97
+ section-order = ["future", "standard-library", "first-party", "third-party", "local-folder"]
98
+
99
+ [tool.ruff.lint.pydocstyle]
100
+ convention = "google"
101
+
102
+ [tool.ruff.format]
103
+ docstring-code-format = true
104
+
105
+ [tool.ruff.lint.flake8-bugbear]
106
+ extend-immutable-calls = ["zync.core.settings.SyncSettings"]
107
+
108
+ [tool.importlinter]
109
+ root_package = "zync"
110
+
111
+ [[tool.importlinter.contracts]]
112
+ name = "The CLI uses the infrastructure, and the infrastructure uses the core"
113
+ type = "layers"
114
+ layers = ["zync.cli", "zync.infra", "zync.core"]
@@ -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
+ )
@@ -0,0 +1 @@
1
+ from .app import main as main
@@ -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)
@@ -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
+ )