carboneio / carbone-sdk-python

The Python SDK to use Carbone Render easily

Carbone Render Python SDK

Python SDK to use Carbone Render easily.

About Carbone

Carbone is a powerful document generator (PDF, DOCX, XLSX, ODT, PPTX, ODS, XML, CSV...) using templates and JSON data. It is based on LibreOffice and can convert any document. It is also possible to convert HTML to PDF. Learn more about supported files and features.

🔖 API REFERENCE

Install

pip install carbone-sdk

Usage

You can copy and run the code bellow to try. Get your API token on your Carbone account: https://account.carbone.io/.

import carbone_sdk

# SDK constructor
# The access token can be passed as an argument to the constructor CarboneSDK
# Or by the environment variable "CARBONE_TOKEN", use the command "export CARBONE_TOKEN=secret-token"
csdk = carbone_sdk.CarboneSDK("secret-token")
# Set API version (default : 4)
csdk.set_api_version("4")
# Set API URL for Carbone On-Premise for example (default: "https://api.carbone.io")
csdk.set_api_url("https://api.carbone.io")

# The template ID, it could be an ODT, DOCX, PPTX, XLSX, ODS file, etc...
template_id = "template"
render_options = {
  # REQUIRED: the "data" object contains all the data to inject into the template
  "data": {
    "id": 42,
    "date": 1492012745,
    "company": {
        "name": "myCompany",
        "address": "here",
        "city": "Notfar",
        "postalCode": 123456
    },
    "customer": {
      "name":"myCustomer",
      "address":"there",
      "city":"Faraway",
      "postalCode":654321
    },
    "products":[
      {"name":"product 1","priceUnit":0.1,"quantity":10,"priceTotal":1}
    ],
    "total":140
  },
  # REQUIRED: the "convertTo" attribute defines the format to generate or convert
  "convertTo":"pdf"
  # All rendering options are available on the following API specification:
  # https://carbone.io/api-reference.html#pdf-export-filter-options
}

# Render and return the report as bytes and a unique report name
report_bytes, unique_report_name = csdk.render(template_id, render_options)
fd = open(unique_report_name, "wb")
fd.write(report_bytes)
fd.close()
# voila 🎉

Documentation

• API REFERENCE

Tests

Tests - Run with Makefile

Install the test packages:

$ make install

To run the tests:

$ make test

To uninstall the test packages:

$ make uninstall

Tests - Run manually

Install:

$ pip install pytest
$ pip install requests_mock

To run all the test (-v for verbose output):

$ pytest -s -v tests

To run a groupe of tests:

$ pytest -s -v ./tests/test_carbone_sdk.py::TestRender

To run a single test:

$ pytest -s -v ./tests/test_carbone_sdk.py::TestRender::test_render_a_report_error_file_missing

To run a single test with all the DEBUG:

$ pytest ./tests/test_carbone_sdk.py::TestRender::test_render_a_report_from_an_existing_template_id --log-cli-level=10

If you need to test the generation of templateId, you can use the nodejs main.js to test the sha256 generation.

$ node ./tests/main.js

👤 Author

• @steevepay

🤝 Contributing

Contributions, issues and feature requests are welcome!

Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

carbone-sdk-python's Issues

Carbone SDK throws UnexpectedToken exception for valid JSON

I am attempting to use the Carbone Python SDK to generate a report.

When I call csdk.render() with a valid template and valid JSON, it throws an error:

  File "/Users/mariekalb/.local/share/virtualenvs/generate-report-pMg8lfbh/lib/python3.10/site-packages/carbone_sdk/carbone_sdk.py", line 109, in render
    raise Exception('Carbone SDK render error: ' + resp['error'])
Exception: Carbone SDK render error: SyntaxError: Unexpected token " in JSON at position 0

I have double checked that the JSON is valid and have tried two different methods of passing in the JSON -- loading from a file, passing in a variable that contains the JSON. Neither of them work.

copy paste issue on render()

def render(self, file_or_template_id = None, json_data = None, payload = ""):
    if file_or_template_id is None:
      raise ValueError('Carbone SDK render error: argument is missing: file_or_template_id')
    if file_or_template_id is None:
      raise ValueError('Carbone SDK render error: argument is missing: json_data')

Should be checking json_data for the second check

Add automatic integration test

• Add a test.py file in this repo
• From carbone-ee repo, add a simple github CI, which install carbone-sdk-python and execute test.py

UnicodeDecodeError

Hello,

using pip install carbone-sdk under Windows Server 2019 with Python 3.11.0 produces following error:

Any ideas?

ACCESS-TOKEN?

Hi,

I'm going to try the carbone-sdk-python in my server, but I'm confused about the part "ACCESS-TOKEN".

Suppose I'm using Cabone in my server, why I still have to set up the ACCESS-TOKEN?

No support for on-prem hosting

URL is hardcoded to hit carbone.io