Metadata-Version: 2.4
Name: cnri-doip-client
Version: 1.1.0
Summary: DOIP Client Library - Python Version
Project-URL: homepage, https://www.cordra.org
Project-URL: source, https://gitlab.com/cnri/cnri-doip-client-python
Project-URL: documentation, https://www.cordra.org/doip/doip-client-python/api-docs/index.html
Author-email: CNRI <support@cordra.org>
License-File: LICENSE.txt
Keywords: client,cordra,doip
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: cnri-json-streaming~=1.0
Requires-Dist: pyjwt[crypto]~=2.7
Requires-Dist: requests-toolbelt~=1.0
Requires-Dist: requests~=2.31
Provides-Extra: dev
Requires-Dist: types-requests~=2.31; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser~=4.0; extra == 'docs'
Requires-Dist: sphinx-autobuild~=2025.8; extra == 'docs'
Requires-Dist: sphinx-rtd-theme~=3.0; extra == 'docs'
Requires-Dist: sphinx~=8.2; extra == 'docs'
Provides-Extra: examples
Requires-Dist: ipyleaflet~=0.17; extra == 'examples'
Requires-Dist: matplotlib~=3.8; extra == 'examples'
Requires-Dist: plotext~=5.2; extra == 'examples'
Requires-Dist: simpleaudio~=1.0; extra == 'examples'
Requires-Dist: urllib3~=2.0; extra == 'examples'
Provides-Extra: test
Requires-Dist: pytest~=8.2; extra == 'test'
Description-Content-Type: text/markdown

# DOIP Client Library - Python Version

A Python client library for the [Digital Object Interface Protocol (DOIP)](https://www.dona.net/sites/default/files/2018-11/DOIPv2Spec_1.pdf).

This DOIP Client Library can be used to develop Python applications
that are based on DOIP. It provides a set of classes for
interacting with DOIP servers, including methods for making requests
and handling responses.

## Requirements

Since this is a client library, you will need a DOIP service to
connect to. The library itself does not provide a DOIP service. For
testing purposes, you can use a local service that implements DOIP,
such as [Cordra](https://www.cordra.org/download.html).
Setting up such a service is beyond the scope of this README.

This library requires Python 3.12 or later.

## Installation

    pip install cnri_doip_client

## Usage

Create a client instance using the DOIP native TCP interface:

```python
import cnri_doip_client as doip_client

service_info = doip_client.ServiceInfo(ip_address="localhost", port=9000)
client = doip_client.StandardDoipClient(service_info=service_info)
```

The DOIP API for HTTP Clients is also supported:

```python
import cnri_doip_client as doip_client

client = doip_client.StandardDoipClient("https://localhost:8443/doip"))
```

Here is an example of searching a Cordra server for all Schema objects, printing out their IDs and names:

```python
results = client.search('type:Schema')
print(f'Number of results: {results.size}')
for result in results:
    print(f'{result.id}: {result.attributes["content"]["name"]}')
```

Here is an example of retrieving a specific object by ID:

```python
import json
result = client.retrieve('20.500.123/1')
print(json.dumps(result.attributes["content"], indent=2))
```

Here is an example of creating, updating, and deleting an object. The client is created with a username and password which is used for each request:

```python
import cnri_doip_client as doip_client

password_auth_info = doip_client.PasswordAuthenticationInfo('username', 'password')
service_info = doip_client.ServiceInfo(ip_address="localhost", port=9000)
client = doip_client.StandardDoipClient(
    service_info=service_info, authentication=password_auth_info
)

dobj = doip_client.DigitalObject(
    type="Document",
    attributes={
        "content": {
          "name": 'Example Document'
        }
      }
)
dobj = client.create(dobj)
print(dobj.id)
dobj.attributes["content"]["name"] = 'Updated Example Document'
dobj = client.update(dobj)
print(dobj.attributes["content"]["name"])
client.delete(dobj.id)
dobj = client.retrieve(dobj.id)
print('Delete successful' if dobj is None else 'Error: Object found after deletion')
client.close()
```

For more information on how to use this library, see the
[API documentation](https://www.cordra.org/doip/doip-client-python/api-docs/index.html).
You can also read the [DOIP Specification](https://www.dona.net/sites/default/files/2018-11/DOIPv2Spec_1.pdf)
for more information about DOIP and its various components; Cordra documentation also includes sections on
[DOIP](https://www.cordra.org/documentation/api/doip.html) and
[the DOIP API for HTTP Clients](https://www.cordra.org/documentation/api/doip-api-for-http-clients.html).
