Builders

Paginator

class freshbooks.builders.paginator.PaginateBuilder(page=None, per_page=None)

Bases: freshbooks.builders.Builder

Builder for making paginated list queries.

Has two attributes, page and per_page. When a PaginateBuilder object is passed to a .list() call, the call will fetch only the per_page number of results and will fetch the results offset by page.

>>> from freshbooks import PaginateBuilder

>>> paginator = PaginateBuilder(2, 4)
>>> paginator
PaginateBuilder(page=2, per_page=4)

>>> clients = freshBooksClient.clients.list(account_id, builders=[paginator])
>>> clients.pages
PageResult(page=2, pages=3, per_page=4, total=9)
build(resource_name=None)

Builds the query string parameters from the PaginateBuilder.

Args: resource_name: The type of resource to generate the query string for. Eg. AccountingResource, ProjectsResource

Returns: The built query string

Return type

:py:class:str

page(page=None)

Set the page you wish to fetch in a list call, or get the currently set the page. When setting, can be chained.

>>> paginator = PaginateBuilder(1, 3)
>>> paginator
PaginateBuilder(page=1, per_page=3)

>>> paginator.page()
1

>>> paginator.page(2).per_page(4)
>>> paginator
PaginateBuilder(page=2, per_page=4)

Args: page: (Optional) The page of results to return in the API call

Returns: The PaginateBuilder instance if a page value is provided, otherwise returns the currently set page value.

Return type

:py:data:~typing.Union``[:py:class:``int, :py:obj:None, :py:class:~freshbooks.builders.Builder]

per_page(per_page=None)

Set the number of results you wish to fetch in a page of a list call, or get the currently set per_page. When setting, can be chained.

The page size is capped at 100.

>>> paginator = PaginateBuilder(1, 3)
>>> paginator
PaginateBuilder(page=1, per_page=3)

>>> paginator.per_page()
3

>>> paginator.per_page(4).page(2)
>>> paginator
PaginateBuilder(page=2, per_page=4)

Args: per_page: (Optional) The number of results to return in each API call

Returns: The PaginateBuilder instance if a per_page value is provided, otherwise returns the currently set per_page value.

Return type

:py:data:~typing.Union``[:py:class:``int, :py:obj:None, :py:class:~freshbooks.builders.Builder]

Filters

class freshbooks.builders.filter.FilterBuilder

Bases: freshbooks.builders.Builder

Builder for making filtered list queries.

Filters can be builts with the methods: equals, in_list, like, between, and boolean, date_time which can be chained together.

>>> from freshbooks import FilterBuilder

>>> f = FilterBuilder()
>>> f.like("email_like", "@freshbooks.com")
FilterBuilder(&search[email_like]=@freshbooks.com)

>>> f = FilterBuilder()
>>> f.in_list("clientids", [123, 456]).boolean("active", False)
FilterBuilder(&search[clientids][]=123&search[clientids][]=456&active=False)

>>> f = FilterBuilder()
>>> f.boolean("active", False).in_list("clientids", [123, 456])
FilterBuilder(&active=False&search[clientids][]=123&search[clientids][]=456)

>>> f = FilterBuilder()
>>> f.between("amount", 1, 10)
FilterBuilder(&search[amount_min]=1&search[amount_max]=10)

>>> f = FilterBuilder()
>>> f.between("start_date", date.today())
FilterBuilder(&search[start_date]=2020-11-21)
between(field, min=None, max=None)

Filters results where the provided field is between two values.

In general ‘between’ filters end in a _min or _max (as in amount_min or amount_max) or _date (as in start_date, end_date). If the provided field does not end in _min/_max or _date, then the appropriate _min/_max will be appended.

For date fields, you can pass the iso format 2020-10-17 or a datetime or date object, which will be converted to the proper string format.

Examples:

  • filter.between("amount", 1, 10) will yield filters &search[amount_min]=1&search[amount_max]=10

  • filter.between("amount_min", min=1) will yield filter &search[amount_min]=1

  • filter.between("amount_max", max=10) will yield filter &search[amount_max]=10

  • filter.between("start_date", "2020-10-17") will yield filter &search[start_date]=2020-10-17

  • filter.between("start_date", datetime.date(year=2020, month=10, day=17)) will yield filter

&search[start_date]=2020-10-17

Args: field: The API response field to filter on min: (Optional) The value the field should be greater than (or equal to) max: (Optional) The value the field should be less than (or equal to)

Returns: The FilterBuilder instance

Return type

:py:class:~freshbooks.builders.Builder

boolean(field, value)

Filters results where the field is equal to true or false.

Example: filter.boolean("active", False) will yield the filter &active=false

Args: field: The API response field to filter on value: True or False

Returns: The FilterBuilder instance

Return type

:py:class:~freshbooks.builders.Builder

build(resource_name=None)

Builds the query string parameters from the FilterBuilder.

Args: resource_name: The type of resource to generate the query string for. Eg. AccountingResource, ProjectsResource

Returns: The built query string

Return type

:py:class:str

date_time(field, value)

Filters for entries that come before or after a particular time, as specified by the field. Eg. “updated_since” on Time Entries will return time entries updated after the provided time.

The url parameter must be in ISO 8601 format (eg. 2010-10-17T05:45:53Z)

Example:

  • filter.date_time("updated_since", "2020-10-17T13:14:07") will yield &updated_since=2020-10-17T13:14:07

Args: field: The API response field to filter on value: The datetime, or ISO 8601 format string value

Returns: The FilterBuilder instance

Return type

:py:class:~freshbooks.builders.Builder

equals(field, value)

Filters results where the field is equal to the provided value.

Example: filter.equals("username", "Bob") will yield the filter &search[username]=Bob

Args: field: The API response field to filter on value: The value the field should equal

Returns: The FilterBuilder instance

Return type

:py:class:~freshbooks.builders.Builder

in_list(field, values)

Filters if the provided field matches a value in a list.

In general, an ‘in’ filter will be bound to the plural form of the field. Eg. userid for an equal filter, userids for a list filter.

Here we only append an ‘s’ to the field name if it doesn’t have one yet. This way we can be as forgiving as possible for developers by accepting: filter.in_list("userid", [1, 2]) or filter.in_list("userids", [1, 2]).

Of course the FreshBooks API is not 100% consistent, so there are a couple of unique cases that may not be handled.

Args: field: The API response field to filter on values: List of values the field should one of

Returns: The FilterBuilder instance

Return type

:py:class:~freshbooks.builders.Builder

like(field, value)

Filters for a match contained within the field being searched. For example, “leaf” will Like-match “aleaf” and “leafy”, but not “leav”, and “leafs” would not Like-match “leaf”.

Args: field: The API response field to filter on value: The value the field should contain

Returns: The FilterBuilder instance

Return type

:py:class:~freshbooks.builders.Builder

Includes

class freshbooks.builders.includes.IncludesBuilder

Bases: freshbooks.builders.Builder

Builder for including relationships, sub-resources, or additional data in the response.

>>> from freshbooks import IncludesBuilder

>>> includes = IncludesBuilder()
>>> includes.include("late_reminders")
IncludesBuilder(&include[]=late_reminders)
build(resource_name=None)

Builds the query string parameters from the IncludesBuilder.

Args: resource_name: The type of resource to generate the query string for. Eg. AccountingResource, ProjectsResource

Returns: The built query string

Return type

:py:class:str

include(key)

Add an include key to the builder.

Example: includes.include("late_reminders") will yield the filter &include[]=late_reminders

Args: key: The key for the resource or data to include

Returns: The IncludesBuilder instance

Return type

:py:class:~freshbooks.builders.Builder