.. _api:

API
===
smartRender contains an API to call it from outside of smartRender.
The following lists all available API functionality and gives some usage
examples with some expected example output.

.. note::
    The API calls require the Nuke module since processing itself happens
    via Nuke.

list_jobs
---------
List IDs of all jobs in the render queue.

**Args:**
    - **status** (str): The status to display jobs for. Choose from one of: ``["all", "waiting", "paused", "canceled", "error", "finished"]``. Default: ``'all'``.

**Returns:**
    :obj:`list` of :obj:`str`: Sequence of job ids in the queue.

.. raw:: python

>>> from smartRender import api
>>> api.list_jobs()
['1719778039_41d1107a', '1719777998_242674b0', '1719777923_63c42a2b', '1719777647_70102203', '1719777598_7da63303']

get_job_info
------------
Show all job info for the given job ID.

**Args:**
    - **job_id** (str): The ID of the job to show all info for.

**Returns:**
    **dict**: Mapping of job data for the given job.

.. raw:: python

>>> from smartRender import api
>>> api.get_job_info("1719778039_41d1107a")
# Shows a dict with all information about that job.

get_job_log_data
----------------
Show render log data for the given job.

**Args:**
    - **job_id** (str): The ID of the job to show render log data for.
    - **filter** (str, optional): Filter job log to show only specific log
        events.
        Choose from:
            - "job: all" -> Show all output.
            - "job: error" -> Show only error messages.
            - "job: info" -> Show all info messages.
            - "job: done" -> Show all render finished messages.

**Returns:**
    str: The job log data of the given job.

.. raw:: python

>>> from smartRender import api
>>> api.get_job_log_data("1719778039_41d1107a")
# Shows all job log data for that job.

get_job_terminal_log
--------------------
Load terminal input or output log and return its content as a String.

**Args:**
    - **job_id** (str): Unique id of job to load terminal output file from.
    - **mode** (str): Which file to choose: 'input' or 'output'.

**Returns:**
    str: File content of the terminal output file.

.. raw:: python

>>> from smartRender import api
>>> api.get_job_terminal_log("1719778039_41d1107a")

add_job
-------
Add job on top of jobs queue xml file.

Args:
    - **workingfile_path** (str): Absolute path of working file to render.
    - **write_name** (str): Name of write node to process.
    - **render_start** (int): Start frame to process.
    - **render_end** (int): End frame to process.
    - **render_step** (int): Incremental steps. Use 1 to render every frame, 2 to render every other frame, etc.
    - **overwrite** (Bool): If True overwrite existing frames. If False skip existing frames.
    - **width** (int): The width to render.
    - **height** (int): The height to render.
    - **transcode_template** (str, optional): Name of the transcode template to use for transcoding once the job has finished. A template with that name must exist. Leave empty if no transcoding is required.
    - **views** (str, optional): Views to process. standard view: "Main".
    - **chunk_size** (int, optional): The number of frames to render per chunk.
    - **framelist** (:obj:`list` of :obj:`str`, optional): If given then render only these frames, not the whole given render start and render end. This is useful for to re-render e.g. just outdated cache frames (smartCache).
    - **job_id** (str, optional): If given then use this id as the internal job id to refer back to it in the future. If not set then smartRender will generate a new unique render id.
    - **silent** (bool, optional): If True show a 'render notification' window once the rendering has finished that lets the user trigger common functionality (reveal render directory, copy path, etc.). If False then don't show this dialog.

- **Returns:** str: The unique job ID of the job that was added to the queue.

.. raw:: python

>>> from smartRender import api
>>> api.add_job(
...     "/path/to/workfile.nk",
...     "Write1",
...     1001,
...     1030,
...     1,
...     True,
...     1920,
...     1080,
... )
1719782468_9ec920f1

update_job
----------
Update given key-value pair in given job ID.

**Args:**
    - **job_id** (str): The ID of the job to update.
    - **key** (str): The name of the key to update.
    - **value** (any): The new value to use.

**Returns:**
    bool: True when the job id and key was found and successfully updated, False otherwise.

.. raw:: python

>>> from smartRender import api

Update render end

>>> api.update_job("1719778039_41d1107a", "render_end", 1020)

Update chunk size

>>> api.update_job("1719778039_41d1107a", "chunk_size", 10)

View a job in your jobs.xml to see a complete list of all offered job settings.

remove_job
----------
Remove the job with the given ID from the job queue.

**Args:**
    - **job_id** (str): The ID of the job to remove from the queue.

.. raw:: python

>>> from smartRender import api
>>> api.remove_job("1719778039_41d1107a")

process_job
-----------
Render a job with the given ID.

**Args:**
    - **job_id** (str): The ID of the job to render.

>>> from smartRender import api
>>> api.process_job("1719778039_41d1107a")