Arkindex API Client
===================

:ref:`genindex` - :ref:`modindex` - :ref:`search`

.. toctree::
   :maxdepth: 2
   :caption: Contents:

``arkindex-client`` provides an API client and a command-line tool to interact with Arkindex servers.

Command-line tool
-----------------

Once installed, a ``arkindex`` script should be in your PATH. Two commands are currently available:

``arkindex login``
   Login to an Arkindex server with an email and a password, then save API tokens to a configuration file.
``arkindex upload``
   Upload and import files into an Arkindex server.

Main options
^^^^^^^^^^^^

These options are available for all ``arkindex`` subcommands and should be applied before the subcommand name, like so::

   arkindex --no-verify-ssl login

``--profile [name]``
   Name of the configuration profile to use. Defaults to ``default``.
``--verify-ssl / --no-verify-ssl``
   Enable or disable SSL certificate checks (enabled by default).
   Useful when the Arkindex server uses self-signed certificates.

Login
^^^^^

To perform authenticated requests against the API, the client must obtain a user's API token.
The ``arkindex login`` commands allows to log in to an Arkindex server, fetch the API token and save it to the configuration file.

``--host [name]``
   Host name of the Arkindex server. Defaults to ``arkindex.teklia.com``.
``--email``
   Email to use for logging in. If this setting is omitted, a prompt will be shown asking for the email.

The script will ask for your password, then login and save tokens.

Upload
^^^^^^

The ``upload`` subcommand allows to upload files and optionally start import processes in batch::

   arkindex upload --mode images Himanis ./himanis/*.jpg

This example will try to find a corpus that contains ``Himanis`` in its name, then upload all ``.jpg`` files
from the ``himanis`` folder and start an import process for each file automatically.

Options
"""""""

::

   arkindex upload [--mode pdf|images] [--start/--no-start] [corpus] [files]

``corpus``
   UUID or part of the name of a corpus to upload files to.
   If a name is specified, corpus name matching is done in a case-insensitive manner.
   If there are multiple matching corpora for a name, the matching corpora names are printed and the script exits.
``files``
   Paths of all files to upload/import. Compatible shells may allow the use of wildcards (``*`` or ``**``) to specify multiple paths at once.
``--start / --no-start``
   Start (or do not start) an import process for each uploaded file. Enabled by default.
   This does not start a single import process for all files.
``--mode pdf / --mode images``
   Set the import process mode. Defaults to ``pdf`` and is ignored if ``--no-start`` is specified.

Package reference
-----------------

API client
^^^^^^^^^^

.. autoclass:: arkindex.client.ArkindexAPI
   :members:

Exceptions
^^^^^^^^^^

.. autoclass:: arkindex.client.ArkindexAPIError
   :members:

Helper classes
^^^^^^^^^^^^^^

.. autoclass:: arkindex.client.ResponsePaginator
   :members:

.. autoclass:: arkindex.conf.LocalConf
   :members: