Improve documentation

README.md

@@ -4,8 +4,9 @@ python-hosts
 
 
 This is a python library for managing a hosts file.
-It enables you to add and remove entries, or import them from a file or URL.
-Utility functions have been streamlined for easier maintenance.
+It enables you to add and remove entries, import them from a file or URL and
+query existing entries. Utility functions have been streamlined for easier
+maintenance.
 It remains compatible with Python 2.7 as well as modern Python 3 releases.
 
 Documentation
@@ -21,21 +22,30 @@ pip install python-hosts
 
 Example usage
 ------------
-Adding an entry to a hosts file
+Create a ``Hosts`` instance and add an entry::
 
     from python_hosts import Hosts, HostsEntry
     hosts = Hosts(path='hosts_test')
     new_entry = HostsEntry(entry_type='ipv4', address='1.2.3.4', names=['www.example.com', 'example'])
     hosts.add([new_entry])
     hosts.write()
 
-Importing a list of host entries by URL
+Import entries from a URL or file::
 
-    from python_hosts import Hosts
-    hosts = Hosts(path='hosts_test')
-    hosts.import_url(url='https://gist.githubusercontent.com/jonhadfield/5b6cdf853ef629f9b187345d89157280/raw/ddfa4a069fb12bf3c1f285249d44922aeb75db3f/hosts')
+    hosts.import_url('https://example.com/hosts')
+    hosts.import_file('extra_hosts')
     hosts.write()
 
+Remove or query entries::
+
+    hosts.remove_all_matching(name='example')
+    hosts.exists(address='1.2.3.4')
+
+Entries can also be merged with existing ones::
+
+    new_entry = HostsEntry(entry_type='ipv4', address='1.2.3.4', names=['alias'])
+    hosts.add([new_entry], merge_names=True)
+
 CLI
 ---
 A command line client using python-hosts can be found here: https://github.com/jonhadfield/hostman

docs/usage.rst

@@ -1,23 +1,42 @@
 Usage
 =====
-**Create an instance of a hosts file**::
 
- from python_hosts import Hosts, HostsEntry
- my_hosts = Hosts()
+Basic operations
+----------------
 
-**Add an entry**::
+Create an instance of a hosts file (the default path for the current platform
+is used when ``path`` is not supplied)::
 
- new_entry = HostsEntry(entry_type='ipv4', address='1.2.3.4', names=['example.com', 'example'])
- my_hosts.add([new_entry])
+    from python_hosts import Hosts, HostsEntry
+    my_hosts = Hosts()
 
-**Remove an entry/entries matching an address**::
+Add an entry::
 
- my_hosts.remove_all_matching(address='1.2.3.4')
+    new_entry = HostsEntry(entry_type='ipv4', address='1.2.3.4', names=['example.com', 'example'])
+    my_hosts.add([new_entry])
 
-**Remove an entry/entries matching an address**::
+Remove entries by address or name::
 
- my_hosts.remove_all_matching(name='example.com')
+    my_hosts.remove_all_matching(address='1.2.3.4')
+    my_hosts.remove_all_matching(name='example.com')
 
-**Write entries**::
+Write changes back to disk::
 
- my_hosts.write()
+    my_hosts.write()
+
+Additional features
+-------------------
+
+Import entries from a file or URL::
+
+    my_hosts.import_file('extra_hosts')
+    my_hosts.import_url('https://example.com/hosts')
+
+Check if a host entry exists::
+
+    my_hosts.exists(address='1.2.3.4')
+
+Merge names with an existing entry while keeping the same address::
+
+    new_entry = HostsEntry(entry_type='ipv4', address='1.2.3.4', names=['alias'])
+    my_hosts.add([new_entry], merge_names=True)