Metadata-Version: 2.4
Name: ditto-client
Version: 0.4.0
Summary: Eclipse Ditto Python Client
Project-URL: repository, https://github.com/ksachdeva/ditto-client
Author: Sachdeva, Kapil
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonpatch>=1.33
Requires-Dist: microsoft-kiota-abstractions>=1.9.7
Requires-Dist: microsoft-kiota-http>=1.9.7
Requires-Dist: microsoft-kiota-serialization-form>=1.9.7
Requires-Dist: microsoft-kiota-serialization-json>=1.9.7
Requires-Dist: microsoft-kiota-serialization-multipart>=1.9.7
Requires-Dist: microsoft-kiota-serialization-text>=1.9.7
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: pydantic>=2.11.5
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

# Eclipse Ditto Client

Eclipse Ditto Project - https://eclipse.dev/ditto/index.html

This repository is the python client generated using Microsoft Kiota ([https://github.com/microsoft/kiota-python](https://github.com/microsoft/kiota-python)) and a CLI based client.

## Install

```bash
uv add ditto-client
```

## Running Ditto

There are 3 modes in which you can run Eclipse Ditto from this repository

### Mode 1

A docker compose that has `nginx` as a reverse proxy and configured to do Basic Authentication.

```bash
# to start nginx reverse proxy based setup (that uses Basic Authentication)
uv run poe compose-ba-up
```

```bash
# to stop nginx reverse proxy based setup
uv run poe compose-ba-down
```

### Mode 2

A docker compose that exposes the Eclipse Ditto Gateway at port 8081 and sets ENABLE_PRE_AUTHENTICATION=true

In this mode, the client application directly talks to the gateway and sets the header

```bash
# to start with out nginx and pre-auth setup
uv run poe compose-pre-up
```

```bash
# to stop
uv run poe compose-pre-down
```

### Mode 3

A docker compose that exposes the Eclipse Ditto Gateway at port 8081 and sets ENABLE_PRE_AUTHENTICATION=false
and requires JWT based authentication

In this mode, the client application first gets the JWT token from the issuer and then pass it to the gateway

> Look at assets/ditto/ditto-gateway-jwt.yml to learn about the settings (A mock oauth server is included)

```bash
# to start with out nginx and pre-auth setup
uv run poe compose-jwt-up
```

```bash
# to stop
uv run poe compose-jwt-down
```

## Usage - API

***Basic Authentication***

```python
auth_provider = BasicAuthProvider(user_name=_USERNAME, password=_PASSWORD)

request_adapter = HttpxRequestAdapter(auth_provider)
request_adapter.base_url = "http://host.docker.internal:8080"

ditto_client = DittoClient(request_adapter)

response = await ditto_client.api.two.things.get()
```

Default setup for Ditto uses Ngix with basic authentication. A custom authentication provider has been included
in the library to support it. See [BasicAuth Provider](src/ditto_client/basic_auth.py).

[See examples/basic.py for the full usage](examples/basic.py)

***Pre Authentication***

```python
auth_provider = PreAuthProvider(auth_subject="ditto:ditto")

request_adapter = HttpxRequestAdapter(auth_provider)
# Note the port is that of gateway
request_adapter.base_url = "http://host.docker.internal:8081"

ditto_client = DittoClient(request_adapter)

response = await ditto_client.api.two.things.get()
```

A custom authentication provider has been included. See [PreAuth Provider](src/ditto_client/pre.py).

[See examples/pre.py for the full usage](examples/pre.py)


**JWT Authentication**

```python
auth_provider = JWTAuthProvider(token=<your_token>")

request_adapter = HttpxRequestAdapter(auth_provider)
# Note the port is that of gateway
request_adapter.base_url = "http://host.docker.internal:8081"

ditto_client = DittoClient(request_adapter)

response = await ditto_client.api.two.things.get()
```

A custom authentication provider has been included. See [JWTAuth Provider](src/ditto_client/jwt.py).

[See examples/jwt.py for the full usage](examples/jwt.py)


## Usage - CLI

The Ditto client includes a comprehensive CLI for interacting with Eclipse Ditto services. The CLI provides the following commands:

```markdown
 Usage: ditto-client [OPTIONS] COMMAND [ARGS]...

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --loglevel            -l      TEXT                  Set the logging level (debug, info, warning, error, critical) [default: warning]                                        │
│ --base-url                    TEXT                  Base URL for the Ditto API (can also be set via DITTO_BASE_URL environment variable) [env var: DITTO_BASE_URL]          │
│                                                     [default: http://host.docker.internal:8080]                                                                             │
│ --auth-type                   [basic|pre-auth|jwt]  Set the authentication type (basic, pre-auth) [default: basic]                                                          │
│ --username                    TEXT                  Username for basic authentication (can also be set via DITTO_USERNAME environment variable) [env var: DITTO_USERNAME]   │
│ --password                    TEXT                  Password for basic authentication (can also be set via DITTO_PASSWORD environment variable) [env var: DITTO_PASSWORD]   │
│ --preauth-subject             TEXT                  Auth subject for pre-authentication (can also be set via DITTO_PREAUTH_SUBJECT environment variable)                    │
│                                                     [env var: DITTO_PREAUTH_SUBJECT]                                                                                        │
│ --jwt-token                   TEXT                  JWT token for authentication (can also be set via DITTO_JWT_TOKEN environment variable) [env var: DITTO_JWT_TOKEN]      │
│ --table                                             Output results as a rich table instead of JSON                                                                          │
│ --install-completion                                Install completion for the current shell.                                                                               │
│ --show-completion                                   Show completion for the current shell, to copy it or customize the installation.                                        │
│ --help                                              Show this message and exit.                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ whoami       Get current user information.                                                                                                                                  │
│ policy       Policy management                                                                                                                                              │
│ thing        Thing management                                                                                                                                               │
│ search       Thing search                                                                                                                                                   │
│ permission   Permission check                                                                                                                                               │
│ devops       DevOps                                                                                                                                                         │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### Global Configuration

You can pass various secrets on the command line and/or use the `.env` file.

See `.env.example` for the entries

---

### Policy Management

#### Create a new policy.

```bash
# Create a new policy
ditto-client policy create "my.sensors:sensor-policy" examples/cli-examples/policy.json
```

#### Retrieve a specific policy by ID.

```bash
# Get a policy
ditto-client policy get "my.sensors:sensor-policy"
```

#### List policy entries.

```bash
# List all policy entries
ditto-client policy entries "my.sensors:sensor-policy"
```

#### Delete policy.

```bash
# Delete a policy
ditto-client policy delete "my.sensors:sensor-policy"
```

---

### Things Management

#### Create a new thing.

```bash
# Make sure to create the policy (my.sensors:sensor-policy) See above example
# Create a new thing
ditto-client thing create "my.sensors:sensor-001" examples/cli-examples/thing-humidity.json
```

#### List all things with optional filtering.

```bash
# List all things
ditto-client thing list

# List things with specific fields
ditto-client thing list --fields "thingId,attributes"

# List specific things by ID
ditto-client thing list --ids "my.sensors:sensor-001"
```

#### Retrieve a specific thing by ID.

```bash
# Get a specific thing
ditto-client thing get "my.sensors:sensor-001"

# Get a specific revision of a thing
ditto-client thing get "my.sensors:sensor-001" --revision 1
```

#### Update a thing using JSON file.

```bash
# Update a thing
ditto-client thing update "my.sensors:sensor-001" examples/cli-examples/thing-humidity.json
```

#### Compare current thing with historical revision.

```bash
# Compare current state with revision 1
ditto-client thing diff "my.sensors:sensor-001" 1
```

#### Delete a thing.

```bash
# Delete a thing
ditto-client thing delete "my.sensors:sensor-001"
```

---

### Search Operations

Refer below documentation to understand RQL syntax:
https://eclipse.dev/ditto/1.5/basic-rql.html

#### Search for things using RQL (Resource Query Language).

```bash
# Search all things
ditto-client search query

# Search with filter
ditto-client search query --filter 'eq(attributes/location,"Kitchen")'

# Search with size limit and sorting
ditto-client search query --option "size(3),sort(+thingId)"

# Search in specific namespaces
ditto-client search query --namespaces "my.sensors"
```

#### Count things matching search criteria.

```bash
# Count all things
ditto-client search count

# Count things with filter
ditto-client search count --filter 'eq(attributes/location,"Kitchen")'
```

---

### Connection Management (DevOps)

#### Create a new connection.

```bash
# Create a connection
ditto-client devops connection create "new-connection" examples/cli-examples/connection.json
```

#### List all connections.

```bash
# List all connections
ditto-client devops connection list

# List with specific fields
ditto-client devops connection list --fields "id,connectionStatus"
```

#### Retrieve a specific connection by ID.

```bash
# Get a connection
ditto-client devops connection get "new-connection"

# Get with specific fields
ditto-client devops connection get "new-connection" --fields "id,status"
```

#### Delete a connection.

```bash
# Delete a connection
ditto-client devops connection delete "new-connection"
```

---

### Configuration Management (DevOps)

#### Retrieve service configuration.

```bash
# Get all configuration
ditto-client devops config get
```

---

### Logging Management (DevOps)

#### Retrieve logging configuration.

```bash
# Get logging configuration
ditto-client devops logging get

# Get module-specific config
ditto-client devops logging get --module-name "gateway"
```

#### Update logging configuration.

```bash
# Update logging configuration
ditto-client devops logging update examples/cli-examples/logging.json
```

---

### Permission Management (DevOps)

#### Check permissions on specified resources.

```bash
# Check permissions
ditto-client permission check examples/cli-examples/permission.json
```

---


#### Get current user information.

```bash
# Get current user info
ditto-client whoami
```
