HUD.ai API python bindings
Project description
# HUD.ai Python Client
[![Build Status][ci-badge]][ci-url]
[![PyPI][pypi-badge]][pypi-url]
[![PyPI][python-versions-badge]][pypi-url]
[![License][license-badge]]()
The HUD.ai Python Client provides an easy to use wrapper to interact with the
HUD.ai API in python applications.
You must first acquire a HUD.ai secret key before you can use this module.
## Installation
`pip install hudai`
## Usage
```python
from hudai.client import HudAi
client = HudAi(api_key='your-api-token-here')
# Alternatively, if you're working with a non-production environment
# client = HudAi(api_key='your-api-token-here', base_url='https://stage.api.hud.ai')
client.company.list()
client.news_api_article.get('17787d76-4198-4775-a49a-b3581c37a482')
```
***DOCUMENTATION NOTES***
- All `Date` types listed below are ISO-8601 formatted strings. e.g.
`2017-07-26T18:18:58Z`
- Bolded `Type`s indicate that the field is required
### Article
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| `authors` | Array\<String\> | List of author names |
| `image_url` | String | Image published in the article's metadata |
| `importance_score` | Number | `hudai-importance-scorer` output |
| `link_hash` | String | MD5 hash of the `link_url` **Cannot be edited** |
| **`link_url`** | **String** | Where the article was originally published |
| `published_at` | Date | Original publishing date |
| **`raw_data_url`** | **String** | Location of raw feed content (e.g. JSON/HTML) |
| **`source_url`** | **String** | URL of the publication source |
| `text` | String | Plaintext format of the article body |
| **`title`** | **String** | Title article was published as |
| **`type`** | **String** | `rss` \| `newsApi` \| `facebook` \| `twitter` |
#### `client.article.list(**params)`
Optional Params:
- `importance_score_min`
- `key_term`
- `link_hash`
- `published_after`
- `published_before`
- `type`
Example:
```
client.article.list(type='rss', published_after='2017-07-26T18:18:58Z')
```
#### `client.article.create(**params)`
Takes all of the model attributes as keyword params (except `link_hash`)
#### `client.article.get(id)`
#### `client.article.update(id, **params)`
Takes all of the model attributes as keyword params (except `link_hash`)
#### `client.article.delete(id)`
#### `client.article.key_terms(id)`
Returns a list of key terms (`String`) associated with the article
### ArticleHighlights
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`article_id`** | **String** | Article being highlighted |
| **`body`** | **String** | Phrases that should be highlighted |
| **`user_id`** | **String** | User the highlights apply to |
#### `client.article_highlights.list(**params)`
Optional Params:
- `article_id`
- `link_hash` MD5 hash of the article URL
- `user_id`
#### `client.article_highlights.create(**params)`
Takes all of the model attributes as keyword params
#### `client.article_highlights.get(id)`
#### `client.article_highlights.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.article_highlights.delete(id)`
### ArticleKeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`article_id`** | **String** | Article identifier |
| **`key_term`** | **String** | Key term in article |
#### `client.article_key_term.list(**params)`
Optional Params:
- `key_term`
- `article_id`
#### `client.article_key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.article_key_term.get(id)`
#### `client.article_key_term.delete(id)`
### Company
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`name`** | **String** | Primary company name (others can be associated as key terms) |
#### `client.company.list()`
#### `client.company.create(**params)`
Takes all of the model attributes as keyword params
#### `client.company.get(id)`
#### `client.company.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.company.delete(id)`
#### `client.company.domains(id)`
Lists all `Domain`s (hostnames) associated with the company
#### `client.company.key_terms(id)`
Lists all `KeyTerm`s associated with the company
### CompanyKeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`company_id`** | **String** | Associated company |
| **`term`** | **String** | Term (can be word or phrase) to find in articles |
#### `client.company_key_term.list(**params)`
Optional Params:
- `company_id`
#### `client.company_key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.company_key_term.get(id)`
#### `client.company_key_term.delete(id)`
### Domain
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`company_id`** | **String** | Associated company |
| **`hostname`** | **String** | FQDN e.g. `api.hud.ai` |
#### `client.domain.list(**params)`
Optional Params:
- `company_id`
- `hostname`
#### `client.domain.create(**params)`
Takes all of the model attributes as keyword params
#### `client.domain.get(id)`
#### `client.domain.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.domain.delete(id)`
### KeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| **`term`** | **String** | Term (can be word or phrase) to find in articles |
#### `client.key_term.list(**params)`
Optional Params:
- `page`
#### `client.key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.key_term.get(term)`
#### `client.key_term.delete(term)`
### SystemEvent
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`name`** | **String** | Event identifier e.g. `article.processed` |
| **`payload`** | **Dictionary** | Event payload e.g. `{'location': 's3://my-bucket/file-path', type:'rss'}` |
#### `client.system_event.list(**params)`
Optional Params:
- `page`
#### `client.system_event.create(**params)`
Takes all of the model attributes as keyword params
#### `client.system_event.get(id)`
### SystemTask
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`task_id`** | **String** | Task identifier (typically from `celery`) |
| `attempts` | Number | How many times has this job been started |
| `started_at` | Date | Last time that the job was attempted |
| `completed_at` | Date | When the job finished (irregardless of success) |
#### `client.system_task.list(**params)`
Optional Params:
- `task_id`
- `page`
- `started_after`
- `started_before`
- `completed` (Boolean)
#### `client.system_task.create(**params)`
Takes all of the model attributes as keyword params
#### `client.system_task.get(id)`
#### `client.system_task.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.system_task.delete(id)`
### TextCorpus
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`user_id`** | **String** | User the corpus is used to identify articles for |
| **`type`** | **String** | Text origin e.g. `email` or `custom` |
| **`body`** | **String** | Text blob to use for relevance matching |
#### `client.text_corpus.list(**params)`
Optional Params:
- `user_id`
- `type`
#### `client.text_corpus.create(**params)`
Takes all of the model attributes as keyword params
#### `client.text_corpus.get(id)`
#### `client.text_corpus.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.text_corpus.delete(id)`
### User
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`name`** | **String** | User's full name (used in emails and other communications) |
| **`email`** | **String** | Primary email address for updates/notifications |
#### `client.user.list(**params)`
Optional Params:
- `email`
#### `client.user.create(**params)`
Takes all of the model attributes as keyword params
#### `client.user.get(id)`
#### `client.user.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.user.delete(id)`
#### `client.user.followed_terms_list(id)`
Returns a list of `UserKeyTerm`s
#### `client.user.followed_terms_add(id, term)`
#### `client.user.followed_terms_remove(id, term)`
#### `client.user.followed_companies_list(id)`
Returns a list of `UserCompany`s
#### `client.user.followed_companies_add(id, company_id)`
#### `client.user.followed_companies_remove(user_id, company_id)`
### UserCompany
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`company_id`** | **String** | Associated company |
| **`user_id`** | **String** | Associated user |
#### `client.user_company.list(**params)`
Optional Params:
- `company_id`
- `user_id`
#### `client.user_company.create(**params)`
Takes all of the model attributes as keyword params
#### `client.user_company.get(id)`
#### `client.user_company.delete(id)`
### UserKeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`user_id`** | **String** | Associated user |
| **`term`** | **String** | Term (can be word or phrase) to find in articles |
#### `client.user_key_term.list(**params)`
Optional Params:
- `term`
- `user_id`
#### `client.user_key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.user_key_term.get(id)`
#### `client.user_key_term.delete(id)`
## Deployment
Deploys occur automatically via Travis-CI on tagged commits that build
successfully. Should you need to manually build the project, follow these steps:
```bash
# Install twine to prevent your password from being set in plaintext
pip install twine
# Build the package
python setup.py sdist
# Upload via twine
twine upload dist/hudai-NEW_VERSION_HERE.tar.gz
```
[ci-badge]: https://travis-ci.org/FoundryAI/hud-ai-python.svg?branch=master
[ci-url]: https://travis-ci.org/FoundryAI/hud-ai-python
[pypi-badge]: https://img.shields.io/pypi/v/hudai.svg
[pypi-url]: https://pypi.python.org/pypi/hudai
[python-versions-badge]: https://img.shields.io/pypi/pyversions/hudai.svg
[license-badge]: https://img.shields.io/pypi/l/hudai.svg
[![Build Status][ci-badge]][ci-url]
[![PyPI][pypi-badge]][pypi-url]
[![PyPI][python-versions-badge]][pypi-url]
[![License][license-badge]]()
The HUD.ai Python Client provides an easy to use wrapper to interact with the
HUD.ai API in python applications.
You must first acquire a HUD.ai secret key before you can use this module.
## Installation
`pip install hudai`
## Usage
```python
from hudai.client import HudAi
client = HudAi(api_key='your-api-token-here')
# Alternatively, if you're working with a non-production environment
# client = HudAi(api_key='your-api-token-here', base_url='https://stage.api.hud.ai')
client.company.list()
client.news_api_article.get('17787d76-4198-4775-a49a-b3581c37a482')
```
***DOCUMENTATION NOTES***
- All `Date` types listed below are ISO-8601 formatted strings. e.g.
`2017-07-26T18:18:58Z`
- Bolded `Type`s indicate that the field is required
### Article
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| `authors` | Array\<String\> | List of author names |
| `image_url` | String | Image published in the article's metadata |
| `importance_score` | Number | `hudai-importance-scorer` output |
| `link_hash` | String | MD5 hash of the `link_url` **Cannot be edited** |
| **`link_url`** | **String** | Where the article was originally published |
| `published_at` | Date | Original publishing date |
| **`raw_data_url`** | **String** | Location of raw feed content (e.g. JSON/HTML) |
| **`source_url`** | **String** | URL of the publication source |
| `text` | String | Plaintext format of the article body |
| **`title`** | **String** | Title article was published as |
| **`type`** | **String** | `rss` \| `newsApi` \| `facebook` \| `twitter` |
#### `client.article.list(**params)`
Optional Params:
- `importance_score_min`
- `key_term`
- `link_hash`
- `published_after`
- `published_before`
- `type`
Example:
```
client.article.list(type='rss', published_after='2017-07-26T18:18:58Z')
```
#### `client.article.create(**params)`
Takes all of the model attributes as keyword params (except `link_hash`)
#### `client.article.get(id)`
#### `client.article.update(id, **params)`
Takes all of the model attributes as keyword params (except `link_hash`)
#### `client.article.delete(id)`
#### `client.article.key_terms(id)`
Returns a list of key terms (`String`) associated with the article
### ArticleHighlights
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`article_id`** | **String** | Article being highlighted |
| **`body`** | **String** | Phrases that should be highlighted |
| **`user_id`** | **String** | User the highlights apply to |
#### `client.article_highlights.list(**params)`
Optional Params:
- `article_id`
- `link_hash` MD5 hash of the article URL
- `user_id`
#### `client.article_highlights.create(**params)`
Takes all of the model attributes as keyword params
#### `client.article_highlights.get(id)`
#### `client.article_highlights.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.article_highlights.delete(id)`
### ArticleKeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`article_id`** | **String** | Article identifier |
| **`key_term`** | **String** | Key term in article |
#### `client.article_key_term.list(**params)`
Optional Params:
- `key_term`
- `article_id`
#### `client.article_key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.article_key_term.get(id)`
#### `client.article_key_term.delete(id)`
### Company
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`name`** | **String** | Primary company name (others can be associated as key terms) |
#### `client.company.list()`
#### `client.company.create(**params)`
Takes all of the model attributes as keyword params
#### `client.company.get(id)`
#### `client.company.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.company.delete(id)`
#### `client.company.domains(id)`
Lists all `Domain`s (hostnames) associated with the company
#### `client.company.key_terms(id)`
Lists all `KeyTerm`s associated with the company
### CompanyKeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`company_id`** | **String** | Associated company |
| **`term`** | **String** | Term (can be word or phrase) to find in articles |
#### `client.company_key_term.list(**params)`
Optional Params:
- `company_id`
#### `client.company_key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.company_key_term.get(id)`
#### `client.company_key_term.delete(id)`
### Domain
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`company_id`** | **String** | Associated company |
| **`hostname`** | **String** | FQDN e.g. `api.hud.ai` |
#### `client.domain.list(**params)`
Optional Params:
- `company_id`
- `hostname`
#### `client.domain.create(**params)`
Takes all of the model attributes as keyword params
#### `client.domain.get(id)`
#### `client.domain.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.domain.delete(id)`
### KeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| **`term`** | **String** | Term (can be word or phrase) to find in articles |
#### `client.key_term.list(**params)`
Optional Params:
- `page`
#### `client.key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.key_term.get(term)`
#### `client.key_term.delete(term)`
### SystemEvent
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`name`** | **String** | Event identifier e.g. `article.processed` |
| **`payload`** | **Dictionary** | Event payload e.g. `{'location': 's3://my-bucket/file-path', type:'rss'}` |
#### `client.system_event.list(**params)`
Optional Params:
- `page`
#### `client.system_event.create(**params)`
Takes all of the model attributes as keyword params
#### `client.system_event.get(id)`
### SystemTask
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`task_id`** | **String** | Task identifier (typically from `celery`) |
| `attempts` | Number | How many times has this job been started |
| `started_at` | Date | Last time that the job was attempted |
| `completed_at` | Date | When the job finished (irregardless of success) |
#### `client.system_task.list(**params)`
Optional Params:
- `task_id`
- `page`
- `started_after`
- `started_before`
- `completed` (Boolean)
#### `client.system_task.create(**params)`
Takes all of the model attributes as keyword params
#### `client.system_task.get(id)`
#### `client.system_task.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.system_task.delete(id)`
### TextCorpus
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`user_id`** | **String** | User the corpus is used to identify articles for |
| **`type`** | **String** | Text origin e.g. `email` or `custom` |
| **`body`** | **String** | Text blob to use for relevance matching |
#### `client.text_corpus.list(**params)`
Optional Params:
- `user_id`
- `type`
#### `client.text_corpus.create(**params)`
Takes all of the model attributes as keyword params
#### `client.text_corpus.get(id)`
#### `client.text_corpus.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.text_corpus.delete(id)`
### User
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`name`** | **String** | User's full name (used in emails and other communications) |
| **`email`** | **String** | Primary email address for updates/notifications |
#### `client.user.list(**params)`
Optional Params:
- `email`
#### `client.user.create(**params)`
Takes all of the model attributes as keyword params
#### `client.user.get(id)`
#### `client.user.update(id, **params)`
Takes all of the model attributes as keyword params
#### `client.user.delete(id)`
#### `client.user.followed_terms_list(id)`
Returns a list of `UserKeyTerm`s
#### `client.user.followed_terms_add(id, term)`
#### `client.user.followed_terms_remove(id, term)`
#### `client.user.followed_companies_list(id)`
Returns a list of `UserCompany`s
#### `client.user.followed_companies_add(id, company_id)`
#### `client.user.followed_companies_remove(user_id, company_id)`
### UserCompany
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`company_id`** | **String** | Associated company |
| **`user_id`** | **String** | Associated user |
#### `client.user_company.list(**params)`
Optional Params:
- `company_id`
- `user_id`
#### `client.user_company.create(**params)`
Takes all of the model attributes as keyword params
#### `client.user_company.get(id)`
#### `client.user_company.delete(id)`
### UserKeyTerm
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | String | Resource ID **Cannot be edited** |
| **`user_id`** | **String** | Associated user |
| **`term`** | **String** | Term (can be word or phrase) to find in articles |
#### `client.user_key_term.list(**params)`
Optional Params:
- `term`
- `user_id`
#### `client.user_key_term.create(**params)`
Takes all of the model attributes as keyword params
#### `client.user_key_term.get(id)`
#### `client.user_key_term.delete(id)`
## Deployment
Deploys occur automatically via Travis-CI on tagged commits that build
successfully. Should you need to manually build the project, follow these steps:
```bash
# Install twine to prevent your password from being set in plaintext
pip install twine
# Build the package
python setup.py sdist
# Upload via twine
twine upload dist/hudai-NEW_VERSION_HERE.tar.gz
```
[ci-badge]: https://travis-ci.org/FoundryAI/hud-ai-python.svg?branch=master
[ci-url]: https://travis-ci.org/FoundryAI/hud-ai-python
[pypi-badge]: https://img.shields.io/pypi/v/hudai.svg
[pypi-url]: https://pypi.python.org/pypi/hudai
[python-versions-badge]: https://img.shields.io/pypi/pyversions/hudai.svg
[license-badge]: https://img.shields.io/pypi/l/hudai.svg
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
hudai-2.0.0.tar.gz
(8.1 kB
view hashes)