API Reference¶

This part of the documentation covers all the interfaces of our client library.

Client¶

class caplena.Client(api_key, *, api_base_uri=ApiBaseUri.PRODUCTION, api_version=ApiVersion.VER_2022_11_22, timeout=120, max_retries=5, backoff_factor=2, http_client=<class 'caplena.http.requests_http_client.RequestsHttpClient'>, logging_level=LoggingLevel.WARNING)¶

Represents a client connection that connects to Caplena. This class is used to interact with the Caplena REST API.

Parameters:

api_key (str) – The API key to use for making requests.
api_base_uri (ApiBaseUri) – The API Base URI to use, defaults to https://api.caplena.com/v2.
api_version (ApiVersion) – The API Version to use, defaults to 2022-06-13.
timeout (int) – The maximum number of seconds before the request times out, defaults to 120.
max_retries (int) – The maximum number of times the request is retried before giving up, defaults to 0.
backoff_factor (float) – The backoff factor to apply between attempts, defaults to 2.
retry_status_codes – A set of HTTP status codes that we should retry on, defaults to {408, 409, 413, 429, 500, 502, 503, 504}.
retry_methods (Iterable[HttpMethod]) – A set of HTTP methods that we should retry on, defaults to {GET, PUT, HEAD}.
http_client (Union[HttpClient, Type[HttpClient]]) – The HTTP client class or instance to use for making requests, defaults to RequestsHttpClient. If an HTTP class is given, the factory method build_http_client is used to create an instance.
logging_level (LoggingLevel) – The level of events to log out to console, defaults to WARNING.

property projects: ProjectsController¶: The projects controller, encapsulating all project actions.

Controllers¶

class caplena.controllers.ProjectsController(*, config)¶

The projects controller, encapsulating all project actions.

Parameters:: config (Configuration) – The configuration object that a particular controller should use.

append_row(*, id, columns)¶

Appends a single row to a previously created project.

Parameters:

id (str) – The project identifier.
columns (List[Dict[str, Any]]) – The columns for the new row.

Raises:

ApiException – An API exception.

Return type:

Row

append_rows(*, id, rows)¶

Appends multiple rows to a previously created project. It is possible to append a maximum of 20 rows in a single request.

Parameters:

id (str) – The project identifier.
rows (List[Dict[str, Any]]) – The rows to append to the specified project.

Raises:

ApiException – An API exception.

Return type:

RowsAppend

create(*, name, language, columns, tags=<caplena.constants._NOT_SET object>, translation_engine=<caplena.constants._NOT_SET object>, anonymize_pii=<caplena.constants._NOT_SET object>)¶

Creates a new project.

Parameters:

name (str) – Project name, as displayed in the user interface.
language (str) – Base language for this project.
columns (List[Dict[str, Any]]) – Columns of a project define its schema. In a sense, every project column corresponds to exactly one column in an Excel sheet. The four column types numerical, date, boolean and text are auxiliary columns, meaning that they won’t be analyzed, but they can be used to visualize your results. Please note that for columns of type numerical, its integer values must be between -(2^53-1) and 2^53-1. For bigger numbers, please use a column of type text.
tags (List[str] | None) – Tags assigned to this project. If omitted, no tags are assigned.
translation_engine (str | None) – Translation engine used to translate rows into the base language of this project. If omitted, no translation will be performed.
anonymize_pii (Dict[str, List[str]] | None) – settings to use for anonymization, visit the developer docs for more information.

Raises:

ApiException – An API exception.

Return type:

ProjectDetail

get_append_status(*, project_id, task_id=None)¶

Checks statuses of all upload tasks for requested project or only requested upload task if its ID is provided

Note: We keep the status of upload tasks only for the 7 days. After that time task info won’t be available.

Parameters:

project_id (str) – (Optional) The project identifier. If it’s missing, all tasks statuses of the project are returned.
task_id (UUID | str | None) – Task id which status will be checked

Raises:

ApiException – An API exception.
ValueError – when task_id is not proper UUID or uuid in a string

Return type:

RowsAppendStatus

list(*, order_by=<caplena.api.api_ordering.ApiOrdering object>, limit=None, filter=None)¶

Returns an iterator of all projects you have previously created. By default, the projects are returned in sorted order, with the most recently modified project appearing first.

