Find #ghostscript on Discord

# Introduction

The Python API is provided by the file gsapi.py - this is the binding to the Ghostscript C library.

In the GhostPDL repository sample Python examples can be found in `/demos/python/examples.py`.

# Platform & setup

Ghostscript should be built as a shared library for your platform.

See Building Ghostscript.

## Specifying the Ghostscript shared library

Two environmental variables can be used to specify where to find the Ghostscript shared library.

`GSAPI_LIB` sets the exact path of the Ghostscript shared library, otherwise, `GSAPI_LIBDIR` sets the directory containing the Ghostscript shared library.

If neither is defined we will use the OS’s default location(s) for shared libraries.

If `GSAPI_LIB` is not defined, the leafname of the shared library is inferred from the OS type:

Platform | Shared library file
--- | ---
Windows | `gsdll64.dll`
MacOS | `libgs.dylib`
Linux / OpenBSD | `libgs.so`

## API test

The `gsapi.py` file that provides the Python bindings can also be used to test the bindings, by running it directly.

Assuming that your Ghostscript library has successfully been created, then from the root of your `ghostpdl` repository checkout do the following:

Windows

> Run `gsapi.py` as a test script in a `cmd.exe` window:

>     set GSAPI_LIBDIR=debugbin&& python ./demos/python/gsapi.py

> Run `gsapi.py` as a test script in a `PowerShell` window:

>     cmd /C "set GSAPI_LIBDIR=debugbin&& python ./demos/python/gsapi.py"

Linux/OpenBSD/MacOS

> Run `gsapi.py` as a test script:

>     GSAPI_LIBDIR=sodebugbin ./demos/python/gsapi.py

Note

If there are no errors then this will have validated that the Ghostscript library is present & operational.

# The gsapi Python module

Assuming that the above platform & setup has been completed, then `gsapi` should be imported into your own Python scripts for API usage.

- Implemented using Python’s `ctypes` module.

- All functions have the same name as the C function that they wrap.

- Functions raise a `GSError` exception if the underlying function returned a negative error code.

- Functions that don’t have out-params return `None`. Out-params are returned directly (using tuples if there are more than one).

## `gsapi_revision()`

Returns a `gsapi_revision_t`.

This method returns the revision numbers and strings of the Ghostscript interpreter library; you should call it before any other interpreter library functions to make sure that the correct version of the Ghostscript interpreter has been loaded.

Sample code:

    version_info = gsapi.gsapi_revision()
    print(version_info)

C code reference: gsapi_revision

## `gsapi_new_instance(caller_handle)`

Returns a new instance of Ghostscript to be used with other gsapi_*() functions.

Parameters:

`caller_handle`

  Typically unused, but is passed to callbacks e.g. via gsapi_set_stdio(). Must be convertible to a `C void*`, so `None` or an `integer` is ok but other types such as strings will fail.

Sample code:

    instance = gsapi.gsapi_new_instance(1)

C code reference: gsapi_new_instance

## `gsapi_delete_instance(instance)`

Destroy an instance of Ghostscript. Before you call this, Ghostscript should ensure to have finished any processes.

Parameters:

`instance`

  Your instance of Ghostscript.

Sample code:

    gsapi.gsapi_delete_instance(instance)

C code reference: gsapi_delete_instance

## `gsapi_set_stdio(instance, stdin_fn, stdout_fn, stderr_fn)`

Set the callback functions for `stdio`, together with the handle to use in the callback functions.

Parameters:

`instance`

  Your instance of Ghostscript.

`stdin_fn`

  If not `None`, will be called with:

  - `(caller_handle, text, len_)`:

      - `caller_handle`: As passed originally to `gsapi_new_instance()`.

      - `text`: A `ctypes.LP_c_char` of length `len_`.

`stdout_fn` , `stderr_fn`

  If not `None`, called with:

  - `(caller_handle, text)`:

      - `caller_handle`: As passed originally to `gsapi_new_instance()`.

      - `text`: A Python bytes object.

Should return the number of bytes of text that they handled; for convenience `None` is converted to `len(text)`.

Sample code:

    def stdout_fn(caller_handle, bytes_):
       sys.stdout.write(bytes_.decode('latin-1'))

    gsapi.gsapi_set_stdio(instance, None, stdout_fn, None)
    print('gsapi_set_stdio() ok.')

C code reference: gsapi_set_stdio

## `gsapi_set_poll(instance, poll_fn)`

Set the callback function for polling.

