Add a CLI

[W1ldPo1nter]

This PR will extend the hubspot3 package by a command line interface, which would make it possible to use all of the package's API-interacting functionality outside of a Python project. This would be useful for things like:

• embedding it in applications not written in Python
• using it to simply test API calls or to perform some quick one-time actions using the command-line

Usage

Using a checkout of the source, it could be called like this: python -m hubspot3 ...

Due to the added entrypoint in the setup.py, the usage becomes even easier after the package was actually installed via setuptools/pip: hubspot3 ...

The actual arguments passed to the CLI would always have the following format: python -m hubspot3 <client args> <api name> <method name> <method args> where

• <client args> are named arguments to pass to the Hubspot3 initializer, e.g. --api_key demo
• <api name> is the name of the "sub-client" to call, whereby the name is derived from the names are the ones of the properties on the Hubspot3 object, e.g. contacts
• <method name> name is the name of the python method to invoke on the "sub-client", e.g. get_contact_by_id for the contacts client
• <method args> are arguments passed as to the called python method als parameters, e.g. simply 51 for positional arguments or --contact_id 51 for named arguments

An example call would therefore look like this: python -m hubspot3 --api_key demo contacts get_contact_by_id --contact_id 51 Assuming a contact with this ID exists, the CLI will then output the JSON-encoded results from the API on stdout.

Further descriptions and options can be found in the added sphinx documentation.

Special options

The CLI also offers two special options:

• Using a JSON config file for the <client args>, so the client parameters don't have to be specified over and over again. This will also help security as credentials like the API key do not have to appear on the command line.
• Reading JSON-encoded data for a method argument from stdin, which is intended for the data that is sent to API endpoints that create/update records. This will also help with security as the data will also not appear on the command line and it helps to not exceed maximum command lengths.

More info on how to use these options can also be found in the added sphinx documentation.

Maintenance

The CLI is designed to be low-maintenance and to not require any changes to the existing code of the API clients. It is built on Google's Fire library, which allows to transform objects of all kinds into CLIs. We introduced some wrapper classes for the Hubspot3 main client and the "sub-clients" that make sure that only the right things are exposed via the Fire-generated CLI:

• The public client properties on the Hubspot3 main client are automatically detected and transformed into CLI options.
• On these clients, all public methods are automatically detected and offered as CLI operations.

New clients should therefore automatically work as long as they are added as a property to the Hubspot3 main class, so there will be no need to touch the CLI code when adding new clients/methods. The only time the CLI code will require some love is when properties on the Hubspot3 main client or methods on "sub-clients" should be explicitly excluded from the CLI (the code for this is already in place).

Requirements

The CLI requires one new python package: Google's Fire. This requirement was added to the setup.py as an extra_requirement, so it won't be installed for people who don't want to use the CLI. The package could therefore still be installed as hubspot3 if CLI usage is not intended or as hubspot3[cli] if someone wants to use the CLI as well. You could also move the fire requirement to the regular install_requires if you don't think this separation of requirements is useful.

I hope this was enough of an explanation. Thank you for maintaining this library and we hope the addition of this CLI is something you consider useful, so it can become a part of hubspot3.

[jpetrucciani]

Woah - thanks for the incredibly detailed PR! 😄

I'll review this today sometime, and hopefully I can get it merged in soon!

[W1ldPo1nter]

No worries, it would totally be understandable if this would take some time to review.

Also, if there are any questions after you were able to take a first look at it, I'll be happy to answer them or make adjustments if required.

[jpetrucciani]

I've got this merged in now! I'll create a new release on pip soon.

The only changes I made were applying black styles, which I always use (and I recommend it if you haven't checked it out! It's amazing to not have to worry about styling anymore).

Don't feel obligated to always use black unless you want to - it's quick for me to run on the code after merging if that's the case!

[jpetrucciani]

This is now available as release 3.2.16 on pip!

Thanks again (and to @hkage and @kantimati) for this awesome contribution! 😄