Skip to main content

PyPI version Code style: black Documentation Status Python 3.8+ supported

A python wrapper around HubSpot's APIs, for python 3.8+.

Built initially around hapipy, but heavily modified.

Check out the documentation here! (thanks readthedocs)

Quick start

Note: I'd recommend that you consider using the official HubSpot Python API. I no longer work at a company that uses HubSpot, and this library is a few versions behind on many of their APIs. I will be open to small PRs and usability fixes, but there will likely not be any further significant work on this library

Installation

# install hubspot3
pip install hubspot3

Basic Usage

from hubspot3 import Hubspot3

API_KEY = "your-api-key"

client = Hubspot3(api_key=API_KEY)

# all of the clients are accessible as attributes of the main Hubspot3 Client
contact = client.contacts.get_contact_by_email('testingapis@hubspot.com')
contact_id = contact['vid']

all_companies = client.companies.get_all()

# new usage limit functionality - keep track of your API calls
client.usage_limits
# <Hubspot3UsageLimits: 28937/1000000 (0.028937%) [reset in 22157s, cached for 299s]>

client.usage_limits.calls_remaining
# 971063

Individual Clients

from hubspot3.companies import CompaniesClient

API_KEY = "your-api-key"

client = CompaniesClient(api_key=API_KEY)

for company in client.get_all():
    print(company)

Passing Params

import json
from hubspot3.deals import DealsClient

deal_id = "12345"
API_KEY = "your_api_key"

deals_client = DealsClient(api_key=API_KEY)

params = {
    "includePropertyVersions": "true"
}  # Note values are camelCase as they appear in the Hubspot Documentation!

deal_data = deals_client.get(deal_id, params=params)
print(json.dumps(deal_data))

Command-line interface

There is also a command-line tool available. Install the extra requirement for that tool via:

pip install hubspot3[cli]

and you can use it as a command:

hubspot3 --help

See the Sphinx documentation for more details and explanations.

Rate Limiting

Be aware that this uses the HubSpot API directly, so you are subject to all of the guidelines that HubSpot has in place.

at the time of writing, HubSpot has the following limits in place for API requests:

Free & Starter:

  • 10 requests per second
  • 250,000 requests per day.

Professional & Enterprise:

  • 10 requests per second
  • 500,000 requests per day.

This daily limit resets at midnight based on the time zone setting of the HubSpot account. There is also an additional addon you can purchase for more requests.

Retrying API Calls

By default, hubspot3 will attempt to retry all API calls up to 2 times upon failure.

If you'd like to override this behavior, you can add a number_retries keyword argument to any Client constructor, or to individual API calls.

Extending the BaseClient - thanks @Guysoft!

Some of the APIs are not yet complete! If you'd like to use an API that isn't yet in this repo, you can extend the BaseClient class!

import json
from hubspot3.base import BaseClient


PIPELINES_API_VERSION = "1"


class PipelineClient(BaseClient):
    """
    Lets you extend to non-existing clients, this example extends pipelines
    """

    def __init__(self, *args, **kwargs):
        super(PipelineClient, self).__init__(*args, **kwargs)

    def get_pipelines(self, **options):
        params = {}

        return self._call("pipelines", method="GET", params=params)

    def _get_path(self, subpath):
        return f"deals/v{self.options.get('version') or PIPELINES_API_VERSION}/{subpath}"


if __name__ == "__main__":
    API_KEY = "your_api_key"
    a = PipelineClient(api_key=API_KEY)
    print(json.dumps(a.get_pipelines()))

Advanced oauth2 token storage - thanks @sangaline!

This is an example of how you can use the oauth2_token_getter and oauth2_token_setter kwargs on the client to use custom storage (in this case redis) so that multiple clients can share the same access/refresh tokens generated by the oauth2 requests.

import aioredis
from hubspot3 import Hubspot3


redis_client = await aioredis.create_redis_pool(url, db=db, encoding='utf-8', timeout=10)

def oauth2_token_getter(token_type: str, client_id: str) -> str:
    loop = asyncio.get_event_loop()
    key = f'hubspot-oauth2-tokens:{token_type}:{client_id}'
    return loop.run_until_complete(redis_client.get(key))

def oauth2_token_setter(token_type: str, client_id: str, token: str) -> None:
    loop = asyncio.get_event_loop()
    key = f'hubspot-oauth2-tokens:{token_type}:{client_id}'
    # Token expiration is six hours, so match that when we store the tokens.
    # See: https://developers.hubspot.com/docs/methods/oauth2/refresh-access-token
    expire_in_seconds = 6 * 60 * 60
    loop.run_until_complete(redis_client.set(key, token, expire=expire_in_seconds))

# This client will share oauth2 credentials with other clients configured in the same way.
hubspot3_client = Hubspot3(
    access_token=access_token,
    client_id=client_id,
    client_secret=client_secret,
    refresh_token=refresh_token,
    oauth2_token_getter=oauth2_token_getter,
    oauth2_token_setter=oauth2_token_setter,
)

Testing

I'm currently working on rewriting many of the tests with pytest to work against the public API and ensure that we get the correct type of mock data back. These tests are currently in a very early state - I'll be working soon to get them all built out.

# Install required test packages
pip install pytest pytest-cov
# or
pip install -r requirements-dev.txt

# run tests
make
# or
make test_all

Metadata

Release files for hubspot3 3.2.56

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hubspot3 3.2.56
File Size Uploaded Provenance Actions
hubspot3-3.2.56.tar.gz 42.7 kB Without provenance Details for hubspot3-3.2.56.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hubspot3 3.2.56
File Interpreter ABI Platform Actions
hubspot3-3.2.56-py3-none-any.whl Python 3 none any Details for hubspot3-3.2.56-py3-none-any.whl

Total release size: 100.4 kB

Release files / hubspot3-3.2.56.tar.gz

Download URL hubspot3-3.2.56.tar.gz
Size 42.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9e7ac2a444c9ce5966afb8f24d29c0ae29787186bfa3f2032c4701b14d5d5f6b
BLAKE2b-256 checksum
How to use checksums
5ae0c241cd349f0ff831afede67f1bf422d627da546118aa9924f027ab1d12bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.11

Release files / hubspot3-3.2.56-py3-none-any.whl

Download URL hubspot3-3.2.56-py3-none-any.whl
Size 57.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8d5fc0c47d50ca1e22b1cbb7d716a3d531fe22a8807d1d7af88397df4c593fc
BLAKE2b-256 checksum
How to use checksums
d47ea4e89f4ea626d58a9e3cade484bc83ce7b15f04ceddb1e58b7b06aa92ec7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.11

Security for hubspot3 3.2.56

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.2.56 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page