Parameters:

`instance`

  Your instance of Ghostscript.

`poll_fn`

  Will be called with `caller_handle` as passed to gsapi_new_instance.

Sample code:

    def poll_fn(caller_handle, bytes_):
        sys.stdout.write(bytes_.decode('latin-1'))

    gsapi.gsapi_set_poll(instance, poll_fn)
    print('gsapi_set_poll() ok.')

C code reference: gsapi_set_poll

## `gsapi_set_display_callback(instance, callback)`

Sets the display callback.

Parameters:

`instance`

  Your instance of Ghostscript.

`callback`

  Must be a `display_callback` instance.

Sample code:

    d = display_callback()
    gsapi.gsapi_set_display_callback(instance, d)
    print('gsapi_set_display_callback() ok.')

C code reference: gsapi_set_display_callback

## `gsapi_set_arg_encoding(instance, encoding)`

Set the encoding used for the interpretation of all subsequent arguments supplied via the GhostAPI interface on this instance. By default we expect args to be in encoding `0` (the ‘local’ encoding for this OS). On Windows this means “the currently selected codepage”. On Linux this typically means utf8. This means that omitting to call this function will leave Ghostscript running exactly as it always has.

This must be called after gsapi_new_instance and before gsapi_init_with_args.

Parameters:

`instance`

  Your instance of Ghostscript.

`encoding`

  Encoding must be one of:

  Encoding enum | Value
  --- | ---
  `GS_ARG_ENCODING_LOCAL` | 0
  `GS_ARG_ENCODING_UTF8` | 1
  `GS_ARG_ENCODING_UTF16LE` | 2

Sample code:

    gsapi.gsapi_set_arg_encoding(instance, gsapi.GS_ARG_ENCODING_UTF8)

Note

Please note that use of the ‘local’ encoding (`GS_ARG_ENCODING_LOCAL`) is now deprecated and should be avoided in new code.

C code reference: gsapi_set_arg_encoding

## `gsapi_set_default_device_list(instance, list_)`

Set the string containing the list of default device names, for example “display x11alpha x11 bbox”. Allows the calling application to influence which device(s) Ghostscript will try, in order, in its selection of the default device. This must be called after gsapi_new_instance and before gsapi_init_with_args.

Parameters:

`instance`

  Your instance of Ghostscript.

`list_`

  A string of device names.

Sample code:

    gsapi.gsapi_set_default_device_list(instance, 'bmp256 bmp32b bmpgray cdeskjet cdj1600 cdj500')

C code reference: gsapi_set_default_device_list

## `gsapi_get_default_device_list(instance)`

Returns a string containing the list of default device names. This must be called after gsapi_new_instance and before gsapi_init_with_args.

Parameters:

`instance`

  Your instance of Ghostscript.

Sample code:

    device_list = gsapi.gsapi_get_default_device_list(instance)
    print(device_list)

C code reference: gsapi_get_default_device_list

## `gsapi_init_with_args(instance, args)`

To initialise the interpreter, pass your `instance` of Ghostscript and your argument variables with `args`.

Parameters:

`instance`

  Your instance of Ghostscript.

`args`

  A list/tuple of strings.

Sample code:

    in_filename = 'tiger.eps'
    out_filename = 'tiger.pdf'
    params = ['gs', '-dNOPAUSE', '-dBATCH', '-sDEVICE=pdfwrite',
              '-o', out_filename, '-f', in_filename]
    gsapi.gsapi_init_with_args(instance, params)

C code reference: gsapi_init_with_args

## `gsapi_run_*`

There is a 64 KB length limit on any buffer submitted to a gsapi_run_* function for processing. If you have more than 65535 bytes of input then you must split it into smaller pieces and submit each in a separate gsapi_run_string_continue call.

On success (underlying C function’s return value is `>=0`), these functions return the underlying C function’s `exit_code` out-parameter (and the return value is discarded). Otherwise they raise a `GSError` in the usual way (and the underlying `exit_code` out-parameter is discarded).

For full details on these return codes please see The C API return codes.

Note

User errors parameter explained

The `user_errors` argument is normally set to zero to indicate that errors should be handled through the normal mechanisms within the interpreted code. If set to a negative value, the functions will return an error code directly to the caller, bypassing the interpreted language. The interpreted language’s error handler is bypassed, regardless of `user_errors` parameter, for the `gs_error_interrupt` generated when the polling callback returns a negative value. A positive `user_errors` is treated the same as zero.

