Command-line interface

The hubspot3 client comes with an optional command-line interface that makes it easy to use the client’s features without necessarily importing it within a Python project.

Installation

To use the command-line interface you will have to install an additional Python requirement:

pip install hubspot3[cli]

Usage

After the installation you can use the client with the hubspot3 command, e.g. to display the help:

hubspot3 --help

This will display all arguments for the general usage of the command-line client, like the API key (or a config file, see below). Please take a look into the constructor of the hubspot3.Hubspot3 class for the list of provided arguments.

By just calling hubspot3 you will get a list of all featured APIs that are available, e.g.:

huspot3

Usage:       hubspot3 -
             hubspot3 - blog
             hubspot3 - blog-comments
             hubspot3 - broadcast
[...]

By attaching the API name you can access the specific API endpoints:

hubspot3 deals

Usage:       hubspot3 deals
             hubspot3 deals associate
             hubspot3 deals create
             hubspot3 deals get
[...]

Each API method has it’s own documentation and the help can be displayed like this:

hubspot3 deals get -- --help

[...]
Docstring:   Supported ARGS/KWARGS are:
DEAL_ID [--OPTIONS ...]
--deal-id DEAL_ID [--OPTIONS ...]
[...]

This will display the methods parameter list and how to pass them to the specific API endpoint, in this case you can get the deal information for a specific deal with:

hubspot3 --api-key xxxxxxxxx-xxxx-xxx-xxxx-xxxxx deals get --deal-id 100

Note

You will notice the leading -- in front of the --help parameter. Hubspot3 uses the python-fire library to generate a dynamic command-line interface for all API clients. If you don’t add the -- the help command will be passed as an argument API method instead of invoking Fire’s help output, so we have to set it. Generally speaking, the arguments for the API method call need to be separated from general CLI arguments using --.

Configuration file

Instead of providing the API key (--api-key) or other settings (like --client-id or --timeout) as parameters you can also create a local JSON file, that contains all the settings you want to pass to the client:

{
    "api_key": "xxxxxxxxx-xxxx-xxx-xxxx-xxxxx",
    "timeout": 60
}

Simply call the hubspot client with the --config parameter:

hubspot3 --config config.json

Using stdin for parameters

Some of the data you want to pass to the hubspot3 may be sensitive or just too much to pass it as a regular parameter. Therefore you can simply pass data from stdin to the client so that the data can be streamed and won’t occur in your shell history. To do so just use the token __stdin__ for one of your parameters:

hubspot3 --config config.json \
   contacts update --contact_id 451 \
   --data "__stdin__" < contact_data.json

In this case contact_data.json is a JSON file that contains the contacts data to update:

{
    "properties": [
        {
            "property": "firstname",
            "value": "Adrian"
        },
        {
            "property": "lastname",
            "value": "Mott"
        }
    ]
}

Extending the APIs

There is one specialty in the way python-fire discovers the API clients: it will parse all classes that are derived from BaseClient and are provided as a property within the hubspot3.Hubspot3 class. Within these API clients python-fire will look for public methods and provide them as a command-line operation.

If you want to hide python-fire certain properties from the hubspot3.Hubspot3 class (e.g. because it will instantly make a call to Hubspot or the property doesn’t reflect an API endpoint) you can hide that property by extending the Hubspot3CLIWrapper.IGNORED_PROPERTIES tuple within hubspot3/__main__.py:

class Hubspot3CLIWrapper(object):

    IGNORED_PROPERTIES = ('me', 'usage_limits', 'my_method_to_hide')

In a similar fashion, public methods of the individual API clients can be hidden by extending the dictionary ClientCLIWrapper.IGNORED_METHODS within the same module. It uses the client classes as keys and iterables containing method names to hide as values:

class ClientCLIWrapper(object):

    IGNORED_METHODS = {
        LeadsClient: ('camelcase_search_options',),
        MyClient: ('my_method',),
    }