helpscout package¶

Subpackages¶

Submodules¶

helpscout.auth_proxy module¶

class helpscout.auth_proxy.AuthProxy(session, proxy_class)[source]¶

Bases: object

This object acts as a transparent authentication proxy for the API.

This is required because the API objects are naive of the authentication that is setup in HelpScout, and all of the API interface methods are classmethods because they are instantiating.

METHOD_NO_PROXY = ['auth_proxy']¶

auth_proxy(method)[source]¶

Authentication proxy for API requests.

This is required because the API objects are naive of HelpScout, so they would otherwise be unauthenticated.

Parameters:	method (callable) – A method call that should be authenticated. It should accept a `requests.Session` as its first parameter, which should be used for the actual API call.
Returns:	The results of the authenticated callable.
Return type:	mixed

helpscout.base_api module¶

class helpscout.base_api.BaseApi[source]¶

Bases: object

This is the API interface object to be implemented by API adapters.

It acts as a collection for the API object that it represents, passing through iteration to the API’s request paginator.

BASE_URI¶: str – HelpScout API URI base.

paginator¶: RequestPaginator – Object to use for producing an iterator representing multiple requests (API response pages). Created on init.

__object__¶: helpscout.models.BaseModel – Model object that API represents.

BASE_URI = 'https://api.helpscout.net/v1'

classmethod create(session, record, endpoint_override=None, out_type=None, **add_params)[source]¶

Create an object on HelpScout.

Parameters:	session (requests.sessions.Session) – Authenticated session. record (helpscout.BaseModel) – The record to be created. endpoint_override (str, optional) – Override the default endpoint using this. out_type (helpscout.BaseModel, optional) – The type of record to output. This should be provided by child classes, by calling super. *add_params (mixed*) – Add these to the request parameters.
Returns:	Newly created record. Will be of the
Return type:	helpscout.models.BaseModel

classmethod delete(session, record, endpoint_override=None, out_type=None)[source]¶

Delete a record.

Parameters:	session (requests.sessions.Session) – Authenticated session. record (helpscout.BaseModel) – The record to be deleted. endpoint_override (str, optional) – Override the default endpoint using this. out_type (helpscout.BaseModel, optional) – The type of record to output. This should be provided by child classes, by calling super.
Returns:	Nothing.
Return type:	NoneType

classmethod get(session, record_id, endpoint_override=None)[source]¶

Return a specific record.

Parameters:

session (requests.sessions.Session) – Authenticated session.
record_id (int) – The ID of the record to get.
endpoint_override (str, optional) – Override the default endpoint using this.

Returns:

A record singleton, if existing. Otherwise: None.

Return type:

helpscout.BaseModel

static get_search_domain(queries)[source]¶

Helper method to create search domains if needed.

Parameters:	queries (Domain or iter) – The queries for the domain. If a `Domain` object is provided, it will simply be returned. Otherwise, a `Domain` object will be generated from the complex queries. In this case, the queries should conform to the interface in `helpscout.domain.Domain.from_tuple()`.
Returns:	Either the provided domain, or one created from `queries`.
Return type:	Domain

classmethod list(session, endpoint_override=None, data=None)[source]¶

Return records in a mailbox.

Parameters:

session (requests.sessions.Session) – Authenticated session.
endpoint_override (str, optional) – Override the default endpoint using this.
data (dict, optional) – Data to provide as request parameters.

Returns:

Results: iterator.

Return type:

RequestPaginator(output_type=helpscout.BaseModel)

classmethod new_object(data)[source]¶

Return a new object of the correct type from the data.

Parameters:	data (dict) – Data dictionary that should be converted to an object. It can use either camelCase keys or snake_case.
Returns:	A model of the type declared in `cls.__object__`.
Return type:	BaseModel

paginator = None

classmethod search(session, queries, out_type)[source]¶

Search for a record given a domain.

Parameters:

session (requests.sessions.Session) – Authenticated session.
queries (helpscout.models.Domain or iter) – The queries for the domain. If a Domain object is provided, it will simply be returned. Otherwise, a Domain object will be generated from the complex queries. In this case, the queries should conform to the interface in helpscout.domain.Domain.from_tuple().
out_type (helpscout.BaseModel) – The type of record to output. This should be provided by child classes, by calling super.