C code reference: gsapi_run_*

## `gsapi_run_string_begin(instance, user_errors)`

Starts a `run_string_` operation.

Parameters:

`instance`

  Your instance of Ghostscript.

`user_errors`

  An `int`, for more see: User errors parameter explained.

Sample code:

    exitcode = gsapi.gsapi_run_string_begin(instance, 0)

C code reference: gsapi_run_*

## `gsapi_run_string_continue(instance, str_, user_errors)`

Processes file byte data (`str_`) to feed as chunks into Ghostscript. This method should typically be called within a buffer context.

Note

An exception is not raised for the `gs_error_NeedInput` return code.

Parameters:

`instance`

  Your instance of Ghostscript.

`str_`

  Should be either a Python string or a bytes object. If the former, it is converted into a bytes object using utf-8 encoding.

`user_errors`

  An `int`, for more see: User errors parameter explained.

Sample code:

    exitcode = gsapi.gsapi_run_string_continue(instance, data, 0)

Note

For the return code, we don’t raise an exception for `gs_error_NeedInput`.

C code reference: gsapi_run_*

## `gsapi_run_string_with_length(instance, str_, length, user_errors)`

Processes file byte data (`str_`) to feed into Ghostscript when the length is known and the file byte data is immediately available.

Parameters:

`instance`

  Your instance of Ghostscript.

`str_`

  Should be either a Python string or a bytes object. If the former, it is converted into a bytes object using utf-8 encoding.

`length`

  An `int` representing the length of `str_`.

`user_errors`

  An `int`, for more see: User errors parameter explained.

Sample code:

    gsapi.gsapi_run_string_with_length(instance,"hello",5,0)

Note

If using this method then ensure that the file byte data will fit into a single (<64k) buffer.

C code reference: gsapi_run_*

## `gsapi_run_string(instance, str_, user_errors)`

Processes file byte data (`str_`) to feed into Ghostscript.

Parameters:

`instance`

  Your instance of Ghostscript.

`str_`

  Should be either a Python string or a bytes object. If the former, it is converted into a bytes object using utf-8 encoding.

`user_errors`

  An `int`, for more see: User errors parameter explained.

Sample code:

    gsapi.gsapi_run_string(instance,"hello",0)

Note

This method can only work on a standard, null terminated C string.

C code reference: gsapi_run_*

## `gsapi_run_string_end(instance, user_errors)`

Ends a `run_string_` operation.

Parameters:

`instance`

  Your instance of Ghostscript.

`user_errors`

  An `int`, for more see: User errors parameter explained.

Sample code:

    exitcode = gsapi.gsapi_run_string_end(instance, 0)

C code reference: gsapi_run_*

## `gsapi_run_file(instance, filename, user_errors)`

Runs a file through Ghostscript.

Parameters:

`instance`

  Your instance of Ghostscript.

`filename`

  String representing file name.

`user_errors`

  An `int`, for more see: User errors parameter explained.

Sample code:

    in_filename = 'tiger.eps'
    gsapi.gsapi_run_file(instance, in_filename, 0)

Note

This will process the supplied input file with any previously supplied argument parameters.

C code reference: gsapi_run_*

## `gsapi_exit(instance)`

Returns a successful exit code `0`, or raises a `GSError` exception on error.

Exit the interpreter. This must be called on shutdown if gsapi_init_with_args has been called, and just before gsapi_delete_instance.

Parameters:

`instance`

  Your instance of Ghostscript.

Sample code:

    gsapi.gsapi_exit(instance)

C code reference: gsapi_exit

## `gsapi_set_param(instance, param, value, type_=None)`

Sets a parameter.

We behave much like the underlying `gsapi_set_param()` C function, except that we also support automatic inference of type `type_` arg by looking at the type of `value`.

Parameters:

`instance`

  Your instance of Ghostscript.

`param`

  Name of parameter, either a `bytes` or a `str`; if `str` it is encoded using `latin-1`.

`value`

  A `bool`, `int`, `float`, `bytes` or `str`. If `str`, it is encoded into a `bytes` using `utf-8`.

