Debian Codegraph @

PKG-INFO

raw
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 -