|
|
|
@ -7,15 +7,6 @@ Painless userscripts for qutebrowser.
|
|
|
|
|
|
|
|
|
|
* Free software: BSD license
|
|
|
|
|
|
|
|
|
|
Status
|
|
|
|
|
======
|
|
|
|
|
|
|
|
|
|
Very alpha, "works for me" on MacOS Sierra with Python 3.6;
|
|
|
|
|
if you like what you see, please test it on your platform
|
|
|
|
|
and help by submitting pull-requests if your current skills
|
|
|
|
|
allow.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
@ -26,8 +17,8 @@ Installation
|
|
|
|
|
pip install -e .
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Usage
|
|
|
|
|
=====
|
|
|
|
|
Example
|
|
|
|
|
=======
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
@ -45,3 +36,166 @@ Usage
|
|
|
|
|
hello_world()
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tutorial
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
At the time of writing this, I know of qutebrowser for only two days.
|
|
|
|
|
That is a testament to how addictive this new keyboard-access browser
|
|
|
|
|
can be if you prefer that kind of a thing. If you haven't heard of it
|
|
|
|
|
yet, and you like vim and python - qutebrowser might be just for you.
|
|
|
|
|
|
|
|
|
|
It is a lightweight browser built on top of PyQt5 toolkit, works
|
|
|
|
|
with current Python (3.6.x) and has affinity for doing things the
|
|
|
|
|
unix way - clean, simple, no bullshit.
|
|
|
|
|
|
|
|
|
|
As with unix philosophy, it can pipe commands with webpage text,
|
|
|
|
|
current URL etc to your shell scripts or binaries, and can accept
|
|
|
|
|
commands through a temporary FIFO/pipe back to the browser.
|
|
|
|
|
|
|
|
|
|
The qutebrowser documentation can get you started:
|
|
|
|
|
|
|
|
|
|
https://github.com/qutebrowser/qutebrowser/blob/master/doc/userscripts.asciidoc
|
|
|
|
|
|
|
|
|
|
Although if you, like me are interested in writing custom userscripts
|
|
|
|
|
to automate tasks and kinda prefer Python to shell scripts, you will
|
|
|
|
|
need some boilerplate code that gets copy-pasted to every new userscript.
|
|
|
|
|
|
|
|
|
|
qutescript is an attempt at reducing that boilerplate, while also adding
|
|
|
|
|
a few helpful features for debugging the script directly from qutebrowser.
|
|
|
|
|
Get exception traceback for a failing script in a new tab instead of
|
|
|
|
|
switching to the terminal to check logs, you were logging to a file instead
|
|
|
|
|
of terminal, weren't you? ;)
|
|
|
|
|
|
|
|
|
|
Alright, enough talk... let's set this up!
|
|
|
|
|
|
|
|
|
|
1. Install qutebrowser:
|
|
|
|
|
https://github.com/qutebrowser/qutebrowser
|
|
|
|
|
|
|
|
|
|
2. Clone qutescript:
|
|
|
|
|
`git clone https://github.com/hiway/python-qutescript.git qutescript`
|
|
|
|
|
|
|
|
|
|
3. Install qutescript:
|
|
|
|
|
`$ cd qutescript; pip install -e .`
|
|
|
|
|
|
|
|
|
|
4. Install an example or two:
|
|
|
|
|
`$ python examples/debug.py --install --bin=debug`
|
|
|
|
|
`$ python examples/shell.py --install --bin=shell`
|
|
|
|
|
|
|
|
|
|
5. Run qutebrowser and run:
|
|
|
|
|
`:spawn --userscript debug --kaboom`
|
|
|
|
|
|
|
|
|
|
6. Create a new file:
|
|
|
|
|
`vim my_hello.py`
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
#!/usr/bin/env python
|
|
|
|
|
# coding=utf-8
|
|
|
|
|
|
|
|
|
|
from qutescript import userscript
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@userscript
|
|
|
|
|
def hello_world(request):
|
|
|
|
|
request.send_text('Hello, me! :P')
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
if __name__ == '__main__':
|
|
|
|
|
hello_world()
|
|
|
|
|
|
|
|
|
|
7. Install your script:
|
|
|
|
|
`$ python examples/my_hello.py --install --bin=myhello`
|
|
|
|
|
|
|
|
|
|
8. Try it in qutebrowser:
|
|
|
|
|
`:spawn --userscript myhello`
|
|
|
|
|
|
|
|
|
|
9. Continue reading the reference section for details.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Reference
|
|
|
|
|
=========
|
|
|
|
|
|
|
|
|
|
@userscript
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
This is a python decorator, it allows qutescript
|
|
|
|
|
to "wrap" your function with extra capabilities such as:
|
|
|
|
|
|
|
|
|
|
- Inject "request" parameter in the wrapped function.
|
|
|
|
|
- Access environment variables passed by qutebrowser
|
|
|
|
|
as properties on request.
|
|
|
|
|
example: `os.getenv('QUTE_URL', '')` maps to => `request.url`
|
|
|
|
|
- Catch any exceptions and log them to file.
|
|
|
|
|
- Also log exceptions to a new browser tab if possible.
|
|
|
|
|
- Interact with the browser through request.send_text() etc.
|
|
|
|
|
- Adds a shortcut: if your function returns a string,
|
|
|
|
|
it is sent to the browser as a command.
|
|
|
|
|
- Install the script to qutebrowser's application directory,
|
|
|
|
|
so you can access the scripts without typing full
|
|
|
|
|
absolute path every time. Remembers to change permissions.
|
|
|
|
|
|
|
|
|
|
request
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
Your function will get an instance of Request() object which has
|
|
|
|
|
the following properties set from environment variables as defined
|
|
|
|
|
here:
|
|
|
|
|
|
|
|
|
|
https://github.com/qutebrowser/qutebrowser/blob/master/doc/userscripts.asciidoc
|
|
|
|
|
|
|
|
|
|
- `mode`
|
|
|
|
|
- `user_agent`
|
|
|
|
|
- `fifo`
|
|
|
|
|
- `html`
|
|
|
|
|
- `text`
|
|
|
|
|
- `config_dir`
|
|
|
|
|
- `data_dir`
|
|
|
|
|
- `download_dir`
|
|
|
|
|
- `commandline_text`
|
|
|
|
|
- `url`:
|
|
|
|
|
- `title`
|
|
|
|
|
- `selected_text`
|
|
|
|
|
- `selected_html`
|
|
|
|
|
|
|
|
|
|
Additional information is available on:
|
|
|
|
|
|
|
|
|
|
- `script_name`: Basename of the running script.
|
|
|
|
|
- `script_path`: Absolute path of the running script.
|
|
|
|
|
|
|
|
|
|
Request also defines a some utility methods:
|
|
|
|
|
|
|
|
|
|
- `as_dict()` returns the above properties as a dictionary.
|
|
|
|
|
|
|
|
|
|
You can interact with the browser with:
|
|
|
|
|
|
|
|
|
|
- `send_text(text)`: send pre-formatted text to new tab.
|
|
|
|
|
- `send_html(html)`: send raw html to new tab.
|
|
|
|
|
- `send_command(command)`: sends a command to the browser.
|
|
|
|
|
|
|
|
|
|
Remember to look at the examples directory for inspiration.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Status
|
|
|
|
|
======
|
|
|
|
|
|
|
|
|
|
Very alpha, "works for me" on MacOS Sierra with Python 3.6;
|
|
|
|
|
if you like what you see, please test it on your platform
|
|
|
|
|
and help by submitting pull-requests if your current skills
|
|
|
|
|
allow. This readme is all the documentation there is, apart
|
|
|
|
|
from the code and comments. Oh, and no tests so far…
|
|
|
|
|
however the code is written to be testable, it's a matter
|
|
|
|
|
of someone taking the effort ;)
|
|
|
|
|
|
|
|
|
|
Please open a new issue if you have questions.
|
|
|
|
|
|
|
|
|
|
Code of Conduct
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
TL;DR:
|
|
|
|
|
|
|
|
|
|
Aggressive, hateful, derogatory or discriminatory
|
|
|
|
|
remarks will not be tolerated: contributions in code
|
|
|
|
|
are never more important than the well-being of our
|
|
|
|
|
communities. That said, it's great to be kind to one
|
|
|
|
|
another, whether writing code or not - let us all
|
|
|
|
|
try more of that? :D
|
|
|
|
|