karrio-cli 2025.5.3

Command line interface for Karrio

Karrio CLI Tools

This folder contains CLI tools for the Karrio project.

Codegen

The codegen command provides utilities for code generation, particularly for transforming JSON schemas into Python code using jstruct.

Transform

The transform command converts Python code generated by quicktype (using dataclasses) into code that uses attrs and jstruct decorators.

# Transform from stdin to stdout
cat input.py | karrio codegen transform > output.py

# Transform from file to file
karrio codegen transform input.py output.py

# Transform from file to stdout
karrio codegen transform input.py

# Disable appending 'Type' to class names
karrio codegen transform input.py output.py --no-append-type-suffix

The transform command makes the following changes:

• Replaces from dataclasses import dataclass with explicit imports: import attr, import jstruct, import typing
• Removes any from typing import ... lines entirely
• Replaces @dataclass with @attr.s(auto_attribs=True)
• Appends 'Type' to all class names (unless they already end with 'Type') by default
• Replaces complex type annotations with jstruct equivalents
• Ensures there are no duplicate import statements

Generate

The generate command generates Python code with jstruct from a JSON schema file using quicktype.

# Generate Python code with jstruct from a JSON schema
karrio codegen generate --src=schema.json --out=output.py

# Specify Python version
karrio codegen generate --src=schema.json --out=output.py --python-version=3.8

# Generate without --just-types
karrio codegen generate --src=schema.json --out=output.py --just-types=false

# Disable appending 'Type' to class names
karrio codegen generate --src=schema.json --out=output.py --no-append-type-suffix

Create Tree

The create-tree command generates a Python code tree from a class definition. It's useful for visualizing the structure of complex nested objects and generating initialization code templates.

# Generate a tree for a class
karrio codegen create-tree --module=karrio.schemas.allied_express.label_request --class-name=LabelRequest

# Generate a tree with a module alias
karrio codegen create-tree --module=karrio.schemas.allied_express.label_request --class-name=LabelRequest --module-alias=allied

Example output:

LabelRequestType(
    bookedBy=None,
    account=None,
    instructions=None,
    itemCount=None,
    items=[
        ItemType(
            dangerous=None,
            height=None,
            itemCount=None,
            length=None,
            volume=None,
            weight=None,
            width=None,
        )
    ],
    jobStopsP=JobStopsType(
        companyName=None,
        contact=None,
        emailAddress=None,
        geographicAddress=GeographicAddressType(
            address1=None,
            address2=None,
            country=None,
            postCode=None,
            state=None,
            suburb=None,
        ),
        phoneNumber=None,
    ),
    jobStopsD=JobStopsType(...),
    referenceNumbers=[],
    serviceLevel=None,
    volume=None,
    weight=None,
)

Migrating carrier connector generate scripts

To migrate carrier connector generate scripts to use the new codegen command, run:

python karrio/modules/cli/commands/migrate_generate_scripts.py /path/to/karrio/workspace

This will update all generate scripts in the carrier connectors to use the new karrio codegen command.

JStruct Overview

JStruct is a Python library for nested object models that offers serialization and deserialization into Python dictionaries. It leverages the attrs library to define structs without boilerplate.

Here's an example of the transformed code:

import attr
import jstruct
import typing

@attr.s(auto_attribs=True)
class PersonType:
    first_name: typing.Optional[str] = None
    last_name: typing.Optional[str] = None

@attr.s(auto_attribs=True)
class RoleModelsType:
    scientists: typing.Optional[typing.List[PersonType]] = jstruct.JList[PersonType]

For more information, see the JStruct README.