Parameters:

order_by (ApiOrdering) – Column on which the results should be ordered on. Defaults to desc:last_modified.
limit (int | None) – Number of results returned per page. If unspecified, will return all results.
filter (ProjectsFilter | None) – Filters to apply to this request. If omitted, no filters are applied.

Raises:

ApiException – An API exception.

Return type:

CaplenaIterator[ListedProject]

list_rows(*, id, limit=None, filter=None)¶

Returns a list of all rows you have previously created for this project. The rows are returned in sorted order, with the least recently added row appearing first.

Parameters:

id (str) – The project identifier.
limit (int | None) – Number of results returned per page. If unspecified, will return all results.
filter (RowsFilter | None) – Filters to apply to this request. If omitted, no filters are applied.

Raises:

ApiException – An API exception.

Return type:

CaplenaIterator[Row]

remove(*, id)¶

Removes a previously created project.

Parameters:: id (str) – The project identifier.
Raises:: ApiException – An API exception.
Return type:: None

remove_row(*, p_id, r_id)¶

Removes a previously created row.

Parameters:

p_id (str) – The project identifier.
r_id (str) – The row identifier.

Raises:

ApiException – An API exception.

Return type:

None

retrieve(*, id)¶

Retrieves a project you have previously created.

Parameters:: id (str) – The project identifier.
Raises:: ApiException – An API exception.
Return type:: ProjectDetail

retrieve_row(*, p_id, r_id)¶

Retrieves a row for a project you have previously created.

Parameters:

p_id (str) – The project identifier.
r_id (str) – The row identifier.

Raises:

ApiException – An API exception.

Return type:

Row

update(*, id, name=<caplena.constants._NOT_SET object>, columns=<caplena.constants._NOT_SET object>, tags=<caplena.constants._NOT_SET object>)¶

Updates a project you have previously created.

Parameters:

id (str) – The project identifier.
name (str | None) – Project name, as displayed in the user interface.
columns (List[Dict[str, Any]] | None) – Columns of a project.
tags (List[str] | None) – Tags assigned to this project.

Raises:

ApiException – An API exception.

Return type:

ProjectDetail

update_row(*, p_id, r_id, columns)¶

Updates a row you have previously created.

Parameters:

p_id (str) – The project identifier.
r_id (str) – The row identifier.
columns (List[Dict[str, Any]]) – Columns for this row.

Raises:

ApiException – An API exception.

Return type:

Row

Resources¶

class caplena.resources.ProjectDetail(id, **attrs)¶

The project detail resource.

class Auxiliary(**attrs)¶

type: typing_extensions.Literal[numerical, boolean, text, date, any]¶: Type of this column.

class Column(**attrs)¶

name: str¶: Human-readable name for this column.

ref: str¶: Human-readable identifier for this column. The reference field is immutable and is unique among all columns within the same project.

type: typing_extensions.Literal[numerical, boolean, text, date, any, text_to_analyze]¶: Type of this column.

class TextToAnalyze(**attrs)¶

class Metadata(**attrs)¶

class LearnsForm(**attrs)¶

project: str¶: Base project that this column learns from.

ref: str¶: Column identifier that this column learns from.

learns_from: LearnsForm | None¶: Base column that this column learns from.

reviewed_count: int¶: Number of reviewed rows for this column.

class Topic(id, **attrs)¶

class Sentiment(**attrs)¶

code: int¶: Code for this topic sentiment.

label: str¶: Label for this topic sentiment.

category: str¶: Category for this topic

color: str¶: Color for this topic.

description: str¶: Description for this topic.

label: str¶: Label for this topic.

sentiment_enabled: bool¶: If enabled, Caplena will assign the topic with a corresponding sentiment.

sentiment_negative: Sentiment¶: Negative topic sentiment.

sentiment_neutral: Sentiment¶: Neutral topic sentiment.

sentiment_positive: Sentiment¶: Positive topic sentiment.

description: str | None = ''¶: Column description displayed for this column.

metadata: Metadata¶: Metadata associated with this column.

topics: CaplenaList[Topic]¶: List of topics associated with this column.

type: typing_extensions.Literal[text_to_analyze]¶: Type of this column.

columns: CaplenaList[Column]¶: Columns for this projects.

