Skip to content
This repository was archived by the owner on Nov 14, 2025. It is now read-only.

Commit 7daa55a

Browse files
fbattellofbattello
committed
Updated Readme
1 parent 49ff9e3 commit 7daa55a

2 files changed

Lines changed: 92 additions & 92 deletions

File tree

‎README.md‎

Lines changed: 53 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,57 @@
2020
- a toolbox to create and modify NGSI-LD entities effortlessly
2121
- a NGSI-LD API client to interact with a Context Broker
2222

23+
## Features
24+
25+
### Build NGSI-LD entities
26+
27+
ngsildclient aims at :
28+
29+
- programatically generate NGSI-LD entities
30+
- load entities from JSON-LD payloads
31+
32+
Four primitives are provided `prop()`, `gprop()`, `tprop()`, `rel()` to build respectively a Property, GeoProperty, TemporalProperty and Relationship.
33+
34+
An Entity is backed by a Python dictionary that stores the JSON-LD payload.
35+
The library operates the mapping between the Entity's attributes and their JSON-LD counterpart, allowing to easily manipulate NGSI-LD value and metadata directly in Python.
36+
37+
### Features list
38+
39+
- primitives to build properties and relationships (chainable)
40+
- benefit from uri naming convention, omit scheme and entity's type, e.g. `parking = Entity("OffStreetParking", "Downtown1")`
41+
- support dot-notation facility, e.g. `reliability = parking["availableSpotNumber.reliability"]`
42+
- easily manipulate a property's value, e.g. `reliability.value = 0.8`
43+
- easily manipulate a property's metadata, e.g. `reliability.datasetid = "dataset1"`
44+
- support nesting
45+
- support multi-attribute
46+
- load/save to file
47+
- load from HTTP
48+
- load well-known sample entities, e.g. `parking = Entity.load(SmartDataModels.SmartCities.Parking.OffStreetParking)`
49+
- provide helpers to ease building some structures, e.g. PostalAddress
50+
- pretty-print entity and properties
51+
52+
### Interact with the Context Broker
53+
54+
Two clients are provided, `Client` and `AsyncClient` respectively for synchronous and asynchronous modes.
55+
56+
Prefer the synchronous one when working in interactive mode, for example to explore and visualize context data in a Jupyter notebook.
57+
Prefer the async one if you're looking for performance, for example to develop a real-time NGSI-LD Agent with a high data-acquisition frequency rate.
58+
59+
### Features list
60+
61+
- synchronous and asynchronous clients
62+
- support batch operations
63+
- support pagination : transparently handle pagination (sending as many requests as needed under the hood)
64+
- support auto-batch : transparently divide into many batch requests if needed
65+
- support queries and alternate (POST) queries
66+
- support temporal queries
67+
- support pandas dataframe as a temporal query result
68+
- support subscriptions
69+
- find subscription conflicts
70+
- SubscriptionBuilder to help build subscriptions
71+
- auto-detect broker vendor and version
72+
- support follow relationships (chainable), e.g. `camera = parking.follow("availableSpotNumber.providedBy")`
73+
2374
## Getting started
2475

2576
### Create our first parking Entity
@@ -46,47 +97,8 @@ Let's print the JSON-LD payload.
4697
e.pprint()
4798
```
4899

49-
```json
50-
{
51-
"@context": [
52-
"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld",
53-
"https://raw.githubusercontent.com/smart-data-models/dataModel.Parking/master/context.jsonld"
54-
],
55-
"id": "urn:ngsi-ld:OffStreetParking:Downtown1",
56-
"type": "OffStreetParking",
57-
"name": {
58-
"type": "Property",
59-
"value": "Downtown One"
60-
},
61-
"availableSpotNumber": {
62-
"type": "Property",
63-
"value": 121,
64-
"observedAt": "2022-10-25T08:00:00Z",
65-
"reliability": {
66-
"type": "Property",
67-
"value": 0.7
68-
},
69-
"providedBy": {
70-
"type": "Relationship",
71-
"object": "urn:ngsi-ld:Camera:C1"
72-
}
73-
},
74-
"totalSpotNumber": {
75-
"type": "Property",
76-
"value": 200
77-
},
78-
"location": {
79-
"type": "GeoProperty",
80-
"value": {
81-
"type": "Point",
82-
"coordinates": [
83-
-8.5,
84-
41.2
85-
]
86-
}
87-
}
88-
}
89-
```
100+
The result is available [here](https://raw.githubusercontent.com/Orange-OpenSource/python-ngsild-client/master/parking_sample.jsonld).<br>
101+
90102

91103
### Persist our parking in the Context Broker
92104

@@ -239,57 +251,6 @@ client.count("ParkingSpot", q='refParkingSite=="urn:ngsi-ld:OffStreetParking:por
239251
client.close()
240252
```
241253

