[](https://badge.fury.io/py/hubspot3)
[](https://github.com/ambv/black)
[](https://hubspot3.readthedocs.io/en/latest/?badge=latest)
[](https://www.python.org/downloads/release/python-380/)
A python wrapper around HubSpot's APIs, _for python 3.8+_.
Built initially around hapipy, but heavily modified.
Check out the [documentation
here](https://hubspot3.readthedocs.io/en/latest/)\! (thanks readthedocs)
# Quick start
## **Note: I'd recommend that you consider using the [official HubSpot Python API](https://github.com/HubSpot/hubspot-api-python). 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
```bash
# install hubspot3
pip install hubspot3
```
## Basic Usage
```python
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
```python
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
```python
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:
```bash
pip install hubspot3[cli]
```
and you can use it as a command:
```bash
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](https://developers.hubspot.com/apps/api_guidelines).
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](https://github.com/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\!
```python
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](https://github.com/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.
```python
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](https://docs.pytest.org/en/latest/) 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.
```bash
# Install required test packages
pip install pytest pytest-cov
# or
pip install -r requirements-dev.txt
# run tests
make
# or
make test_all
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jpetrucciani/hubspot3.git",
"name": "hubspot3",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "HubSpot Dev Team, Jacobi Petrucciani",
"author_email": "j@cobi.dev",
"download_url": "https://files.pythonhosted.org/packages/3c/25/2be77bef61dfde64c5caa19f79fe595524fca131d90fae2091a3f5953642/hubspot3-3.2.54.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/hubspot3)\n[](https://github.com/ambv/black)\n[](https://hubspot3.readthedocs.io/en/latest/?badge=latest)\n[](https://www.python.org/downloads/release/python-380/)\n\nA python wrapper around HubSpot's APIs, _for python 3.8+_.\n\nBuilt initially around hapipy, but heavily modified.\n\nCheck out the [documentation\nhere](https://hubspot3.readthedocs.io/en/latest/)\\! (thanks readthedocs)\n\n# Quick start\n\n## **Note: I'd recommend that you consider using the [official HubSpot Python API](https://github.com/HubSpot/hubspot-api-python). 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**\n\n## Installation\n\n```bash\n# install hubspot3\npip install hubspot3\n```\n\n## Basic Usage\n\n```python\nfrom hubspot3 import Hubspot3\n\nAPI_KEY = \"your-api-key\"\n\nclient = Hubspot3(api_key=API_KEY)\n\n# all of the clients are accessible as attributes of the main Hubspot3 Client\ncontact = client.contacts.get_contact_by_email('testingapis@hubspot.com')\ncontact_id = contact['vid']\n\nall_companies = client.companies.get_all()\n\n# new usage limit functionality - keep track of your API calls\nclient.usage_limits\n# <Hubspot3UsageLimits: 28937/1000000 (0.028937%) [reset in 22157s, cached for 299s]>\n\nclient.usage_limits.calls_remaining\n# 971063\n```\n\n## Individual Clients\n\n```python\nfrom hubspot3.companies import CompaniesClient\n\nAPI_KEY = \"your-api-key\"\n\nclient = CompaniesClient(api_key=API_KEY)\n\nfor company in client.get_all():\n print(company)\n```\n\n## Passing Params\n\n```python\nimport json\nfrom hubspot3.deals import DealsClient\n\ndeal_id = \"12345\"\nAPI_KEY = \"your_api_key\"\n\ndeals_client = DealsClient(api_key=API_KEY)\n\nparams = {\n \"includePropertyVersions\": \"true\"\n} # Note values are camelCase as they appear in the Hubspot Documentation!\n\ndeal_data = deals_client.get(deal_id, params=params)\nprint(json.dumps(deal_data))\n```\n\n## Command-line interface\n\nThere is also a command-line tool available. Install the extra\nrequirement for that tool via:\n\n```bash\npip install hubspot3[cli]\n```\n\nand you can use it as a command:\n\n```bash\nhubspot3 --help\n```\n\nSee the Sphinx documentation for more details and explanations.\n\n# Rate Limiting\n\nBe aware that this uses the HubSpot API directly, so you are subject to\nall of the [guidelines that HubSpot has in\nplace](https://developers.hubspot.com/apps/api_guidelines).\n\nat the time of writing, HubSpot has the following limits in place for\nAPI requests:\n\nFree & Starter:\n\n- 10 requests per second\n- 250,000 requests per day.\n\nProfessional & Enterprise:\n\n- 10 requests per second\n- 500,000 requests per day.\n\nThis daily limit resets at midnight based on the time zone setting of\nthe HubSpot account. There is also an additional addon you can purchase\nfor more requests.\n\n# Retrying API Calls\n\nBy default, hubspot3 will attempt to retry all API calls up to 2 times\nupon failure.\n\nIf you'd like to override this behavior, you can add a `number_retries`\nkeyword argument to any Client constructor, or to individual API calls.\n\n# Extending the BaseClient - thanks [@Guysoft](https://github.com/guysoft)\\!\n\nSome of the APIs are not yet complete\\! If you'd like to use an API that\nisn't yet in this repo, you can extend the BaseClient class\\!\n\n```python\nimport json\nfrom hubspot3.base import BaseClient\n\n\nPIPELINES_API_VERSION = \"1\"\n\n\nclass PipelineClient(BaseClient):\n \"\"\"\n Lets you extend to non-existing clients, this example extends pipelines\n \"\"\"\n\n def __init__(self, *args, **kwargs):\n super(PipelineClient, self).__init__(*args, **kwargs)\n\n def get_pipelines(self, **options):\n params = {}\n\n return self._call(\"pipelines\", method=\"GET\", params=params)\n\n def _get_path(self, subpath):\n return f\"deals/v{self.options.get('version') or PIPELINES_API_VERSION}/{subpath}\"\n\n\nif __name__ == \"__main__\":\n API_KEY = \"your_api_key\"\n a = PipelineClient(api_key=API_KEY)\n print(json.dumps(a.get_pipelines()))\n```\n\n# Advanced oauth2 token storage - thanks [@sangaline](https://github.com/sangaline)\\!\n\nThis 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.\n\n```python\nimport aioredis\nfrom hubspot3 import Hubspot3\n\n\nredis_client = await aioredis.create_redis_pool(url, db=db, encoding='utf-8', timeout=10)\n\ndef oauth2_token_getter(token_type: str, client_id: str) -> str:\n loop = asyncio.get_event_loop()\n key = f'hubspot-oauth2-tokens:{token_type}:{client_id}'\n return loop.run_until_complete(redis_client.get(key))\n\ndef oauth2_token_setter(token_type: str, client_id: str, token: str) -> None:\n loop = asyncio.get_event_loop()\n key = f'hubspot-oauth2-tokens:{token_type}:{client_id}'\n # Token expiration is six hours, so match that when we store the tokens.\n # See: https://developers.hubspot.com/docs/methods/oauth2/refresh-access-token\n expire_in_seconds = 6 * 60 * 60\n loop.run_until_complete(redis_client.set(key, token, expire=expire_in_seconds))\n\n# This client will share oauth2 credentials with other clients configured in the same way.\nhubspot3_client = Hubspot3(\n access_token=access_token,\n client_id=client_id,\n client_secret=client_secret,\n refresh_token=refresh_token,\n oauth2_token_getter=oauth2_token_getter,\n oauth2_token_setter=oauth2_token_setter,\n)\n```\n\n# Testing\n\nI'm currently working on rewriting many of the tests with\n[pytest](https://docs.pytest.org/en/latest/) to work against the public\nAPI and ensure that we get the correct type of mock data back. These\ntests are currently in a **very** early state - I'll be working soon to\nget them all built out.\n\n```bash\n# Install required test packages\npip install pytest pytest-cov\n# or\npip install -r requirements-dev.txt\n\n# run tests\nmake\n# or\nmake test_all\n```\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "A python wrapper around HubSpot's APIs, for python 3. Built initially around hapipy, but heavily modified.",
"version": "3.2.54",
"project_urls": {
"Download": "https://github.com/jpetrucciani/hubspot3.git",
"Homepage": "https://github.com/jpetrucciani/hubspot3.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "85514d6c386a2b786252c7a559c2fe002541c1b1ffdbe4aab20362574eae3fe6",
"md5": "ccc9c6980dd582a821141de7153174da",
"sha256": "505fe0b3df5aebf9ac13812ce8de926d98543f5fe0e02aff97d03bf7feb79d88"
},
"downloads": -1,
"filename": "hubspot3-3.2.54-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ccc9c6980dd582a821141de7153174da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 57464,
"upload_time": "2023-12-22T17:24:59",
"upload_time_iso_8601": "2023-12-22T17:24:59.230013Z",
"url": "https://files.pythonhosted.org/packages/85/51/4d6c386a2b786252c7a559c2fe002541c1b1ffdbe4aab20362574eae3fe6/hubspot3-3.2.54-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3c252be77bef61dfde64c5caa19f79fe595524fca131d90fae2091a3f5953642",
"md5": "86f908af6c7f194025ba2ed1882da845",
"sha256": "9dd83a6fb87e2c9bee3fb2d3b655f54c19c44a05447fe910acab0b77bfb5346f"
},
"downloads": -1,
"filename": "hubspot3-3.2.54.tar.gz",
"has_sig": false,
"md5_digest": "86f908af6c7f194025ba2ed1882da845",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 42587,
"upload_time": "2023-12-22T17:25:01",
"upload_time_iso_8601": "2023-12-22T17:25:01.283285Z",
"url": "https://files.pythonhosted.org/packages/3c/25/2be77bef61dfde64c5caa19f79fe595524fca131d90fae2091a3f5953642/hubspot3-3.2.54.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-22 17:25:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jpetrucciani",
"github_project": "hubspot3",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "hubspot3"
}
JSON
