Python库 | py4jps-1.0.16.tar.gz

# What is py4jps `Py4jps` is a thin Python wrapper for the [TheWorldAvatar](https://github.com/cambridge-cares/TheWorldAvatar) project. The code is heavily based on the [py4j](https://www.py4j.org/index.html) package, which enables Python programs running in a Python interpreter to dynamically access Java objects in a Java Virtual Machine. # Requirements - You need Python >=3.5 to run the py4jps. You can install Python by going to the official Python [download page](https://www.python.org/getit/) - You also need to install a [Java Runtime Environment version 8](https://adoptopenjdk.net/?variant=openjdk8&jvmVariant=hotspot) # Installation These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. ## Virtual environment setup It is highly recommended to use a [virtual environment](https://docs.python.org/3/tutorial/venv.html) for the `py4jps` installation. The virtual environment can be created as follows: `(Windows)` ```cmd $ python -m venv py4jps_venv $ py4jps_venv\Scripts\activate.bat (py4jps_venv) $ ``` `(Linux)` ```sh $ python3 -m venv py4jps_venv $ source py4jps_venv\bin\activate (py4jps_venv) $ ``` The above commands will create and activate the virtual environment `py4jps_venv` in the current directory. ## Installation via pip To install the `py4jps` simply run the following command: ```sh (py4jps_venv) $ pip install py4jps ``` The above command will install the `py4jps` package including the `JpsBaseLib` library that has been packaged together with the code. ## Installation from the version-controlled source (for developers) This type of installation is only for the developers. To install `py4jps` directly from its repository you need to first clone the `TheWorldAvatar` project. Then simply navigate to the *TheWorldAvatar\JPS_BASE_LIB\python_wrapper* directory and execute the following commands: ```bash # build and install (py4jps_venv) $ pip install . # or build for in-place development (py4jps_venv) $ pip install -e . # or use the provided "install_wrapper.sh" convenience script, # that can create virtual environment and install the py4jps package in one go # build and install $ install_wrapper.sh -v -i # or build for in-place development $ install_wrapper.sh -v -i -e ``` The above commands will install the `py4jps` package only. To include the [JpsBaseLib](https://github.com/cambridge-cares/TheWorldAvatar/tree/master/JPS_BASE_LIB) library, please see the next section. ## Installing additional java resources The `py4jps` project can be easily extended to provide wrapping for other `TheWorldAvatar` java projects. To do that, all resource files and their dependencies must be collated into a single directory, with the main jar file located at the directory root. The `JpsBaseLib pom.xml` file shows an example of how to do it with maven. If you wish to do it for other `TheWorldAvatar` project, simply copy the `maven-jar-plugin` and `maven-dependency-plugin` plugins into the project pom file and add the `net.sf.py4j` dependency. These changes will collate all the project dependencies into the `target\lib` directory and include the required `py4j` package in your project. Once that is done and the project is successfully built, the `py4jps` resource manager command-line utility, `jpsrm`, can be used to install and register the resource. Here are the steps: 1. Copy the project main jar file and the entire `lib` folder a temporary directory, e.g., `tmp_dir`. 2. Run the following command in the terminal (with `py4jps_venv` virtual environment activated): ```bash (py4jps_venv) $ jpsrm install <name> <from> --jar JARFILE ``` where `jpsrm` is the `py4jps` resource manager, `<name>` is the name you wish to assign to your java resource. Note that the `<name>` MUST follow python's classes names requirements, otherwise it will be impossible to import it in python. The `<from>` argument is the absolute path to the `tmp_dir` with all the java project files and the `--jar` option is used to provide a name of the main jar file, `JARFILE`, to be used for communication. 3. After the successful installation you can access the resource (classes and methods) in `py4jps` by simply importing it: ```python from py4jps.resources import yourResourceName ``` 4. Remove the no longer needed `tmp_dir` directory. To see all `jpsrm` commands and options, run `jpsrm -h` in the terminal. ## Installing resources (for developers) These instructions explain how to install the `JPS_BASE_LIB` library and are useful for developers working directly with the `TheWorldAvatar` repository. Steps to install the `JPS_BASE_LIB` library: 1. Build the `JPS_BASE_LIB` project. 2. Go to the `JPS_BASE_LIB/target` directory and copy the main project jar file, `jps-base-lib.jar`, and the entire `lib` folder containing the project dependencies into a temporary directory, let us call it `tmp_JpsBaseLib`. 3. Run the following command in the terminal (with `py4jps_venv` virtual environment activated): ```bash (py4jps_venv) $ jpsrm install JpsBaseLib <path_to_the_tmp_JpsBaseLib_directory> --jar jps-base-lib.jar ``` 4. After successful installation you can access the `JpsBaseLib` resource (classes and methods) in `py4jps` by simply importing it: ```python from py4jps.resources import JpsBaseLib ``` 5. Remove the no longer needed `tmp_JpsBaseLib` directory. Note. The `jpsrm` includes a developer-only convenience command `devinstall` which will run all the above steps and install the `JpsBaseLib` resource. The command will only work if: - the `JPS_BASE_LIB` project is present and was successfully built - the `py4jps` project was installed in a developer mode (-e option) inside the `TheWorldAvatar` repository Here is how to execute the `devinstall` command: ```bash # execute devinstall (py4jps_venv) $ jpsrm devinstall ``` # How to use This section explains how to effectively use the `py4jps` package by following the best practices. Note that `py4jps` is a very thin wrapper, thus it does not provide a high-level abstraction to the java classes. Therefore, the java project documentation must be consulted with to know which java objects to call to perform a desired task. ## Python-Java communication via Python's JPSGateway wrapper class The Python-Java communication, handled by the `py4j` package, happens via the local network sockets. The main interaction point between a Python and Java is provided by the [py4j JavaGateway](https://www.py4j.org/py4j_java_gateway.html#javagateway) class. This class is wrapped within the `py4jps JPSGateway` class for convenience. The `JPSGateway` class is the parent class for any installed java resources that one wishes to access. **Although, it is not recommended to use it directly**, the `JPSGateway` class can be useful in experimenting with different resources without installing them first, as it allows to change the resources at runtime. Please see the [JPSGateway help](https://github.com/cambridge-cares/TheWorldAvatar/blob/master/JPS_BASE_LIB/python_wrapper/py4jps/JPSGateway.py) to learn more, whereas below, only the most important aspects are covered. The `py4jps JPSGateway` class can be imported to your project via the following command `from py4jps import JPSGateway`. The class can be used in the following way: ```python from py4jps import JPSGateway yourGateway = JPSGateway(resName=yourResName, jarPath=yourResJarPath, **JGkwargs) ``` where `resName` is the name you wish to give to your resource, `yourResJarPath` is the absolute path to the resource main jar file and `**JGkwargs` is a dictionary of any optional `argument: value` pairs one wishes to pass to the [py4j JavaGateway](https://www.py4j.org/py4j_java_gateway.html#py4j.java_gateway.JavaGateway) constructor. Note that if you wish to access an already installed resource through the `JPSGateway` (not recommended), then the `jarPath` argument can be omitted as it can be looked up by the resource name in the