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.
- zync_py-0.1.0/.gitignore +26 -0
- zync_py-0.1.0/LICENSE +21 -0
- zync_py-0.1.0/PKG-INFO +138 -0
- zync_py-0.1.0/README.md +113 -0
- zync_py-0.1.0/pyproject.toml +114 -0
- zync_py-0.1.0/zync/__init__.py +23 -0
- zync_py-0.1.0/zync/cli/__init__.py +1 -0
- zync_py-0.1.0/zync/cli/app.py +183 -0
- zync_py-0.1.0/zync/core/__init__.py +21 -0
- zync_py-0.1.0/zync/core/attachments.py +57 -0
- zync_py-0.1.0/zync/core/concurrency.py +22 -0
- zync_py-0.1.0/zync/core/folders.py +184 -0
- zync_py-0.1.0/zync/core/library.py +89 -0
- zync_py-0.1.0/zync/core/patterns.py +86 -0
- zync_py-0.1.0/zync/core/removals.py +57 -0
- zync_py-0.1.0/zync/core/settings.py +27 -0
- zync_py-0.1.0/zync/core/sync/__init__.py +2 -0
- zync_py-0.1.0/zync/core/sync/additions.py +61 -0
- zync_py-0.1.0/zync/core/sync/deletions.py +95 -0
- zync_py-0.1.0/zync/core/sync/index.py +85 -0
- zync_py-0.1.0/zync/core/sync/paths.py +7 -0
- zync_py-0.1.0/zync/core/sync/report.py +37 -0
- zync_py-0.1.0/zync/core/sync/zync.py +133 -0
- zync_py-0.1.0/zync/infra/__init__.py +10 -0
- zync_py-0.1.0/zync/infra/disk.py +30 -0
- zync_py-0.1.0/zync/infra/zotero/__init__.py +11 -0
- zync_py-0.1.0/zync/infra/zotero/credentials.py +33 -0
- zync_py-0.1.0/zync/infra/zotero/library.py +278 -0
- zync_py-0.1.0/zync/py.typed +0 -0
zync_py-0.1.0/.gitignore
ADDED
|
@@ -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
|
zync_py-0.1.0/README.md
ADDED
|
@@ -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
|
+
)
|