Returns:

Results: iterator of the out_type that is defined.

Return type:

RequestPaginator(output_type=helpscout.BaseModel)

classmethod update(session, record)[source]¶

Update a record.

Parameters:	session (requests.sessions.Session) – Authenticated session. record (helpscout.BaseModel) – The record to be updated.
Returns:	Freshly updated record.
Return type:	helpscout.BaseModel

helpscout.base_model module¶

class helpscout.base_model.BaseModel(**kwargs)[source]¶

Bases: properties.base.base.HasProperties

This is the model that all other models inherit from.

It provides some convenience functions, and the standard id property.

Required Properties:

id (Integer): Unique identifier, an integer

classmethod from_api(**kwargs)[source]¶

Create a new instance from API arguments.

This will switch camelCase keys into snake_case for instantiation.

It will also identify any Instance or List properties, and instantiate the proper objects using the values. The end result being a fully Objectified and Pythonified API response.

Returns:	Instantiated model using the API values.
Return type:	BaseModel

get(key, default=None)[source]¶: Return the field indicated by the key, if present.

static get_non_empty_vals(mapping)[source]¶: Return the mapping without any None values.

id¶: Unique identifier

to_api()[source]¶

Return a dictionary to send to the API.

Returns:	Mapping representing this object that can be sent to the API.
Return type:	dict

helpscout.exceptions module¶

exception helpscout.exceptions.HelpScoutException(message)[source]¶

Bases: exceptions.Exception

Base exception for HelpScout library errors.

exception helpscout.exceptions.HelpScoutRemoteException(status_code, message)[source]¶

Bases: helpscout.exceptions.HelpScoutException

Indicates that an error occurred when communicating with the remote.

exception helpscout.exceptions.HelpScoutSecurityException(message)[source]¶

Bases: helpscout.exceptions.HelpScoutException

Indicates a security error; probably by an invalid web hook signature.

exception helpscout.exceptions.HelpScoutValidationException(message)[source]¶

Bases: helpscout.exceptions.HelpScoutException

Indicates an error while validating user-supplied data.

Module contents¶

class helpscout.AuthProxy(session, proxy_class)[source]¶

Bases: object

This object acts as a transparent authentication proxy for the API.

This is required because the API objects are naive of the authentication that is setup in HelpScout, and all of the API interface methods are classmethods because they are instantiating.

METHOD_NO_PROXY = ['auth_proxy']¶

auth_proxy(method)[source]¶

Authentication proxy for API requests.

This is required because the API objects are naive of HelpScout, so they would otherwise be unauthenticated.

Parameters:	method (callable) – A method call that should be authenticated. It should accept a `requests.Session` as its first parameter, which should be used for the actual API call.
Returns:	The results of the authenticated callable.
Return type:	mixed

class helpscout.BaseApi[source]¶

Bases: object

This is the API interface object to be implemented by API adapters.

It acts as a collection for the API object that it represents, passing through iteration to the API’s request paginator.

BASE_URI¶: str – HelpScout API URI base.

paginator¶: RequestPaginator – Object to use for producing an iterator representing multiple requests (API response pages). Created on init.

__object__¶: helpscout.models.BaseModel – Model object that API represents.

BASE_URI = 'https://api.helpscout.net/v1'

classmethod create(session, record, endpoint_override=None, out_type=None, **add_params)[source]¶

Create an object on HelpScout.

Parameters:	session (requests.sessions.Session) – Authenticated session. record (helpscout.BaseModel) – The record to be created. endpoint_override (str, optional) – Override the default endpoint using this. out_type (helpscout.BaseModel, optional) – The type of record to output. This should be provided by child classes, by calling super. *add_params (mixed*) – Add these to the request parameters.
Returns:	Newly created record. Will be of the
Return type:	helpscout.models.BaseModel

classmethod delete(session, record, endpoint_override=None, out_type=None)[source]¶

Delete a record.

Parameters:	session (requests.sessions.Session) – Authenticated session. record (helpscout.BaseModel) – The record to be deleted. endpoint_override (str, optional) – Override the default endpoint using this. out_type (helpscout.BaseModel, optional) – The type of record to output. This should be provided by child classes, by calling super.
Returns:	Nothing.
Return type:	NoneType