242-
## Features
243-
244-
### Build NGSI-LD entities
245-
246-
ngsildclient aims at :
247-
248-
- programatically generating NGSI-LD entities
249-
- load entities from a JSON-LD payload and further amend
250-
251-
Four primitives are provided `prop()`, `gprop()`, `tprop()`, `rel()` to build respectively a Property, GeoProperty, TemporalProperty and Relationship.
252-
253-
An Entity is backed by a Python dictionary that stores the JSON-LD payload.
254-
The library operates the mapping between the Entity's attributes and their JSON-LD counterpart, allowing to easily manipulate NGSI-LD value and metadata directly in Python.
255-
256-
### Features list
257-
258-
- primitives to build properties and relationships (chainable)
259-
- benefit from uri naming convention, omit scheme and entity's type, e.g. `parking = Entity("OffStreetParking", "Downtown1")`
260-
- support dot-notation facility, e.g. `reliability = parking["availableSpotNumber.reliability"]`
261-
- easily manipulate a property's value, e.g. `reliability.value = 0.8`
262-
- easily manipulate a property's metadata, e.g. `reliability.datasetid = "dataset1"`
263-
- support nesting
264-
- support multi-attribute
265-
- load/save to file
266-
- load from HTTP
267-
- load well-known sample entities, e.g. `parking = Entity.load(SmartDataModels.SmartCities.Parking.OffStreetParking)`
268-
- provide helpers to ease building some structures, e.g. PostalAddress
269-
- pretty-print entity and properties
270-
271-
### Interact with the Context Broker
272-
273-
Two clients are provided, `Client` and `AsyncClient` respectively for synchronous and asynchronous modes.
274-
275-
Prefer the synchronous one when working in interactive mode, for example to explore and visualize context data in a Jupyter notebook.
276-
Prefer the async one if you're looking for performance, for example to develop a real-time NGSI-LD Agent with a high data-acquisition frequency rate.
277-
278-
### Features list
279-
280-
- synchronous and asynchronous clients
281-
- support batch operations
282-
- support pagination : transparently handle pagination (sending as many requests as needed under the hood)
283-
- support auto-batch : transparently divide into many batch requests if needed
284-
- support queries and alternate (POST) queries
285-
- support temporal queries
286-
- support pandas dataframe as a temporal query result
287-
- support subscriptions
288-
- find subscription conflicts
289-
- SubscriptionBuilder to help build subscriptions
290-
- auto-detect broker vendor and version
291-
- support follow relationships (chainable), e.g. `camera = parking.follow("availableSpotNumber.providedBy")`
292-
293254
## Where to get it
294255

295256
The source code is currently hosted on GitHub at :

‎parking_sample.jsonld‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"@context": [
3+
"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld",
4+
"https://raw.githubusercontent.com/smart-data-models/dataModel.Parking/master/context.jsonld"
5+
],
6+
"id": "urn:ngsi-ld:OffStreetParking:Downtown1",
7+
"type": "OffStreetParking",
8+
"name": {
9+
"type": "Property",
10+
"value": "Downtown One"
11+
},
12+
"availableSpotNumber": {
13+
"type": "Property",
14+
"value": 121,
15+
"observedAt": "2022-10-25T08:00:00Z",
16+
"reliability": {
17+
"type": "Property",
18+
"value": 0.7
19+
},
20+
"providedBy": {
21+
"type": "Relationship",
22+
"object": "urn:ngsi-ld:Camera:C1"
23+
}
24+
},
25+
"totalSpotNumber": {
26+
"type": "Property",
27+
"value": 200
28+
},
29+
"location": {
30+
"type": "GeoProperty",
31+
"value": {
32+
"type": "Point",
33+
"coordinates": [
34+
-8.5,
35+
41.2
36+
]
37+
}
38+
}
39+
}

0 commit comments

Comments
 (0)