cjpy 0.3.6

Usage: cjpy json_input_file1 -options_for_file1 ...
[json_input_file2 -options_for_file2 ...]
[--with common_json_files -common_options ...]

Command liner for python routines using json based input parameter files. Ver 0.3.6 by Jaesub Hong (jhong@cfa.harvard.edu)

  cjpy --help [overview json pars cmdline all ... func:]
  cjpy [json_files ...] --Help
  cjpy --main module.routine --Help

Installation and Startup

Install the cjpy package using pip,

  % pip install cjpy

then assign an alias for easy use: e.g., in bash,

  % alias cjpy="python -m cjpy"

Alternatively, this program can be used without installation: simply place cjson.py in the python path and use

  % alias cjpy="python cjson.py"

For a common parameter configuration, assign an environmental variable CJSON_STARTUP to a JSON file with the common paramters: e.g., in bash,

  % export CJSON_STARTUP="~/my_startup.json"

The parameters in this file will be loaded as well.

By default, cjpy will attempt to pass parameters starting only with alphabets to the routine in call, but one can accept the full parameter sets (including -main) by adding an optional parameter in your function:

  import cjpy.cjson
  ...
  def my_routine(..., cfg=cjson.native, ...):
        ...

then, cfg, which is an collections.OrderedDict, will inherit all the parameters.

One can also use cjpy inside python or ipython for a single task: e.g.,

  >>> import cjpy.cjson as cj
  >>> cfg = cj.get_parameters(['json file name','options', ...])
  >>> out = cj.execute(cfg)

Or the args contain a set of parameters for multiple tasks:

  >>> sets=cj.get_parameter_sets(['input args string array'])
  >>> out=cj.execute_sets(sets)

Quick Overview of the Basic Concept:

The cjson input parameter files can contain the name of the routine to call: e.g., "-main": "module.routine". Keys starting with alphabets are assumed to be fed into the main routine set by "-main" key. Assume that a python script example.py has

  def my_sum(name, x, y):
       """ This is my sum. """
       print(name+':', x+y)

Then with a json file input.json,

  "-main": "example.my_sum",
      "x": 5,
      "y": 7,
   "name": "answer",

one can execute the routine my_sum in a shell command prompt like

  % cjpy input.json
  answer: 12

In princinple, all the content in the json files can be fed as a long string in the command line or as optional parameters for individual keys with "-". So the above example is equivalent to the followings even without the json file input.json.

  % cjpy --main example.my_sum -#x 5 -#y 7 -name "answer"
  % cjpy '{"-main":"example.my_sum","x":5,"y":7,"name":"answer"}'

or some combination of all three examples:

  % cjpy '{"-main":"example.my_sum","name":"answer"}' -#x 5 -#y 7
  % cjpy input.json '{"name":"answer"}' -#x 5 -#y 7

When both json files and command line input options are available for the same key, the command line options take a priority. Note # in -#x ensures it is a number but not a string. See more details with cjpy --help cmdline. Note --Help (capital H) prints out the doc string of the routine.

  % cjpy input.json --Help
  This is my sum.

Calling multiple JSON files execute them in sequence.

  % cjpy input.json input.json
  answer: 12
  answer: 12

  % cjpy input.json -#x 7 input.json -#x 6
  answer: 14
  answer: 13

Find out what kind of parameters are needed to call the routine using --show func option.

  % cjpy --main os.path.isfile --show func
   main: os.path.isfile
   path

The above example shows isfile expect a parameter called path.

  % cjpy --main os.path.isfile -path cjson.py --show output
  True

Can check how the parameters get fed to the routine.

  % cjpy --main os.path.isfile -path cjson.py --show feed
   main: os.path.isfile
   path << str cjson.py

  % cjpy input.json --show feed
   main: example.my_sum
   name << str answer
      x << int 5
      y << int 7

Can call a routine needing no input parameters.

  % cjpy --main datetime.datetime.now --show output
  2022-04-27 22:11:52.983532

One can force the parameters to a function with --pars option.

  % cjpy --main math.sin --pars x --show output -#x 1.0
  0.8414709848078965

In the case of the built-in functions: e.g.,

  % cjpy --main eval --pars x --show output -x 3+3
  6

  % cjpy --main pow -*-pars x,y --show output -#x 1.5 -#y 3
  3.375

  % cjpy --main eval --pars x --show output -x 'pow(1.5,3)'
  3.375

try also: --help overview | features | json | pars | startup | iteration | decoration | logging | sequential | cmdline | changes | all | func: | func:[function name]