https://github.com/ksachdeva/ditto-client
https://github.com/ksachdeva/ditto-client
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/ksachdeva/ditto-client
- Owner: ksachdeva
- License: apache-2.0
- Created: 2025-09-22T20:10:15.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-05-24T19:55:51.000Z (about 2 months ago)
- Last Synced: 2026-06-05T21:05:31.296Z (about 2 months ago)
- Language: Python
- Size: 318 KB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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=")
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
```