Skip to content

Replists

ptnad.api.replists.RepListsAPI 

RepListsAPI(client)

Methods:

Name Description
add_dynamic_list_item

Add an item to a dynamic reputation list.
bulk_add_items

Add multiple items to a dynamic reputation list.
bulk_delete_items

Delete multiple items from a dynamic reputation list.
create_list

Create a new reputation list.
delete_list

Delete a reputation list.
get_all_lists

Get all reputation lists using pagination.
get_dynamic_list_items

Get items from a dynamic reputation list.
get_list

Get information about a specific reputation list.
get_lists

Get a list of reputation lists.
get_stats

Get statistics about reputation lists.
remove_item

Remove an item from a dynamic reputation list.
update_list

Update a reputation list.
Source code in src/ptnad/api/replists.py 
8
9
def __init__(self, client) -> None:
    self.client = client

add_dynamic_list_item 

add_dynamic_list_item(external_key: str, value: str, attributes: Dict[str, Any] | None = None) -> Dict[str, Any]

Add an item to a dynamic reputation list.

Args: external_key (str): External key of the reputation list. value (str): Value to add to the list. attributes (Optional[Dict[str, Any]]): Additional attributes for the item.

Returns: Dict[str, Any]: Information about the added item.

Raises: PTNADAPIError: If there's an error adding the item.

Source code in src/ptnad/api/replists.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
def add_dynamic_list_item(self, external_key: str, value: str, attributes: Dict[str, Any] | None = None) -> Dict[str, Any]:
    """
    Add an item to a dynamic reputation list.

    Args:
        external_key (str): External key of the reputation list.
        value (str): Value to add to the list.
        attributes (Optional[Dict[str, Any]]): Additional attributes for the item.

    Returns:
        Dict[str, Any]: Information about the added item.

    Raises:
        PTNADAPIError: If there's an error adding the item.

    """
    try:
        response = self.client.post(f"/replists/dynamic/{external_key}/{value}", json=attributes or {})
        if response.status_code in (200, 201):
            return response.json()
        raise PTNADAPIError(f"Failed to add item to reputation list {external_key}: {response.text}")
    except PTNADAPIError as e:
        e.operation = f"add item to reputation list {external_key}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to add item to reputation list {external_key}: {str(e)}")

bulk_add_items 

bulk_add_items(external_key: str, items: List[Dict[str, Any]]) -> None

Add multiple items to a dynamic reputation list.

Args: external_key (str): External key of the reputation list. items (List[Dict[str, Any]]): List of items to add, each item should have 'value' and optionally 'attrs'.

Raises: PTNADAPIError: If there's an error adding the items.

Source code in src/ptnad/api/replists.py 
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
def bulk_add_items(self, external_key: str, items: List[Dict[str, Any]]) -> None:
    """
    Add multiple items to a dynamic reputation list.

    Args:
        external_key (str): External key of the reputation list.
        items (List[Dict[str, Any]]): List of items to add, each item should have 'value' and optionally 'attrs'.

    Raises:
        PTNADAPIError: If there's an error adding the items.

    """
    try:
        self.client.post(f"/replists/dynamic/{external_key}/_bulk", json=items)
    except PTNADAPIError as e:
        e.operation = f"bulk add items to reputation list {external_key}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to bulk add items to reputation list {external_key}: {str(e)}")

bulk_delete_items 

bulk_delete_items(external_key: str, values: List[str]) -> None

Delete multiple items from a dynamic reputation list.

Args: external_key (str): External key of the reputation list. values (List[str]): List of values to delete from the list.

Raises: PTNADAPIError: If there's an error deleting the items.

