Merge pull request #40 from smolvik1/add-px-online-server

Add px online server

Author: sogunneroed

.github/workflows/cd.yml

@@ -17,9 +17,9 @@ jobs:
         uses: actions/checkout@v3
 
       - name: "Set up uv"
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: "3.11"
+          python-version: "3.13"
 
       - name: "Build distributions"
         run: |

.github/workflows/ci.yml

@@ -23,9 +23,9 @@ jobs:
         uses: actions/checkout@v3
 
       - name: "Set up uv"
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: "3.11"
+          python-version: "3.13"
 
       - name: "Build distribution"
         run: |

.gitignore

@@ -14,4 +14,7 @@ sdist/
 
 # Environment
 .venv/
-venv/
+venv/
+
+# Swagger
+swagger.json

README.md

@@ -62,3 +62,72 @@ DoCmd('PROSPER.OPENFILE("C:\\well_2.OUT")')
 DoSet('PROSPER.SIN.SUM.Comments', 'Testing OpenServer from Python')
 ```
 
+## Remote OpenServer (PxOnlineServer)
+
+In addition to the local COM client, the package ships a `PxOnlineServer` client
+that talks to a Petroleum Experts [PxOnlineServer](https://www.petex.com/products/ipm-suite/openserver/)
+instance over its REST API. It runs the *same* `DoCmd`/`DoSet`/`DoGet` commands as
+the local client, but against a model hosted on the server - no local IPM install
+is required.
+
+`requests` is used for the HTTP calls and is installed automatically.
+
+### Connecting to a session
+
+A remote model lives in a *master session* on the server. On connect, the master
+session is copied into a temporary *user session* that your commands run against;
+the user session is removed again on disconnect.
+
+```python
+from openserver import PxOnlineServer
+
+with PxOnlineServer(
+    base_url="http://my-pxserver:8056",
+    master_session="my_master_session",  # a master session containing a PROSPER module
+    module_name="IPM-OS",                # the server-side OpenServer module name
+) as c:
+    print(c.DoGet("PROSPER.SIN.SUM.Comments"))
+    c.DoSet("PROSPER.SIN.SUM.Comments", "Testing remote OpenServer from Python")
+```
+
+To attach to an existing user session instead of creating one, pass `guid` and
+`session` instead of `master_session`.
+
+### Loading a model from the Model Catalogue
+
+The Model Catalogue is the server's versioned file store. `open_catalogue_file`
+is the remote analogue of `PROSPER.OPENFILE`: it loads a catalogue model into the
+session so the familiar `DoCmd`/`DoSet`/`DoGet` calls operate on it. There is no
+`PROSPER.START()` remotely - the module is already running in the session.
+
+```python
+from openserver import PxOnlineServer
+
+with PxOnlineServer(base_url="http://my-pxserver:8056",
+                    master_session="my_master_session",
+                    module_name="IPM-OS") as c:
+    # Remote equivalent of PROSPER.OPENFILE - give the catalogue host + file path
+    c.open_catalogue_file(
+        "Root/Europe/Norway/North Sea/Yggdrasil/ByteAll/ProsperModel/SK1.Out",
+        host_alias="MyCatalogueHost",
+    )
+
+    # ...then it's the same as the local COM client
+    c.DoSet("PROSPER.SIN.SUM.Comments", "Testing remote OpenServer from Python")
+    print(c.DoGet("PROSPER.SIN.SUM.Comments"))
+```
+
+`open_catalogue_file` returns the catalogue guid, so you can pass it back in as
+`catalogue_guid=...` to open further files without re-initialising the catalogue.
+
+The file is uploaded under the existing main file's name, so the session's
+reported `MainFile` label is unchanged - but its contents (and everything
+`DoGet`/`DoSet`/`DoCmd` see) are the catalogue file you loaded.
+
+See [examples/px_online_server_basic.py](examples/px_online_server_basic.py) for a
+complete, runnable walkthrough.
+
+### Limitations
+
+`PxOnlineServer` currently targets a PxOnlineServer instance that requires no
+authentication - it sends no credentials. 

changelog.md

@@ -1,3 +1,8 @@
+## 1.154
+* Added `PxOnlineServer`, a remote OpenServer client for Petroleum Experts PxOnlineServer (REST API)
+* Added Model Catalogue support: browse folders/files by path, download files, and load a catalogue file into a running session via `open_catalogue_file`
+* Added `requests` as a dependency for the remote client
+
 ## 1.153
 * Switched packaging and dependency management from Poetry to uv
 * Updated CI/CD pipelines to use Python 3.11 and uv

examples/px_online_server_basic.py

@@ -0,0 +1,53 @@
+"""Basic remote OpenServer usage via PxOnlineServer.
+
+Runs the same DoCmd/DoSet/DoGet calls as the local COM client, but against a
+Petroleum Experts PxOnlineServer instance. No local IPM install is required.
+
+The base_url, master_session and module_name below are examples - replace them
+with values for your own server. `master_session` is referenced by name and is
+copied into a temporary user session on connect; that user session is removed
+again on disconnect.
+"""
+
+from openserver import PxOnlineServer
+
+BASE_URL: str = "http://my-pxserver:8056"
+MASTER_SESSION: str = "my-master-session"   # a master session that contains a PROSPER OpenServer module
+MODULE_NAME: str = "IPM-OS"      # the server-side OpenServer module name
+
+MC_FILE_PATH: str = r'Root/Europe/Norway/prosper-testfile.OUT'  # Case-sensitive
+MC_HOST_ALIAS: str = "my-mc-alias"
+
+# --- Generic OpenServer usage against a Model Catalogue file ---
+with PxOnlineServer(base_url=BASE_URL, master_session=MASTER_SESSION, module_name=MODULE_NAME) as c:
+    # Open a model from the Model Catalogue
+    # Perform a simple VLP/IPR calculation
+    # Return the liquid rate result
+    c.open_catalogue_file(MC_FILE_PATH, host_alias=MC_HOST_ALIAS)
+    print(f"Opened {MC_FILE_PATH}")
+
+    unit_system = "Norwegian S.I."
+    c.DoCmd(f"PROSPER.SETUNITSYS(\"{unit_system}\")")
+
+    whp: float = 30  # bara
+    wc: float = 40  # percent water cut
+    gor_tot: float = 79  # gas-oil ratio total
+    c.DoSet("PROSPER.ANL.SYS.Pres", whp)  # Set top node pressure
+    c.DoSet("PROSPER.ANL.SYS.WC", wc)  # Set water cut
+    c.DoSet("PROSPER.ANL.SYS.GOR", gor_tot)  # Set GOR total
+
+    c.DoCmd("PROSPER.ANL.SYS.CALC")  # Calculate VLP/IPR
+
+    qliq = c.DoGet("PROSPER.OUT.SYS.SOL[0].QLIQ")  # Get liquid flow rate
+    print(f"Liquid flow rate: {qliq}")
+
+
+with PxOnlineServer(base_url=BASE_URL, master_session=MASTER_SESSION, module_name=MODULE_NAME) as d:
+    catalogue_guid: str = d.open_catalogue_file(MC_FILE_PATH, host_alias=MC_HOST_ALIAS)
+
+    # --- Download a copy of a Model Catalogue file to disk ---
+    file_bytes = d.mc_download_file(catalogue_guid, MC_FILE_PATH)
+    local_name = MC_FILE_PATH.rsplit("/", 1)[-1]
+    with open(local_name, "wb") as f:
+        f.write(file_bytes)
+    print(f"Downloaded {len(file_bytes)} bytes to {local_name}")