mhucka/zowie

Adds Zotero "select" links to attachment files in a Zotero database on macOS, so that outside of Zotero, you can find the bibliographic entry to which a file belongs. (Only works for local storage, not linked attachments.)

Zowie

Zowie ("Zotero link writer") is a command-line program for macOS that writes Zotero select links into the file attachments contained in a Zotero database.

Table of contents

• Introduction
• Installation
• Usage
• Known issues and limitations
• Additional tips
• Getting help
• Contributing
• License
• Acknowledgments

Introduction

When using Zotero, you may on occasion want to work with PDF files and other attachment files outside of Zotero. For example, if you're a DEVONthink user, you will at some point discover the power of indexing your local Zotero database from DEVONthink. However, when viewing or manipulating the attachments from outside of Zotero, you may run into the following problem: when looking at a given file, how do you find out which Zotero entry it belongs to?

Enter Zowie (a loose acronym for "Zotero link writer", and pronounced like the interjection). Zowie scans through the files on your disk in a local Zotero database, looks up the Zotero bibliographic record corresponding to each file found, and writes a Zotero select link into the file and/or certain macOS Finder/Spotlight metadata fields (depending on the user's choice). A Zotero select link has the form zotero://select/... and when opened on macOS, causes the Zotero desktop application to open that item in your database. Zowie thus makes it possible to go from a file opened in an application other than Zotero (e.g., DEVONthink, Adobe Acrobat), to the Zotero record corresponding to that file.

Regretfully, Zowie can only work with Zotero libraries that use normal/local data storage; it cannot work when Zotero is configured to use linked attachments.

Installation

There are multiple ways of installing Zowie, ranging from downloading a self-contained, single-file, ready-to-run program, to installing it as a typical Python program using pip. Please choose the alternative that suits you and your Mac environment.

Alternative 1: downloading the ready-to-run program

On macOS Catalina (10.15) or later, you can use a ready-to-run version of Zowie that only needs a Python interpreter version 3.8 or higher on your computer. That's the case for macOS 10.15 and later, but before you can use it, you may need to let macOS install some additional software components from Apple. To test it, run the following command in a terminal and take note of the version of Python that it prints:

python3 --version

If this is the first time you've run python3 on your system, macOS will either ask you if you want to install certain additional software components, or it may produce an error about xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools) .... In either case, the solution is to run the following command in the terminal:

xcode-select --install

In the pop-up dialog box that this brings up, click the Install button and agree to let it install the Command Line Tools package from Apple.

Next,

1. Go to the latest release on GitHub and find the Assets
2. Download the ZIP file whose name contains the version of Python on your computer (which you determined by running python3 --version above)
3. Unzip the file (if your browser didn't unzip it)
4. Open the folder that gets created (it will have a name like zowie-1.2.0-macos-python3.8)
5. Look inside for zowie and move it to a location where you put other command-line programs (such as /usr/local/bin).

If you want to put it in /usr/local/bin but that folder does not exist on your computer yet, you can create it by opening a terminal window and running the following command (prior to moving zowie into /usr/local/bin):

sudo mkdir /usr/local/bin

The following is an example command that you can type in a terminal to move Zowie there:

sudo mv zowie /usr/local/bin

Alternative 2: installing Zowie using pipx

You can use pipx to install Zowie. Pipx will install it into a separate Python environment that isolates the dependencies needed by Zowie from other Python programs on your system, and yet the resulting zowie command wil be executable from any shell – like any normal program on your computer. If you do not already have pipx on your system, it can be installed in a variety of easy ways and it is best to consult Pipx's installation guide for instructions. Once you have pipx on your system, you can install Zowie with the following command:

pipx install zowie

Pipx can also let you run Zowie directly using pipx run zowie, although in that case, you must always prefix every Zowie command with pipx run. Consult the documentation for pipx run for more information.

Alternative 3: installing Zowie using pip

The instructions below assume you have a Python 3 interpreter installed on your computer. Note that the default on macOS at least through 10.14 (Mojave) is Python 2 – please first install Python version 3 and familiarize yourself with running Python programs on your system before proceeding further.

You should be able to install zowie with pip for Python 3. To install zowie from the Python package repository (PyPI), run the following command:

python3 -m pip install zowie

As an alternative to getting it from PyPI, you can use pip to install zowie directly from GitHub:

python3 -m pip install git+https://github.com/mhucka/zowie.git

If you already installed Zowie once before, and want to update to the latest version, add --upgrade to the end of either command line above.

Alternative 4: installing Zowie from sources

If you prefer to install Zowie directly from the source code, you can do that too. To get a copy of the files, you can clone the GitHub repository:

git clone https://github.com/mhucka/zowie

Alternatively, you can download the files as a ZIP archive using this link directly from your browser using this link: https://github.com/mhucka/zowie/archive/refs/heads/main.zip

Next, after getting a copy of the files, run setup.py inside the code directory:

cd zowie
python3 setup.py install

Usage

For help with usage at any time, run zowie with the option -h.

The zowie command-line program should end up installed in a location where software is normally installed on your computer, if the installation steps described in the previous section proceeded successfully. Running Zowie from a terminal shell then should be as simple as running any other shell command on your system:

zowie -h

If you installed it as a Python package, then an alternative method is available to run Zowie from anywhere, namely to use the normal approach for running Python modules:

python3 -m zowie -h

Credentials for Zotero access

Zowie relies on the Zotero sync API to get information about your references. This allows it to look up Zotero item URIs for files regardless of whether they belong to your personal library or shared libraries, and from there, construct the appropriate Zotero select link for the files. If you do not already have a Zotero sync account, it will be necessary to create one before going any further.

To use Zowie, you will also need both an API user identifier (also known as the userID) and an API key. To find out your Zotero userID and create a new API key, log in to your Zotero account at Zotero.org and visit the Feeds/API tab of the your Settings page. On that page you can find your userID and create a new API key for Zowie.

The first time you run Zowie, it will ask for this information and (unless the -K option is given) store it in your macOS keychain so that it does not have to ask for it again on future occasions. It is also possible to supply the identifier and API key directly on the command line using the -i and -a options, respectively; the given values will then override any values stored in the keychain and (unless the -K option is also given) will be used to update the keychain for the next time.

Basic usage

Zowie can operate on a folder, or one or more individual files, or a mix of both. Suppose your local Zotero database is located in ~/Zotero/. Perhaps the simplest way to run Zowie is the following command:

zowie ~/Zotero

If this is your first run of Zowie, it will ask you for your userID and API key, then search for files recursively under ~/Zotero/. For each file found, Zowie will contact the Zotero servers over the network and determine the Zotero select link for the bibliographic entry containing that file. Finally, it will use the default method of recording the link, which is to write it into the macOS Finder comments for the file. It will also store your Zotero userID and API key into the system keychain so that it does not have to ask for them in the future.

If you are a user of DEVONthink, you will probably want to add the -s option (see the explanation below for the details):

zowie -s ~/Zotero

Instead of a folder, you can also invoke Zowie on one or more individual files (but be careful to put quotes around pathnames with spaces in them, such as in this example):

zowie -s "~/Zotero/storage/26GS7CZL/Smith 2020 Paper.pdf"

Available methods of writing Zotero links

Zowie supports multiple methods of writing the Zotero select link. The option -l will cause Zowie to print a list of all the methods available, then exit.

The option -m can be used to select one or more methods when running Zowie. Write the method names separated with commas without spaces. For example, the following command will make Zowie write the Zotero select link into the Finder comments as well as the PDF metadata attribute Subject:

zowie -m findercomment,pdfsubject ~/Zotero/storage

At this time, the following methods are available:

• findercomment: (The default method.) Writes the Zotero select link into the Finder comments of each file, attempting to preserve other parts of the comments. If Zowie finds an existing Zotero select link in the text of the Finder comments attribute, it only updates the link portion and tries to leave the rest of the comment text untouched. Otherwise, Zowie only writes into the comments attribute if either the attribute value is empty or Zowie is given the overwrite (-o) option. (Note that updating the link text requires rewriting the entire Finder comments attribute on a given file. Finder comments have a reputation for being easy to get into inconsistent states, so if you have existing Finder comments that you absolutely don't want to lose, it may be safest to avoid this method.)

• pdfproducer: (Only applicable to PDF files.) Writes the Zotero select link into the "Producer" metadata field of each PDF file. If the "Producer" field is not empty on a given file, Zowie looks for an existing Zotero link within the value and updates the link if one is found; otherwise, Zowie leaves the field untouched unless given the overwrite flag (-o), in which case, it replaces the entire contents of the field with the Zotero select link. For some users, the "Producer" field has not utility, and thus can be usefully hijacked for the purpose of storing the Zotero select link. The value is accessible from macOS Preview, Adobe Acrobat, DEVONthink, and presumably any other application that can display the PDF metadata fields. However, note that some users (archivists, forensics investigators, possibly others) do use the "Producer" field, and overwriting it may be undesirable.

• pdfsubject: (Only applicable to PDF files.) Writes the Zotero select link into the "Subject" metadata field of each PDF file. If the "Subject" field is not empty on a given file, Zowie looks for an existing Zotero link within the value and updates the link if one is found; otherwise, Zowie leaves the field untouched unless given the overwrite flag (-o), in which case, it replaces the entire contents of the field with the Zotero select link. Note that the PDF "Subject" field is not the same as the "Title" field. For some users, the "Subject" field is not used for any purpose and thus can be usefully hijacked for storing the Zotero select link. The value is accessible from macOS Preview, Adobe Acrobat, DEVONthink, and presumably any other application that can display the PDF metadata fields.

• wherefrom: Writes the Zotero select link to the "Where from" metadata field of each file (the com.apple.metadata:kMDItemWhereFroms extended attribute). This field is displayed as "Where from" in Finder "Get Info" panels; it is typically used by web browsers to store a file's download origin. The field is a list. If Zowie finds a Zotero select link as the first item in the list, it updates that value; otherwise, Zowie prepends the Zotero select link to the list of existing values, keeping the other values unless the overwrite option (-o) is used. When the overwrite option is used, Zowie deletes the existing list of values and writes only the Zotero select link. Note that if macOS Spotlight indexing is turned on for the volume containing the file, the macOS Finder will display the updated "Where from" values in the Get Info panel of the file; if Spotlight is not turned on, the Get info panel will not be updated, but other applications will still be able to read the updated value.

Note that, depending on the attribute, it is possible that a file has an attribute value that is not visible in the Finder or other applications. This is especially true for "Where from" values and Finder comments. The implication is that it may not be apparent when a file has a value for a given attribute, which can lead to confusion if Zowie thinks there is a value and refuses to change it without the -o option.

Filtering by file type

By default, Zowie acts on all files it finds on the command line, except for certain files that it always ignores: hidden files and files with extensions .sqlite, .bak, .csl, .css, .js, .json, .pl, and a few others. If the -m option is used to select methods that only apply to specific file types, Zowie will examine each file it finds in turn and only apply the methods that match that particular file's type, but it will still consider every file it finds in the directories it scans and apply the methods that are not limited to specific types.

You can use the option -f to make Zowie filter the files it finds based on file name extensions. This is useful if you want it to concentrate only on particular file types and ignore other files it might find while scanning folders. Here is an example (this also using the -s option for reasons given below):

zowie -s -f pdf,mp4,mov ~/Zotero

will cause it to only work on PDF, MP4, and QuickTime format files. You can provide multiple file extensions separated by commas, without spaces and without the leading periods.

Filtering by date

If the -d option is given, the files will be filtered to use only those whose last-modified date/time stamp is no older than the given date/time description. Valid descriptors are those accepted by the Python dateparser library. Make sure to enclose descriptions within single or double quotes. Examples:

zowie -d "2 weeks ago" ....
zowie -d "2014-08-29" ....
zowie -d "12 Dec 2014" ....
zowie -d "July 4, 2013" ....

Special-case behavior

Although Zowie is not aimed solely at DEVONthink users, its development was motivated by the author's desire to use Zotero with that software. A complication arose due to an undocumented feature in DEVONthink: it ignores a Finder comment if it is identical to the value of the "URL" attribute (which is the name it gives to the com.apple.metadata:kMDItemWhereFroms attribute discussed above). In practical terms, if you do something like write the Zotero select link into the Finder comment of a file and then have a DEVONthink smart rule copy the value to the URL field, the Finder comment will subsequently appear blank in DEVONthink (even though it exists on the actual file). This can be unexpected and confusing, and has caught people (including the author of Zowie) unaware. To compensate, Zowie 1.2 introduced a new option: it can add a trailing space character to the end of the value it writes into the Finder comment when using the findercomment method. Since approaches to copy the Zotero link from the Finder comment to the URL field in DEVONthink will typically strip whitespace around the URL value, the net effect is to make the value in the Finder comment just different enough from the URL field value to prevent DEVONthink from ignoring the Finder comment. Use the option -s to make Zowie to add the trailing space character.

Additional command-line arguments

To make Zowie only print what it would do without actually doing it, use the -n "dry run" option.

If given the -q option, Zowie will not print its usual informational messages while it is working. It will only print messages for warnings or errors. By default, messages printed by Zowie are also color-coded. If given the option -C, Zowie will not color the text of messages it prints. (This latter option is useful when running Zowie within subshells inside other environments such as Emacs.)

If given the -V option, this program will print the version and other information, and exit without doing anything else.

If given the -@ argument, this program will output a detailed trace of what it is doing. The debug trace will be sent to the given destination, which can be - to indicate console output, or a file path to send the output to a file.

When -@ has been given, Zowie also installs a signal handler on signal SIGUSR1 that will drop Zowie into the pdb debugger if the signal is sent to the running process.

Summary of command-line options

The following table summarizes all the command line options available.

Short	Long form opt	Meaning	Default
-aA	--api-keyA	API key to access the Zotero API service
-C	--no-color	Don't color-code the output	Use colors in the terminal
-d	--after-dateD	Only act on files modified after date "D"	Act on all files found
-f	--file-extF	Only act on files with extensions in "F"	Act on all files found	⚑
-h	--help	Display help text and exit
-i	--identifierI	Zotero user ID for API calls
-K	--no-keyring	Don't use a keyring/keychain	Store login info in keyring
-l	--list	Display known services and exit
-m	--methodM	Select how Zotero select links are written	findercomment
-n	--dry-run	Say what would be done, but don't do it	Do it
-o	--overwrite	Overwrite previous metadata content	Don't write if already present
-q	--quiet	Don't print messages while working	Be chatty while working
-s	--space	Append trailing space to Finder comments	Don't add a space	★
-V	--version	Display program version info and exit
-@OUT	--debugOUT	Debugging mode; write trace to OUT	Normal mode	⬥

⚑   Certain files are always ignored: hidden files, macOS aliases, and files with extensions .sqlite, .sqlite-journal, .bak, .csl, .css, .js, .json, .pl, and .config_resp.
⬥   To write to the console, use the character - as the value of OUT; otherwise, OUT must be the name of a file where the output should be written.
★   See the explanation in the section on special-case behavior.

Return values

This program exits with a return code of 0 if no problems are encountered. It returns a nonzero value otherwise. The following table lists the possible return values:

Code	Meaning
0	success – program completed normally
1	the user interrupted the program's execution
2	encountered a bad or missing value for an option
3	no network detected – cannot proceed
4	file error – encountered a problem with a file
5	server error – encountered a problem with a server
6	an exception or fatal error occurred

Known issues and limitations

The following is a list of currently-known issues and limitations:

• Zowie can only work when Zotero is set to use direct data storage; i.e., where attached files are stored in Zotero. It cannot work if you use linked attachments, that is, if you set Linked Attachment Base Directory in your Zotero Preferences' Advanced → Files and Folders panel.

• If you use DEVONthink in a scheme in which you index your Zotero folder and use Zowie to write the Zotero select link into the Finder comments of files, beware of the following situation. If you use a DEVONthink smart rule to copy the comment string into the "URL" field, DEVONthink will (after reindexing the file) suddenly display an empty Finder comment, even though the comment is still there. This is due to a deliberate behavior in DEVONthink and not a problem with Zowie, as discussed in the section on special-case behavior. Using the -s option will avoid this, but at the cost of adding an extra character to the Finder comment, so make sure to account for the added space character in any scripts or other actions you take on the Finder comment.

• DEVONthink bases the "URL" value of a file on the file's com.apple.metadata:kMDItemWhereFroms extended attribute. The original hope behind Zowie was to make it write Zotero select links directly into that attribute value. Unfortunately, it turns out that if a file has already been indexed by DEVONthink, then it will not detect any changes to the com.apple.metadata:kMDItemWhereFroms attribute made by an external program. Thus, if you index your Zotero folder within DEVONthink, you cannot use Zowie's wherefroms method to update the "URL" field directly. You are advised instead to use Zowie's findercomment method (the default) in combination with smart rules in DEVONthink, as discussed in the wiki. I share your frustration.

• For reasons I have not had time to investigate, the binary version of zowie takes a very long time to start up on macOS 10.15 (Catalina) and 11.1 (Big Sur). On my test system inside a virtual machine running on a fast iMac, it takes 10 seconds or more before the first output from zowie appears.

Additional tips

In the wiki associated with the Zowie project in GitHub, I have started writing some notes about how I personally use Zowie to combine Zotero with DEVONthink.

Getting help

If you find an issue, please submit it in the GitHub issue tracker for this repository.

Contributing

I would be happy to receive your help and participation if you are interested. Everyone is asked to read and respect the code of conduct when participating in this project. Development generally takes place on the development branch.

License

This software is Copyright (C) 2020–2023, by Michael Hucka and the California Institute of Technology (Pasadena, California, USA). This software is freely distributed under a 3-clause BSD type license. Please see the LICENSE file for more information.

Acknowledgments

This work is a personal project developed by the author, using computing facilities and other resources of the California Institute of Technology Library.

The vector artwork of an exclamation point circled by a zigzag, used as the icon for this repository, was created by Alfredo @ IconsAlfredo.com from the Noun Project. It is licensed under the Creative Commons CC-BY 3.0 license.

Zowie makes use of numerous open-source packages, without which Zowie could not have been developed. I want to acknowledge this debt. In alphabetical order, the packages are:

• aenum – advanced enumerations for Python
• biplist – A binary plist parser/writer for Python
• boltons – package of miscellaneous Python utilities
• bun – a set of basic user interface classes and functions
• CommonPy – a collection of commonly-useful Python functions
• fastnumbers – number testing and conversion functions
• ipdb – the IPython debugger
• keyring – access the system keyring service from Python
• pdfrw – a pure Python library for reading and writing PDFs
• plac – a command line argument parser
• py-applescript – a Python interface to AppleScript
• PyInstaller – a packaging program that creates standalone applications from Python programs
• pyobjc – Python ⇌ Objective-C and macOS frameworks bridge
• pyxattr – access extended file attributes from Python
• pyzotero – a Python API client for Zotero
• setuptools – library for setup.py
• Shiv – command-line utility for creating self-contained Python zipapps
• Sidetrack – simple debug logging/tracing package
• wheel – setuptools extension for building wheels

The developers of DEVONthink, especially Jim Neumann and Christian Grunenberg, quickly and consistently replied to my many questions on the DEVONtechnologies forums.

zowie's Issues

Encountered error KeyError: 'parentItem'

When trying to add some pdfs with this:

zowie -m findercomment,wherefrom ~/Zotero/storage/ -o

I run into this error:

Ovewriting Finder comments with Zotero link for file 
/Users/mhaehnel/Zotero/storage/2CEBUQ7U/humboldt1815-prolegomena-xiv.pdf
Overwriting "Where From" metadata with Zotero link in 
/Users/mhaehnel/Zotero/storage/2CEBUQ7U/humboldt1815-prolegomena-xiv.pdf
Encountered error KeyError: 'parentItem'

with this PDF:

humboldt1815-prolegomena-xiv.pdf

And this citation:

Question—Is Zowie necessary with Zotero 6?

https://www.zotero.org/blog/zotero-6/

Trying to understand if the underlying problem is solved in the latest version (it seems like it is). 🤔

New Failure: ImportError: cannot import name '_objc' from partially initialized module 'objc' (most likely due to a circular import)

Started sometime after installing the most recent zowie update. Have reinstalled with same result.

macOS 13.5.2
Python 3.9.6
zowie 1.3.0 for Python 3.9

Zowie fails to start, gives traceback with error:

ImportError: cannot import name '_objc' from partially initialized module 'objc' (most likely due to a circular import) (/Users/username/.shiv/zowie_31546c4ecd8bf8e4b3cad617a60dd581617524d69e1487d41d9aeb4e1df8ddb0/site-packages/objc/__init__.py)

"tuple index out of range"

I'm sure this is on me, but I mis-entered my Zotero UserID and API key initially. On re-running Zowie with the -a argument and a newly created API key, and then the correct Zotero UserID, I'm getting a "Encountered error IndexError: tuple index out of range." and then Zowie exits. I tried running it with the debug option, but the process fails in the same place.

Write zotero select link on top of each PDF page

I think your software is great: it helps me a lot in everyday researching life.

I have one suggestion for improvement: when dealing with hundreds of files per week in scientific research, the metadata step always involves opening an additional window in Acrobat Reader or other programs. In Reader it is also not possible for me to open the select link directly.

It would be much faster if zowie offered the possibility to insert the select link e.g. at the top of the PDF in small font.
Example with select item links on the right top of each page:

I realize that this changes the PDF a lot and also takes a long time per file to insert a link on each page. However, it would give me the ability to jump immediately to Zotero with a single click when reading any page.

Thanks a lot for zowie!

Update to Python 3.12?

Hi, I really like Zowie but it does not have a Python 3.12 version. Would it be possible to have an updated version?

Thanks,
SS

Question: using DevonThink ToGo to read / comment / index Zotero files?

Hi

Zowie sounds great - and I am will try it out but would like to know

1. if I can index the Zotero pdf folder from DevonThink ToGo, or if I have to use DevonThink for that?
2. when indexed (by DevonThink or ToGo), can I read the pdfs from DevonThink and from DevonThink ToGo and annotate them?

Thanks a lot,

Rainer

Zowie for ms windows

is there any alternative for windows that can carry the same function of getting a hyperlink from Zotero document to be opened directly from another app via this link.
thanks in advance.

Sonoma

Hi,

I love Zowie.

But, after updating to Sonoma, I got the following error in Deveonthink, which was running smoothly before:

The self-contained executable of Zowie 1.3.0 that you are
attempting to run was built to work specifically (and only)
with version 3.11 of Python. The version of Python obtained
by running "python3" on your computer is 3.9. This makes it
incompatible and prevents this copy of Zowie from running.

However it works in terminal as follows:
zowie /path to folder/Zotero -s -KEY -i ID -d "2023-09-01"

What I did
A)
I deleted Python.
However, there is a Python in user/bin I can't get rid of. This must be the default and protected Python installed by Apple. I found some information telling me: Don't touch that!

B)
I reinstalled Python 3.11.0 and looked for other versions of Python, but none were found:
python3 --version
Python 3.11.0

whereis python3
python3: /usr/bin/python3 /Library/Frameworks/Python.framework/Versions/3.11/share/man/man1/python3.1

C)
I reinstalled Zowie:
python3 -m pip install zowie