created: datetime¶: Timestamp at which the project was created.

language: str¶: Base language for this project as an ISO-639-1 Code

last_modified: datetime¶: Timestamp at which the project was last updated.

name: str¶: Name of this project.

owner: str¶: Identifier of the user that owns this project.

tags: List[str]¶: Tags associated with this project.

translation_engine: str | None¶: Translation engine used for translating text_to_analyze columns.

translation_status: str | None¶: Current translation status for this project.

upload_status: typing_extensions.Literal[pending, in_progress, succeeded, failed]¶: Current upload status of this project.

class caplena.resources.ListedProject(id, **attrs)¶

The project list resource.

created: datetime¶: Timestamp at which the project was created.

language: str¶: Base language for this project as an ISO-639-1 Code

last_modified: datetime¶: Timestamp at which the project was last updated.

name: str¶: Name of this project.

owner: str¶: Identifier of the user that owns this project.

tags: List[str]¶: Tags associated with this project.

translation_engine: str | None¶: Translation engine used for translating text_to_analyze columns.

translation_status: str | None¶: Current translation status for this project.

upload_status: typing_extensions.Literal[pending, in_progress, succeeded, failed]¶: Current upload status of this project.

class caplena.resources.RowsAppend(**attrs)¶

The bulk row create response object.

class RowsAppendResult(**attrs)¶

id: str¶: The identifier of the row that was appended.

estimated_minutes: float¶: Estimation in minutes about how long this bulk operation will approximately take.

queued_rows_count: int¶: Number of rows that were queued for appending.

results: CaplenaList[RowsAppendResult]¶: The results of the bulk append operation.

status: typing_extensions.Literal[pending]¶: Status of the bulk append operation.

task_id: str¶: Task ID of the bulk append operation.

class caplena.resources.RowsAppendStatus(**attrs)¶

Status of requested task

class LongRunningTaskStatus(**attrs)¶

Task status

id: UUID¶: ID of the task

status: typing_extensions.Literal[in_progress, succeeded, failed] | None¶: Status of the task

status: typing_extensions.Literal[in_progress, succeeded, failed]¶: Status of requested upload task

tasks: List[LongRunningTaskStatus] | None¶: tasks of the project

class caplena.resources.Row(id, **attrs)¶

The Row resource.

class AnyColumn(**attrs)¶

type: typing_extensions.Literal[any]¶: Type of this column.

value: None¶: Any value assigned to this column.

class BooleanColumn(**attrs)¶

type: typing_extensions.Literal[boolean]¶: Type of this column.

value: bool | None¶: Boolean value assigned to this column.

class Column(**attrs)¶

ref: str¶: Human-readable identifier for this column.

type: typing_extensions.Literal[numerical, boolean, text, date, any, text_to_analyze]¶: Type of this column.

value: int | float | bool | None | str | datetime¶: Value assigned to this column.

class DateColumn(**attrs)¶

type: typing_extensions.Literal[date]¶: Type of this column.

value: datetime | None¶: ISO 8601 datetime or date value assigned to this column.

class NumericalColumn(**attrs)¶

type: typing_extensions.Literal[numerical]¶: Type of this column.

value: int | float | None¶: Numerical value assigned to this column.

class TextColumn(**attrs)¶

type: typing_extensions.Literal[text]¶: Type of this column.

value: str¶: Text value assigned to this column.

class TextToAnalyzeColumn(**attrs)¶

class Topic(**attrs)¶

category: str¶: Category for this topic.

code: int¶: Code for the inferred topic sentiment. If sentiment is disabled, the neutral topic sentiment code will be used.

id: str¶: Unique identifier for this topic.

label: str¶: Label for this topic.

sentiment: typing_extensions.Literal[neutral, positive, negative, any]¶: Inferred sentiment for this column value.

sentiment_label: str¶: Label for the inferred topic sentiment. If sentiment is disabled, the neutral topic sentiment label will be used.

sentiment_overall: typing_extensions.Literal[neutral, positive, negative] | None¶: Inferred overall sentiment for this column.