classmethod get(session, record_id, endpoint_override=None)[source]¶

Return a specific record.

Parameters:

session (requests.sessions.Session) – Authenticated session.
record_id (int) – The ID of the record to get.
endpoint_override (str, optional) – Override the default endpoint using this.

Returns:

A record singleton, if existing. Otherwise: None.

Return type:

helpscout.BaseModel

static get_search_domain(queries)[source]¶

Helper method to create search domains if needed.

Parameters:	queries (Domain or iter) – The queries for the domain. If a `Domain` object is provided, it will simply be returned. Otherwise, a `Domain` object will be generated from the complex queries. In this case, the queries should conform to the interface in `helpscout.domain.Domain.from_tuple()`.
Returns:	Either the provided domain, or one created from `queries`.
Return type:	Domain

classmethod list(session, endpoint_override=None, data=None)[source]¶

Return records in a mailbox.

Parameters:

session (requests.sessions.Session) – Authenticated session.
endpoint_override (str, optional) – Override the default endpoint using this.
data (dict, optional) – Data to provide as request parameters.

Returns:

Results: iterator.

Return type:

RequestPaginator(output_type=helpscout.BaseModel)

classmethod new_object(data)[source]¶

Return a new object of the correct type from the data.

Parameters:	data (dict) – Data dictionary that should be converted to an object. It can use either camelCase keys or snake_case.
Returns:	A model of the type declared in `cls.__object__`.
Return type:	BaseModel

paginator = None

classmethod search(session, queries, out_type)[source]¶

Search for a record given a domain.

Parameters:

session (requests.sessions.Session) – Authenticated session.
queries (helpscout.models.Domain or iter) – The queries for the domain. If a Domain object is provided, it will simply be returned. Otherwise, a Domain object will be generated from the complex queries. In this case, the queries should conform to the interface in helpscout.domain.Domain.from_tuple().
out_type (helpscout.BaseModel) – The type of record to output. This should be provided by child classes, by calling super.

Returns:

Results: iterator of the out_type that is defined.

Return type:

RequestPaginator(output_type=helpscout.BaseModel)

classmethod update(session, record)[source]¶

Update a record.

Parameters:	session (requests.sessions.Session) – Authenticated session. record (helpscout.BaseModel) – The record to be updated.
Returns:	Freshly updated record.
Return type:	helpscout.BaseModel

class helpscout.BaseModel(**kwargs)[source]¶

Bases: properties.base.base.HasProperties

This is the model that all other models inherit from.

It provides some convenience functions, and the standard id property.

Required Properties:

id (Integer): Unique identifier, an integer

classmethod from_api(**kwargs)[source]¶

Create a new instance from API arguments.

This will switch camelCase keys into snake_case for instantiation.

It will also identify any Instance or List properties, and instantiate the proper objects using the values. The end result being a fully Objectified and Pythonified API response.

Returns:	Instantiated model using the API values.
Return type:	BaseModel

get(key, default=None)[source]¶: Return the field indicated by the key, if present.

static get_non_empty_vals(mapping)[source]¶: Return the mapping without any None values.

id¶: Unique identifier

to_api()[source]¶

Return a dictionary to send to the API.

Returns:	Mapping representing this object that can be sent to the API.
Return type:	dict

class helpscout.Domain(queries=None, join_with='AND')[source]¶

Bases: properties.base.base.HasProperties

This represents a full search query.

AND = 'AND'¶

OR = 'OR'¶

add_query(query, join_with='AND')[source]¶

Join a new query to existing queries on the stack.

Parameters:	query (tuple or list or DomainCondition) – The condition for the query. If a `DomainCondition` object is not provided, the input should conform to the interface defined in `from_tuple()`. join_with (str) – The join string to apply, if other queries are already on the stack.

classmethod from_tuple(queries)[source]¶

Create a Domain given a set of complex query tuples.

Parameters:

queries (iter) –

An iterator of complex queries. Each iteration should contain either:

A data-set compatible with add_query()
A string to switch the join type

Example:

[('subject', 'Test1'),
 'OR',
 ('subject', 'Test2')',
 ('subject', 'Test3')',
 ]
