From 36e4021cb79f1fa9fb5c938478bd5701cc247290 Mon Sep 17 00:00:00 2001 From: Harshad Sharma Date: Sat, 17 Jun 2017 02:14:38 +0530 Subject: [PATCH] Update readme. Fix missing properties in as_json() --- README.rst | 176 +++++++++++++++++++++++++++++++++++--- src/qutescript/request.py | 2 + 2 files changed, 167 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index c58ac24..36d7d73 100644 --- a/README.rst +++ b/README.rst @@ -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 diff --git a/src/qutescript/request.py b/src/qutescript/request.py index 5b39cb0..014dbb8 100644 --- a/src/qutescript/request.py +++ b/src/qutescript/request.py @@ -38,6 +38,8 @@ class Request(object): 'title': self.title, 'selected_text': self.selected_text, 'selected_html': self.selected_html, + 'script_path': self.script_path, + 'script_name': self.script_name, } def send_command(self, command):