Skip to content

conversion-model.md

Latest commit

 

History

History
102 lines (71 loc) · 2.14 KB

conversion-model.md

File metadata and controls

102 lines (71 loc) · 2.14 KB
Raw

Conversion Model

Principle

CPython4J converts data, not objects.

It supports:

  1. primitive direct conversion;
  2. JSON-shaped structural conversion for non-primitives.

It does not preserve identity, cycles, object methods, shared references, or arbitrary object graphs.

Direct primitive conversion

Java Python
void None
null None
boolean / Boolean bool
int / Integer int
long / Long int
double / Double float
String str

byte[] is deferred until a clear policy is chosen. Options are direct bytes for primitive mode or base64 inside JSON mode.

JSON structural conversion

Used for:

  • Java records;
  • DTOs;
  • List<T>;
  • arrays;
  • Map<String, T>;
  • enums;
  • Optional<T>;
  • nested structures.

Java argument flow:

Java object -> ObjectMapper JSON -> Python json.loads -> Python dict/list/scalar

Python return flow:

Python dict/list/scalar -> Python json.dumps -> ObjectMapper JSON -> Java target type

Python authors should not manually call json.dumps; the bridge should do this internally.

Recommended DTO style

Use Java records:

public record Document(String text, String source) {}
public record Analysis(String language, int wordCount) {}

Python sees and returns dictionaries:

def analyze(document):
    return {
        "language": "en",
        "wordCount": len(document["text"].split())
    }

Naming policy

V1 default: use Java names exactly.

Example: wordCount remains wordCount, not word_count.

A later optional policy may support snake_case mapping.

Exclusions

V1 does not support:

  • cyclic graphs;
  • object identity;
  • shared references;
  • arbitrary Python objects returned to Java;
  • arbitrary Java object method access from Python;
  • Python classes implementing Java classes;
  • Java objects as live Python objects.

Failure policy

If a value cannot be structurally converted, fail early with a conversion exception that includes:

  • Java contract method;
  • argument or return position;
  • Java target type;
  • Python value type, where available;
  • JSON error, if relevant.