Added some comments and basic write support

Crx/connection.py

@@ -1,10 +1,10 @@
-from typing import Union, List
+from typing import Union, List, Optional
 
 import requests
 from urllib.parse import urljoin
 
 from .simplenode import SimpleNode
-
+from .patchbuilder import PatchBuilder
 
 # TODO validation
 
@@ -47,18 +47,38 @@ class Connection:
                  query: str = CRX_QUERY,
                  image_references: str = WCM_REFERENCES):
 
-        self.host = f'{protocol}://{host}:{port}'
-        self.data_root = self.host + root
-        self.query_path = self.host + query
-        self.image_references = self.host + image_references
+        self._host = f'{protocol}://{host}:{port}'
+        self._data_root = self._host + root
+        self._query_path = self._host + query
+        self._image_references = self._host + image_references
 
-        self.session = requests.session()
+        self._session = requests.session()
+
+        self._patch_builder: Optional[PatchBuilder] = None
 
     def login_basic(self, username: str, password: str):
-        self.session.auth = (username, password)
+        """
+        Set the credentials to use for this connection.
+
+        Args:
+            username: The username to use
+            password: The password to use
+        """
+        self._session.auth = (username, password)
 
     def query(self, query: str, query_type: str = 'SQL2') -> List[str]:
-        response = self.session.get(self.query_path, params={
+        """
+        Perform an query and return the matching paths.
+        Query may be an XPATH, SQL or SQL2 Query
+
+        Args:
+            query: The query to perform
+            query_type: The type of the query (defaults to SQL2)
+
+        Returns:
+            The matching paths of the query
+        """
+        response = self._session.get(self._query_path, params={
             '_charset': 'utf-8',
             'type': QUERY_TYPES.get(query_type, query_type),
             'stmt': query,
@@ -71,15 +91,35 @@ class Connection:
         return list(map(lambda node: node['path'], data['results']))
 
     def get_image_references(self, path: str):
-        response = self.session.get(self.image_references, params={
+        """
+        Find all image references for a given image resource.
+        This uses the DAM Asset Manager > Image > File References tap's backend
+
+        Args:
+            path: The path of the image to check (no the rendition)
+
+        Returns:
+            The references of the image (see Chrome/Firefox developer tab for details)
+        """
+        response = self._session.get(self._image_references, params={
             'path': path
         })
         return response.json()['pages']
 
     def get_node_raw(self, path: str):
-        url = urljoin(self.data_root, '.' + path + JSON_DATA_EXTENSION)
+        """
+        Get the raw JSON dictionary of a node.
+        This is mostly an internal method.
+
+        Args:
+            path: The path of the node
+
+        Returns:
+            A dict representing the node
+        """
+        url = urljoin(self._data_root, '.' + path + JSON_DATA_EXTENSION)
         try:
-            response = self.session.get(url)
+            response = self._session.get(url)
         except requests.exceptions.RequestException as exception:
             raise CrxException()  # todo more specific exceptions
 
@@ -90,21 +130,44 @@ class Connection:
 
         return data
 
+    def get_simple_node(self, path: str) -> SimpleNode:
+        """
+        Get a Node as a `SimpleNode` object.
+
+        Args:
+            path: The path of the node
+
+        Returns:
+            The SimpleNode object for that path
+        """
+        return SimpleNode(path, self.get_node_raw(path), self)
+
     def download_binary(self, path: str) -> bytes:
+        """
+        Download the binary data of a node. (usually jcr:data).
+        Usually called via `SimpleNode.download()`
+
+        Args:
+            path: The path of the node property to download
+
+        Returns:
+            The binary content of the response
+        """
         # TODO verify if it is not b64 encoded. for some reason it is in FireFox
-        resp = self.session.get(
-            urljoin(self.data_root, '.' + path)
+        resp = self._session.get(
+            urljoin(self._data_root, '.' + path)
         )
         return resp.content
 
-    def get_simple_node(self, path: str) -> SimpleNode:
-        return SimpleNode(path, self.get_node_raw(path), self)
-
     def rename_node(self, old_path: str, new_path: str):
         diff = f'>{old_path} : {new_path}'
-        resp = self.session.post(self.data_root, data={':diff': diff})
+        resp = self._session.post(self._data_root, data={':diff': diff})
         resp.raise_for_status()
 
+    def start_patch_builder(self) -> PatchBuilder:
+        self._patch_builder = PatchBuilder(self)
+        return self._patch_builder
+
     def apply_diff(self, diff: Union[str, bytes]):
         files = {
             ':diff': (
@@ -114,5 +177,5 @@ class Connection:
             )
         }
         # todo check for exception
-        resp = self.session.post(self.data_root, files=files)
+        resp = self._session.post(self._data_root, files=files)
         resp.raise_for_status()