From e55ae7bbe1584d48bc0a5246dc7787cdc71f1d35 Mon Sep 17 00:00:00 2001
From: anima <p.schreiner@4nima.de>
Date: Fri, 7 Mar 2025 18:41:08 +0100
Subject: [PATCH] add basic docs

---
 PiholeAPI.py |  2 ++
 README.md    | 49 ++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/PiholeAPI.py b/PiholeAPI.py
index ad8de48..eb7e2bc 100644
--- a/PiholeAPI.py
+++ b/PiholeAPI.py
@@ -141,6 +141,8 @@ class PiholeAPI:
     def delete_session(self, session_id: int = None) -> bool:
         """Delete session by ID
 
+            with no arguments it will clear it own session
+
         Args:
             session_id (int, optional): Session ID get from get_sessions. Defaults to None.
 
diff --git a/README.md b/README.md
index 81f0b8a..5c1ff94 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,54 @@
 # API Wrapper: Pi-hole
 >A basic API wrapper for Pi-hole
 
-## Functions
+## Usage Pihole v6 (PiholeAPI.py)
+> still in progress...
+### base usage
+```python
+pih = PiholeAPI() # if pihole.json exists
+pih = PiholeAPI(host='10.10.10.10', password='mypassword') # without conf file
+```
+
+### auth handling
+```python
+pih.need_auth() # get a valid session if no auth required
+pih._check_auth() # check if wrapper has a valid session stored
+pih.do_auth() # (runs automaticly if need) do a auth with password
+pih.get_sessions() # get all known sessions (webgui sessions too...)
+pih.delete_session() # delet a session by id (collect from get_sessions) - withour parameters it will clear it own sessions
+pih.clear_sessions() # delete all sessions without it own
+pih.get_app_password() # generate a app password. good for use without TOTP. clears all sessions! (Hint: must be set in config, not implementet at now)
+```
+
+### metric handling
+```python
+pih.get_history() # Get activity graph data of dns querys
+pih.get_history_timerange() # bugged!
+pih.get_client_history() # Get per-client activity graph data of dns querys
+pih.get_client_history_timerange() # bugged!
+pih.get_queries() # Request query details.
+```
+
+### config handling
+```python
+pih.get_config() # get full running config
+pih.get_config('dns/hosts') # get full tree but only ['dns']['hosts'] be filled
+pih.patch_config(config) # send config update, all given elemnts will be overriden. config from get_config can be use.
+```
+
+#### custom dns handling
+```python
+pih.get_dns_host(['ip', 'fqdn']) # get a custom dns hosts als list
+# return: [[ip, fqdn], [ip, fqdn]]
+pih.remove_dns_host(['', 'fqdn'], match_ip=False) # get all custom dns hosts als list which match fqdn only
+pih.remove_dns_host(['ip', ''], match_fqdn=False) # get all custom dns hosts als list which match ip only
+pih.add_dns_host(['ip', 'fqdn']) # add new custom dns host. checks fist if identical host exists
+pih.remove_dns_host(['ip', 'fqdn']) # remove a host which match ip and fqdn
+pih.remove_dns_host(['', 'fqdn'], match_ip=False) # remove all hosts which match fqdn only
+pih.remove_dns_host(['ip', ''], match_fqdn=False) # remove all hosts which match ip only
+```
+
+## Usage Pihole v5 and below (Pihole.py)
 ### Custom DNS
 Read, add or delete a custom dns entry (no cname's!)
 ```python