cliquery 1.9.0

a command-line browser interface

cliquery |PyPI Version| |Build Status| |PyPI Monthly downloads|
===============================================================

a command-line browser interface
--------------------------------

cliquery cuts down on clicking through command-line web searching, page
previewing, and page bookmarking, among other features. An interactive
prompt allows users to easily make successive queries and enter program
flags dynamically; simply typing help will list all possible flags to
enter. Opening a link will invoke a browser supplied by the user or
detected automatically across Windows, OSX, and Linux platforms.

Installation
------------

::

pip install cliquery

or

::

pip install git+https://github.com/huntrar/cliquery.git#egg=cliquery

or

::

git clone https://github.com/huntrar/cliquery
cd cliquery
python setup.py install

If you encounter issues installing lxml, see
`here <http://lxml.de/installation.html>`__.

Recommended setup
-----------------

Sign up for a `Google Custom Search API
key <https://code.google.com/apis/console>`__ to access Google results,
otherwise search results will come from Bing.

Upon signing into Google, click on API Manager, then Credentials, and
create an API key. Enter this under the 'google\_api\_key' field in
.cliqrc.

Next, `create a custom search engine <https://cse.google.com/all>`__.
You must choose at least one site to search during creation (I chose
stackoverflow.com), but to search the entire web you must click on this
new search engine, go to Setup, then Basics, and select 'Search the
entire web but emphasize included sites.' Then you may choose to keep or
delete the site you originally provided.

After creating a custom search engine, click on the engine, go to Setup,
and under Details click Search engine ID. Enter this under the
'google\_engine\_key' field in .cliqrc.

To use cliquery for scientific computations, sign up for a `WolframAlpha
API key <https://developer.wolframalpha.com/portal/apisignup.html>`__
and enter this under the 'wolfram\_api\_key' field in .cliqrc.

A browser may be explicitly chosen by entering the executable name under
the 'browser' field in .cliqrc (if you do not set a browser, one will be
detected automatically). An alternative method of setting your browser
is with the BROWSER environment variable.

It is advised to copy the blank .cliqrc into .local.cliqrc, as .cliqrc
will be emptied after a program update. To do this, enter the following:

::

cd "$(dirname "$(cliquery -c)")"
sudo cp .cliqrc .local.cliqrc

Users may also import Firefox or Chrome bookmarks into .cliqrc by
exporting the bookmarks to HTML and importing to cliquery with the -i
flag. The imported bookmarks will be added to your existing bookmarks,
which may result in duplicates.

Usage
-----

::

usage: cliquery.py [-h] [-b] [-c] [-C] [-d] [-e] [-f] [-i [IMPORT]] [-o] [-p]
[-s] [-v] [-w]
[QUERY [QUERY ...]]

a command-line browser interface

positional arguments:
QUERY keywords to search

optional arguments:
-h, --help show this help message and exit
-b, --bookmark view and modify bookmarks
-c, --config print config file location
-C, --clear-cache clear the cache
-d, --describe summarize links
-e, --edit edit config file
-f, --first open first link
-i [IMPORT], --import [IMPORT]
import bookmarks from file
-o, --open directly open links
-p, --print print links to stdout
-s, --search search for links
-v, --version display current version
-w, --wolfram search WolframAlpha

Author
------

- Hunter Hammond ([e-mail])

Notes
-----

- Supports both Python 2.x and Python 3.x.
- NOTE: If you receive the following message (or similar) when trying
to modify bookmarks:

::

IOError: [Errno 13] Permission denied: '/usr/local/lib/python2.7/dist-packages/cliquery/.cliqrc'

Then you have two options:

::

1. (recommended) Change file ownership from root to user by entering the following:

sudo chown $USER "$(cliquery -c)"

2. Execute cliquery as root, using su or sudo.

- A search may return immediate results, such as calculations or facts
made possible by WolframAlpha, or instead a page of Google search
results comprised of links and their descriptions.
- Interactive usage allows the user to continue making new queries by
dynamically executing new program flags and/or queries. Entering h or
help will list all possible prompt commands.

::

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
1. Guido van Rossum - Official Site
2. Images of python guido
3. Guido van Rossum - Wikipedia, the free encyclopedia
4. Guido van Rossum (@gvanrossum) | Twitter
5. Guido van Rossum Wants to Bring Type Annotations to Python
6. The Python Tutorial — Python 2.7.10 documentation
7. Python (programming language) - Wikipedia, the free ...
8. Van Rossum: Python is not too slow | InfoWorld
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
: d 1

Guido's Personal Home Page Guido van Rossum - Personal Home Page "Gawky and proud of it."
Dutch spelling rules dictate that when used in combination with myfirst name, "van" is not capitalized: "Guido van Rossum".
But when mylast name is used alone to refer to me, it is capitalized, forexample: "As usual, Van Rossum was right."
More Hyperlinks Here's a collection of essays relating to Pythonthat I've written, including the foreword I wrote for Mark Lutz' book"Programming Python".
The Audio File Formats FAQ I was the original creator and maintainer of the Audio File FormatsFAQ. It is now maintained by Chris Bagwellat http://www.cnpbagwell.com/audio-faq .
[Press Enter to continue..]

- To choose multiple links at once, a range may be specified by
separating the start and end range with a dash. Leaving one end of
the range blank will choose all links until the other end of that
range. For example, given 10 links, entering 5- would effectively be
the same as entering 5-10.
- Requests cache is enabled by default to cache webpages, it can be
disabled by setting the environment variable CLIQ\_DISABLE\_CACHE.
- Using the bookmark flag with no arguments will list all current
bookmarks in .cliqrc, naturally ordered by time of entry. Entering
help with the flag will list all possible commands including open,
add, remove, tag/untag (for aliasing), describe, and move. Bookmarks
like other flags may be entered during runtime in the link prompt.
- Additional arguments may be appended to bookmarks while opening them.
These are interpreted as any non-integer arguments which are not
found in any bookmarks (URLs or tags).

.. |PyPI Version| image:: https://img.shields.io/pypi/v/cliquery.svg
:target: https://pypi.python.org/pypi/cliquery
.. |Build Status| image:: https://travis-ci.org/huntrar/cliquery.svg?branch=master
:target: https://travis-ci.org/huntrar/cliquery
.. |PyPI Monthly downloads| image:: https://img.shields.io/pypi/dm/cliquery.svg?style=flat
:target: https://pypi.python.org/pypi/cliquery


News
====

1.9.0
------

- Bugfix: UnicodeEncodeError for py3 descriptions

1.8.10
------

- Removed some bookmarks that snuck into the config

1.8.9
------

- Bugfix: No longer interprets 'Automatically detected' as a valid browser

1.8.8
------

- Bugfix: lxml decoding error with requests in Python 3
- Bugfix: another itertools.izip replacement with six.move.zip

1.8.7
------

- Bugfix: Replaced itertools.izip with six.move.zip for Python 3

1.8.6
------

- Updated LICENSE

1.8.5
------

- 3.6 added as supported version in setup

1.8.4
------

- Add scheme to URL's before opening in browser
- Changed *_protocol util functions to *_scheme as it refers to http:// only

1.8.3
------

- Removed error message during webbrowser IndexError

1.8.2
------

- Fixed webbrowser module throwing IndexError

1.8.1
------

- Removed multiple browser options in .cliqrc

1.8.0
------

- Added -e argument to edit configuration

1.7.12
------

- Converted markdown README to rst
- Added setup topic Utilities

1.7.11
------

- Updated old function references
- More refactoring

1.7.10
------

- Fixed issues with six module requirement

1.7.9
------

- Check for version before encoding strings
- Changed six module version to 1.9.0

1.7.8
------

- Replaced compat.py with six module
- Made imports relative rather than from PATH

1.7.7
------

- Bugfix: Import 2-3 compatible range and input (will be replacing this with six)
- Refactorings

1.7.6
------

- Moved requests cache to utils
- Tagged function blocks in utils
- Removed redundant assignments in __init__

1.7.5
------

- Removed crange, cinput definitions and reassigned builtins instead
- Updated setup keywords
- Removed --use-mirrors for 3.5 support

