Noko Tags

The NokoClient offers multiple methods to interact with tags 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_tags(names: list[str]) → list[dict]

Create new Noko tags.

If any one tag cannot be created for any reason, it will be ignored and will not affect the response.

Parameters:

names (list[str]) – A list of the names of the tags to create. Adding a “*” at the end of a string indicates that the tag is unbillable.

Returns:

A list of all created tags.

Return type:

(list[dict])

delete_single_tag(tag_id: str | int) → None

Delete a single tag.

When a tag is deleted, entries associated with it are not deleted. This action will, however, affect their descriptions. It will be updated so that the tag’s text becomes part of the description.

Parameters:

tag_id (str | int) – The ID of the tag to delete.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

delete_tags(tag_ids: list[str | int]) → None

Delete multiple tags at once.

When a tag is deleted, entries associated with it are not deleted. This action will, however, affect their descriptions. It will be updated so that the tag’s text becomes part of the description.

If one of the tags in the provided list of IDs cannot be deleted, it will be ignored and it will not affect the response.

Parameters:

tag_ids (list [str | int]) – The list of IDs of the tags to delete.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)

edit_tag(tag_id: str | int, name: str) → list[dict]

Edit a single tag based on the tag ID.

Parameters:

  • tag_id (str | int) – the ID of the tag to edit.

  • name (str) – The name for the tag. Adding a “*” at the end of the string indicates an unbillable tag.

Returns:

The edited tag as a dictionary.

Return type:

(list[dict])

get_all_entries_for_tag(tag_id: str | int, **kwargs) → list[dict]

Retrieve all time entries associated with a tag.

Results can be filtered using the same keyword arguments as the ones used for the list entries endpoint. All keyword arguments are optional.

Parameters:

tag_id (str | int) – The ID of the tag to retrieve entries for.

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:

A list of all retrieved entries meeting the specified criteria.

Return type:

(list[dict])

get_single_tag(tag_id: int | str) → list[dict]

Retrieve a single tag based on the tag ID.

Parameters:

tag_id (str | int) – the ID of the tag to retrieve.

Returns:

The retrieved tag as a dictionary.

Return type:

(list[dict])

list_tags(**kwargs) → list[dict]

List all tags.

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

Keyword Arguments:

  • name (str | None) – Only tags containing the provided string in the name are returned. Defaults to None.

  • billable (bool | None) – Return only billable or unbillable tags. Defaults to both (set to None).

Returns:

All retrieved tags as a list of dictionaries.

Return type:

(list[dict])

merge_tag_into_this_tag(tag_id: str | int, tag_to_merge_id: str | int) → None

Merge a tag into another one.

When one tag is merged into another, the entries associated with the tag are associated with the new tag, and any instances of the old tags are replaced with the new tags in the Entry Description. This action is permanent, so you cannot undo after you merge tags.

Parameters:

  • tag_id (str | int) – The ID of the tag to keep. This is the tag the other tag will be merged into.

  • tag_to_merge_id (str | int) – The ID of the tag to merge. This is the tag that will be merged into the other one.

Returns:

Doesn’t return anything, if unsuccessful, will raise an exception.

Return type:

(None)