{"author":null,"author_email":"SciJava developers ","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","Intended Audience :: Education","Intended Audience :: Science/Research","Intended Audience :: System Administrators","License :: OSI Approved :: The Unlicense (Unlicense)","Operating System :: MacOS","Operating System :: Microsoft :: Windows","Operating System :: Unix","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Scientific/Engineering","Topic :: Software Development :: Libraries :: Java Libraries","Topic :: Software Development :: Libraries :: Python Modules","Topic :: System :: Installation/Setup","Topic :: System :: Shells","Topic :: System :: System Shells","Topic :: Utilities"],"description":"[![build status](https://github.com/scijava/jgo/actions/workflows/build.yml/badge.svg)](https://github.com/scijava/jgo/actions/workflows/build.yml)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n# jgo: painless Java component execution\n\n![](https://raw.githubusercontent.com/scijava/jgo/main/jgo.png)\n\n## Summary\n\n[Maven](https://maven.apache.org/) is a great tool. It manages dependencies so\nthat Java projects become reusable \"building blocks\" in a robust way, like\n`pip` for Python, `npm` for JavaScript, `gem` for Ruby, `cpan` for Perl, etc.\nAnd the [Maven Central repository](https://search.maven.org/) contains a\ntremendous wealth of code, ripe for reuse in your own projects.\n\nUnfortunately, Maven provides no easy way to actually __launch code__ from the\nbeautifully managed dependencies stored so lovingly into `~/.m2/repository`.\n\nThis project fills that gap: `jgo` launches Java code. You do not need to\ndownload or install any JARs; you just specify an \"endpoint\" consisting of a\n[Maven artifact](https://stackoverflow.com/a/2487511/1207769) identifier, plus\na main class if needed/desired, and `jgo` uses Maven to obtain and run it.\n\nTo do this, `jgo` builds the local environment on demand, caching it into a\nsubfolder of `~/.jgo`, so that the endpoint's particular dependencies are\navailable in one place.\n\n## Installation\n\nThe `jgo` project began life as a shell script, but was later translated into\nPython, so that tools such as [scyjava](https://github.com/scijava/scyjava)\ncould leverage its environment-building capabilities.\n\nAs such, there are now two implementations from which to choose!\nEach has pros and cons.\n\n### Prerequisites\n\n`jgo` uses `mvn` and `java` for the heavy lifting.\nThe shell script version needs some common utilities (e.g., `cat`).\nIf you are missing anything, the script will tell you.\n\n### The shell script\n\nThe `jgo.sh` shell script requires a POSIX-friendly system. It is known to\nwork on Linux, macOS, [Cygwin](https://www.cygwin.com/), Microsoft's\n[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install),\nand Git BASH from the [Git for Windows](https://git-for-windows.github.io/) project.\n\n

Installing the shell script

\n\nJust clone this repo and symlink `jgo.sh` into your favorite `bin` directory.\n\nFor example, assuming `~/bin` is on your PATH:\n\n```shell\ncd\ngit clone https://github.com/scijava/jgo\ncd bin\nln -s ../jgo/jgo.sh jgo\njgo --help\n```\n\n

\n\n### The Python module\n\nThe Python version of `jgo` offers a `jgo` console script, as\nwell as a `jgo` module for programmatically creating endpoints.\n\n

Installing with pip

\n\n```shell\npip install jgo\n```\n\n

Installing with conda

\n\n```shell\nconda install -c conda-forge jgo\n```\n\n

Installing from source

\n\n```shell\ngit clone https://github.com/scijava/jgo\ncd jgo\n\n# install globally (not recommended unless using a virtual environment)\npip install .\n\n# install into ~/.local (see pip install --help for details)\npip install --user .\n\n# install into $PREFIX\npip install --prefix=$PREFIX .\n\n# install globally in developer mode (hot linked to working copy folder)\npip install -e .\n```\n\n

\n\n## Usage\n\n```\nUsage: jgo [-v] [-u] [-U] [-m]