D) I checked the path in
sudo nano /etc/paths
It is as follows:

/usr/local/bin
/System/Cryptexes/App/usr/bin
/usr/bin
/bin
/usr/sbin
/sbin

In the Devonthink script, I entered the path to Zowie:
set result to do shell script
"/usr/local/bin/zowie -s -q"

But still, Devonthink/Zowie do not find Python 3.11.0.

How can I tell Deventhink/Zowie to use Python 3.11.0?

Best wishes, Christof

Would it be possible to hijack this tool to insert devonthink tags into zotero tags, and vice versa?

I'm not asking if you can do it, I'm wondering if you think this would be doable using this tool? If so, I might have time to think about it in a couple of months (!) ...

Trying a new username id

Hello,
I was able to download and run zowie except that I inputted an incorrect user ID and when I try to try again it just keeps telling me the same error. How can I input a new user id?
-Andrea

Doesn't work with linked attachments?

Can you please put this issue (a disclaimer) at the very beginning of the Readme file (or the post)?

Most people use Zotero with Zotfile extension (linked attachments).

I went through all the processes of setting up, and running the commands, only to learn later that this script doesn't work for linked attachments.

What a waste of time.

Have you made me know from the beginning, I would have never installed it.

sh: zowie: command not found when applying smart rule

When a new file is added, my smart rule which should create the comment with the Zotero link fails with this message:

sh: zowie: command not found

I'm using the script and the smart rule setting from this link:
https://github.com/mhucka/zowie/wiki/Example:-using-Zowie-with-DEVONthink

When I run Zowie from command line with zowie -s ~/Zotero everything works fine. I checked also the installation of Zowie with pip show zowie:

Name: zowie
Version: 1.2.0
Summary: Write Zotero select links into article attachment files
Home-page: https://github.com/mhucka/zowie
Author: Michael Hucka
Author-email: [email protected]
License: BSD 3-clause
Location: /opt/homebrew/Caskroom/miniforge/base/lib/python3.9/site-packages
Requires: aenum, biplist, boltons, bun, commonpy, keyring, keyrings.alt, pdfrw, plac, py-applescript, pyobjc-core, pyobjc-framework-AppleScriptKit, pyobjc-framework-AppleScriptObjC, pyxattr, pyzotero, setuptools, sidetrack
Required-by:

I tried adding /opt/homebrew/Caskroom/miniforge/base/lib/python3.9/site-packages to the script:
set result to do shell script ¬ ¬ "PATH=$PATH:$HOME/.local/bin:/usr/local/bin:/opt/homebrew/Caskroom/miniforge/base/lib/python3.9/site-packages" & " zowie -s -q " & quoted_file_path