source_language: str | None¶: Source language of this value as an ISO-639-1 Code (https://cloud.google.com/translate/docs/languages).

topics: CaplenaList[Topic]¶: Topics matching the value of this column. If no topics match, an empty array is returned.

translated_value: str | None¶: Translated value if translation is enabled for this column.

type: typing_extensions.Literal[text_to_analyze]¶: Type of this column.

value: str¶: Text value assigned to this column.

was_reviewed: bool | None¶: Indicates whether the row value for this column has been reviewed.

columns: CaplenaList[Column]¶: Columns for this row.

created: datetime¶: Timestamp at which this row was created.

last_modified: datetime¶: Timestamp at which this row was last updated.

refresh()¶

Refreshes the properties of this row.

Raises:: ApiException – An API exception.
Return type:: None

remove()¶

Removes this row.

Raises:: ApiException – An API exception.
Return type:: None

retrieve_project()¶

Retrieves the project that this row belongs to.

Raises:: ApiException – An API exception.
Return type:: ProjectDetail

save()¶

Saves the unpersisted properties of this row.

Raises:: ApiException – An API exception.
Return type:: None

Filters¶

class caplena.filters.ProjectsFilter(constraints=None, has_conjunction=False)¶

The filter that can be used to filter projects.

Parameters:

constraints (Dict[str, List[Dict[str, List[Any]]]] | None) – The internal filter constraints. Should never be manually given.
has_conjunction (bool) – The internal conjunction boolean. Should never be manually given.

__and__(other)¶

Creates and returns the immutable conjunction of two separate filters. The original filters will not be modified.

Parameters:

self (Filter) – The first filter.
other (Filter) – The second filter.

Return type:

Filter

__or__(other)¶

Creates and returns the immutable disjunction of two separate filters. The original filters will not be modified.

Parameters:

self (Filter) – The first filter.
other (Filter) – The second filter.

Return type:

Filter

classmethod created(*, gte=None, gt=None, lte=None, lt=None, range=None, year=None, year__gte=None, year__gt=None, year__lte=None, year__lt=None, month=None, month__gte=None, month__gt=None, month__lte=None, month__lt=None, day=None, day__gte=None, day__gt=None, day__lte=None, day__lt=None)¶

Allows filtering results based on date fields. For example, filtering with ProjectsFilter.created(year=2022, month=1) returns all results for January 2022 for the specified field.

Parameters:

gte (datetime | List[datetime] | None) – Greater than or equal to filter for date times.
gt (datetime | List[datetime] | None) – Greater than filter for date times.
lte (datetime | List[datetime] | None) – Less than or equal to filter for date times.
lt (datetime | List[datetime] | None) – Less than filter for date times.
range (typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year] | List[typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year]] | None) – Range filter for date times.
year (int | List[int] | None) – Allows filtering on the year.
year__gte (int | List[int] | None) – Greater than or equal to filter on the year.
year__gt (int | List[int] | None) – Greater than filter on the year.
year__lte (int | List[int] | None) – Less than or equal to filter on the year.
year__lt (int | List[int] | None) – Less than filter on the year.
month (int | List[int] | None) – Allows filtering on the month of the year.
month__gte (int | List[int] | None) – Greater than or equal to filter on the month of the year.
month__gt (int | List[int] | None) – Greater than filter on the month of the year.
month__lte (int | List[int] | None) – Less than or equal to filter on the month of the year.
month__lt (int | List[int] | None) – Greater than filter on the month of the year.
day (int | List[int] | None) – Allows filtering on the day of the month.
day__gte (int | List[int] | None) – Greater than or equal to filter on the day of the month.
day__gt (int | List[int] | None) – Greater than filter on the day of the month.
day__lte (int | List[int] | None) – Less than or equal to filter on the day of the month.
day__lt (int | List[int] | None) – Greater than filter on the day of the month.

Return type:

ProjectsFilter

classmethod language(language)¶

Allows filtering projects based on their language. For example, filtering with ProjectsFilter.language(['en', 'es']) returns all English and Spanish projects.

Parameters:: language (str | List[str] | None) – Allows filtering on project language.
Return type:: ProjectsFilter

classmethod last_modified(*, gte=None, gt=None, lte=None, lt=None, range=None, year=None, year__gte=None, year__gt=None, year__lte=None, year__lt=None, month=None, month__gte=None, month__gt=None, month__lte=None, month__lt=None, day=None, day__gte=None, day__gt=None, day__lte=None, day__lt=None)¶