`type_`

  If `type_` is not `None`, `value` must be convertible to the Python type implied by `type_`:

  `type_` | Python type(s)
  --- | ---
  `gs_spt_null` | [Ignored]
  `gs_spt_bool` | bool
  `gs_spt_int` | int
  `gs_spt_float` | float
  `gs_spt_name` | [Error]
  `gs_spt_string` | (bytes, str)
  `gs_spt_long` | int
  `gs_spt_i64` | int
  `gs_spt_size_t` | int
  `gs_spt_parsed` | (bytes, str)
  `gs_spt_more_to_come` | (bytes, str)

  An exception is raised if `type_` is an integer type and `value` is outside its range.

  If `type_` is `None`, we choose something suitable for type of `value`:

  Python type of `value` | `type_`
  --- | ---
  bool | `gs_spt_bool`
  int | `gs_spt_i64`
  float | `gs_spt_float`
  bytes | `gs_spt_parsed`
  str | `gs_spt_parsed` (encoded with utf-8)

  If value is `None`, we use `gs_spt_null`.

  Otherwise `type_` must be a `gs_spt_*` except for `gs_spt_invalid` and `gs_spt_name` (we don’t allow `psapi_spt_name` because the underlying C does not copy the string, so cannot be safely used from Python).

Sample code:

    set_margins = gsapi.gsapi_set_param(instance, "Margins", "[10 10]")

C code reference: gsapi_set_param

## `gsapi_get_param(instance, param, type_=None, encoding=None)`

Returns value of specified parameter, or `None` if parameter `type` is `gs_spt_null`.

Parameters:

`instance`

  Your instance of Ghostscript.

`param`

  Name of parameter, either a `bytes` or `str`; if a `str` it is encoded using `latin-1`.

`type_`

  A `gs_spt_*` constant or `None`. If `None` we try each `gs_spt_*` until one succeeds; if none succeeds we raise the last error.

`encoding`

  Only affects string values. If `None` we return a `bytes` object, otherwise it should be the encoding to use to decode into a string, e.g. ‘utf-8’.

Sample code:

    get_margins = gsapi.gsapi_get_param(instance, "Margins")

C code reference: gsapi_get_param

## `gsapi_enumerate_params(instance)`

Enumerate the current parameters on the instance of Ghostscript.

Yields `(key, value)` for each `param`. `key` is decoded as `latin-1`.

Parameters:

`instance`

  Your instance of Ghostscript.

Sample code:

    for param, type_ in gsapi.gsapi_enumerate_params(instance):
        val = gsapi.gsapi_get_param(instance,param, encoding='utf-8')
        print('%-24s : %s' % (param, val))

C code reference: gsapi_enumerate_params

## `gsapi_add_control_path(instance, type_, path)`

Add a (case sensitive) path to one of the lists of permitted paths for file access.

Parameters:

`instance`

  Your instance of Ghostscript.

`type_`

  An `int` which must be one of:

  Enum | Value
  --- | ---
  `GS_PERMIT_FILE_READING` | 0
  `GS_PERMIT_FILE_WRITING` | 1
  `GS_PERMIT_FILE_CONTROL` | 2

`path`

  A string representing the file path.

Sample code:

    gsapi.gsapi_add_control_path(instance, gsapi.GS_PERMIT_FILE_READING, "/docs/secure/")

C code reference: gsapi_add_control_path

## `gsapi_remove_control_path(instance, type_, path)`

Remove a (case sensitive) path from one of the lists of permitted paths for file access.

Parameters:

`instance`

  Your instance of Ghostscript.

`type_`

  An int representing the permission type.

`path`

  A string representing the file path.

Sample code:

    gsapi.gsapi_remove_control_path(instance, gsapi.GS_PERMIT_FILE_READING, "/docs/secure/")

C code reference: gsapi_remove_control_path

## `gsapi_purge_control_paths(instance, type_)`

Clear all the paths from one of the lists of permitted paths for file access.

Parameters:

`instance`

  Your instance of Ghostscript.

`type_`

  An `int` representing the permission type.

Sample code:

    gsapi.gsapi_purge_control_paths(instance, gsapi.GS_PERMIT_FILE_READING)

C code reference: gsapi_purge_control_paths

## `gsapi_activate_path_control(instance, enable)`

Enable/Disable path control (i.e. whether paths are checked against permitted paths before access is granted).

Parameters:

`instance`

  Your instance of Ghostscript.

`enable`

  `bool` to enable/disable path control.

Sample code:

    gsapi.gsapi_activate_path_control(instance, true)

C code reference: gsapi_activate_path_control

## `gsapi_is_path_control_active(instance)`

Query whether path control is activated or not.

Parameters:

`instance`

  Your instance of Ghostscript.

Sample code:

    isActive = gsapi.gsapi_is_path_control_active(instance)

C code reference: gsapi_is_path_control_active