Source code in src/ptnad/api/replists.py 
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
def bulk_delete_items(self, external_key: str, values: List[str]) -> None:
    """
    Delete multiple items from a dynamic reputation list.

    Args:
        external_key (str): External key of the reputation list.
        values (List[str]): List of values to delete from the list.

    Raises:
        PTNADAPIError: If there's an error deleting the items.

    """
    try:
        response = self.client.post(f"/replists/dynamic/{external_key}/_delete", json=values)
        if response.status_code != 204:
            raise PTNADAPIError(f"Failed to bulk delete items from reputation list {external_key}: {response.text}")
    except PTNADAPIError as e:
        e.operation = f"bulk delete items from reputation list {external_key}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to bulk delete items from reputation list {external_key}: {str(e)}")

create_list 

create_list(name: str, type: str, color: str, description: str | None = None, content: Union[str, List[str], None] = None, external_key: str | None = None) -> Dict[str, Any]

Create a new reputation list.

Args: name (str): Name of the reputation list. Must be a valid slug (letters, numbers, underscores, hyphens). type (str): Type of the reputation list ('ip', 'dn', 'uri', or 'md5'). color (str): Color code for the reputation list ('0' to '7'). description (Optional[str]): Description of the reputation list. content (Optional[Union[str, List[str]]]): Content of the reputation list. Can be a string or a list of strings that will be joined with newlines. external_key (Optional[str]): External key for the reputation list.

Returns: Dict[str, Any]: Information about the created reputation list.

Raises: ValidationError: If the input parameters are invalid. PTNADAPIError: If there's an error creating the list.

Source code in src/ptnad/api/replists.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def create_list(self, name: str, type: str, color: str, description: str | None = None,
                content: Union[str, List[str], None] = None, external_key: str | None = None) -> Dict[str, Any]:
    """
    Create a new reputation list.

    Args:
        name (str): Name of the reputation list. Must be a valid slug (letters, numbers, underscores, hyphens).
        type (str): Type of the reputation list ('ip', 'dn', 'uri', or 'md5').
        color (str): Color code for the reputation list ('0' to '7').
        description (Optional[str]): Description of the reputation list.
        content (Optional[Union[str, List[str]]]): Content of the reputation list. Can be a string or a list of strings that will be joined with newlines.
        external_key (Optional[str]): External key for the reputation list.

    Returns:
        Dict[str, Any]: Information about the created reputation list.

    Raises:
        ValidationError: If the input parameters are invalid.
        PTNADAPIError: If there's an error creating the list.

    """
    if not self._is_valid_slug(name):
        raise ValidationError("Name must be a valid slug consisting of letters, numbers, underscores or hyphens.")

    data = {
        "name": name,
        "type": type,
        "color": color,
    }
    if description:
        data["description"] = description
    if content:
        # Convert list of strings to newline-separated string if needed
        if isinstance(content, list):
            data["content"] = "\n".join(content)
        else:
            data["content"] = content
    if external_key:
        data["external_key"] = external_key

    try:
        response = self.client.post("/replists", json=data)
        if response.status_code == 201:
            return response.json()
        error_message = response.json() if response.headers.get("Content-Type") == "application/json" else response.text
        raise PTNADAPIError(f"Failed to create reputation list. Status code: {response.status_code}. Error: {error_message}")
    except PTNADAPIError as e:
        e.operation = "create reputation list"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to create reputation list: {str(e)}")

delete_list 

delete_list(list_id: int) -> None

Delete a reputation list.

Args: list_id (int): ID of the reputation list to delete.

Raises: PTNADAPIError: If there's an error deleting the reputation list.

Source code in src/ptnad/api/replists.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def delete_list(self, list_id: int) -> None:
    """
    Delete a reputation list.

    Args:
        list_id (int): ID of the reputation list to delete.

    Raises:
        PTNADAPIError: If there's an error deleting the reputation list.

    """
    try:
        response = self.client.delete(f"/replists/{list_id}")
        if response.status_code != 204:
            raise PTNADAPIError(f"Failed to delete reputation list {list_id}: {response.text}")
    except PTNADAPIError as e:
        e.operation = f"delete reputation list {list_id}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to delete reputation list {list_id}: {str(e)}")

get_all_lists 

get_all_lists(search: str | None = None, ordering: str | None = None, limit: int = 100) -> List[Dict[str, Any]]

Get all reputation lists using pagination.

Args: search (Optional[str]): Keyword to filter the lists by name, description, or vendor name. ordering (Optional[str]): Field to sort the results by (id, name, color, type, created, modified, items_count, description, vendor__name). Use prefix with '-' for descending order. limit (int): Number of lists to fetch per request (default: 100).

Returns: List[Dict[str, Any]]: A list of dictionaries containing all reputation list information.

Raises: PTNADAPIError: If there's an error retrieving the lists.

Source code in src/ptnad/api/replists.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def get_all_lists(self, search: str | None = None, ordering: str | None = None,
                  limit: int = 100) -> List[Dict[str, Any]]:
    """
    Get all reputation lists using pagination.

    Args:
        search (Optional[str]): Keyword to filter the lists by name, description, or vendor name.
        ordering (Optional[str]): Field to sort the results by (id, name, color, type, created, modified, items_count, description, vendor__name). Use prefix with '-' for descending order.
        limit (int): Number of lists to fetch per request (default: 100).

    Returns:
        List[Dict[str, Any]]: A list of dictionaries containing all reputation list information.

    Raises:
        PTNADAPIError: If there's an error retrieving the lists.

    """
    all_lists = []
    offset = 0

    while True:
        response = self._get_lists_data(search, ordering, limit, offset)
        lists = response["results"]
        all_lists.extend(lists)

        if response["next"] is None:
            break

        offset += limit

    return all_lists

get_dynamic_list_items 

get_dynamic_list_items(external_key: str, ordering: str | None = None) -> List[Dict[str, Any]]

Get items from a dynamic reputation list.

Args: external_key (str): External key of the reputation list. ordering (Optional[str]): Field to sort the results by (value or modified).

Returns: List[Dict[str, Any]]: List of items in the reputation list.

Raises: PTNADAPIError: If there's an error retrieving the items.

Source code in src/ptnad/api/replists.py 
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
def get_dynamic_list_items(self, external_key: str, ordering: str | None = None) -> List[Dict[str, Any]]:
    """
    Get items from a dynamic reputation list.

    Args:
        external_key (str): External key of the reputation list.
        ordering (Optional[str]): Field to sort the results by (value or modified).

    Returns:
        List[Dict[str, Any]]: List of items in the reputation list.

    Raises:
        PTNADAPIError: If there's an error retrieving the items.

    """
    params = {}
    if ordering:
        params["ordering"] = ordering

    try:
        response = self.client.get(f"/replists/dynamic/{external_key}", params=params).json()
        return response["results"]
    except PTNADAPIError as e:
        e.operation = f"get items from reputation list {external_key}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to get items from reputation list {external_key}: {str(e)}")

get_list 

get_list(list_id: int) -> Dict[str, Any]

Get information about a specific reputation list.

Args: list_id (int): ID of the reputation list.

Returns: Dict[str, Any]: Information about the reputation list.

Raises: PTNADAPIError: If there's an error retrieving the list.

Source code in src/ptnad/api/replists.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def get_list(self, list_id: int) -> Dict[str, Any]:
    """
    Get information about a specific reputation list.

    Args:
        list_id (int): ID of the reputation list.

    Returns:
        Dict[str, Any]: Information about the reputation list.

    Raises:
        PTNADAPIError: If there's an error retrieving the list.

    """
    try:
        response = self.client.get(f"/replists/{list_id}").json()
        return response
    except PTNADAPIError as e:
        e.operation = f"get reputation list {list_id}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to get reputation list {list_id}: {str(e)}")

get_lists 

get_lists(search: str | None = None, ordering: str | None = None, limit: int = 100, offset: int = 0) -> List[Dict[str, Any]]

Get a list of reputation lists.

Args: search (Optional[str]): Keyword to filter the lists by name, description, or vendor name. ordering (Optional[str]): Field to sort the results by (id, name, color, type, created, modified, items_count, description, vendor__name). Use prefix '-' for descending order. limit (int): Maximum number of lists to return (default: 100). offset (int): Number of lists to skip (default: 0).

Returns: List[Dict[str, Any]]: A list of dictionaries containing reputation list information.

Raises: PTNADAPIError: If there's an error retrieving the lists.

Source code in src/ptnad/api/replists.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def get_lists(self, search: str | None = None, ordering: str | None = None,
              limit: int = 100, offset: int = 0) -> List[Dict[str, Any]]:
    """
    Get a list of reputation lists.

    Args:
        search (Optional[str]): Keyword to filter the lists by name, description, or vendor name.
        ordering (Optional[str]): Field to sort the results by (id, name, color, type, created, modified, items_count, description, vendor__name). Use prefix '-' for descending order.
        limit (int): Maximum number of lists to return (default: 100).
        offset (int): Number of lists to skip (default: 0).

    Returns:
        List[Dict[str, Any]]: A list of dictionaries containing reputation list information.

    Raises:
        PTNADAPIError: If there's an error retrieving the lists.

    """
    response = self._get_lists_data(search, ordering, limit, offset)
    return response["results"]

get_stats 

get_stats() -> Dict[str, Any]

Get statistics about reputation lists.

Returns: Dict[str, Any]: Statistics about reputation lists.

Raises: PTNADAPIError: If there's an error retrieving the statistics.

Source code in src/ptnad/api/replists.py 
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
def get_stats(self) -> Dict[str, Any]:
    """
    Get statistics about reputation lists.

    Returns:
        Dict[str, Any]: Statistics about reputation lists.

    Raises:
        PTNADAPIError: If there's an error retrieving the statistics.

    """
    try:
        response = self.client.get("/replists/stats").json()
        return response
    except PTNADAPIError as e:
        e.operation = "get reputation lists statistics"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to get reputation lists statistics: {str(e)}")

remove_item 

remove_item(external_key: str, value: str) -> None

Remove an item from a dynamic reputation list.

Args: external_key (str): External key of the reputation list. value (str): Value to remove from the reputation list.

Raises: PTNADAPIError: If there's an error removing the item.

Source code in src/ptnad/api/replists.py 
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def remove_item(self, external_key: str, value: str) -> None:
    """
    Remove an item from a dynamic reputation list.

    Args:
        external_key (str): External key of the reputation list.
        value (str): Value to remove from the reputation list.

    Raises:
        PTNADAPIError: If there's an error removing the item.

    """
    try:
        response = self.client.delete(f"/replists/dynamic/{external_key}/{value}")
        if response.status_code != 204:
            raise PTNADAPIError(f"Failed to remove item from reputation list {external_key}: {response.text}")
    except PTNADAPIError as e:
        e.operation = f"remove item from reputation list {external_key}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to remove item from reputation list {external_key}: {str(e)}")

update_list 

update_list(list_id: int, **kwargs) -> Dict[str, Any]

Update a reputation list.

Args: list_id (int): ID of the reputation list to update. **kwargs: Fields to update (color, name, type, description, content).

Returns: Dict[str, Any]: Updated information about the reputation list.

Raises: PTNADAPIError: If there's an error updating the list.

Source code in src/ptnad/api/replists.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
def update_list(self, list_id: int, **kwargs) -> Dict[str, Any]:
    """
    Update a reputation list.

    Args:
        list_id (int): ID of the reputation list to update.
        **kwargs: Fields to update (color, name, type, description, content).

    Returns:
        Dict[str, Any]: Updated information about the reputation list.

    Raises:
        PTNADAPIError: If there's an error updating the list.

    """
    try:
        response = self.client.patch(f"/replists/{list_id}", json=kwargs).json()
        return response
    except PTNADAPIError as e:
        e.operation = f"update reputation list {list_id}"
        raise
    except Exception as e:
        raise PTNADAPIError(f"Failed to update reputation list {list_id}: {str(e)}")