Skip to content

Commit 43aa3c2

Browse files
adator85adator85
authored
Merge pull request #11 from adator85/dev
Dev
2 parents 4c3d89a + 513b011 commit 43aa3c2

File tree

5 files changed

+153
-80
lines changed

5 files changed

+153
-80
lines changed

‎README.MD‎

Lines changed: 130 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -5,108 +5,167 @@
55
![Static Badge](https://img.shields.io/badge/Maintained-Yes-green)
66

77

8-
#### If you are using Python3, this package can help you to parse all json responses it does all the work for you.
9-
10-
## How to use this package
8+
## Introduction
9+
If you are using Python3, this package can help you to parse all json responses it does all the work for you.
10+
11+
## How to install this package
12+
```bash
13+
pip3 install unrealircd_rpc_py
14+
```
15+
> [!NOTE]
16+
> I recommend installing a virtual environment and then installing the package within it.
17+
18+
## How to establish the link
19+
```python
20+
# Using requests method
21+
rpc = Loader(
22+
req_method='requests',
23+
url='https://your.irc.domaine.org:8600/api',
24+
username='apiname',
25+
password='apiPASSWORD'
26+
)
1127

12-
$ pip3 install unrealircd_rpc_py
28+
# Using socket method
29+
rpc = Loader(
30+
req_method='socket',
31+
url='https://your.irc.domaine.org:8600/api',
32+
username='apiname',
33+
password='apiPASSWORD'
34+
)
1335

14-
## How to work with (remotly)
36+
# Using unixsocket method (Local only)
37+
rpc = Loader(
38+
req_method='unixsocket',
39+
path_to_socket_file='/path/to/unrealircd/data/rpc.socket'
40+
)
1541

16-
This package allows easy interfacing with UnrealIRCd through regular Python3 code, such as:
42+
# Live Connection (Local only)
43+
LiveRpc = Live(
44+
path_to_socket_file='/path/to/unrealircd/data/rpc.socket',
45+
callback_object_instance=Callback_class_instance,
46+
callback_method_name='your_method_name'
47+
)
1748

18-
from unrealircd_rpc_py.Loader import Loader
49+
```
1950

20-
# Initialize your connexion to unrealircd
21-
rpc = Loader(
22-
req_method='requests', # you can also use 'socket'
23-
url='https://your.irc.domaine.org:8600/api',
24-
username='apiname',
25-
password='apiPASSWORD'
26-
)
51+
## How to work with (remotly)
2752

28-
# Enjoy the power of JSON-RPC
53+
This package allows easy interfacing with UnrealIRCd through regular Python3 code, such as:
54+
```python
55+
from unrealircd_rpc_py.Loader import Loader
56+
57+
# Initialize your connexion to unrealircd
58+
rpc = Loader(
59+
req_method='requests', # you can also use 'socket'
60+
url='https://your.irc.domaine.org:8600/api',
61+
username='apiname',
62+
password='apiPASSWORD'
63+
)
2964

30-
User = rpc.User
31-
response = User.get('adator')
65+
# Enjoy the power of JSON-RPC
3266

33-
print(f'Nickname: {response.name}')
34-
print(f'Ip: {response.ip}')
67+
User = rpc.User
68+
response = User.get('adator')
3569

36-
Channels = rpc.Channel
37-
response = Channels.list_(_object_detail_level=3)
70+
print(f'Nickname: {response.name}')
71+
print(f'Ip: {response.ip}')
3872

39-
for chan in Channels.DB_CHANNELS:
40-
print(f'-' * 16)
41-
print(f'Channel: {chan.name}')
42-
print(f'Created on: {chan.creation_time}')
43-
print(f'Bans: {chan.bans}')
44-
print(f'Members: {chan.members}')
45-
print(f'-' * 16)
73+
Channels = rpc.Channel
74+
response = Channels.list_(_object_detail_level=3)
4675

76+
for chan in Channels:
77+
print(f'-' * 16)
78+
print(f'Channel: {chan.name}')
79+
print(f'Created on: {chan.creation_time}')
80+
print(f'Bans: {chan.bans}')
81+
print(f'Members: {chan.members}')
82+
print(f'-' * 16)
83+
```
4784
## How to work with (using unix socket locally)
4885

4986
This package allows easy interfacing with UnrealIRCd through regular Python3 code, such as:
87+
```python
88+
from unrealircd_rpc_py.Loader import Loader
5089

51-
from unrealircd_rpc_py.Loader import Loader
52-
53-
# Initialize your connexion to unrealircd
54-
rpc = Loader(
55-
req_method='unixsocket',
56-
path_to_socket_file='/path/to/unrealircd/data/rpc.socket'
57-
)
58-
59-
# Enjoy the power of JSON-RPC
90+
# Initialize your connexion to unrealircd
91+
rpc = Loader(
92+
req_method='unixsocket',
93+
path_to_socket_file='/path/to/unrealircd/data/rpc.socket'
94+
)
6095

61-
User = rpc.User
62-
response = User.get('adator')
96+
# Enjoy the power of JSON-RPC
6397

64-
print(f'Nickname: {response.name}')
65-
print(f'Ip: {response.ip}')
98+
User = rpc.User
99+
response = User.get('adator')
66100

67-
Channels = rpc.Channel
68-
response = Channels.list_(_object_detail_level=3)
101+
print(f'Nickname: {response.name}')
102+
print(f'Ip: {response.ip}')
69103

70-
for chan in Channels.DB_CHANNELS:
71-
print(f'-' * 16)
72-
print(f'Channel: {chan.name}')
73-
print(f'Created on: {chan.creation_time}')
74-
print(f'Bans: {chan.bans}')
75-
print(f'Members: {chan.members}')
76-
print(f'-' * 16)
104+
Channels = rpc.Channel
105+
response = Channels.list_(_object_detail_level=3)
77106

107+
# The auto completion should help you to find all available attributes
108+
for chan in Channels:
109+
print(f'-' * 16)
110+
print(f'Channel: {chan.name}')
111+
print(f'Created on: {chan.creation_time}')
112+
print(f'Bans: {chan.bans}')
113+
print(f'Members: {chan.members}')
114+
print(f'-' * 16)
115+
```
78116
## How to work with (using Live unix socket)
117+
```python
118+
from unrealircd_rpc_py.Live import Live
79119

80-
from unrealircd_rpc_py.Live import Live
120+
# This is un callback class that will recieve the response
121+
from TestObject import TestObject
81122

82-
# This is un callback class that will recieve the response
83-
from TestObject import TestObject
123+
InitCallbackClass = TestObject()
84124

85-
InitCallbackClass = TestObject()
125+
# The Callback method must always have 1 parameter as string
126+
liveRpc = Live(
127+
path_to_socket_file='/path/to/unrealircd/data/rpc.socket',
128+
callback_object_instance=InitCallbackClass,
129+
callback_method_name='your_method_name'
130+
)
86131

87-
# The Callback method must always have 1 parameter as string
88-
liveRpc = Live(
89-
path_to_socket_file='/path/to/unrealircd/data/rpc.socket',
90-
callback_object_instance=InitCallbackClass,
91-
callback_method_name='your_method_name'
92-
)
93-
94-
# This method will run forever and will send to your callback method the response
95-
# in SimpleNameSpace type that you can parse
96-
liveRpc.execute_async_method()
132+
# This method will run forever and will send to your callback method the response
133+
# in SimpleNameSpace type that you can parse
134+
liveRpc.subscribe()
135+
```
97136

98137
## Exemple of a Callback Class
138+
```python
139+
class CallbackObject:
99140

100-
class CallbackObject:
141+
def __init__(self) -> None:
142+
pass
101143

102-
def __init__(self) -> None:
103-
pass
144+
def run(self, json_response) -> bool:
104145

105-
def run(self, json_response) -> bool:
146+
print(json_response)
106147

107-
print(json_response)
148+
if type(json_response.result) != bool:
149+
print(json_response.result.channel)
150+
```
108151

109-
if type(json_response.result) != bool:
110-
print(json_response.result.channel)
152+
## Object that you can use in a synchrone mode
153+
```python
154+
from unrealircd_rpc_py.Loader import Loader
155+
156+
# Initialize your connexion to unrealircd using the unixsocket
157+
rpc = Loader(
158+
req_method='unixsocket',
159+
path_to_socket_file='/path/to/unrealircd/data/rpc.socket'
160+
)
111161

162+
Channel = rpc.Channel
163+
Name_ban = rpc.Name_ban
164+
Server_ban_exception = rpc.Server_ban_exception
165+
Server_ban = rpc.Server_ban
166+
Spamfilter = rpc.Spamfilter
167+
Stats = rpc.Stats
168+
User = rpc.User
169+
Whowas = rpc.Whowas
112170

171+
```

‎how_to_use_id.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
get_user = rpc.User.get('adator')
2020
print(get_user.name, get_user.hostname, sep=' / ')
21-
21+
2222
# Use Channel object
2323
Channels = rpc.Channel.list_()
2424
for c in Channels:

‎setup.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
setup(
44
name='unrealircd_rpc_py',
5-
version='0.1.0',
5+
version='0.1.1',
66
packages=find_packages(),
77
install_requires=[
88
"requests>=2.25.1"

‎unrealircd_rpc_py/Live.py‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ def __init__(self, path_to_socket_file: str, callback_object_instance: object, c
3030
self.str_response = ''
3131
self.json_response = ''
3232

33+
self.connected: bool = True
34+
3335
# Option 2 with Namespaces
3436
self.json_response_np: SimpleNamespace
3537

@@ -64,14 +66,13 @@ async def __send_to_permanent_unixsocket(self):
6466

6567
sock = socket.socket(socket.AddressFamily.AF_UNIX, socket.SocketKind.SOCK_STREAM)
6668
sock.connect(self.path_to_socket_file)
67-
connected = True
6869

6970
if not self.request:
7071
return None
7172

7273
sock.sendall(f'{self.request}\r\n'.encode())
7374

74-
while connected:
75+
while self.connected:
7576
# Recieve the data from the rpc server, decode it and split it
7677
response = sock.recv(4096).decode().split('\n')
7778

@@ -105,8 +106,22 @@ def __init_log_system(self) -> None:
105106
encoding='UTF-8',
106107
format='%(asctime)s - %(levelname)s - %(filename)s - %(lineno)d - %(funcName)s - %(message)s')
107108

108-
def execute_async_method(self):
109-
asyncio.run(self.query('log.subscribe', param={"sources": ["all"]}))
109+
def subscribe(self, param: dict = {"sources": ["all"]}):
110+
"""Subscribe to the rpc server stream
111+
param exemple:
112+
\n ["!debug","all"] would give you all log messages except for debug messages
113+
see: https://www.unrealircd.org/docs/List_of_all_log_messages
114+
Args:
115+
param (dict, optional): The ressources you want to subscribe. Defaults to {"sources": ["all"]}.
116+
"""
117+
asyncio.run(self.query('log.subscribe', param=param))
118+
119+
def unsubscribe(self):
120+
"""Run a del timer to trigger an event and then unsubscribe from the stream
121+
"""
122+
self.connected = False
123+
asyncio.run(self.query(method='rpc.del_timer', param={"timer_id":"timer_impossible_to_find_as_i_am_not_a_teapot"}))
124+
asyncio.run(self.query(method='log.unsubscribe'))
110125

111126
async def query(self, method: Union[Literal['log.subscribe', 'log.unsubscribe'], str], param: dict = {}, id: int = 123, jsonrpc:str = '2.0') -> Union[str, any, None, bool]:
112127
"""This method will use to run the queries
@@ -144,7 +159,6 @@ async def query(self, method: Union[Literal['log.subscribe', 'log.unsubscribe'],
144159
self.request = json.dumps(response)
145160

146161
await asyncio.gather(self.__send_to_permanent_unixsocket())
147-
# self.__send_to_permanent_unixsocket()
148162

149163
if self.json_response == '':
150164
return False
@@ -166,4 +180,4 @@ def set_error(self, json_error: dict):
166180
except KeyError as ke:
167181
self.Logs.error(ke)
168182
except Exception as err:
169-
self.Logs.error(err)
183+
self.Logs.error(err)

‎version.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"version": "0.1.0"
2+
"version": "0.1.1"
33
}

0 commit comments

Comments
 (0)