| 1 |
Metadata-Version: 2.4 |
| 2 |
Name: goobook |
| 3 |
Version: 3.5.4 |
| 4 |
Summary: Search your google contacts from the command-line or mutt. |
| 5 |
Keywords: abook,mutt,e-mail,gmail,google,address-book |
| 6 |
Author-Email: =?utf-8?q?Christer_Sj=C3=B6holm?= <[email protected]> |
| 7 |
Maintainer-Email: Reuben Thomas <[email protected]> |
| 8 |
License-Expression: GPL-3.0-only |
| 9 |
Classifier: Development Status :: 5 - Production/Stable |
| 10 |
Classifier: Environment :: Console |
| 11 |
Classifier: Operating System :: OS Independent |
| 12 |
Classifier: Intended Audience :: End Users/Desktop |
| 13 |
Classifier: Topic :: Communications :: Email :: Address Book |
| 14 |
Requires-Python: <4.0,>=3.9 |
| 15 |
Requires-Dist: google-api-python-client~=2.0 |
| 16 |
Requires-Dist: simplejson~=3.16 |
| 17 |
Requires-Dist: setuptools>=62.6.0 |
| 18 |
Requires-Dist: pyxdg>=0.28 |
| 19 |
Requires-Dist: google-auth~=2.21 |
| 20 |
Requires-Dist: google-auth-oauthlib~=1.0 |
| 21 |
Requires-Dist: google-auth-httplib2~=0.1 |
| 22 |
Description-Content-Type: text/x-rst |
| 23 |
|
| 24 |
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: |
| 25 |
GooBook -- Access your Google contacts from the command line. |
| 26 |
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: |
| 27 |
|
| 28 |
.. contents:: **Table of Contents** |
| 29 |
:depth: 1 |
| 30 |
|
| 31 |
About |
| 32 |
===== |
| 33 |
|
| 34 |
The purpose of GooBook is to make it possible to use your Google Contacts from |
| 35 |
the command-line and from MUAs such as Mutt. |
| 36 |
It can be used from Mutt the same way as abook. |
| 37 |
|
| 38 |
Installation Instructions |
| 39 |
========================= |
| 40 |
|
| 41 |
pipx |
| 42 |
---- |
| 43 |
|
| 44 |
This is the recommended way to install goobook for most users that don't |
| 45 |
have it available in their distribution. You may first need to install pipx |
| 46 |
itself, which should be available in your distribution. If not, you can |
| 47 |
install it with pip; see: https://pypi.org/project/pipx/ |
| 48 |
|
| 49 |
Install goobook like this:: |
| 50 |
|
| 51 |
$ pipx install goobook |
| 52 |
|
| 53 |
This will install goobook as `~/.local/bin/goobook` (In a UNIX environment). |
| 54 |
|
| 55 |
|
| 56 |
Configuration |
| 57 |
============= |
| 58 |
|
| 59 |
First you need to authenticate yourself: |
| 60 |
|
| 61 |
- Go to https://developers.google.com/people/quickstart/python |
| 62 |
- and click "Enable the People API" |
| 63 |
- select a name (ex. GooBook) |
| 64 |
- select desktop app and create |
| 65 |
- click "Download JSON" and save the file to be used below |
| 66 |
|
| 67 |
run:: |
| 68 |
|
| 69 |
$ goobook authenticate -- client_secrets.json |
| 70 |
|
| 71 |
and follow the instructions, this part is web based. |
| 72 |
|
| 73 |
In case you've already been using goobook and have authenticated with Google |
| 74 |
in the past there is no need to re-authenticate again. |
| 75 |
|
| 76 |
|
| 77 |
If the procedure above to get client secrets stops working this is an alternative way to do it: |
| 78 |
|
| 79 |
- Go to the Google developer console https://console.developers.google.com/ |
| 80 |
- Create a new project (drop down at the top of the screen) (you are free to use an existing one if you so prefer) |
| 81 |
- Select the newly created project |
| 82 |
- Go to OAuth consent screen from sidebar |
| 83 |
- Select the interal user type if you can but most will only be able to select external. |
| 84 |
- On next screen give it a name (ex. GooBook) |
| 85 |
- select Add scope, click manually paste and write "https://www.googleapis.com/auth/contacts" inte the lower text box. |
| 86 |
- and hit hit add and then save |
| 87 |
- Go to Credentials from sidebar |
| 88 |
- Click Create Credentials from top, then OAuth Client ID in the dropdown |
| 89 |
- Choose Desktop app, enter any name you want, and hit create |
| 90 |
- click "Download JSON" and save the file to be used below |
| 91 |
|
| 92 |
|
| 93 |
To authenticate with Google you need a web browser installed. You will be directed to Google and finally |
| 94 |
to http://localhost:8080. Make sure, no other service is bound to port tcp/8080 - otherwise the authentication |
| 95 |
will fail. Make also sure, no local firewall prevents local access to port 8080. |
| 96 |
|
| 97 |
If you do not have a browser installed locally and do not want to install one, you can perform the |
| 98 |
authentication on another system on which goobook and a browser are installed. You will need the client_secrets.json |
| 99 |
file and by performing the authentication create an oauth token file, which you must transfer back to your |
| 100 |
original system. To easily find the oauth token file, create a configuration file in which you enter |
| 101 |
the location and name of the file by:: |
| 102 |
|
| 103 |
oauth_db_filename: ~/.goobook_auth.json |
| 104 |
|
| 105 |
See details about the configuration file in the next section. |
| 106 |
|
| 107 |
This configuration file gets included in the authenticate run like this:: |
| 108 |
|
| 109 |
$ goobook ~/.config/goobookrc authenticate -- client_secrets.json |
| 110 |
|
| 111 |
|
| 112 |
To get access too more settings you can create a configuration file:: |
| 113 |
|
| 114 |
goobook config-template > ~/.config/goobookrc |
| 115 |
|
| 116 |
It will look like this:: |
| 117 |
|
| 118 |
# Use this template to create your ~/.goobookrc |
| 119 |
|
| 120 |
# "#" or ";" at the start of a line makes it a comment. |
| 121 |
|
| 122 |
[DEFAULT] |
| 123 |
# The following are optional, defaults are shown when not other specified. |
| 124 |
|
| 125 |
# This file is written by the oauth library, and should be kept secure, |
| 126 |
# it's like a password to your google contacts. |
| 127 |
# default is to place it in the XDG_DATA_HOME |
| 128 |
;oauth_db_filename: ~/.goobook_auth.json |
| 129 |
|
| 130 |
;cache_filename: ~/.goobook_cache # default is in the XDG_CACHE_HOME |
| 131 |
;cache_expiry_hours: 24 |
| 132 |
;filter_groupless_contacts: yes |
| 133 |
|
| 134 |
# New contacts will be added to this group in addition to "My Contacts" |
| 135 |
# Note that the group has to already exist on google or an error will occur. |
| 136 |
# One use for this is to add new contacts to an "Unsorted" group, which can |
| 137 |
# be sorted easier than all of "My Contacts". |
| 138 |
;default_group: |
| 139 |
|
| 140 |
|
| 141 |
Files |
| 142 |
----- |
| 143 |
|
| 144 |
GooBook is using three files, the optional config file that can be placed in |
| 145 |
the ``XDG_CONFIG_HOME`` (``~/.config/goobookrc``) or in the home directory |
| 146 |
(``~/.goobookrc``). |
| 147 |
|
| 148 |
The authentication file that is created by running goobook authenticate in |
| 149 |
``XDG_DATA_HOME`` (``~/.local/share/goobook_auth.json``) but can also be placed |
| 150 |
in the home directory (``~/.goobook_auth.json``). |
| 151 |
|
| 152 |
The contacts cache file that is created in ``XDG_CACHE_HOME`` |
| 153 |
(``~/.cache/goobook_cache``) but can also be placed in the home directory |
| 154 |
(``~/.goobook_cache``). |
| 155 |
|
| 156 |
Proxy settings |
| 157 |
-------------- |
| 158 |
|
| 159 |
If you use a proxy you need to set the ``https_proxy`` environment variable. |
| 160 |
|
| 161 |
Mutt |
| 162 |
---- |
| 163 |
|
| 164 |
If you want to use goobook from mutt, set in your .muttrc file:: |
| 165 |
|
| 166 |
set query_command="goobook query %s" |
| 167 |
|
| 168 |
to query address book. (Normally bound to "Q" key.) |
| 169 |
|
| 170 |
If you want to be able to use <tab> to complete email addresses instead of Ctrl-t add this:: |
| 171 |
|
| 172 |
bind editor <Tab> complete-query |
| 173 |
|
| 174 |
To add email addresses (with "a" key normally bound to create-alias command):: |
| 175 |
|
| 176 |
macro index,pager a "<pipe-message>goobook add<return>" "add the sender address to Google contacts" |
| 177 |
|
| 178 |
If you want to add an email's sender to Contacts, press a while it's selected in the index or pager. |
| 179 |
|
| 180 |
Usage |
| 181 |
===== |
| 182 |
|
| 183 |
To query your contacts:: |
| 184 |
|
| 185 |
$ goobook query QUERY |
| 186 |
|
| 187 |
The add command reads a email from STDIN and adds the From address to your Google contacts:: |
| 188 |
|
| 189 |
$ goobook add |
| 190 |
|
| 191 |
The cache is updated automatically according to the configuration but you can also force an update:: |
| 192 |
|
| 193 |
$ goobook reload |
| 194 |
|
| 195 |
For more commands see:: |
| 196 |
|
| 197 |
$ goobook -h |
| 198 |
|
| 199 |
and:: |
| 200 |
|
| 201 |
$ goobook COMMAND -h |
| 202 |
|
| 203 |
Links, Feedback and getting involved |
| 204 |
==================================== |
| 205 |
|
| 206 |
- PyPI home: https://pypi.org/project/goobook/ |
| 207 |
- Code Repository: http://gitlab.com/goobook/goobook |
| 208 |
- Issue tracker: https://gitlab.com/goobook/goobook/issues |
| 209 |
- |