Tag

pyticktick.models.v2.responses.tag

Response for a batch tag POST request 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
BatchTagRespV2	Model for the response of a batch tag request via the V2 API.

BatchTagRespV2 pydantic-model

Bases: BaseModelV2

Model for the response of a batch tag request via the V2 API.

Since tags do not have an id field, the id2etag and id2error fields return the name field as the key instead. Otherwise, the structure is the same as the BatchRespV2 model.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Model for the response of a batch tag request via the V2 API.\n\nSince tags do not have an `id` field, the `id2etag` and `id2error` fields return\nthe `name` field as the key instead. Otherwise, the structure is the same as the\n`BatchRespV2` model.",
  "properties": {
    "id2error": {
      "description": "Tag name to error message mapping",
      "patternProperties": {
        "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$": {
          "pattern": "^[a-z0-9]{8}$",
          "type": "string"
        }
      },
      "title": "Id2Error",
      "type": "object"
    },
    "id2etag": {
      "description": "Tag name to ETag mapping of objects that were successfully created / updated",
      "patternProperties": {
        "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$": {
          "pattern": "^[a-z0-9]{8}$",
          "type": "string"
        }
      },
      "title": "Id2Etag",
      "type": "object"
    }
  },
  "required": [
    "id2error",
    "id2etag"
  ],
  "title": "BatchTagRespV2",
  "type": "object"
}

Fields:

• id2error (dict[TagName, ETag])
• id2etag (dict[TagName, ETag])

Validators:

• empty_str_to_none
• override_forbid_extra_message_injector

etags property

etags: list[str]

List of all the ETags in the response.

id2error pydantic-field

id2error: dict[TagName, ETag]

Tag name to error message mapping

id2etag pydantic-field

id2etag: dict[TagName, ETag]

Tag name to ETag mapping of objects that were successfully created / updated

ids property

ids: list[str]

List of all the IDs in the response.

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

@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

@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