Noko Entries

The NokoClient offers multiple methods to interact with entries in Noko. On methods where keyword arguments are supported, parameter validation happens through Pydantic, allowing Python types other than what’s supported by the Noko API to be used when making requests, and providing a validation layer before the request is even made to the API.

class noko_client.client.NokoClient(access_token: str)

Simple Client for the Noko API.

Provide a friendlier interface to interact with the Noko API. Where Noko expects parameters to be passed in a specific way (for example, a list of strings for IDs, provide support for multiple types and handle formatting and validation.

This client does not currently support oAuth.

access_token

The Noko access token to authenticate the requests.

Type:

str

create_entry(**kwargs) → list[dict]

Create new entry in Noko.

Keyword Arguments:

  • date (str | datetime) – Date the entry will be logged to. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

  • user_id (str | int) – The ID of the user who logged this time entry.

  • minutes (int) – The total number of minutes logged to the time entry. The number will automatically be rounded up to meet the project’s billing_increment settings.

  • description (str | None) – The description to attach to the time entry. Defaults to None.

  • project_id (str | int | None) – The ID of the project to log the entry under. Defaults to None.

  • project_name (str | None) – The name of the project to log the entry under. If both project_id and project_name are provided, project_id will be used. If no project_id or project_name are provided, the entry won’t be logged under any project. If a name is provided and a project with this name does not exist yet, one will be created. Defaults to None.

  • source_url (str | None) – A URL representing the work completed in this time entry. For example, the URL to a GitHub PR or a Jira ticket ID. Defaults to None.

Returns:

The entry created with the provided information as a dictionary.

Return type:

(dict)

delete_entry(entry_id: str | int) → None

Delete a time entry.

Entries that have been invoiced, approved or belong to an archived project cannot be deleted. In these cases, the request will fail with a custom error indicative of the issue.

Parameters:

entry_id (str | int) – The ID of the time entry to delete.

Returns:

If unsuccessful, will raise an exception.

Return type:

(None)

edit_entry(entry_id: int | str, **kwargs) → list[dict]

Edit an existing entry.

Parameters:

entry_id (int | str) – The ID of the time entry to edit.

Keyword Arguments:

  • date (str | datetime | None) – Date the entry will be logged to. If provided as string, must be in ISO 8601 format (YYYY-MM-DD). If not provided, date will not be changed.

  • user_id (str | int | None) – The ID of the user who logged this time entry. If not provided, user will not be changed.

  • minutes (int | None) – The total number of minutes logged to the time entry. The number will automatically be rounded up to meet the project’s billing_increment settings. If not provided, minutes will not be changed.

  • description (str | None) – The description to attach to the time entry. Any tags or hashtags will be automatically parsed. If not provided, description will not be changed.

  • project_id (str | int | None) – The ID of the project the entry is logged under. If not provided, the project will not be changed.

  • project_name (str | None) – The name of the project to log the entry under. If both project_id and project_name are provided, project_id will be used. If no project_id or project_name are provided, the entry won’t be logged under any project. If a name is provided and a project with this name does not exist yet, one will be created. If not provided, the project will not be changed.

  • source_url (str | None) – A URL representing the work completed in this time entry. For example, the URL to a GitHub PR or a Jira ticket ID. If not provided, the source URL will not be changed.

Returns:

The edited entry with the provided information as a dictionary.

Return type:

(dict)

get_single_entry(entry_id: str | int) → list[dict]

Retrieve a single entry based on the entry ID.

Parameters:

entry_id (str | int) – the ID of the entry to retrieve.

Returns:

The retrieved entry as a dictionary.

Return type:

(list[dict])

list_entries(**kwargs) → list[dict]

List all entries.

By default, retrieves all entries. The entries to retrieve can be filtered based on accepted Keyword Arguments.

Keyword Arguments:

  • user_ids (str | list | None) – IDs of users to filter. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • description (str | None) – Only descriptions containing the provided text will be returned. Defaults to None.

  • project_ids (str | list | None) – IDs of projects to filter for. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • tag_ids (str | list | None) – IDs of users to filter for. If provided as a string, must be comma separated. If provided as a list, can be provided as a list of integers or strings. Defaults to None.

  • tag_filter_type (str | None) – The type of filter to apply if filtering for tag_ids. Defaults to None.

  • from (str | datetime | None) – The date from which to search. Only entries logged on this day onwards will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

  • to (str | datetime | None) – The date up to which to search. Only entries logged up to this day will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

  • invoiced (bool | str | None) – Whether to filter for invoiced or uninvoiced entries. If provided as string, must be lower case. Defaults to None.

  • updated_from (str | datetime | None) – Only entries with updates from this timestamp onwards are returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Defaults to None.

  • updated_to (str | datetime | None) – Only entries with updates up to this timestamp are returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Defaults to None.

  • billable (bool | str | None) – Whether to filter for billable or unbillable entries. If provided as string, must be lower case. Defaults to None.

  • approved_at_from (str | datetime | None) – Only entries with approvals from this date on will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD). Defaults to None.

  • approved_at_to (str | datetime | None) – Only entries with approvals up to this date will be returned. If provided as string, must be in ISO 8601 format (YYYY-MM-DD). Defaults to None.

Returns:

The complete response from Noko as a list of dictionaries.

Return type:

(list[dict])

mark_as_approved(entry_ids: int | str | list[int | str], approved_at: str | datetime | None = None) → None

Mark an entry or a list of entries as approved.

Approved entries cannot be edited or deleted.

If a single entry is provided and is associated with an archived project or is already approved, the request will fail.

Any entries in a bulk request that cannot be edited or approved will be ignored and will not cause an unsuccessful response.

Parameters:

  • entry_ids (int | str | list[int] | list[str]) – The ID of the entry (or entries) to mark as invoiced.

  • approved_at (str | datetime | None) – The timestamp for when the entry was approved. If provided as string,

  • (YYYY-MM-DDTHH (must be in ISO 8601 format) – MM:SSZ). If not provided, current time will be used.

Returns:

If unsuccessful, will raise an exception.

Return type:

(None)

mark_as_invoiced(entry_ids: int | str | list[int] | list[str], date: str | datetime) → None

Mark an entry or a list of entries as invoiced outside of Noko.

If an entry has already been marked as invoiced outside of noko, the action will modify the invoiced_at date for that entry.

Parameters:

  • entry_ids (int | str | list[int] | list[str]) – The ID of the entry (or entries) to mark as invoiced.

  • date (str | datetime) – The date to mark the entry as invoiced at. If provided as string, must be in ISO 8601 format (YYYY-MM-DD).

Returns:

If unsuccessful, will raise an exception.

Return type:

(None)

mark_as_unapproved(entry_ids: int | str | list[int | str]) → None

Mark an entry or a list of entries as unapproved.

Unapproved entries can be edited or deleted.

If a single entry is provided and is associated with an archived project, the request will fail.

Any entries in a bulk request that cannot be edited or unapproved will be ignored and will not cause an unsuccessful response.

Parameters:

entry_ids (int | str | list[int] | list[str]) – The ID of the entry (or entries) to mark as invoiced.

Returns:

If unsuccessful, will raise an exception.

Return type:

(None)