Skip to content

Commit 2405cbd

Browse files
bytebutcherbytebutcher
committed
Initial commit
1 parent a8764f5 commit 2405cbd

28 files changed

+3029
-2
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.idea
2+
*.egg-info
3+
__pycache__

‎README.md

+76-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,76 @@
1-
# py-display-filter
2-
Wireshark-like display filter for datastores
1+
2+
<p align="center">
3+
<img src="https://github.com/bytebutcher/python-dict-display-filter/raw/main/images/python_dict_display_filter_logo.png" alt="python_dict_display_filter Logo"/>
4+
</p>
5+
<p align="center"><font size="5">Python Dictionary Display Filter</font></p>
6+
<div align="center">
7+
8+
![made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)
9+
![PyPI](https://img.shields.io/pypi/v/python-dict-display-filter)
10+
![GitHub](https://img.shields.io/github/license/bytebutcher/python-dict-display-filter)
11+
12+
</div>
13+
<br>
14+
15+
Wireshark-like display filter for python dictionaries.
16+
17+
## Setup
18+
```commandline
19+
pip3 install python-dict-display-filter
20+
```
21+
22+
## Usage
23+
24+
The basics and the syntax of the display filter are described in the
25+
<a href="https://github.com/bytebutcher/python-dict-display-filter/raw/main/docs/USER_GUIDE.md">User Guide</a>.
26+
27+
If you want to see some advanced examples of how ```python-dict-display-filter``` can be put to use checkout the
28+
<a href="https://github.com/bytebutcher/python-dict-display-filter/raw/main/docs/EXAMPLES.md">Examples</a>.
29+
30+
If you want to use ```python-dict-display-filter``` in your own application and customize it to your needs
31+
check out the
32+
<a href="https://github.com/bytebutcher/python-dict-display-filter/raw/main/docs/DEVELOPER_GUIDE.md">Developer Guide</a>.
33+
34+
## Examples
35+
36+
Initialize ```DictDisplayFilter``` with a dictionary:
37+
```
38+
> from pydictdisplayfilter import DictDisplayFilter
39+
> actors = [
40+
{"name": ["Laurence", "Fishburne"], "age": {"born": "1961"}, "gender": "male"},
41+
{"name": ["Keanu", "Reeves"], "age": {"born": "1964"}, "gender": "male", "power": ["flight", "bulle-time"]},
42+
{"name": ["Joe", "Pantoliano"], "age": {"born": "1951"}, "gender": "male"},
43+
{"name": ["Carrie-Anne", "Moss"], "age": {"born": "1967"}, "gender": "female"}
44+
]
45+
> ddf = DictDisplayFilter(actors)
46+
```
47+
48+
Show only actors with some kind of super-power:
49+
```
50+
> ddf.filter("power")
51+
```
52+
53+
Show only actors which were born before 1965:
54+
```
55+
> ddf.filter("age.born < 1965")
56+
```
57+
58+
Show only female actors:
59+
```
60+
> ddf.filter("gender == female")
61+
```
62+
63+
Show all male actors which are born between 1960 and 1965:
64+
```
65+
> ddf.filter("gender == male and (age.born > 1960 and age.born < 1965)")
66+
```
67+
68+
Show all actors which name contain the character 'e':
69+
```
70+
> ddf.filter("name contains e")
71+
```
72+
73+
Show all actors which name matches a regular expression:
74+
```
75+
> ddf.filter("name matches .*e$")
76+
```

‎data/csv_example.csv

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
"name","age","gender","killed"
2+
"Morpheus",38,"male",False
3+
"Neo",35,"male",False
4+
"Cipher",48,"male",True
5+
"Trinity",32,"female",False

‎data/nmap_example.xml

+481
Large diffs are not rendered by default.

‎docs/DEVELOPER_GUIDE.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<p align="center">
2+
<img src="https://github.com/bytebutcher/pydictdisplayfilter/raw/main/images/python_dict_display_filter_logo.png" alt="python_dict_display_filter Logo"/>
3+
</p>
4+
<p align="center"><font size="5">Python Dictionary Display Filter</font></p>
5+
<p align="center"><font size="5">Developer Guide</font></p>
6+
<br>
7+
8+
## Customizing Display Filters
9+
10+
The display filter can be customized to your needs. The constructor of the ```BaseDisplayFilter``` accepts following
11+
parameters:
12+
13+
| Parameter | Description |
14+
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
15+
| ```data``` | A list of dictionaries to filter on. |
16+
| ```field_names``` | A list of field names which are allowed in the display filter. If no field names are given there are no restrictions regarding specifying field names in the display filter query.<br/> However, in some cases it may make sense to allow only a set of ```field names``` to be queried and disallow others. |
17+
| ```functions``` | A dictionary of functions whereby the key specifies the name of the function. If no functions are supplied "len", "lower" and "upper" are used as default ones. <br/>If you don't require functions you may provide an empty dictionary. |
18+
| ```slicers``` | A list of slicers. If no slicers are supplied the BasicSlicer is used per default. If you require additional slicers you can provide your own list here. |
19+
| ```evaluator``` | A evaluator which does the evaluation of the expressions. If no evaluator is defined the ```DefaultEvaluator``` is used which supports all kind of types.<br/> If you want to down-trim or extend evaluation you can provide a custom evaluator here. |
20+
21+
## Exceptions
22+
23+
The ```python-dict-display-filter``` defines some custom exceptions which may be thrown during runtime:
24+
25+
| Exception | Description |
26+
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
27+
| ```ParserError``` | This error indicates that there was an error during parsing the display filter which usually happens when the user input (aka the display filter) is not correctly specified. |
28+
| ```EvaluationError``` | This error indicates that there was an error during evaluating an expression which usually happens when some illegal operations are performed (e.g. 'lower(int)' -> only works with strings). |
29+
| ```ProgrammingError``` | This error indicates an internal error likely due to some programming error. If this error is thrown please open a ticket. |
30+
31+
## Helpers
32+
33+
The ```python-dict-display-filter``` defines a set of helpers which may be used in standalone applications:
34+
35+
| Helper Class | Description |
36+
|------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
37+
| ```DictDisplayFilterShell``` | A command line loop which allows to filter data on a provided data store. Uses DictTable to print the result in a pretty table. |
38+
| ```DictTable``` | Initialized with a data store, provides a filter method, prints results in a pretty table. |

‎docs/EXAMPLES.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
<p align="center">
2+
<img src="https://github.com/bytebutcher/pydictdisplayfilter/raw/main/images/python_dict_display_filter_logo.png" alt="python_dict_display_filter Logo"/>
3+
</p>
4+
<p align="center"><font size="5">Python Dictionary Display Filter</font></p>
5+
<p align="center"><font size="5">Examples</font></p>
6+
<br>
7+
8+
### CSV Display Filter
9+
10+
This example shows how easy it is to create a display filter for CSV-files:
11+
```commandline
12+
python3 examples/csv_display_filter.py data/example.csv
13+
# Enter ?help for a list of commands.
14+
```
15+
```
16+
> fields
17+
name
18+
age
19+
gender
20+
killed
21+
```
22+
```
23+
> filter name == Neo
24+
25+
name | age | gender | killed
26+
---- | --- | ------ | ------
27+
Neo | 35 | male | False
28+
29+
1 row in set (0.01 secs)
30+
```
31+
32+
See <a href="https://github.com/bytebutcher/python-dict-display-filter/raw/main/examples/csv_display_filter.py">examples/csv_display_filter.py</a> for the actual source code.
33+
34+
### Nmap Display Filter
35+
36+
This example shows how easy it is to create a display filter for nmap-xml-files:
37+
```commandline
38+
python3 examples/nmap_display_filter.py -iC data/nmap_example.xml
39+
# Enter ?help for a list of commands.
40+
```
41+
```
42+
> fields
43+
host
44+
port
45+
protocol
46+
status
47+
service
48+
```
49+
```
50+
> filter port == 179
51+
52+
host | port | protocol | status | service
53+
------------ | ---- | -------- | ------ | -------
54+
72.14.207.99 | 179 | tcp | closed | bgp
55+
72.14.253.83 | 179 | tcp | closed | bgp
56+
57+
2 rows in set (0.01 secs)
58+
```
59+
```
60+
> filter lower(service) ~= apache
61+
62+
host | port | protocol | status | service
63+
-------------- | ---- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------
64+
66.35.250.168 | 80 | tcp | open | product: Apache httpd version: 1.3.39 extrainfo: (Unix) PHP/4.4.7
65+
64.13.134.48 | 80 | tcp | open | product: Apache httpd version: 2.2.2 extrainfo: (Fedora)
66+
204.152.191.37 | 80 | tcp | open | product: Apache httpd version: 2.2.2 extrainfo: (Fedora)
67+
199.185.137.3 | 80 | tcp | open | product: Apache httpd
68+
204.152.190.12 | 80 | tcp | open | product: Apache httpd version: 2.0.61 extrainfo: (Unix) mod_ssl/2.0.61 DAV/2 mod_fastcgi/2.4.2 mod_apreq2-20051231/2.6.0
69+
204.152.190.12 | 443 | tcp | open | product: Apache httpd version: 2.0.61 extrainfo: mod_ssl/2.0.61 DAV/2 mod_fastcgi/2.4.2 mod_apreq2-20051231/2.6.0 hostname: rt.NetBSD.org
70+
71+
6 rows in set (0.01 secs)
72+
```
73+
74+
See <a href="https://github.com/bytebutcher/python-dict-display-filter/raw/main/examples/nmap_display_filter.py">examples/nmap_display_filter.py</a> for the actual source code.

0 commit comments

Comments
 (0)