1.7.4
------

- Bugfix: updated new configuration file writing

1.7.3
------

- Bugfix: updated reference api_key to wolfram_api_key

1.7.2
------

- Cannot support 3.5 until --no-mirrors removed (thanks lxml!)

1.7.1
------

- Support for 3.2 removed (Google API can't handle) and support for 3.5 added

1.7.0
------

- google removed old API, now requires google api key and search engine key

1.6.10
------

- check for no results from google

1.6.9
------

- fixed tagging multiple bookmarks during add

1.6.8
------

- import bookmarks now appends to existing

1.6.7
------

- can now import bookmarks from firefox or chrome

1.6.6
------

- had to rename compatible builtins for python3

1.6.5
------

- new files for bookmarks, config, and url opening

1.6.4
------

- unescape html when printing links

1.6.3
------

- removed adding url extension, too unreliable

1.6.2
------

- multi-platform browser auto detect replaced "cygwin" option
- added link to lxml installation & fixed formatting in readme

1.6.1
------

- updated error handling notes regarding .cliqrc permissions
- updated setup.py description and added new keywords
- wrapped requests_cache in try/except as it is a non-crucial library
- wrapped all webbrowser.get()'s in try/except

1.6.0
------

- can now enter multiple browsers to fall back on in .cliqrc
- moved config setup out of cmd line runner and into search

1.5.10
------

- catches KeyboardInterrupt/EOFError in search

1.5.9
------

- fixed IndexError when passing no args to some bookmark cmds

1.5.8
------

- fixed search/wolfram not opening homepages if no query given

1.5.7
------

- renamed "browsing utility" to browser interface

1.5.6
------

- improved method of identifying extensions (still not totally reliable)

1.5.5
------

- development status reverted to beta

1.5.4
------

- replaced zip with itertools.izip

1.5.3
------

- refined search and query preprocessing behavior

1.5.2
------

- improvements to bookmark functions

1.5.1
------

- can now print URL behind bookmark with 'desc'

1.5.0
------

- entering f/first in link prompt now equivalent to entering '1'

1.4.9
------

- fixed get_title bug that snuck in during cleanup

1.4.8
------

- decode google response for python3 compatibility

1.4.7
------

- replaced bing scraping with google ajax api
- other general cleanup

1.4.6
------

- search now checks bookmark and first flags before others
- other general cleanup

1.4.5
------

- empty browser no longer opened when out of range link number entered
- fixed open ended range mistakenly printing help message (like -num)
- proper bounds checking for open ended ranges
- added in_range utils function
- moved bookmark mv error before file overwriting

1.4.4
------

- can now append additional arguments when opening bookmark URL's

1.4.3
------

- fixed simple search and open not working

1.4.2
------

- link prompt now supports multiple dynamic flag arguments

1.4.1
------

- catch EOFError during link prompt polling

1.4.0
------

- fixed unicode warning in pyteaser
- removed whitespace from pyteaser summary

1.3.9
------

- can now display search results in browser using -so or -wo
- moved python 2 to 3 compatibility functions to their own file
- added module docstrings

1.3.8
------

- fixed unicode encode/decode errors

1.3.7
------

- removed pyteaser test for now due to inconsistent results
- changed definition of uni(x) in pyteaser back again

1.3.6
------

- changed definition of uni(x) in pyteaser back

1.3.5
------

- renamed u(x) and a(x) to uni(x) and asc(x)
- changed u(x) definition in pyteaser.py to match cliquery.py

1.3.4
------

- fixed python 2 vs 3 encodings
- added bing instant test

1.3.3
------

- fixed describe function not working for python3

1.3.2
------

- docstring improvements to conform to pep257

1.3.1
------

- second attempt at fixing pyteaser unicode conversion

1.3.0
------

- fixed bytes compatibility issue in pyteaser unicode function

1.2.9
------

- allowed all urls to be candidates for describe_url()
- changed pyteaser unicode codecs function with encode()

1.2.8
------

- replaced unicode() with a cross-version compatible function

1.2.7
------

- added pyteaser test
- removed extraneous print statements
- updated program flag descriptions
- updated README example in notes

1.2.6
------

- removed 'u' string prefix for python 3.2 support

1.2.5
------

- added pyteaser file with no third party dependencies

1.2.4
------

- replaced pyteaser SummarizeUrl with Summarize, removing dependency on Goose

1.2.3
------

- forgot to print pyteaser description

1.2.2
------

- fixed describe error message

1.2.1
------

- describe method now uses pyteaser.SummarizeUrl()

1.2.0
------

- open bookmarks with most matched terms rather than first found

1.1.9
------

- bookmark commands move and del changed to mv and rm
- bookmark move now inserts at an index and shifts entries rather than swapping

1.1.8
------

- added docstrings to all functions
- added dictionary iter helper functions for python 2 to 3 compatibility

1.1.7
------

- added print_function to list of __future__ imports

1.1.6
------

- added base_url back to bing_search()

1.1.5
------

- opens google instead of bing when running cliquery -s with no arguments

1.1.4
------

- prompt no longer exits when no input given
- modularized some functions

1.1.3
------

- can now untag individual tags in bookmarks by tag substrings
- can no longer untag multiple bookmarks at once
- added KeyboardInterrupt to list of exceptions to handle in link prompt
- an exception during link prompt now causes prompt to exit

1.1.2
------

- rearranged globals and made names more descriptive

1.1.1
------

- print tag names in place of bookmark urls if any found

1.1.0
------

- fixed UnicodeEncodeError in wolfram xml response

1.0.9
------

- dynamically entered flags are now kept active until new flag entered

1.0.8
------

- optimizations in check_input()

1.0.7
------

- fixed number ranges and handling multiple links in link prompt

1.0.6
------

- fixed opening links with no special flags (default is open)

1.0.5
------

- ran pep8 check and made changes

1.0.4
------

- can use -s and -w with no args to open bing and wolframalpha respectively

1.0.3
------

- added move bookmark command for repositioning bookmarks

1.0.2
------

- missing colon

1.0.1
------

- improvements to read_config()

1.0.0
------

- bookmarks now fully functional

0.9.9
------

- fixed link prompt exiting after one command, still fixing interactive use of bookmarks

0.9.8
------

- removed an unnecessary print statement

0.9.7
------

- added tag/untag command for bookmarks to add aliases
- can now add/delete/tag multiple bookmarks at once

0.9.6
------

- hotfix for description flag

0.9.5
------

- massive code cleanup using pylint as reference

0.9.4
------

- slightly changed long program description

0.9.3
------

- changed program description and keywords
- added pypi monthly downloads to readme

0.9.2
------

- returns None in bing_search and open_first if internet connection problem causes no html to be found
- this way unit tests will not show a false positive due to a non programming issue

0.9.1
------

- made open_first more readable

0.9.0
------

- open_first now filters /images/ and /videos/ if using describe flag as well

0.8.11
------

- placed describe() functionality within describe_url() and removed describe()

0.8.10
------

- added more error handling custom messages

0.8.9
------

- improved troubleshooting instructions in readme

0.8.8
------

- added more startswith('http://') replacements in utils
- added linebreak after travis-ci status image
- more function documentation

0.8.7
------

- added error handling for attempting to describe a video link (unsupported, as are images)

0.8.6
------

- added travis-ci status image to readme

0.8.5
------

- removed incompatible version 2.6 (due to collections.OrderedDict) from .travis.yml and setup.py

0.8.4
------

- added further troubleshooting to IOError when adding/deleting bookmarks
- more replacements of 'http://' in with startswith('http://')
- url_quote (aka urllib.quote_plus) no longer called with bookmark flag
- fixed bookmarks add/remove after quote_plus change
- added from __future__ import absolute_import for explicit relative imports
- added more keywords to setup.py

0.8.3
------

- removed import utils from cliquery unit test

0.8.2
------

- added .travis.yml to test build and requirements.txt which holds list of dependencies

0.8.1
------

- no longer triggers no search terms error if flag is 'open' to allow for plain browser open

0.8.0
------

- added return statements to all functions in search()
- added test_cliquery.py unit tests
- switched 'http://' in url to url.startswith('http://'), same for https

0.7.12
------

- minor wording changes to installation instructions

0.7.11
------

- added instructions to create .local.cliqrc file in installation instructions

0.7.10
------

- fixed bad formatting with README installation instructions

0.7.9
------

- added urllib getproxies for use with requests
- replaced url special character encoding (hardcoded symbol_dict) with urllib's quote_plus
- replaced occurrences of 'link' with 'url' when referring to a web address specifically
- general function cleanup, including use of format instead of concat'ing strings when conveniently possible

0.7.8
------

- checks for .local.cliqrc before .cliqrc

0.7.4
------

- updated usage in README

0.7.3
------

- changed --CLEAR-CACHE back to --clear-cache, previously thought name conflict is avoided by not allowing to clear cache from link prompt

0.7.2
------

- added -p, --print flag for printing links to stdout
- removed bing_open function as open_link does its job already

0.7.1
------

- removed .testrc file that snuck in

0.7.0
------

- improvements to documentation

0.6.12
------

- changed occurence of args['clear_cache'] to args['CLEAR_CACHE'] per the previous update

0.6.11
------

- changed --clear-cache flag to --CLEAR-CACHE, necessary to avoid a name conflict when resolving link prompt flags (--clear-cache and --config both resolve to 'c')

0.6.10
------

- updated README

0.6.9
------

- added requests-cache which caches recent queries in ~/.cache/cliquery

0.6.8
------

- describe fetches lines with length at least a fifth of avg length, changed from half

0.6.7
------

- returns bookmarks even if fail to find browser and api key in cliqrc

0.6.6
------

- dist upload to pypi failed due to permissions error, just a reupload of 6.5

0.6.5
------

- removed check for 'describe' flag in search() as it is checked in subsequent functions anyways

0.6.4
------

- removed border printed when describing links

0.6.3
------

- added package_data field in setup.py to include .cliqrc in the sdist
- subsequently removed check_config() as .cliqrc will be included
- added LICENSE.txt to MANIFEST.in
- now allows empty browser: field in .cliqrc, webbrowser lib can resolve browser itself

0.6.2
------

- added requests to setup.py install_requires

0.5.8
------

- reformatting to conform with PEP 8
- added shebang

0.5.7
------

- moved a lot of generic functions to utils.py
- fixed some spacing formatting and changed % to format()

0.5.6
------

- uncommented version import

0.5.5
------

- more flag support, 'first' now works in link prompt
- description flag now allows ranges and multiple numbers

0.5.4
------

- more improvements to link prompt flags and command line behavior
- removed ad block regex, too broad

0.5.3
------

- changed instances of type() to isinstance()

0.5.2
------

- removed some misplaced lines

0.5.1
------

- updated link prompt help message

0.5.0
------

- reworked a lot of logic in bing_search for more flexibility when changing flags
- bookmarks are read even when bookmark flag isnt specified from command line runner also for flexibility

0.4.9
------

- fixed UnboundLocalError when api_key not in config
- made Wolfram API key optional

0.4.8
------

- uncommented version import

0.4.7
------

- quick fix for deleting/opening bookmarks using a num

0.4.6
------

- can add and delete bookmarks using -b add [url] and -b del [url] or [num]
- can now open and delete bookmarks using a substring of the url

0.4.5
------

- removed bookmark test code that snuck into commit

0.4.4
------

- updates to setup.py

0.4.3
------

- calling -o with no arguments opens browser in current directory

0.4.2
------

- fixed version import

0.4.1
------

- python 3 support, switched urllib2 to requests and other minor changes

0.4.0
------

- rehaul of interactive mode, can now reuse most flags without exiting the prompt

0.3.3
------

- added -c flag to print location of config

0.3.2
------

- renamed CLIQuery to cliquery

0.3.1
------

- improved description output readability

0.3.0
------

- fixed desc flag behavior when given standalone

0.2.9
------

- proper checking for 'cygwin' as browser before writing errors

0.2.8
------

- updates to .cliqrc creation and error messages

0.2.5
------

- .cliqrc now created on first run

0.2.4
------

- Now available on PyPI

0.2.3
------

- First entry