Skip to content

Project#

pyticktick.models.v2.parameters.project #

Parameters for creating and updating projects via the V2 API.

Unofficial API

These models are part of the unofficial TickTick API. They were created by reverse engineering the API. They may be incomplete or inaccurate.

Classes:

Name Description
CreateProjectV2

Model for creating a project via the V2 API.
PostBatchProjectV2

Model for batch project operations via the V2 API.
UpdateProjectV2

Model for updating a project via the V2 API.

CreateProjectV2 pydantic-model #

Bases: BaseModelV2

Model for creating a project via the V2 API.

This model is used to create a project via the V2 API. It mostly maps to the create project documentation in the API docs. The main differences are the addition of the id and group_id fields. This is used in the PostBatchProjectV2 model.

Show JSON schema: 
{
  "additionalProperties": false,
  "description": "Model for creating a project via the V2 API.\n\nThis model is used to create a project via the V2 API. It mostly maps to the\n[create project](https://developer.ticktick.com/docs#/openapi?id=create-project)\ndocumentation in the API docs. The main differences are the addition of the `id`\nand `group_id` fields. This is used in the `PostBatchProjectV2` model.",
  "properties": {
    "name": {
      "description": "name of the project",
      "title": "Name",
      "type": "string"
    },
    "color": {
      "anyOf": [
        {
          "format": "color",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "color of project, eg. '#F18181'",
      "title": "Color"
    },
    "group_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "ID of the project group to add the project to",
      "title": "Group Id"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "ID of the project to create",
      "title": "Id"
    },
    "kind": {
      "anyOf": [
        {
          "enum": [
            "TASK",
            "NOTE"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "\"TASK\" or \"NOTE\"",
      "title": "Kind"
    },
    "view_mode": {
      "anyOf": [
        {
          "enum": [
            "list",
            "kanban",
            "timeline"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "view mode, \"list\", \"kanban\", \"timeline\"",
      "title": "View Mode"
    },
    "sort_order": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sort Order"
    }
  },
  "required": [
    "name"
  ],
  "title": "CreateProjectV2",
  "type": "object"
}

Fields:

Validators:

color pydantic-field #

color: Color | None = None

color of project, eg. '#F18181'

group_id pydantic-field #

group_id: ObjectId | None = None

ID of the project group to add the project to

id pydantic-field #

id: ObjectId | None = None

ID of the project to create

kind pydantic-field #

kind: Literal['TASK', 'NOTE'] | None = None

"TASK" or "NOTE"

name pydantic-field #

name: str

name of the project

view_mode pydantic-field #

view_mode: Literal["list", "kanban", "timeline"] | None = (
    None
)

view mode, "list", "kanban", "timeline"

empty_str_to_none pydantic-validator #

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name Type Description Default
v Any

The value to validate.

 required

Returns:

Name Type Description
Any Any

The input value if it is not an empty string, otherwise None.
Source code in src/pyticktick/models/v2/models.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v

override_forbid_extra_message_injector pydantic-validator #

override_forbid_extra_message_injector(
    data: Any,
    handler: ModelWrapValidatorHandler[BaseModelV2],
) -> BaseModelV2

Provide a better error message for extra fields.

The TickTick V2 API is unofficial and may change without notice. As such, the models may not always be up to date with the API. This validator catches the extra_forbidden errors and provides a more informative error message, including a link to the documentation on how to override the extra_forbidden behavior if needed.

Parameters:

Name Type Description Default
data Any

The input data to validate.

 required
handler ModelWrapValidatorHandler[BaseModelV2]

The handler to call the next validator in the chain.

 required

Raises:

Type Description
ValidationError

If the pydantic model fails validation for any reason.

Returns:

Name Type Description
BaseModelV2 BaseModelV2

The validated model instance.
Source code in src/pyticktick/models/v2/models.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@model_validator(mode="wrap")
@classmethod
def override_forbid_extra_message_injector(
    cls,
    data: Any,
    handler: ModelWrapValidatorHandler[BaseModelV2],
) -> BaseModelV2:
    """Provide a better error message for extra fields.

    The TickTick V2 API is unofficial and may change without notice. As such, the
    models may not always be up to date with the API. This validator catches the
    `extra_forbidden` errors and provides a more informative error message,
    including a link to the documentation on how to override the `extra_forbidden`
    behavior if needed.

    Args:
        data (Any): The input data to validate.
        handler (ModelWrapValidatorHandler[BaseModelV2]): The handler to call the
            next validator in the chain.

    Raises:
        ValidationError: If the pydantic model fails validation for any reason.

    Returns:
        BaseModelV2: The validated model instance.
    """  # noqa: DOC501, DOC502 # ruff thinks `from_exception_data` should be raised instead of `ValidationError`
    try:
        return handler(data)
    except ValidationError as e:
        errors = []
        for error_dict in e.errors():
            if error_dict.get("type") in (
                "extra_forbidden",
                "custom_pyticktick_extra_forbidden",
            ):
                _type: str | PydanticCustomError = PydanticCustomError(
                    "custom_pyticktick_extra_forbidden",
                    f"Extra inputs are not permitted by default for `{cls.__name__}`. Please set `override_forbid_extra` to `True` if you believe the TickTick API has diverged from the model. See https://pyticktick.pretzer.io/guides/settings/overriding_models_that_forbid_extra_fields/ for more information.",  # pyright: ignore[reportArgumentType] # ty: ignore[invalid-argument-type]
                )
            else:
                _type = error_dict["type"]

            init_error_details: InitErrorDetails = {
                "type": _type,
                "input": error_dict["input"],
            }
            if "loc" in error_dict:
                init_error_details["loc"] = error_dict["loc"]
            if "ctx" in error_dict:
                init_error_details["ctx"] = error_dict["ctx"]

            errors.append(init_error_details)

        raise ValidationError.from_exception_data(e.title, errors) from e

PostBatchProjectV2 pydantic-model #

Bases: BaseModelV2

Model for batch project operations via the V2 API.

This model is used to create, update, and delete projects in bulk against the V2 API endpoint POST /batch/project.

Show JSON schema: 
{
  "$defs": {
    "CreateProjectV2": {
      "additionalProperties": false,
      "description": "Model for creating a project via the V2 API.\n\nThis model is used to create a project via the V2 API. It mostly maps to the\n[create project](https://developer.ticktick.com/docs#/openapi?id=create-project)\ndocumentation in the API docs. The main differences are the addition of the `id`\nand `group_id` fields. This is used in the `PostBatchProjectV2` model.",
      "properties": {
        "name": {
          "description": "name of the project",
          "title": "Name",
          "type": "string"
        },
        "color": {
          "anyOf": [
            {
              "format": "color",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "color of project, eg. '#F18181'",
          "title": "Color"
        },
        "group_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ID of the project group to add the project to",
          "title": "Group Id"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ID of the project to create",
          "title": "Id"
        },
        "kind": {
          "anyOf": [
            {
              "enum": [
                "TASK",
                "NOTE"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "\"TASK\" or \"NOTE\"",
          "title": "Kind"
        },
        "view_mode": {
          "anyOf": [
            {
              "enum": [
                "list",
                "kanban",
                "timeline"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "view mode, \"list\", \"kanban\", \"timeline\"",
          "title": "View Mode"
        },
        "sort_order": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sort Order"
        }
      },
      "required": [
        "name"
      ],
      "title": "CreateProjectV2",
      "type": "object"
    },
    "UpdateProjectV2": {
      "additionalProperties": false,
      "description": "Model for updating a project via the V2 API.\n\nThis model is used to update a project via the V2 API. It mostly maps to the\n[update project](https://developer.ticktick.com/docs#/openapi?id=update-project)\ndocumentation in the API docs. The main differences are the addition of the `id`\nand `group_id` fields. This is used in the `PostBatchProjectV2` model.",
      "properties": {
        "id": {
          "description": "ID of the project to update",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "description": "name of the project, must be set even on update",
          "title": "Name",
          "type": "string"
        },
        "color": {
          "anyOf": [
            {
              "format": "color",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "color of project, eg. '#F18181'",
          "title": "Color"
        },
        "group_id": {
          "anyOf": [
            {
              "const": "NONE",
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ID of the project group to move the project to, `\"NONE\"` to actively be ungrouped, `None` to be set to the group it was in before",
          "title": "Group Id"
        },
        "kind": {
          "anyOf": [
            {
              "enum": [
                "TASK",
                "NOTE"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "\"TASK\" or \"NOTE\"",
          "title": "Kind"
        },
        "view_mode": {
          "anyOf": [
            {
              "enum": [
                "list",
                "kanban",
                "timeline"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "view mode, \"list\", \"kanban\", \"timeline\"",
          "title": "View Mode"
        },
        "sort_order": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sort Order"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "title": "UpdateProjectV2",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Model for batch project operations via the V2 API.\n\nThis model is used to create, update, and delete projects in bulk against the V2 API\nendpoint `POST /batch/project`.",
  "properties": {
    "add": {
      "default": [],
      "description": "List of projects to add",
      "items": {
        "$ref": "#/$defs/CreateProjectV2"
      },
      "title": "Add",
      "type": "array"
    },
    "delete": {
      "default": [],
      "description": "List of project IDs to delete",
      "items": {
        "type": "string"
      },
      "title": "Delete",
      "type": "array"
    },
    "update": {
      "default": [],
      "description": "List of projects to update",
      "items": {
        "$ref": "#/$defs/UpdateProjectV2"
      },
      "title": "Update",
      "type": "array"
    }
  },
  "title": "PostBatchProjectV2",
  "type": "object"
}

Fields:

Validators:

add pydantic-field #

add: list[CreateProjectV2] = []

List of projects to add

delete pydantic-field #

delete: list[ObjectId] = []

List of project IDs to delete

update pydantic-field #

update: list[UpdateProjectV2] = []

List of projects to update

empty_str_to_none pydantic-validator #

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name Type Description Default
v Any

The value to validate.

 required

Returns:

Name Type Description
Any Any

The input value if it is not an empty string, otherwise None.
Source code in src/pyticktick/models/v2/models.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v

override_forbid_extra_message_injector pydantic-validator #

override_forbid_extra_message_injector(
    data: Any,
    handler: ModelWrapValidatorHandler[BaseModelV2],
) -> BaseModelV2

Provide a better error message for extra fields.

The TickTick V2 API is unofficial and may change without notice. As such, the models may not always be up to date with the API. This validator catches the extra_forbidden errors and provides a more informative error message, including a link to the documentation on how to override the extra_forbidden behavior if needed.

Parameters:

Name Type Description Default
data Any

The input data to validate.

 required
handler ModelWrapValidatorHandler[BaseModelV2]

The handler to call the next validator in the chain.

 required

Raises:

Type Description
ValidationError

If the pydantic model fails validation for any reason.

Returns:

Name Type Description
BaseModelV2 BaseModelV2

The validated model instance.
Source code in src/pyticktick/models/v2/models.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@model_validator(mode="wrap")
@classmethod
def override_forbid_extra_message_injector(
    cls,
    data: Any,
    handler: ModelWrapValidatorHandler[BaseModelV2],
) -> BaseModelV2:
    """Provide a better error message for extra fields.

    The TickTick V2 API is unofficial and may change without notice. As such, the
    models may not always be up to date with the API. This validator catches the
    `extra_forbidden` errors and provides a more informative error message,
    including a link to the documentation on how to override the `extra_forbidden`
    behavior if needed.

    Args:
        data (Any): The input data to validate.
        handler (ModelWrapValidatorHandler[BaseModelV2]): The handler to call the
            next validator in the chain.

    Raises:
        ValidationError: If the pydantic model fails validation for any reason.

    Returns:
        BaseModelV2: The validated model instance.
    """  # noqa: DOC501, DOC502 # ruff thinks `from_exception_data` should be raised instead of `ValidationError`
    try:
        return handler(data)
    except ValidationError as e:
        errors = []
        for error_dict in e.errors():
            if error_dict.get("type") in (
                "extra_forbidden",
                "custom_pyticktick_extra_forbidden",
            ):
                _type: str | PydanticCustomError = PydanticCustomError(
                    "custom_pyticktick_extra_forbidden",
                    f"Extra inputs are not permitted by default for `{cls.__name__}`. Please set `override_forbid_extra` to `True` if you believe the TickTick API has diverged from the model. See https://pyticktick.pretzer.io/guides/settings/overriding_models_that_forbid_extra_fields/ for more information.",  # pyright: ignore[reportArgumentType] # ty: ignore[invalid-argument-type]
                )
            else:
                _type = error_dict["type"]

            init_error_details: InitErrorDetails = {
                "type": _type,
                "input": error_dict["input"],
            }
            if "loc" in error_dict:
                init_error_details["loc"] = error_dict["loc"]
            if "ctx" in error_dict:
                init_error_details["ctx"] = error_dict["ctx"]

            errors.append(init_error_details)

        raise ValidationError.from_exception_data(e.title, errors) from e

UpdateProjectV2 pydantic-model #

Bases: BaseModelV2

Model for updating a project via the V2 API.

This model is used to update a project via the V2 API. It mostly maps to the update project documentation in the API docs. The main differences are the addition of the id and group_id fields. This is used in the PostBatchProjectV2 model.

Show JSON schema: 
{
  "additionalProperties": false,
  "description": "Model for updating a project via the V2 API.\n\nThis model is used to update a project via the V2 API. It mostly maps to the\n[update project](https://developer.ticktick.com/docs#/openapi?id=update-project)\ndocumentation in the API docs. The main differences are the addition of the `id`\nand `group_id` fields. This is used in the `PostBatchProjectV2` model.",
  "properties": {
    "id": {
      "description": "ID of the project to update",
      "title": "Id",
      "type": "string"
    },
    "name": {
      "description": "name of the project, must be set even on update",
      "title": "Name",
      "type": "string"
    },
    "color": {
      "anyOf": [
        {
          "format": "color",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "color of project, eg. '#F18181'",
      "title": "Color"
    },
    "group_id": {
      "anyOf": [
        {
          "const": "NONE",
          "type": "string"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "ID of the project group to move the project to, `\"NONE\"` to actively be ungrouped, `None` to be set to the group it was in before",
      "title": "Group Id"
    },
    "kind": {
      "anyOf": [
        {
          "enum": [
            "TASK",
            "NOTE"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "\"TASK\" or \"NOTE\"",
      "title": "Kind"
    },
    "view_mode": {
      "anyOf": [
        {
          "enum": [
            "list",
            "kanban",
            "timeline"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "view mode, \"list\", \"kanban\", \"timeline\"",
      "title": "View Mode"
    },
    "sort_order": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sort Order"
    }
  },
  "required": [
    "id",
    "name"
  ],
  "title": "UpdateProjectV2",
  "type": "object"
}

Fields:

Validators:

color pydantic-field #

color: Color | None = None

color of project, eg. '#F18181'

group_id pydantic-field #

group_id: Literal['NONE'] | None | ObjectId = None

ID of the project group to move the project to, "NONE" to actively be ungrouped, None to be set to the group it was in before

id pydantic-field #

id: ObjectId

ID of the project to update

kind pydantic-field #

kind: Literal['TASK', 'NOTE'] | None = None

"TASK" or "NOTE"

name pydantic-field #

name: str

name of the project, must be set even on update

view_mode pydantic-field #

view_mode: Literal["list", "kanban", "timeline"] | None = (
    None
)

view mode, "list", "kanban", "timeline"

empty_str_to_none pydantic-validator #

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name Type Description Default
v Any

The value to validate.

 required

Returns:

Name Type Description
Any Any

The input value if it is not an empty string, otherwise None.
Source code in src/pyticktick/models/v2/models.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v

override_forbid_extra_message_injector pydantic-validator #

override_forbid_extra_message_injector(
    data: Any,
    handler: ModelWrapValidatorHandler[BaseModelV2],
) -> BaseModelV2

Provide a better error message for extra fields.

The TickTick V2 API is unofficial and may change without notice. As such, the models may not always be up to date with the API. This validator catches the extra_forbidden errors and provides a more informative error message, including a link to the documentation on how to override the extra_forbidden behavior if needed.

Parameters:

Name Type Description Default
data Any

The input data to validate.

 required
handler ModelWrapValidatorHandler[BaseModelV2]

The handler to call the next validator in the chain.

 required

Raises:

Type Description
ValidationError

If the pydantic model fails validation for any reason.

Returns:

Name Type Description
BaseModelV2 BaseModelV2

The validated model instance.
Source code in src/pyticktick/models/v2/models.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@model_validator(mode="wrap")
@classmethod
def override_forbid_extra_message_injector(
    cls,
    data: Any,
    handler: ModelWrapValidatorHandler[BaseModelV2],
) -> BaseModelV2:
    """Provide a better error message for extra fields.

    The TickTick V2 API is unofficial and may change without notice. As such, the
    models may not always be up to date with the API. This validator catches the
    `extra_forbidden` errors and provides a more informative error message,
    including a link to the documentation on how to override the `extra_forbidden`
    behavior if needed.

    Args:
        data (Any): The input data to validate.
        handler (ModelWrapValidatorHandler[BaseModelV2]): The handler to call the
            next validator in the chain.

    Raises:
        ValidationError: If the pydantic model fails validation for any reason.

    Returns:
        BaseModelV2: The validated model instance.
    """  # noqa: DOC501, DOC502 # ruff thinks `from_exception_data` should be raised instead of `ValidationError`
    try:
        return handler(data)
    except ValidationError as e:
        errors = []
        for error_dict in e.errors():
            if error_dict.get("type") in (
                "extra_forbidden",
                "custom_pyticktick_extra_forbidden",
            ):
                _type: str | PydanticCustomError = PydanticCustomError(
                    "custom_pyticktick_extra_forbidden",
                    f"Extra inputs are not permitted by default for `{cls.__name__}`. Please set `override_forbid_extra` to `True` if you believe the TickTick API has diverged from the model. See https://pyticktick.pretzer.io/guides/settings/overriding_models_that_forbid_extra_fields/ for more information.",  # pyright: ignore[reportArgumentType] # ty: ignore[invalid-argument-type]
                )
            else:
                _type = error_dict["type"]

            init_error_details: InitErrorDetails = {
                "type": _type,
                "input": error_dict["input"],
            }
            if "loc" in error_dict:
                init_error_details["loc"] = error_dict["loc"]
            if "ctx" in error_dict:
                init_error_details["ctx"] = error_dict["ctx"]

            errors.append(init_error_details)

        raise ValidationError.from_exception_data(e.title, errors) from e