Allows filtering results based on date fields. For example, filtering with ProjectsFilter.last_modified(year=2022, month=1) returns all results for January 2022 for the specified field.

Parameters:

gte (datetime | List[datetime] | None) – Greater than or equal to filter for date times.
gt (datetime | List[datetime] | None) – Greater than filter for date times.
lte (datetime | List[datetime] | None) – Less than or equal to filter for date times.
lt (datetime | List[datetime] | None) – Less than filter for date times.
range (typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year] | List[typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year]] | None) – Range filter for date times.
year (int | List[int] | None) – Allows filtering on the year.
year__gte (int | List[int] | None) – Greater than or equal to filter on the year.
year__gt (int | List[int] | None) – Greater than filter on the year.
year__lte (int | List[int] | None) – Less than or equal to filter on the year.
year__lt (int | List[int] | None) – Less than filter on the year.
month (int | List[int] | None) – Allows filtering on the month of the year.
month__gte (int | List[int] | None) – Greater than or equal to filter on the month of the year.
month__gt (int | List[int] | None) – Greater than filter on the month of the year.
month__lte (int | List[int] | None) – Less than or equal to filter on the month of the year.
month__lt (int | List[int] | None) – Greater than filter on the month of the year.
day (int | List[int] | None) – Allows filtering on the day of the month.
day__gte (int | List[int] | None) – Greater than or equal to filter on the day of the month.
day__gt (int | List[int] | None) – Greater than filter on the day of the month.
day__lte (int | List[int] | None) – Less than or equal to filter on the day of the month.
day__lt (int | List[int] | None) – Greater than filter on the day of the month.

Return type:

ProjectsFilter

classmethod name(*, exact__i=None, contains__i=None)¶

Allows filtering results based on text fields. For example, filtering with ProjectsFilter.name(contains__i='reviews') only returns results containing the text reviews for the specified field.

Parameters:

exact__i (str | List[str] | None) – Allows filtering on exact, case-insensitive text.
contains__i (str | List[str] | None) – Allows filtering on partial, case-insensitive text.

Return type:

ProjectsFilter

classmethod owner(*, id, email__exact__i, email__contains__i)¶

Allows filtering projects based on their owner. For example, filtering with ProjectsFilter.owner(email__exact__i='katy@acme.com') only returns projects that belong to katy@acme.com.

Parameters:

id (str | List[str] | None) – Allows filtering on project owner identifiers.
email__exact__i (str | List[str] | None) – Allows filtering on exact, case-insensitive email addresses of project owners.
email__contains__i (str | List[str] | None) – Allows filtering on partial, case-insensitive email addresses of project owners.

Return type:

ProjectsFilter

classmethod tags(tag)¶

Allows filtering projects based on the tags they contain. For example, filtering with ProjectsFilter.tags('tag1') & ProjectsFilter.tags('tag2') returns all projects that are tagged with both tag1 and tag2.

Parameters:: tag (str | List[str] | None) – Allows filtering on project tags.
Return type:: ProjectsFilter

classmethod translation_engine(translation_engine)¶

Allows filtering projects based on their translation engine. For example, filtering with ProjectsFilter.translation_engine('google_translate') returns all projects that have Google Translate enabled.

Parameters:: translation_engine (str | List[str] | None) – Allows filtering on translation engine.
Return type:: ProjectsFilter

classmethod translation_status(translation_status)¶

Allows filtering projects based on their translation status. For example, filtering with ProjectsFilter.translation_status(['disabled', 'pending']) returns all projects that have translation disabled or translation is still pending.

Parameters:: translation_status (str | List[str] | None) – Allows filtering on translation status.
Return type:: ProjectsFilter

classmethod upload_status(upload_status)¶

Allows filtering projects based on their upload status. For example, filtering with ProjectsFilter.upload_status(['pending', 'failed']) returns all projects that are pending or have failed.

Parameters:: upload_status (str | List[str] | None) – Allows filtering on upload status.
Return type:: ProjectsFilter

class caplena.filters.RowsFilter(constraints=None, has_conjunction=False)¶

The filter that can be used to filter rows.

Parameters:

