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
andper_page
. When aPaginateBuilder
object is passed to a.list()
call, the call will fetch only theper_page
number of results and will fetch the results offset bypage
.>>> 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 setpage
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 setper_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
, andboolean
,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 inamount_min
oramount_max
) or_date
(as instart_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 adatetime
ordate
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])
orfilter.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