Skip to content

Commit ca8c508

Browse files
aiantsenaiantsen
committed
updated README
1 parent f7595ed commit ca8c508

File tree

1 file changed

+76
-26
lines changed

1 file changed

+76
-26
lines changed

‎README.md‎

Lines changed: 76 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
[![Tests](https://github.com/zabbix/python-zabbix-utils/actions/workflows/tests.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/tests.yaml)
44
[![Zabbix API](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_api.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_api.yaml)
55
[![Zabbix sender](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_sender.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_sender.yaml)
6-
[![Zabbix get](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_get.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_get.yaml)
6+
[![Zabbix get](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_getter.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_getter.yaml)
77
[![Zabbix 5.0](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_50.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_50.yaml)
88
[![Zabbix 6.0](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_60.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_60.yaml)
99
[![Zabbix 6.4](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_64.yaml/badge.svg)](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_64.yaml)
@@ -30,6 +30,10 @@ Tested on:
3030
* Zabbix 5.0, 6.0, 6.4 and pre-7.0
3131
* Python 3.8, 3.9, 3.10, 3.11 and 3.12
3232

33+
Dependencies:
34+
35+
* [aiohttp](https://github.com/aio-libs/aiohttp) (in case of async use)
36+
3337
## Documentation
3438

3539
### Installation
@@ -40,11 +44,17 @@ Install **zabbix_utils** library using pip:
4044
$ pip install zabbix_utils
4145
```
4246

47+
To install the library with dependencies for asynchronous work use the following way:
48+
49+
```bash
50+
$ pip install zabbix_utils[async]
51+
```
52+
4353
### Use cases
4454

4555
##### To work with Zabbix API
4656

47-
To work with Zabbix API you can import and use **zabbix_utils** library as follows:
57+
To work with Zabbix API via synchronous I/O you can import and use **zabbix_utils** library as follows:
4858

4959
```python
5060
from zabbix_utils import ZabbixAPI
@@ -62,20 +72,38 @@ for user in users:
6272
api.logout()
6373
```
6474

65-
You can also authenticate using an API token (supported since Zabbix 5.4):
75+
To work with Zabbix API via asynchronous I/O you can use the following way:
6676

6777
```python
68-
from zabbix_utils import ZabbixAPI
78+
import asyncio
79+
from zabbix_utils import AsyncZabbixAPI
80+
81+
async def main():
82+
api = AsyncZabbixAPI(url="127.0.0.1")
83+
await api.login(user="User", password="zabbix")
84+
85+
users = await api.user.get(
86+
output=['userid','name']
87+
)
88+
89+
for user in users:
90+
print(user['name'])
91+
92+
await api.logout()
6993

94+
asyncio.run(main())
95+
```
96+
97+
You can also authenticate using an API token (supported since Zabbix 5.4):
98+
99+
```python
70100
api = ZabbixAPI(url="127.0.0.1")
71101
api.login(token="xxxxxxxx")
102+
```
72103

73-
users = api.user.get(
74-
output=['userid','name']
75-
)
76-
77-
for user in users:
78-
print(user['name'])
104+
```python
105+
api = AsyncZabbixAPI(url="127.0.0.1")
106+
await api.login(token="xxxxxxxx")
79107
```
80108

81109
When token is used, calling `api.logout()` is not necessary.
@@ -86,14 +114,6 @@ It is possible to specify authentication fields by the following environment var
86114
You can compare Zabbix API version with strings and numbers, for example:
87115

88116
```python
89-
from zabbix_utils import ZabbixAPI
90-
91-
url = "127.0.0.1"
92-
user = "User"
93-
password = "zabbix"
94-
95-
api = ZabbixAPI(url=url, user=user, password=password)
96-
97117
# Method to get version
98118
ver = api.api_version()
99119
print(type(ver).__name__, ver) # APIVersion 7.0.0
@@ -111,11 +131,9 @@ print(ver != "7.0.0") # False
111131
print(ver.major) # 7.0
112132
print(ver.minor) # 0
113133
print(ver.is_lts()) # True
114-
115-
api.logout()
116134
```
117135

118-
In case the API object or method name matches one of Python keywords, you can use the suffix `_` in their name to execute correctly:
136+
In case the API object or method name matches one of Python keywords, you can use the suffix `_` in their name to execute correctly, for example:
119137
```python
120138
from zabbix_utils import ZabbixAPI
121139

@@ -136,7 +154,7 @@ if response:
136154
print("Template imported successfully")
137155
```
138156

139-
> Please, refer to the [Zabbix API Documentation](https://www.zabbix.com/documentation/current/manual/api/reference) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/api/synchronous) for more information.
157+
> Please, refer to the [Zabbix API Documentation](https://www.zabbix.com/documentation/current/manual/api/reference) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/api) for more information.
140158
141159
##### To work via Zabbix sender protocol
142160

@@ -152,7 +170,23 @@ print(response)
152170
# {"processed": 1, "failed": 0, "total": 1, "time": "0.000338", "chunk": 1}
153171
```
154172

155-
Or you can prepare a list of item values and send all at once:
173+
The asynchronous way:
174+
175+
```python
176+
import asyncio
177+
from zabbix_utils import AsyncSender
178+
179+
async def main():
180+
sender = AsyncSender(server='127.0.0.1', port=10051)
181+
response = await sender.send_value('host', 'item.key', 'value', 1695713666)
182+
183+
print(response)
184+
# {"processed": 1, "failed": 0, "total": 1, "time": "0.000338", "chunk": 1}
185+
186+
asyncio.run(main())
187+
```
188+
189+
You can also prepare a list of item values and send all at once:
156190

157191
```python
158192
from zabbix_utils import ItemValue, Sender
@@ -197,11 +231,11 @@ print(response.details)
197231

198232
In such case, the value will be sent to the first available node of each cluster.
199233

200-
> Please, refer to the [Zabbix sender protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_sender) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/sender/synchronous) for more information.
234+
> Please, refer to the [Zabbix sender protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_sender) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/sender) for more information.
201235
202236
##### To work via Zabbix get protocol
203237

204-
To get a value by item key from a Zabbix agent or agent 2 you can import and use the library as follows:
238+
To get a value by item key from a Zabbix agent or agent 2 via synchronous I/O the library can be imported and used as follows:
205239

206240
```python
207241
from zabbix_utils import Getter
@@ -213,7 +247,23 @@ print(resp.value)
213247
# Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
214248
```
215249

216-
> Please, refer to the [Zabbix agent protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_agent) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/get/synchronous) for more information.
250+
The library can be used via asynchronous I/O, as in the following example:
251+
252+
```python
253+
import asyncio
254+
from zabbix_utils import AsyncGetter
255+
256+
async def main():
257+
agent = AsyncGetter(host='127.0.0.1', port=10050)
258+
resp = await agent.get('system.uname')
259+
260+
print(resp.value)
261+
# Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
262+
263+
asyncio.run(main())
264+
```
265+
266+
> Please, refer to the [Zabbix agent protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_agent) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/get) for more information.
217267
218268
### Enabling debug log
219269

0 commit comments

Comments
 (0)