\n\n -v : verbose mode flag\n -u : update/regenerate cached environment\n -U : force update from remote Maven repositories (implies -u)\n -m : use endpoints for dependency management (see \"Pitfalls\" below)\n : any list of arguments to the JVM\n : the artifact(s) + main class to execute\n : any list of arguments to the main class\n\nThe endpoint should have one of the following formats:\n\n- groupId:artifactId\n- groupId:artifactId:version\n- groupId:artifactId:mainClass\n- groupId:artifactId:version:mainClass\n- groupId:artifactId:version:classifier:mainClass\n\nIf version is omitted, then RELEASE is used.\nIf mainClass is omitted, it is auto-detected.\nYou can also write part of a class beginning with an @ sign,\nand it will be auto-completed.\n\nMultiple artifacts can be concatenated with pluses,\nand all of them will be included on the classpath.\nHowever, you should not specify multiple main classes.\n```\n\n### Examples\n\n| Program | Command |\n|-----------------------------:|:------------------------------------------------------------------------------------|\n| Jython REPL | `jgo org.python:jython-standalone` |\n| JRuby eval | `echo \"puts 'Hello Ruby'\" \\| jgo org.jruby:jruby-complete:@jruby.Main` |\n| Groovy REPL | `jgo org.codehaus.groovy:groovy-groovysh:@shell.Main+commons-cli:commons-cli:1.3.1` |\n\nNote the usage of the `+` syntax as needed to append elements to the classpath.\n\nIf you add\n`scijava.public = https://maven.scijava.org/content/groups/public`\nto the\n`[repositories]` section of your `.jgorc`\n(see [Repositories](#repositories) below),\nyou can also try:\n\n| Program | Command |\n|-----------------------------:|:------------------------------------------------------------------------------------|\n| SciJava REPL with JRuby | `jgo org.scijava:scijava-common:@ScriptREPL+org.scijava:scripting-jruby` |\n| SciJava REPL with Jython | `jgo org.scijava:scijava-common:@ScriptREPL+org.scijava:scripting-jython` |\n| SciJava REPL with Groovy | `jgo org.scijava:scijava-common:@ScriptREPL+org.scijava:scripting-groovy` |\n| SciJava REPL with Clojure | `jgo org.scijava:scijava-common:@ScriptREPL+org.scijava:scripting-clojure` |\n| SciJava REPL with JavaScript | `jgo org.scijava:scijava-common:@ScriptREPL+org.scijava:scripting-javascript` |\n\n### FAQ\n\n* __Is it fast?__\n Endpoints are synthesized in a local cache under `~/.jgo`.\n So invoking the same endpoint a second time is really quick.\n* __What does \"no installation\" mean?__\n Classpath elements are [hard-linked](https://en.wikipedia.org/wiki/Hard_link)\n into `~/.jgo` from `~/.m2/repository` rather than copied, so the `~/.jgo`\n folder has a tiny footprint even if you execute lots of different endpoints.\n* __What if an endpoint has a new version?__\n Pass the `-U` flag to `jgo` to rebuild the endpoint.\n Note that unlike `mvn`, though, `jgo` does not check for updates otherwise.\n\n### Configuration\n\nYou can configure the behavior of `jgo` using the `~/.jgorc` file.\n\n#### Repositories\n\nYou can define additional remote Maven repositories,\nfrom which artifacts will be retrieved. E.g.:\n\n```ini\n[repositories]\nscijava.public = https://maven.scijava.org/content/groups/public\n```\n\nIf you need more control over where artifacts come from—for example, if you\nwant to use your own remote Maven repository as a mirror of Maven Central—you\ncan do it using Maven's usual `~/.m2/settings.xml`; see [Using Mirrors for\nRepositories](https://maven.apache.org/guides/mini/guide-mirror-settings.html).\n\nYou can also use the `-r` flag to pass additional repositories to individual\ninvocations of jgo.\n\n#### Shortcuts\n\nYou can define shortcuts for launching commonly used programs:\n\n```ini\n[shortcuts]\nrepl = imagej:org.scijava.script.ScriptREPL\nimagej = net.imagej:imagej\nfiji = sc.fiji:fiji:LATEST\nscifio = io.scif:scifio-cli\n```\n\nShortcuts are substituted verbatim from the beginning of the endpoint,\nsingle-pass in the order they are defined. So e.g. now you can run:\n```shell\njgo repl\n```\nNote that with the `repl` shortcut above, the main class\n(`org.scijava.script.ScriptREPL`) comes from a _different_ artifact than\nthe toplevel artifact (`net.imagej:imagej`). This is intentional, so that\nall of [ImageJ](https://imagej.net/), including all of the various SciJava\n`scripting-` plugins, is included in the classpath of the REPL.\n\n#### Settings\n\nThere are a few configurable settings:\n\n```ini\n[settings]\nm2Repo = /path/to/.m2Repo (default ~/.m2/repository)\ncacheDir = /path/to/.jgo (default ~/.jgo)\nlinks = soft (options: hard, soft, none; default hard)\n```\nNote that the `jgo` cache dir can also be set via the `JGO_CACHE_DIR` environment\nvariable when using **Python** `jgo`. The precedence of reading the cache dir, from\nhighest to lowest:\n - `JGO_CACHE_DIR` environment variable\n - `cacheDir` in `settings` sections in `~/.jgorc`\n - default to `~/.jgo`\n\n### Pitfalls\n\n#### Dependency management\n\nMaven has a feature whereby a project can override the versions of transitive\n(a.k.a. inherited) dependencies, via a `` configuration.\nThe problem is: a library may then believe it depends on components at\nparticular versions as defined by its ``, but downstream\nprojects which depend on that library will resolve to different versions.\nSee [this SO thread](https://stackoverflow.com/q/45041888/1207769) and\n[this gist](https://gist.github.com/ctrueden/d058330c8a3687317806ce8cc18332c3)\nfor full details.\n\nTo work around this issue, you can pass `-m` to jgo, which\ncauses it to add all endpoints to the synthesized POM's\n`` section using\n[import scope](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Importing_Dependencies).\nBy doing this, the versions of transitive dependencies used in the synthesized\nproject should more precisely match those of each endpoint itself—although in\nthe case of multiple endpoints concatenated via the `+` operator with\nconflicting dependency management, the earlier endpoints will win because they\nwill be declared earlier in the POM. See also\n[issue #9](https://github.com/scijava/jgo/issues/9) in the jgo issue tracker.\n\n## Development\n\n### Code style\n\n`jgo` uses [`black`](https://github.com/psf/black) for its code style.\n\nAfter `pip install tox`, you can lint the code with:\n\n```shell\ntox -e lint\n```\n\n## Alternatives\n\n* [JBang](https://github.com/jbangdev/jbang)\n* [mvnx](https://github.com/mvnx/mvnx)\n* [JPM4J](https://github.com/jpm4j) (discontinued)\n* [Mop](https://github.com/chirino/mop) (unmaintained)\n* [marun](https://github.com/nishemon/marun) (unmaintained, Python 2 only)\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"java, maven, launch","license":"Unlicense","license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"jgo","package_url":"https://pypi.org/project/jgo/","platform":null,"project_url":"https://pypi.org/project/jgo/","project_urls":{"documentation":"https://github.com/scijava/jgo/blob/main/README.md","download":"https://pypi.org/project/jgo/","homepage":"https://github.com/scijava/jgo","source":"https://github.com/scijava/jgo","tracker":"https://github.com/scijava/jgo/issues"},"provides_extra":["dev"],"release_url":"https://pypi.org/project/jgo/1.0.6/","requires_dist":["psutil","autopep8; extra == \"dev\"","build; extra == \"dev\"","black; extra == \"dev\"","flake8; extra == \"dev\"","isort; extra == \"dev\"","pre-commit; extra == \"dev\"","pyflakes; extra == \"dev\"","pytest; extra == \"dev\"","pytest-cov; extra == \"dev\"","validate-pyproject[all]; extra == \"dev\""],"requires_python":">=3.8","summary":"Launch Java code from Python and the CLI, installation-free.","version":"1.0.6","yanked":false,"yanked_reason":null}

Dependency	Optional
psutil	false
autopep8	true
black	true
build	true
flake8	true
isort	true
pre-commit	true
pyflakes	true
pytest	true
pytest-cov	true
validate-pyproject	true

Package search

jgo

project_urls

Dependencies

All package metadata

Releases