Metadata-Version: 2.4
Name: retp
Version: 0.3.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Networking
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=1.21
License-File: LICENSE
License-File: NOTICE
Summary: An ETP v1.2 client for Python, over retp: sessions, dataspaces, EnergyML objects and data arrays
Keywords: etp,energistics,energyml,resqml,witsml,prodml,rddms
Author: Geosiris
Maintainer: Geosiris
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://geosiris-technologies.github.io/retp/
Project-URL: Homepage, https://www.geosiris.com
Project-URL: Issues, https://github.com/geosiris-technologies/retp/issues
Project-URL: Repository, https://github.com/geosiris-technologies/retp

# retp (Python)

An [ETP v1.2](https://www.energistics.org/) client for Python, over the Rust
`retp` stack: open a session with an ETP server, list its dataspaces and
resources, read and write EnergyML objects, read data arrays into numpy.

```python
import retp

with retp.connect("wss://etp.example.org/", token=token) as session:
    for space in session.dataspaces():
        print(space["path"], space["uri"])

    listed = session.resources("demo")
    objects, errors = session.get_objects([r["uri"] for r in listed["resources"]])

    values, dimensions = session.read_array(uri, "/RESQML/.../points")
    points = values.reshape(dimensions)
```

**It is only a bridge.** Every operation is a call into the Rust library
(`retp-client`, `energyml-etp-store`); the Python layer converts arguments and
results and carries no feature the Rust library does not have. What Python
needs and Rust lacks is added in Rust first.

**Objects are dictionaries**, in the EnergyML JSON encoding: every node carries
its `$type`. No generated classes. This is the same convention as
`energyml-rust`'s Python bridge (`energyml.rust`), so an object read here can be
put there, and the other way round.

**Arrays are numpy arrays**, copied out of the Rust buffer, flat and row-major,
with the dimensions beside them.

**A failure is named.** Exceptions derive from `retp.RetpError` and tell apart
what a caller does differently: reconnect (`ConnectionLost`), log in again
(`AuthorizationNeeded`), check before retrying a write (`OutcomeUnknown`), give
up on a feature (`Unsupported`). A call never returns an empty result to mean
"not supported".

**The token is never stored**: it is handed to the Rust client and is in no
`repr`, no attribute and no error message.

Status: first draft, alpha. See `DESIGN.md` for the scope, the decisions still
open, and what the Rust API must grow before the bridge
can offer more. See `ARCHITECTURE.md` for why the code is shaped as it is, and
`docs/python.md` (at the root of the repository) for the user guide.

## Install

```
pip install retp
```

TODO(verify): not published to PyPI yet. From a checkout of the repository
(needs the HDF5 C library, or add `hdf5-static` to the features for CMake and a
C compiler instead):

```
pip install maturin
cd crates/retp-python
maturin develop
```

## License

Apache-2.0.

