Merge pull request #269 from jllorente/iptc_easy

Improve usability via iptc.easy

Author: ldx

README.md

@@ -135,6 +135,31 @@ Full documentation with API reference is available
 Examples
 ========
 
+High level abstractions
+-----------------------
+
+``python-iptables`` implements a low-level interface that tries to closely
+match the underlying C libraries. The module ``iptc.easy`` improves the
+usability of the library by providing a rich set of high-level functions
+designed to simplify the interaction with the library, for example::
+
+    >>> import iptc
+    >>> iptc.easy.dump_table('nat', ipv6=False)
+    {'INPUT': [], 'OUTPUT': [], 'POSTROUTING': [], 'PREROUTING': []}
+    >>> iptc.easy.dump_chain('filter', 'OUTPUT', ipv6=False)
+    [{'comment': {'comment': 'DNS traffic to Google'},
+      'dst': '8.8.8.8/32',
+      'protocol': 'udp',
+      'target': 'ACCEPT',
+      'udp': {'dport': '53'}}]
+    >>> iptc.easy.add_chain('filter', 'TestChain')
+    True
+    >>> rule_d = {'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
+    >>> iptc.easy.insert_rule('filter', 'TestChain', rule_d)
+    >>> iptc.easy.dump_chain('filter', 'TestChain')
+    [{'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}]
+    >>> iptc.easy.delete_chain('filter', 'TestChain', flush=True)
+
 Rules
 -----
 
@@ -546,6 +571,21 @@ or more rules, than commit it:
 The drawback is that Table is a singleton, and if you disable
 autocommit, it will be disabled for all instances of that Table.
 
+Easy rules with dictionaries
+----------------------------
+To simplify operations with ``python-iptables`` rules we have included support to define and convert Rules object into python dictionaries.
+
+    >>> import iptc
+    >>> table = iptc.Table(iptc.Table.FILTER)
+    >>> chain = iptc.Chain(table, "INPUT")
+    >>> # Create an iptc.Rule object from dictionary
+    >>> rule_d = {'comment': {'comment': 'Match tcp.22'}, 'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
+    >>> rule = iptc.easy.encode_iptc_rule(rule_d)
+    >>> # Obtain a dictionary representation from the iptc.Rule
+    >>> iptc.easy.decode_iptc_rule(rule)
+    {'tcp': {'dport': '22'}, 'protocol': 'tcp', 'comment': {'comment': 'Match tcp.22'}, 'target': 'ACCEPT'}
+
+
 Known Issues
 ============
 

doc/examples.rst

@@ -1,6 +1,31 @@
 Examples
 ========
 
+High level abstractions
+-----------------------
+
+``python-iptables`` implements a low-level interface that tries to closely
+match the underlying C libraries. The module ``iptc.easy`` improves the
+usability of the library by providing a rich set of high-level functions
+designed to simplify the interaction with the library, for example::
+
+    >>> import iptc
+    >>> iptc.easy.dump_table('nat', ipv6=False)
+    {'INPUT': [], 'OUTPUT': [], 'POSTROUTING': [], 'PREROUTING': []}
+    >>> iptc.easy.dump_chain('filter', 'OUTPUT', ipv6=False)
+    [{'comment': {'comment': 'DNS traffic to Google'},
+      'dst': '8.8.8.8/32',
+      'protocol': 'udp',
+      'target': 'ACCEPT',
+      'udp': {'dport': '53'}}]
+    >>> iptc.easy.add_chain('filter', 'TestChain')
+    True
+    >>> rule_d = {'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
+    >>> iptc.easy.insert_rule('filter', 'TestChain', rule_d)
+    >>> iptc.easy.dump_chain('filter', 'TestChain')
+    [{'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}]
+    >>> iptc.easy.delete_chain('filter', 'TestChain', flush=True)
+
 Rules
 -----
 
@@ -419,9 +444,9 @@ To simplify operations with ``python-iptables`` rules we have included support t
     >>> chain = iptc.Chain(table, "INPUT")
     >>> # Create an iptc.Rule object from dictionary
     >>> rule_d = {'comment': {'comment': 'Match tcp.22'}, 'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
-    >>> rule = iptc.Rule.from_dict(rule_d)
+    >>> rule = iptc.easy.encode_iptc_rule(rule_d)
     >>> # Obtain a dictionary representation from the iptc.Rule
-    >>> rule.to_dict()
+    >>> iptc.easy.decode_iptc_rule(rule)
     {'tcp': {'dport': '22'}, 'protocol': 'tcp', 'comment': {'comment': 'Match tcp.22'}, 'target': 'ACCEPT'}
 
 

iptc/__init__.py

@@ -10,6 +10,7 @@
 from iptc.ip4tc import (is_table_available, Table, Chain, Rule, Match, Target, Policy, IPTCError)
 from iptc.ip6tc import is_table6_available, Table6, Rule6
 from iptc.errors import *
+import iptc.easy
 
 
 __all__ = []