But this doesn't help. Any suggestion what might be wrong?

Allow use with other files besides PDFs

The findercomment and wherefrom methods actually don't have anything to do with PDF files, and could work for other file types. Zowie could therefore support the ability to work on more file types besides PDF. (Perhaps it should have a flag to indicate file extensions to work on. Maybe --file-type or --extensions?)

Python Error with sidetracked?

Hello,
This is a great idea. I'd love to have it working.
There seems to be something the matter with the python3 installation though on both of my machines.
Not sure what is causing this.

Thanks,
Maurice

Traceback (most recent call last):
File "/usr/local/Cellar/[email protected]/3.9.5/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 197, in _run_module_as_main
return _run_code(code, main_globals, None,
File "/usr/local/Cellar/[email protected]/3.9.5/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 87, in _run_code
exec(code, run_globals)
File "/usr/local/lib/python3.9/site-packages/zowie/main.py", line 33, in
from zowie.main_body import MainBody
File "/usr/local/lib/python3.9/site-packages/zowie/main_body.py", line 32, in
from .zotero import Zotero
File "/usr/local/lib/python3.9/site-packages/zowie/zotero.py", line 30, in
from sidetrack import log, logr
ImportError: cannot import name 'logr' from 'sidetrack' (/usr/local/lib/python3.9/site-packages/sidetrack/init.py)

Problem running script in Devonthink

I have downloaded ZOWIE from your site and installed it and works fine running from the command line. I am using python 3.9. I also have implanted the Devonthink rules that you list. The 'Run Zowie on newly indexed PDF.applescript' scrript, throws an error within Devonthink saying that I have python 3.8. Don't understand why it runs at command line but not in the script. Possible has something to do with the path, but not sure. Any thoughts? Thanks in advance for your help.

Find itemkey based on SQLite database

One method to solve the issue of getting the itemkey for linked attachments is to read the SQLite database ~/Zotero/zotero.sqlite, iterate through each attachment, then find the corresponding itemkey. I've peeped into the database and saw that there are two tables that would be useful: itemAttachments and items.

One can query the itemID (or perhaps parentItemID) of each attachment in the itemAttachments table then lookup the corresponding key in the items table. I've attached photos of example entries of each table.

Note that the absolute path of an attachment can be found if the attachment is linked. We can also filter attachments by whether the path column starts with storage:.

Expert from itemAttachments:

Expert from items:

Error installing zowie with pipx

I'm not able to install zowie with pipx. Which pip install with no issue.

pipx install zowie
Fatal error from pip prevented installation. Full pip output in file:
    /Users/luispuerto/Developer/zzStorageRoom/dotfiles/.local/pipx/logs/cmd_2023-03-17_17.03.52_pip_errors.log

pip seemed to fail to build package:
    pyobjc-framework-Cocoa>=7.3

Some possibly relevant errors from pip install:
    error: subprocess-exited-with-error
    TypeError: not enough arguments for format string
    error: metadata-generation-failed

Error installing zowie.
Fatal error from pip prevented installation. Full pip output in file:
    /Users/luispuerto/Developer/zzStorageRoom/dotfiles/.local/pipx/logs/cmd_2023-03-17_17.03.52_pip_errors.log

pip seemed to fail to build package:
    pyobjc-framework-Cocoa>=7.3

Some possibly relevant errors from pip install:
    error: subprocess-exited-with-error
    TypeError: not enough arguments for format string
    error: metadata-generation-failed

Error installing zowie.

PIP STDOUT
----------
Collecting zowie
  Using cached zowie-1.2.0-py3-none-any.whl (38 kB)
Collecting aenum==3.1.0
  Using cached aenum-3.1.0-py3-none-any.whl (123 kB)
Collecting biplist==1.0.3
  Using cached biplist-1.0.3.tar.gz (21 kB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
Collecting boltons==21.0.0
  Using cached boltons-21.0.0-py2.py3-none-any.whl (193 kB)
Collecting bun==0.0.8
  Using cached bun-0.0.8-py3-none-any.whl (11 kB)
Collecting commonpy==1.5.0
  Using cached commonpy-1.5.0-py3-none-any.whl (23 kB)
Collecting keyring==23.2.1
  Using cached keyring-23.2.1-py3-none-any.whl (33 kB)
Collecting keyrings.alt==4.1.0
  Using cached keyrings.alt-4.1.0-py3-none-any.whl (20 kB)
Collecting pdfrw==0.4
  Using cached pdfrw-0.4-py2.py3-none-any.whl (69 kB)
Collecting plac==1.3.3
  Using cached plac-1.3.3-py2.py3-none-any.whl (22 kB)
Collecting py-applescript==1.0.2
  Using cached py_applescript-1.0.2-py3-none-any.whl (22 kB)
Collecting pyzotero==1.4.26
  Using cached Pyzotero-1.4.26-py2.py3-none-any.whl (27 kB)
Collecting pyxattr==0.7.2
  Using cached pyxattr-0.7.2.tar.gz (31 kB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
Collecting setuptools==58.3.0
  Using cached setuptools-58.3.0-py3-none-any.whl (946 kB)
Collecting sidetrack==2.0.0
  Using cached sidetrack-2.0.0-py3-none-any.whl (10 kB)
Collecting pyobjc-core==7.3.0
  Using cached pyobjc-core-7.3.tar.gz (684 kB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
Collecting pyobjc-framework-AppleScriptKit==7.3.0
  Using cached pyobjc_framework_AppleScriptKit-7.3-py2.py3-none-any.whl (3.8 kB)
Collecting pyobjc-framework-AppleScriptObjC==7.3.0
  Using cached pyobjc_framework_AppleScriptObjC-7.3-py2.py3-none-any.whl (3.9 kB)
Collecting pytest>=6.1.0
  Using cached pytest-7.2.2-py3-none-any.whl (317 kB)
Collecting rich>=9.0.0
  Using cached rich-13.3.2-py3-none-any.whl (238 kB)
Requirement already satisfied: wheel>=0.33.6 in ./Developer/zzStorageRoom/dotfiles/.local/pipx/shared/lib/python3.11/site-packages (from bun==0.0.8->zowie) (0.40.0)
Collecting PyYAML>=5.3.1
  Using cached PyYAML-6.0-cp311-cp311-macosx_11_0_arm64.whl (167 kB)
Collecting dateparser>=1.0.0
  Using cached dateparser-1.1.7-py2.py3-none-any.whl (293 kB)
Collecting h2>=3.2.0
  Using cached h2-4.1.0-py3-none-any.whl (57 kB)
Collecting httpx>=0.18.2
  Using cached httpx-0.23.3-py3-none-any.whl (71 kB)
Collecting humanize>=3.0.0
  Using cached humanize-4.6.0-py3-none-any.whl (109 kB)
Collecting python-dateutil>=2.8.1
  Using cached python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
Collecting tldextract>=2.2.3
  Using cached tldextract-3.4.0-py3-none-any.whl (93 kB)
Collecting validator-collection>=1.5.0
  Using cached validator_collection-1.5.0-py2.py3-none-any.whl (36 kB)
Collecting importlib-metadata>=3.6
  Using cached importlib_metadata-6.0.0-py3-none-any.whl (21 kB)
Collecting pyobjc-framework-Cocoa>=7.3
  Using cached pyobjc_framework_Cocoa-9.0.1-cp311-cp311-macosx_10_9_universal2.whl (388 kB)
Collecting pytz
  Using cached pytz-2022.7.1-py2.py3-none-any.whl (499 kB)
Collecting requests>=2.21.0
  Using cached requests-2.28.2-py3-none-any.whl (62 kB)
Collecting bibtexparser
  Using cached bibtexparser-1.4.0.tar.gz (51 kB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
Collecting feedparser>=6
  Using cached feedparser-6.0.10-py3-none-any.whl (81 kB)
Collecting regex!=2019.02.19,!=2021.8.27
  Using cached regex-2022.10.31-cp311-cp311-macosx_11_0_arm64.whl (287 kB)
Collecting tzlocal
  Using cached tzlocal-4.2-py3-none-any.whl (19 kB)
Collecting sgmllib3k
  Using cached sgmllib3k-1.0.0.tar.gz (5.8 kB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
Collecting hyperframe<7,>=6.0
  Using cached hyperframe-6.0.1-py3-none-any.whl (12 kB)
Collecting hpack<5,>=4.0
  Using cached hpack-4.0.0-py3-none-any.whl (32 kB)
Collecting certifi
  Using cached certifi-2022.12.7-py3-none-any.whl (155 kB)
Collecting httpcore<0.17.0,>=0.15.0
  Using cached httpcore-0.16.3-py3-none-any.whl (69 kB)
Collecting rfc3986[idna2008]<2,>=1.3
  Using cached rfc3986-1.5.0-py2.py3-none-any.whl (31 kB)
Collecting sniffio
  Using cached sniffio-1.3.0-py3-none-any.whl (10 kB)
Collecting zipp>=0.5
  Using cached zipp-3.15.0-py3-none-any.whl (6.8 kB)
Collecting pyobjc-framework-Cocoa>=7.3
  Using cached pyobjc_framework_Cocoa-9.0-cp311-cp311-macosx_10_9_universal2.whl (388 kB)
  Using cached pyobjc_framework_Cocoa-8.5.1-cp311-cp311-macosx_10_9_universal2.whl (388 kB)
  Using cached pyobjc-framework-Cocoa-8.5.tar.gz (4.6 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
  Using cached pyobjc-framework-Cocoa-8.4.1.tar.gz (4.6 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
  Using cached pyobjc-framework-Cocoa-8.4.tar.gz (4.6 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
  Using cached pyobjc-framework-Cocoa-8.3.tar.gz (4.0 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
  Using cached pyobjc-framework-Cocoa-8.2.tar.gz (4.0 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
  Using cached pyobjc-framework-Cocoa-8.1.tar.gz (4.0 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
  Using cached pyobjc-framework-Cocoa-8.0.tar.gz (4.0 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
  Using cached pyobjc-framework-Cocoa-7.3.tar.gz (3.5 MB)
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'error'

PIP STDERR
----------
  error: subprocess-exited-with-error
  
  × python setup.py egg_info did not run successfully.
  │ exit code: 1
  ╰─> [9 lines of output]
      Traceback (most recent call last):
        File "<string>", line 2, in <module>
        File "<pip-setuptools-caller>", line 34, in <module>
        File "/private/var/folders/zm/clm72_7978105k4sj96x794r0000gn/T/pip-install-tspdoh0w/pyobjc-framework-cocoa_e861cadae9024920801682e43b4fabd0/setup.py", line 23, in <module>
          Extension(
        File "/private/var/folders/zm/clm72_7978105k4sj96x794r0000gn/T/pip-install-tspdoh0w/pyobjc-framework-cocoa_e861cadae9024920801682e43b4fabd0/pyobjc_setup.py", line 459, in Extension
          "-DPyObjC_BUILD_RELEASE=%02d%02d" % (tuple(map(int, os_level.split("."))))
          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      TypeError: not enough arguments for format string
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

Messages about database lookup errors do not indicate which file is at fault

Issue #1 demonstrates that the error printed due to a Zotero record lookup failure does not clearly identify which file is at fault, misleading users about the cause of the error. The messages need to include the file name or otherwise do a better job of attributing the cause.

Suggest to loosen the dependency on boltons

Hi, your project zowie(commit id: 9f840a7) requires "boltons==21.0.0" in its dependency. After analyzing the source code, we found that the following versions of boltons can also be suitable, i.e., boltons 0.6.0, 0.6.1, 0.6.2, 0.6.3, 0.6.4, 0.6.5, 0.6.6, 15.0.0, 15.0.1, 15.0.2, 15.1.0, 15.1.1, 16.0.0, 16.0.1, 16.1.0, 16.1.1, 16.2.0, 16.2.1, 16.2.2, 16.3.0, 16.3.1, 16.4.0, 16.4.1, 16.5.0, 16.5.1, 17.0.0, 17.1.0, 17.2.0, 18.0.0, 18.0.1, 19.0.0, 19.0.1, 19.1.0, 19.2.0, 19.3.0, 20.0.0, 20.1.0, 20.2.0, 20.2.1, since all functions that you directly (1 APIs: boltons.debugutils.pdb_on_signal) or indirectly (propagate to 0 boltons's internal APIs and 3 outsider APIs) used from the package have not been changed in these versions, thus not affecting your usage.

Therefore, we believe that it is quite safe to loose your dependency on boltons from "boltons==21.0.0" to "boltons>=0.6.0,<=21.0.0". This will improve the applicability of zowie and reduce the possibility of any further dependency conflict with other projects.

May I pull a request to further loosen the dependency on boltons?

By the way, could you please tell us whether such an automatic tool for dependency analysis may be potentially helpful for maintaining dependencies easier during your development?

-d option can't be used wit ~/Zotero folder

I tried to select only the recent files by using the -d option like that: zowie -d "2022-02-18" -s ~/Zotero. But in that case, zowie is only looking at the given folder and is not searching the sub-folders, which results in this message:

Will process 1 file using method findercomment.
Unable to retrieve Zotero record for /Users/myusername/Zotero

Do I need to add another option?