# The above is equivalent to:
#    subject:'Test1' OR subject:'Test2' OR subject:'Test3'

[('modified_at', datetime(2017, 01, 01)),
 ('status', 'active'),
 ]
# The above is equivalent to:
#    modified_at:[2017-01-01T00:00:00Z TO *]
#    AND status:"active"

Returns: A domain representing the input queries.

Return type: Domain

class helpscout.HelpScout(api_key)[source]¶

Bases: object

This object is the primary point of interaction with HelpScout.

Properties will be set on this HelpScout instance that will mirror the class names of APIs in the helpscout.api module.

These API classes are naive of authentication, so the actual properties set will be using the AuthProxy class, which will transparently inject authentication into the API requests while still allowing for a naive API object.

This allows for the HelpScout instance to act as a container for all of the authenticated API objects.

Examples:

from helpscout import HelpScout
hs = HelpScout('api_key')
for customer in hs.Customers.list():
    print(customer)

Conversations¶: helpscout.api.conversations.Conversations – Conversations API endpoint.

Customers¶: helpscout.api.customers.Customers – Customers API endpoint.

Mailboxes¶: helpscout.api.mailboxes.Mailboxes – Mailboxes API endpoint.

Tags¶: helpscout.api.tags.Tags – Tags API endpoint.

Teams¶: helpscout.api.teams.Teams – Teams API endpoint.

Users¶: helpscout.api.users.Users – Users API endpoint.

WebHook¶: helpscout.api.web_hook.WebHook – Web Hook API endpoint.

__apis__¶: dict – References to all available APIs, keyed by class name.

class helpscout.HelpScoutWebHook(**kwargs)[source]¶

Bases: helpscout.models.web_hook.WebHook

This provides the ability to easily create & process web hook events.

Required Properties:

events (a list of StringChoice): The events to subscribe to., a list (each item is any of “convo.agent.reply.created” (An agent replied to the conversation.), “convo.assigned” (Conversation was assigned.), “convo.created” (Conversation was created.), “convo.customer.reply.created” (The customer replied to the conversation.), “convo.deleted” (Conversation was deleted.), “convo.merged” (Conversation was merged.), “convo.moved” (Conversation was moved.), “convo.note.created” (A note was added to the conversation.), “convo.status” (Conversation status was updated.), “convo.tags” (Conversation tags were updated.), “customer.created” (A customer was created.), “satisfaction.ratings” (A rating was received.))
helpscout (object): The authenticated HelpScout object. Used for create., an instance of object
id (Integer): Unique identifier, an integer
secret_key (String): A randomly-generated (by you) string of 40 characters or less used to create signatures for each webhook method. Help Scout uses this secret key to generate a signature for each webhook message. When the message is received at your callback URL, you can calculate a signature and compare to the one Help Scout sends. If the signatures match, you know it’s from Help Scout., a unicode string
url (String): The callback URL where Help Scout will post your webhook events. This is the script or location where you’ll handle the data received from Help Scout., a unicode string

create()[source]¶: Create the web hook on HelpScout.

helpscout¶: The authenticated HelpScout object. Used for create.

receive(event_type, signature, data_str)[source]¶

Receive a web hook for the event and signature.

Parameters:	event_type (str) – Name of the event that was received (from the request `X-HelpScout-Event` header). signature (str) – The signature that was received, which serves as authentication (from the request `X-HelpScout-Signature` header). data_str (str) – The raw data that was posted by HelpScout to the web hook. This must be the raw string, because if it is parsed with JSON it will lose its ordering and not pass signature validation.
Raises:	`helpscout.exceptions.HelpScoutSecurityException` – If an invalid signature is provided, and `raise_if_invalid` is `True`.
Returns:	The authenticated web hook request.
Return type:	helpscout.web_hook.WebHookEvent

validate_signature(signature, data, encoding='utf8')[source]¶

Validate the signature for the provided data.

Parameters:	signature (str or bytes or bytearray) – Signature that was provided for the request. data (str or bytes or bytearray) – Data string to validate against the signature. encoding (str, optional) – If a string was provided for `data` or `signature`, this is the character encoding.
Returns:	Whether the signature is valid for the provided data.
Return type:	bool