How to Modify

Rebuild Process

jpy’s source distribution directory layout uses the Maven common directory structure.

  • setup.py - Python build/installation script, will compile Python and Java sources, install the libraries and run all unit-level tests.
  • pom.xml - Maven project file to build the Java sources. Called by setup.py.
  • src/main/c - C source files for the jpy Python API
  • src/test/python - Python API test cases
  • src/main/java - Java source files for the jpy Java API
  • src/test/java - Java API test cases

After changing any source code just run setup again as indicated in the Build from Sources process.

After changing signatures of native methods in src/main/java/org/jpy/PyLib.java, you need to compile the Java classes and regenerate the C headers for the PyLib class using Maven:

mvn compile
javah -d src/main/c/jni -v -classpath target/classes org.jpy.PyLib

Then always adapt changes org_jpy_PyLib.c according to newly generated org_jpy_PyLib.h and org_jpy_PyLib_Diag.h. Files are found in src/main/c/jni/. Then run setup again as indicated above.

C Programming Guideline

  • Follow style used in Python itself

  • Python type global variable names: J<type>_Type

  • Python type instance structs: JPy_J<type>

  • Python function decl for a type: J<type>_<FunctionName>(JNIEnv* jenv, JPy_J<type>* <type>, ...)

  • The pointer is always the first parameter, only type slots obtain their jenv from JPy_GetJEnv()

  • Python slots function for a type: J<type>_<slot_name>(JNIEnv* jenv, JPy_J<type>* self, ...)

  • Usually functions shall indicate errors by returning NULL or -1 on error. Callers can expect that the PyErr_SetError has been set correctly and thus simply return NULL or -1 again. Exception: very simple functions, e.g. JObj_Check(), can go without error status indication.

  • Naming conventions:

    • jpy_jtype.h/c - The Java Meta-Type
      • JPy_JType type
      • JType_xxx() functions
    • jpy_jobj.h/c - The Java Object Wrapper
      • JPy_JObj type
      • JObj_xxx() functions
    • jpy_jmethod.h/c - The Java Method Wrapper
      • JPy_JMethod type
      • JPy_JOverloadedMethod type
      • JMethod_xxx() functions
      • JOverloadedMethod_xxx() functions
    • jpy_jfield.h/c - The Java Field Wrapper
      • JPy_JField type
      • JField_xxx() functions
    • jpy_conv.h/c - Conversion of Python objects from/to Java values
      • JPy_From<JType> functions / JPy_FROM_<JTYPE> macros create Python objects (new references!) from Java types
      • JPy_As<JType> functions / JPy_AS_<JTYPE> macros convert from Python objects to Java types
    • jpy_diag.h/c - Control of outputting diagnostic info
      • JPy_Diag type
      • JPy_DIAG_F_<name> macros
      • JPy_DIAG_PRINT(flags, format, ...) macros
    • jpy_module.h/c - The ‘jpy’ module definition
      • JPy_xxx() functions
    • jni/org_jpy_PyLib.h - generated by javah from PyLib.java

    • jni/org_jpy_PyLib_Diag.h - generated by javah from PyLib.java

    • jni/org_jpy_PyLib.c - native implementations from PyLib.java