| Name | znp JSON |
| Version |
0.0.13
JSON |
| download |
| home_page | |
| Summary | Simple program to open a file in existing zathura instance |
| upload_time | 2023-04-21 22:36:29 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | GNU General Public License v3 (GPLv3) |
| keywords |
zathura
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# znp
znp stands for Zathura Next Or Previous. You can also use znp to add a given
file to an instance of [zathura](https://pwmt.org/projects/zathura/).
# Usage
## Next or Previous
The main goal of znp is to provide an easy way to go to the next or previous
file from within zathura. As of
[yet](https://git.pwmt.org/pwmt/zathura/-/issues/93) this functionality is not a
part of zathura's functionality. However, after installing `znp` you can add the
following to your `zathurarc` to set `N` and `P` to go to the next or previous
file:
``` vim-snippet
map N exec "znp -n '$FILE'"
map P exec "znp -p '$FILE'"
" Please note the ^ ^ apostrophes around $FILE.
" These are necessary for files with whitespace
```
*Note* that if your system does not use extended window manager hints
([ewmh](https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html)), or
you do not have the ewmh python package installed; then, this command may fail
if you have two instances of zathura open in the same directory. This is not
something that I have a reasonable fix for and there is no way to reliably
determine the instance issuing the next or previous command. The only way I can
think of fixing this would require patching zathura to include expansion of a
`$PID` variable from the exec function and include that in the zathurarc
command. However, I am a not a programmer so reviewing the code base and
getting this functionality added may take me some time.
## Adding files
znp can act as a zathura wrapper and add a given file to an existing instance:
``` shell
znp file.pdf
znp /path/to/file.pdf
```
You can give znp a relative or absolute path to file. znp will insert the
current working directory to make a relative path absolute. No variable
expansion will performed by znp as it expects `$HOME` and such to get expanded
by the shell calling znp.
The above works best when only one instance of zathura exists. However, if
multiple exist then zathura will use the user defined `prompt_cmd` set in
`$XDG_CONFIG_HOME/znp/znp.conf` to present a list of zathura instances to open
the file in. The default is `fzf` but you may use `dmenu` or `rofi`. Here is
how this looks in practice:
To aviod any prompting you can pass the desired pid to use with the `-P` flag:
``` shell
znp -P 123456 file.pdf
znp -P 123456 /path/to/file.pdf
```
This would require a bit more work on your part but it may be useful in
scripting.
## Query
Speaking of scripting, I added the `-q, --query` flag for my personal scripting
purposes.
The `--query` flag will take the `FILE` argument given to znp and search all
zathura pids for the _first_ (see the note in the [next or
previous](#next-or-previous) section) one that has that file open and return
it's pid. I make use of this to track my last read pdf, epub, cbz/r, zip, etc.
using the returned pid to kill the assumed instance issuing the command.
Basically a session tracker so to speak. Maybe there are other purposes for this
or maybe the `zathura.py` module would be useful as a standalone module for
interacting with zathura via dbus. No clue, let me know.
## User config
You can set the default command prompt in `$XDG_CONFIG_HOME/znp/znp.conf` like
so:
```
prompt_cmd = dmenu
```
**Note** there are no quotes. You can also skip the spaces if you like.
If you have any args/flags you want to use with your command prompt add them
like so:
```
prompt_args = -l 20 -i
```
Simply provide the args/flags as you would normally when using your chosen
prompt_cmd.
**Note** If your prompt_args contain an `=` sign then please escape it with a
backslash otherwise you will get an error.
# Installation
znp is available via [pypi](https://pypi.org/project/znp/) and can install it
via pip in the usual way:
``` shell
pip install znp
```
Use the following if you are installing on a system running X and using
[ewmh](https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html):
``` shell
pip install znp[x11]
```
Ensure `~/.local/bin` is in your `$PATH` otherwise znp will not be callable from
zathura unless you give the full path to znp.
## Dependencies
1. `python-magic` - used to detect the file type of the next file to prevent
zathura from opening an unreadable file, e.g. log files, markdown files, etc.
2. `psutil` - used to get zathura pids.
## Optional Dependency
1. `ewmh` - used to get the pid of window calling znp. This is a bit hacky but
does allow for the core functionality (opening the next or previous file) to
work without issue. Provided under the `[x11]` branch.
Raw data
{
"_id": null,
"home_page": "",
"name": "znp",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "zathura",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/04/1f/e20117ef765de5bf8ea1239c9bf2ae45e4728f85968bb761f7fbd7967408/znp-0.0.13.tar.gz",
"platform": null,
"description": "# znp\nznp stands for Zathura Next Or Previous. You can also use znp to add a given\nfile to an instance of [zathura](https://pwmt.org/projects/zathura/).\n\n# Usage\n\n## Next or Previous\nThe main goal of znp is to provide an easy way to go to the next or previous\nfile from within zathura. As of\n[yet](https://git.pwmt.org/pwmt/zathura/-/issues/93) this functionality is not a\npart of zathura's functionality. However, after installing `znp` you can add the\nfollowing to your `zathurarc` to set `N` and `P` to go to the next or previous\nfile:\n\n``` vim-snippet\nmap N exec \"znp -n '$FILE'\"\nmap P exec \"znp -p '$FILE'\"\n\" Please note the ^ ^ apostrophes around $FILE. \n\" These are necessary for files with whitespace\n```\n\n*Note* that if your system does not use extended window manager hints\n([ewmh](https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html)), or\nyou do not have the ewmh python package installed; then, this command may fail\nif you have two instances of zathura open in the same directory. This is not\nsomething that I have a reasonable fix for and there is no way to reliably\ndetermine the instance issuing the next or previous command. The only way I can\nthink of fixing this would require patching zathura to include expansion of a\n`$PID` variable from the exec function and include that in the zathurarc\ncommand. However, I am a not a programmer so reviewing the code base and\ngetting this functionality added may take me some time.\n\n## Adding files\nznp can act as a zathura wrapper and add a given file to an existing instance:\n\n``` shell\nznp file.pdf\nznp /path/to/file.pdf\n```\n\nYou can give znp a relative or absolute path to file. znp will insert the\ncurrent working directory to make a relative path absolute. No variable\nexpansion will performed by znp as it expects `$HOME` and such to get expanded\nby the shell calling znp.\n\nThe above works best when only one instance of zathura exists. However, if\nmultiple exist then zathura will use the user defined `prompt_cmd` set in\n`$XDG_CONFIG_HOME/znp/znp.conf` to present a list of zathura instances to open\nthe file in. The default is `fzf` but you may use `dmenu` or `rofi`. Here is\nhow this looks in practice:\n\n![fzf.png](https://codeberg.org/johndovern/znp/raw/branch/master/media/fzf.png \"fzf.png\")\n\n![dmenu.png](https://codeberg.org/johndovern/znp/raw/commit/c5d58cb9a0745c5cfda810f406bbeb84c423566f/media/dmenu.png \"dmenu.png\")\n\nTo aviod any prompting you can pass the desired pid to use with the `-P` flag:\n\n``` shell\nznp -P 123456 file.pdf\nznp -P 123456 /path/to/file.pdf\n```\n\nThis would require a bit more work on your part but it may be useful in\nscripting.\n\n## Query\nSpeaking of scripting, I added the `-q, --query` flag for my personal scripting\npurposes.\n\nThe `--query` flag will take the `FILE` argument given to znp and search all\nzathura pids for the _first_ (see the note in the [next or\nprevious](#next-or-previous) section) one that has that file open and return\nit's pid. I make use of this to track my last read pdf, epub, cbz/r, zip, etc.\nusing the returned pid to kill the assumed instance issuing the command.\nBasically a session tracker so to speak. Maybe there are other purposes for this\nor maybe the `zathura.py` module would be useful as a standalone module for\ninteracting with zathura via dbus. No clue, let me know.\n\n## User config\nYou can set the default command prompt in `$XDG_CONFIG_HOME/znp/znp.conf` like\nso:\n\n```\nprompt_cmd = dmenu\n```\n\n**Note** there are no quotes. You can also skip the spaces if you like.\n\nIf you have any args/flags you want to use with your command prompt add them\nlike so:\n\n```\nprompt_args = -l 20 -i\n```\n\nSimply provide the args/flags as you would normally when using your chosen\nprompt_cmd.\n\n**Note** If your prompt_args contain an `=` sign then please escape it with a\nbackslash otherwise you will get an error.\n\n# Installation\nznp is available via [pypi](https://pypi.org/project/znp/) and can install it\nvia pip in the usual way:\n\n``` shell\npip install znp\n```\n\nUse the following if you are installing on a system running X and using\n[ewmh](https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html):\n\n``` shell\npip install znp[x11]\n```\n\nEnsure `~/.local/bin` is in your `$PATH` otherwise znp will not be callable from\nzathura unless you give the full path to znp.\n\n## Dependencies\n1. `python-magic` - used to detect the file type of the next file to prevent\nzathura from opening an unreadable file, e.g. log files, markdown files, etc.\n2. `psutil` - used to get zathura pids.\n\n## Optional Dependency\n1. `ewmh` - used to get the pid of window calling znp. This is a bit hacky but\ndoes allow for the core functionality (opening the next or previous file) to\nwork without issue. Provided under the `[x11]` branch.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Simple program to open a file in existing zathura instance",
"version": "0.0.13",
"split_keywords": [
"zathura"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a05e32baa212dc4cd714ae7e9211c401a55c26e5b392f49d627ebcab86ee4aad",
"md5": "be468cbe2f2bc6d3da966f215fa09b56",
"sha256": "639730e6c854fd48ca42ddbac77afcba7a3a1732909500afd9a1333fb765260c"
},
"downloads": -1,
"filename": "znp-0.0.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be468cbe2f2bc6d3da966f215fa09b56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24870,
"upload_time": "2023-04-21T22:36:27",
"upload_time_iso_8601": "2023-04-21T22:36:27.810923Z",
"url": "https://files.pythonhosted.org/packages/a0/5e/32baa212dc4cd714ae7e9211c401a55c26e5b392f49d627ebcab86ee4aad/znp-0.0.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "041fe20117ef765de5bf8ea1239c9bf2ae45e4728f85968bb761f7fbd7967408",
"md5": "ff87a4a9918fb65234a9504db4715d76",
"sha256": "4ca4c5f69f2d29de88dbffbd18c2ec9b048fd39a220ab670c7ca3186fd6abdd4"
},
"downloads": -1,
"filename": "znp-0.0.13.tar.gz",
"has_sig": false,
"md5_digest": "ff87a4a9918fb65234a9504db4715d76",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24883,
"upload_time": "2023-04-21T22:36:29",
"upload_time_iso_8601": "2023-04-21T22:36:29.667422Z",
"url": "https://files.pythonhosted.org/packages/04/1f/e20117ef765de5bf8ea1239c9bf2ae45e4728f85968bb761f7fbd7967408/znp-0.0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-21 22:36:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "znp"
}