constraints (Dict[str, List[Dict[str, List[Any]]]] | None) – The internal filter constraints. Should never be manually given.
has_conjunction (bool) – The internal conjunction boolean. Should never be manually given.

class Columns¶

Allows filtering rows based on the values of its columns.

classmethod boolean(*, ref, exact=None)¶

Allows filtering on boolean columns.

Parameters:

ref (str) – The boolean column reference.
exact (bool | List[bool] | None) – Exact filter for boolean values.

Return type:

RowsFilter

classmethod date(*, ref, gte=None, gt=None, lte=None, lt=None, range=None)¶

Allows filtering on date columns.

Parameters:

gte (datetime | List[datetime] | None) – Greater than or equal to filter for date times.
gt (datetime | List[datetime] | None) – Greater than filter for date times.
lte (datetime | List[datetime] | None) – Less than or equal to filter for date times.
lt (datetime | List[datetime] | None) – Less than filter for date times.
range (typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year] | List[typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year]] | None) – Range filter for date times.
ref (str) –

Return type:

RowsFilter

static numerical(*, ref, exact=None, gte=None, gt=None, lte=None, lt=None)¶

Allows filtering on numerical columns.

Parameters:

ref (str) – The numerical column reference.
exact (float | List[float] | None) – Exact filter for numerical values.
gte (float | List[float] | None) – Greater than or equal to filter for numerical values.
gt (float | List[float] | None) – Greater than filter for numerical values.
lte (float | List[float] | None) – Less than or equal to filter for numerical values.
lt (float | List[float] | None) – Less than filter for numerical values.

Return type:

RowsFilter

classmethod text(*, ref, exact__i=None, contains__i=None)¶

Allows filtering on text columns.

Parameters:

ref (str) – The text column reference.
exact__i (str | List[str] | None) – Allows filtering on exact, case-insensitive text values.
contains__i (str | List[str] | None) – Allows filtering on partial, case-insensitive text values.

Return type:

RowsFilter

classmethod text_to_analyze(*, ref, exact__i=None, contains__i=None, was_reviewed=None, source_language=None, translated_value__exact__i=None, translated_value__contains__i=None)¶

Allows filtering on verbatim columns.

Parameters:

ref (str) – The verbatim column reference.
exact__i (str | List[str] | None) – Allows filtering on exact, case-insensitive verbatims.
contains__i (str | List[str] | None) – Allows filtering on partial, case-insensitive verbatims.
was_reviewed (bool | List[bool] | None) – Allows filtering on reviewed columns.
source_language (str | List[str] | None) – Allows filtering on the source language of this column.
translated_value__exact__i (str | List[str] | None) – Allows filtering on exact, case-insensitive translated text verbatims.
translated_value__contains__i (str | List[str] | None) – Allows filtering on partial, case-insensitive translated text verbatims.

Return type:

RowsFilter

__and__(other)¶

Creates and returns the immutable conjunction of two separate filters. The original filters will not be modified.

Parameters:

self (Filter) – The first filter.
other (Filter) – The second filter.

Return type:

Filter

__or__(other)¶

Creates and returns the immutable disjunction of two separate filters. The original filters will not be modified.

Parameters:

self (Filter) – The first filter.
other (Filter) – The second filter.

Return type:

Filter

Allows filtering results based on date fields. For example, filtering with RowsFilter.created(year=2022, month=1) returns all results for January 2022 for the specified field.

Parameters:

gte (datetime | List[datetime] | None) – Greater than or equal to filter for date times.
gt (datetime | List[datetime] | None) – Greater than filter for date times.
lte (datetime | List[datetime] | None) – Less than or equal to filter for date times.
lt (datetime | List[datetime] | None) – Less than filter for date times.
range (typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year] | List[typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year]] | None) – Range filter for date times.
year (int | List[int] | None) – Allows filtering on the year.
year__gte (int | List[int] | None) – Greater than or equal to filter on the year.
year__gt (int | List[int] | None) – Greater than filter on the year.
year__lte (int | List[int] | None) – Less than or equal to filter on the year.
year__lt (int | List[int] | None) – Less than filter on the year.
month (int | List[int] | None) – Allows filtering on the month of the year.
month__gte (int | List[int] | None) – Greater than or equal to filter on the month of the year.
month__gt (int | List[int] | None) – Greater than filter on the month of the year.
month__lte (int | List[int] | None) – Less than or equal to filter on the month of the year.
month__lt (int | List[int] | None) – Greater than filter on the month of the year.
day (int | List[int] | None) – Allows filtering on the day of the month.
day__gte (int | List[int] | None) – Greater than or equal to filter on the day of the month.
day__gt (int | List[int] | None) – Greater than filter on the day of the month.
day__lte (int | List[int] | None) – Less than or equal to filter on the day of the month.
day__lt (int | List[int] | None) – Greater than filter on the day of the month.

