Metadata-Version: 2.3
Name: goobook
Version: 3.5.3
Summary: Search your google contacts from the command-line or mutt.
License: GPL-3.0-only
Keywords: abook,mutt,e-mail,gmail,google,address-book
Author: Christer Sjöholm
Author-email: goobook2@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email :: Address Book
Requires-Dist: google-api-python-client (>=1.7.12,<2.0.0)
Requires-Dist: google-auth (>=2.21.0,<3.0.0)
Requires-Dist: google-auth-httplib2 (>=0.1.0,<0.2.0)
Requires-Dist: google-auth-oauthlib (>=1.0.0,<2.0.0)
Requires-Dist: pyxdg (>=0.28,<0.29)
Requires-Dist: setuptools (>=62.6.0,<63.0.0)
Requires-Dist: simplejson (>=3.16.0,<4.0.0)
Project-URL: Repository, http://gitlab.com/goobook/goobook
Description-Content-Type: text/x-rst

:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
GooBook -- Access your Google contacts from the command line.
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

.. contents:: **Table of Contents**
   :depth: 1

About
=====

The purpose of GooBook is to make it possible to use your Google Contacts from
the command-line and from MUAs such as Mutt.
It can be used from Mutt the same way as abook.

Installation Instructions
=========================

There is a number of ways to install Python software.

- Using pip
- Using a source tarball
- Using source directly from gitorius
- From a distribution specific repository

Which version to use
--------------------

If you have Python 3.7+ you need to use GooBook 3.x.

pipx
----

This is the recommended way to install goobook for most users that don't
have it available in their distribution. You may first need to install pipx
itself, which should be available in your distribution. If not, you can
install it with pip; see: https://pypi.org/project/pipx/

Install goobook like this::

    $ pipx install goobook

This will install goobook as ~/.local/bin/goobook (In a UNIX environment).


Poetry
------

This is the recommended way if you want to run from a git checkout.
Install poetry if you don't have it, https://python-poetry.org.

clone the git repos, cd into in, and run::

    $ poetry install

Goobook is now installed in a virtualenv created by poetry.
You can test goobook by running::

    $ poetry run goobook

To locate the virtualenv where goobook is installed::

    $ poetry env list --full-path

Source installation from tarball
--------------------------------

Download the source tarball, uncompress it, then run the install command::

    $ tar -xzvf goobook-*.tar.gz
    $ cd goobook-*
    $ sudo python ./setup.py install


Configuration
=============

First you need to authenticate yourself:

- Go to https://developers.google.com/people/quickstart/python
- and click "Enable the People API"
- select a name (ex. GooBook)
- select desktop app and create
- click "Download JSON" and save the file to be used below

run::

    $ goobook authenticate -- client_secrets.json

and follow the instructions, this part is web based.


If the procedure above to get client secrets stops working this is an alternative way to do it:

- Go to the Google developer console  https://console.developers.google.com/
- Create a new project (drop down at the top of the screen) (you are free to use an existing one if you so prefer)
- Select the newly created project
- Go to OAuth consent screen from sidebar
- Select the interal user type if you can but most will only be able to select external.
- On next screen give it a name (ex. GooBook)
- select Add scope, click manually paste and write "https://www.googleapis.com/auth/contacts" inte the lower text box.
- and hit hit add and then save
- Go to Credentials from sidebar
- Click Create Credentials from top, then OAuth Client ID in the dropdown
- Choose Desktop app, enter any name you want, and hit create
- click "Download JSON" and save the file to be used below


To get access too more settings you can create a configuration file::

    goobook config-template > ~/.config/goobookrc

It will look like this::

    # Use this template to create your ~/.goobookrc

    # "#" or ";" at the start of a line makes it a comment.

    [DEFAULT]
    # The following are optional, defaults are shown when not other specified.

    # This file is written by the oauth library, and should be kept secure,
    # it's like a password to your google contacts.
    # default is to place it in the XDG_DATA_HOME
    ;oauth_db_filename: ~/.goobook_auth.json

    ;cache_filename: ~/.goobook_cache   # default is in the XDG_CACHE_HOME
    ;cache_expiry_hours: 24
    ;filter_groupless_contacts: yes

    # New contacts will be added to this group in addition to "My Contacts"
    # Note that the group has to already exist on google or an error will occur.
    # One use for this is to add new contacts to an "Unsorted" group, which can
    # be sorted easier than all of "My Contacts".
    ;default_group:


Files
-----

GooBook is using three files, the optional config file that can be placed in
the ``XDG_CONFIG_HOME`` (``~/.config/goobookrc``) or in the home directory
(``~/.goobookrc``).

The authentication file that is created by running goobook authenticate in
``XDG_DATA_HOME`` (``~/.local/share/goobook_auth.json``) but can also be placed
in the home directory (``~/.goobook_auth.json``).

The contacts cache file that is created in ``XDG_CACHE_HOME``
(``~/.cache/goobook_cache``) but can also be placed in the home directory
(``~/.goobook_cache``).

Proxy settings
--------------

If you use a proxy you need to set the ``https_proxy`` environment variable.

Mutt
----

If you want to use goobook from mutt.

Set in your .muttrc file::

    set query_command="goobook query %s"

to query address book. (Normally bound to "Q" key.)

If you want to be able to use <tab> to complete email addresses instead of Ctrl-t add this::

    bind editor <Tab> complete-query

To add email addresses (with "a" key normally bound to create-alias command)::

    macro index,pager a "<pipe-message>goobook add<return>" "add the sender address to Google contacts"

If you want to add an email's sender to Contacts, press a while it's selected in the index or pager.

Usage
=====

To query your contacts::

    $ goobook query QUERY

The add command reads a email from STDIN and adds the From address to your Google contacts::

    $ goobook add

The cache is updated automatically according to the configuration but you can also force an update::

    $ goobook reload

For more commands see::

    $ goobook -h

and::

    $ goobook COMMAND -h

Links, Feedback and getting involved
====================================

- PyPI home: https://pypi.org/project/goobook/
- Code Repository: http://gitlab.com/goobook/goobook
- Issue tracker: https://gitlab.com/goobook/goobook/issues
- Mailing list: http://groups.google.com/group/goobook