[bug] documents.import_ function signature requires return_id or return_doc when neither is required

[rchui]

The function signature for documents.import_ is incorrect. The function signature requires that either return_id or return_doc be passed as a parameter as part one of:

DocumentImportParameters: typing.TypeAlias = typing.Union[
    DocumentImportParametersReturnId,
    DocumentImportParametersReturnDoc,
    DocumentImportParametersReturnDocAndId,
]

but the documentation does not require either. you should just be able to just pass the import action:

documents = [{
  'id': '124',
  'company_name': 'Stark Industries',
  'num_employees': 5215,
  'country': 'USA'
}]

# IMPORTANT: Be sure to increase connection_timeout_seconds to at least 5 minutes or more for imports,
#  when instantiating the client

client.collections['companies'].documents.import_(documents, {'action': 'create'})

https://typesense.org/docs/28.0/api/documents.html#index-multiple-documents

[tharropoulos]

The base signature of the import_ function is this:

    def import_(
        self,
        documents: typing.Union[bytes, str, typing.List[TDoc]],
        import_parameters: _ImportParameters = None,
        batch_size: typing.Union[int, None] = None,
    ) -> typing.Union[ImportResponse[TDoc], str]:

where _ImportParameters is:

_ImportParameters = typing.Union[
    DocumentImportParameters,
    None,
]

And DocumentImportParameters is a union of ReturnDoc, ReturnDocAndId and ReturnId:

DocumentImportParameters: typing.TypeAlias = typing.Union[
    DocumentImportParametersReturnId,
    DocumentImportParametersReturnDoc,
    DocumentImportParametersReturnDocAndId,
]
"""Set of all possible parameters for importing documents."""

Which all extend DocumentWriteParameters:

class DocumentWriteParameters(DirtyValuesParameters):
    """
    Parameters for writing documents.

    Attributes:
      action (str): [Action](https://typesense.org/docs/26.0/api/documents.html#action-modes-create-upsert-update-emplace) to perform on the document.

        - `create`: Creates a new document. Fails if a document with the same id
          already exists (default).
        - `upsert`: Creates a new document or updates an existing document if a
          document with the same id already exists. Requires the whole document to be sent.
          For partial updates, use the update action below.
        - `update`: Updates an existing document. Fails if a document with the
          given id does not exist. You can send a partial document containing only the
          fields that are to be updated.
        - `emplace`: Creates a new document or updates an existing document if a
          document with the same id already exists. You can send either the whole document
          or a partial document for update.

      dirty_values (str): [Handling of dirty values](https://typesense.org/docs/26.0/api/documents.html#dealing-with-dirty-data) in the document.

        - `coerce_or_reject`: Attempt coercion of the field's value to previously inferred type.
          If coercion fails, reject the write outright with an error message.
        - `coerce_or_drop`: Attempt coercion of the field's value to previously inferred type.
          If coercion fails, drop the particular field and index the rest of the document.
        - `drop`: Drop the particular field and index the rest of the document.
        - `reject`: Reject the write outright with an error message.
    """

    action: typing.NotRequired[typing.Literal["create", "update", "upsert", "emplace"]]

The overload singatures take care of typing on that.

Is mypy erroring on your side, or was this an observation that's outside of the type checker?

[rchui]

@tharropoulos it doesn't seem like DocumentWriteParameters is part of the type union? I guess I never found the base document so it's possible the parent types also work.

[tharropoulos]

@tharropoulos it doesn't seem like DocumentWriteParameters is part of the type union?

Added them here