Return type:

RowsFilter

Allows filtering results based on date fields. For example, filtering with RowsFilter.last_modified(year=2022, month=1) returns all results for January 2022 for the specified field.

Parameters:

gte (datetime | List[datetime] | None) – Greater than or equal to filter for date times.
gt (datetime | List[datetime] | None) – Greater than filter for date times.
lte (datetime | List[datetime] | None) – Less than or equal to filter for date times.
lt (datetime | List[datetime] | None) – Less than filter for date times.
range (typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year] | List[typing_extensions.Literal[all_time, this_month, last_month, this_quarter, last_quarter, this_year, last_year]] | None) – Range filter for date times.
year (int | List[int] | None) – Allows filtering on the year.
year__gte (int | List[int] | None) – Greater than or equal to filter on the year.
year__gt (int | List[int] | None) – Greater than filter on the year.
year__lte (int | List[int] | None) – Less than or equal to filter on the year.
year__lt (int | List[int] | None) – Less than filter on the year.
month (int | List[int] | None) – Allows filtering on the month of the year.
month__gte (int | List[int] | None) – Greater than or equal to filter on the month of the year.
month__gt (int | List[int] | None) – Greater than filter on the month of the year.
month__lte (int | List[int] | None) – Less than or equal to filter on the month of the year.
month__lt (int | List[int] | None) – Greater than filter on the month of the year.
day (int | List[int] | None) – Allows filtering on the day of the month.
day__gte (int | List[int] | None) – Greater than or equal to filter on the day of the month.
day__gt (int | List[int] | None) – Greater than filter on the day of the month.
day__lte (int | List[int] | None) – Less than or equal to filter on the day of the month.
day__lt (int | List[int] | None) – Greater than filter on the day of the month.

Return type:

RowsFilter

Iterator¶

class caplena.iterator.CaplenaIterator(*, results_fetcher, current_page=0, total_results_fetched=0, results=None, total_count=None, limit=None, has_next=True)¶

A lazy iterator, only fetches more results when the entries are iterated.

property count: int¶: The total number of elements that exist for the requested resource.

Exceptions¶

class caplena.api.ApiException(*, type, code, message='An unknown error occurred. Please reach out to us at support@caplena.com.', details=None, help=None, context=None)¶

The API Exception that is thrown by the Caplena REST API.

Parameters:

type (str) – The type of the error returned.
code (str) – A short string that uniquely identifies the reason for this error. Useful for programmatic error handling. Should never be shown to your end users.
message (str) – A brief human-readable message providing more details about the error that has occurred. Please note that error messages might change and are therefore not suitable for programmatic error handling. Can be shown to end users.
details (str | None) – A lengthier human-readable explanation of the error. This property is intened for use by developers only and provides additional information on how this issue could be resolved. Should never be shown to your end users.
help (str | None) – URL that links to part of our developer documentation, allowing engineers to learn more about how to fix the given issue. Should never be shown to your end users.
context (Any) – Additional context that might be present depending on the error type and code.

code: str¶: A short string that uniquely identifies the reason for this error. Useful for programmatic error handling. Should never be shown to your end users.

context: Any¶: Additional context that might be present depending on the error type and code.

details: str | None¶: A lengthier human-readable explanation of the error. This property is intened for use by developers only and provides additional information on how this issue could be resolved. Should never be shown to your end users.

help: str | None¶: URL that links to part of our developer documentation, allowing engineers to learn more about how to fix the given issue. Should never be shown to your end users.

message: str¶: A brief human-readable message providing more details about the error that has occurred. Please note that error messages might change and are therefore not suitable for programmatic error handling. Can be shown to end users.

type: str¶: The type of the error returned.