{"id":20449748,"url":"https://github.com/bytedeco/javacpp-embedded-python","last_synced_at":"2025-04-13T02:10:09.435Z","repository":{"id":37083251,"uuid":"346250810","full_name":"bytedeco/javacpp-embedded-python","owner":"bytedeco","description":"With this library, you can embed Python to your Java or Scala project. The main purpose of this library is to use Python libraries from Java or Scala.","archived":false,"fork":false,"pushed_at":"2024-08-25T12:05:04.000Z","size":547,"stargazers_count":10,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T02:09:56.085Z","etag":null,"topics":["java","python","scala"],"latest_commit_sha":null,"homepage":"http://bytedeco.org/javacpp-embedded-python/apidocs/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bytedeco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-10T06:07:05.000Z","updated_at":"2025-03-10T13:49:23.000Z","dependencies_parsed_at":"2024-11-15T10:44:25.202Z","dependency_job_id":"d9a81149-dd21-4d19-8615-7edd00593cd8","html_url":"https://github.com/bytedeco/javacpp-embedded-python","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedeco%2Fjavacpp-embedded-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedeco%2Fjavacpp-embedded-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedeco%2Fjavacpp-embedded-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedeco%2Fjavacpp-embedded-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytedeco","download_url":"https://codeload.github.com/bytedeco/javacpp-embedded-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654090,"owners_count":21140236,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","python","scala"],"created_at":"2024-11-15T10:44:21.633Z","updated_at":"2025-04-13T02:10:09.315Z","avatar_url":"https://github.com/bytedeco.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JavaCPP Embedded Python\n\nWith this library, you can embed Python to your Java or Scala project.\nThis library is a wrapper of javacpp-presets/cpython.\nThe main purpose of this library is to use Python libraries from Java or Scala.\n\n## Apache Maven and sbt\n\nI have not uploaded this library to the Apache Maven Central Repository yet.\nYou have to do ```mvn install```.\n\nApache Maven\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.bytedeco\u003c/groupId\u003e\n    \u003cartifactId\u003ejavacpp-embedded-python\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0-SNAPSHOT\u003c/version\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.bytedeco\u003c/groupId\u003e\n    \u003cartifactId\u003enumpy-platform\u003c/artifactId\u003e\n    \u003cversion\u003e1.20.1-1.5.5\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nsbt\n\n```scala\nlibraryDependencies += \"org.bytedeco\" % \"javacpp-embedded-python\" % \"1.0.0-SNAPSHOT\"\nlibraryDependencies += \"org.bytedeco\" % \"numpy-platform\" % \"1.20.1-1.5.5\"\n```\n\nJavaCPP 1.5.3 or later is supported.\nIf you want to use Python 3.7, replace numpy-platform version to ```1.19.1-1.5.4```.\n\n## Javadoc\n\nhttp://bytedeco.org/javacpp-embedded-python/apidocs/\n\n## Usage\n\nYou can put the global variable ```a```.\n\n```Java\nPython.put(\"a\", 1);\n```\n\nExecute the Python code.\n\n```Java\nPython.exec(\"b = a + 2\");\n```\n\nGet the global variable ```b```.\n\n```Java\nlong b = Python.get(\"b\");\n```\n\nYou can add a built-in global function to Python.\nThe ```scala.Function2``` interface comes from scala-java8-compat library.\nIf you don't need the return value, please return ```null```.\nThis will return ```None``` in Python.\n\n```Java\nimport scala.Function2;\n\nPython.put(\"f\", (Function2\u003cLong, Long, Long\u003e) (a, b) -\u003e a + b);\nlong v = Python.eval(\"f(1, 2)\");\n```\n\nYou can also use a Numpy np.ndarray and convert it to a Java array.\n\n```Java\nNpNdarrayFloat ndary = Python.eval(\"np.arange(6, dtype=np.float32).reshape([2, 3])\");\nfloat[][] ary = ndary.toArray2d();\n```\n\nIf you need a Python library, please use the Pip class.\n\n```Java\nPip.install(\"pandas\");\n```\n\nIf you want to use the local Python files, use ```sys.path.append(\"your_src_dir\")``` in Python.\n\n## Type mappings\n\n### Python to Java\n\n| Python | Java |\n|--------|------|\n| None | null |\n| bool\u003cbr\u003escalar np.bool8 | boolean |\n| scalar np.int8 | byte |\n| scalar np.int16 | short |\n| scalar np.uint16 | char |\n| scalar np.int32 | int |\n| int\u003cbr\u003escalar np.int64 | long |\n| scalar np.float32 | float |\n| float\u003cbr\u003escalar np.float64 | double |\n| scalar np.datetime64[W, D, h, m, s, ms, us, or ns] | Instant |\n| str | String |\n| bytes\u003cbr\u003ebytearray | byte[] |\n| dict | LinkedHashMap |\n| ndarray np.int8 | NpNdarrayByte |\n| ndarray np.bool8 | NpNdarrayBoolean |\n| ndarray np.int16 | NpNdarrayShort |\n| ndarray np.uint16 | NpNdarrayChar |\n| ndarray np.int32 | NpNdarrayInt |\n| ndarray np.int64 | NpNdarrayLong |\n| ndarray np.float32 | NpNdarrayFloat |\n| ndarray np.float64 | NpNdarrayDouble |\n| ndarray np.datetime64[W, D, h, m, s, ms, us, or ns] | NpNdarrayInstant |\n| iterable | ArrayList |\n\nIf you want to use Pandas DataFrames, please use ```DataFrame.reset_index().to_dict('list')```.\nIf you are using datetimes in DataFrame, use ```DatetimeIndex.to_numpy()```.\n\n### Java to Python\n\n| Java | Python |\n|--------|------|\n| null | None |\n| boolean | bool |\n| byte\u003cbr\u003eshort\u003cbr\u003echar\u003cbr\u003eint\u003cbr\u003elong | int |\n| float\u003cbr\u003edouble | float |\n| Instant | np.datetime64[ns] |\n| String | str |\n| byte[] | bytes |\n| boolean[]\u003cbr\u003eNpNdarrayBoolean | np.ndarray, dtype=np.bool8 |\n| NpNdarrayByte | np.ndarray, dtype=np.int8 |\n| short[]\u003cbr\u003eNpNdarrayShort | np.ndarray, dtype=np.int16 |\n| char[]\u003cbr\u003eNpNdarrayChar | np.ndarray, dtype=np.uint16 |\n| int[]\u003cbr\u003eNpNdarrayInt | np.ndarray, dtype=np.int32 |\n| long[]\u003cbr\u003eNpNdarrayLong | np.ndarray, dtype=np.int64 |\n| float[]\u003cbr\u003eNpNdarrayFloat | np.ndarray, dtype=np.float32 |\n| double[]\u003cbr\u003eNpNdarrayDouble | np.ndarray, dtype=np.float64 |\n| Instant[]\u003cbr\u003eNpNdarrayInstant | np.ndarray, dtype=np.datetime64[ns] |\n| java.util.Map\u003cbr\u003escala.collection.Map | dict |\n| Object[]\u003cbr\u003eIterable | list |\n| scala.Function0 - Function22 | built-in global Python function |\n\n### Value type tree\n\nIf the value type conversion fails, its value type tree is included in the Exception message.\n\nFor example, for this Java code,\n\n```Java\nHashMap\u003cString, Object\u003e map = new HashMap\u003c\u003e();\nmap.put(\"a\", Arrays.asList(1, 2));\nmap.put(\"b\", UUID.randomUUID());\nPython.put(\"v\", map);\n```\n\nyou get this message. Because UUID is unsupported, you have to convert it to a String.\n\n```\norg.bytedeco.embeddedpython.PythonException: Cannot convert the Java object to a Python object.\n\nValue type tree\n  Map\n    Map.Entry\n      String\n      Iterable(java.util.Arrays$ArrayList)\n        Integer\n        Integer\n    Map.Entry\n      String\n      java.util.UUID  \u003c- Unsupported\n```\n\n### Tips\n\nBecause Python is a duck typing language, the Python value type is unclear statically.\nFor example, people don't care about the difference between ```int``` and ```np.int64``` scalar.\nTherefore, I recommend converting the Python value type\nbefore passing it to the Java side and making it clear statically.\nFor example, use such as ```int()```, ```np.array()```, or ```bytes()```.\n\n## Exceptions\n\n### Python to Java\nWhen Python code throws exceptions in ```Python.eval()``` or ```Python.exec()```,\ntracebacks are printed to stderr,\nand ```PythonException``` is thrown in Java.\n\n### Java to Python\nWhen Java code throws exceptions in the Java lambda,\n```Throwable.printStackTrace()``` is called,\nand ```RuntimeError``` is thrown in Python.\n\n## Intel Math Kernel Library\n\nIf you are using Intel CPU, add this dependency.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.bytedeco\u003c/groupId\u003e\n    \u003cartifactId\u003emkl-platform-redist\u003c/artifactId\u003e\n    \u003cversion\u003e2021.1-1.5.5\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Version matrix\n\n| javacpp-embedded-python | [numpy-platform](https://mvnrepository.com/artifact/org.bytedeco/numpy-platform) | [mkl-platform-redist](https://mvnrepository.com/artifact/org.bytedeco/mkl-platform-redist) | [CPython](https://mvnrepository.com/artifact/org.bytedeco/cpython-platform) |\n|-----|-----|-----|-----|\n|1.x.x|1.18.2-1.5.3|2020.1-1.5.3|3.7.7|\n|1.x.x|1.19.1-1.5.4|2020.3-1.5.4|3.7.9|\n|1.x.x|1.20.1-1.5.5|2021.1-1.5.5|3.9.2|\n\n## Linux problem\n\nBecause javacpp-presets/cpython has not been built correctly on Linux, you have to rebuild it.\nYou can do it by this if you are using Ubuntu 20.04.\nSee also https://devguide.python.org/setup/#linux for other Linux distributions.\nChange ```1.5.5``` to your JavaCPP version.\njavacpp-presets/cpython forgets to do ```apt-get build-dep python3.8```.\n\n```bash\necho 'deb-src http://archive.ubuntu.com/ubuntu/ focal main' | sudo tee -a /etc/apt/sources.list\nsudo apt update\nsudo apt-get build-dep python3.8\nsudo apt install maven openjdk-11-jdk\n\ngit clone https://github.com/bytedeco/javacpp-presets.git\ncd javacpp-presets\ngit checkout -b 1.5.5 refs/tags/1.5.5\ncd cpython\nmvn install\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedeco%2Fjavacpp-embedded-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytedeco%2Fjavacpp-embedded-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedeco%2Fjavacpp-embedded-python/lists"}