carbone-sdk

Carbone Python SDK

Generate Documents in Python: Seamless Integration with Carbone API.

About Carbone

Carbone is a document generator that utilizes Templates and JSON data to create a wide range of file formats, including PDF, DOCX, XLSX, ODT, PPTX, ODS, XML, CSV, and more. With Carbone, you can produce professional, high-quality, rich reports without limitations and streamline document creation processes across all industries:

• For Organizations: Effortlessly generate contracts, agreements, invoices, receipts, financial statements, marketing materials, employment contracts, NDAs, training manuals, and compliance documents.
• For Governments: Create legislation and regulations, policy documents, budget reports, permits and licenses, public records, certificates, audit reports, and health and safety regulations with ease.
• For Finance: Produce budget reports, tax returns, investment portfolios, loan agreements, audit reports, insurance policies, and financial forecasts efficiently.
• For Health: Generate medical records, prescriptions, medical certificates, lab reports, and health insurance claims seamlessly.

Learn more about Carbone and Supported files and features.

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 : 5)
csdk.set_api_version("5")
# 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
}

# Generate and return the document 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 -r requirements.txt

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!