Fix some docstrings

Janos Tolgyesi · Janos Tolgyesi · commit 5ea45ecb1e4c · 2023-07-28T18:24:58.000+02:00
diff --git a/docs/Makefile b/docs/Makefile
@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
+SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = dynamodb_mapping
 SOURCEDIR     = .
 BUILDDIR      = _build
diff --git a/docs/conf.py b/docs/conf.py
@@ -31,7 +31,12 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -64,7 +69,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -77,13 +82,12 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output -------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
@@ -94,7 +98,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 
 # -- Options for HTMLHelp output ---------------------------------------
@@ -105,7 +109,7 @@
 
 # -- Options for LaTeX output ------------------------------------------
 
-latex_elements = {
+# latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
@@ -121,7 +125,7 @@
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
-}
+# }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
@@ -159,4 +163,19 @@
 ]
 
 
+# =======
+
 
+autodoc_typehints = 'description'
+autodoc_member_order = 'bysource'
+add_module_names = False
+autodoc_default_options = {
+    'special-members': '__iter__,__len__,__getitem__,__setitem__,__delitem__',
+    'undoc-members': False,
+}
+
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/3', None),
+    'boto3': ('https://boto3.amazonaws.com/v1/documentation/api/latest/', None),
+    'botocore': ('https://botocore.readthedocs.io/en/latest/', None),
+}
diff --git a/docs/dynamodb_mapping.rst b/docs/dynamodb_mapping.rst
@@ -12,6 +12,14 @@ dynamodb\_mapping.dynamodb\_mapping module
    :undoc-members:
    :show-inheritance:
 
+dynamodb\_mapping.utils module
+------------------------------
+
+.. automodule:: dynamodb_mapping.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 
diff --git a/dynamodb_mapping/dynamodb_mapping.py b/dynamodb_mapping/dynamodb_mapping.py
@@ -67,7 +67,7 @@ def get_key_names(table: DynamoDBTable) -> DynamoDBKeyName:
 
     Returns:
         DynamoDBKeyName: A tuple with either one (if only the partition key is defined on the table)
-            or two (if both the partition and range key is defined) elements.
+        or two (if both the partition and range key is defined) elements.
     """
     schema: Dict[str, str] = {s["KeyType"]: s["AttributeName"] for s in table.key_schema}
     return (schema["HASH"], schema["RANGE"]) if "RANGE" in schema else (schema["HASH"], )
@@ -204,31 +204,31 @@ class DynamoDBMapping(MutableMapping):
     You have the following options to configure the underlying boto3 session:
 
     - Automatic configuration: pass nothing to DynamoDBMapping initializer. This will prompt
-    DynamoDBMapping to load the default `Session` object, which in turn will use the standard boto3
-    credentials chain to find AWS credentials (e.g., the ~/.aws/credentials file, environment
-    variables, etc.).
-    - Pass a preconfigured boto3 `Session` object
-    - Pass `aws_access_key_id` and `aws_secret_access_key` as keyword arguments. Additionally,
-    the optional `aws_region` and `aws_profile` arguments are also considered.
+      DynamoDBMapping to load the default ``boto3.Session`` object, which in turn will use the
+      standard boto3 credentials chain to find AWS credentials (e.g., the ``~/.aws/credentials``
+      file, environment variables, etc.).
+    - Pass a preconfigured ``boto3.Session`` object
+    - Pass ``aws_access_key_id`` and ``aws_secret_access_key`` as keyword arguments. Additionally,
+      the optional ``aws_region`` and ``aws_profile`` arguments are also considered.
 
-    Example:
-    ```python
-    from dynamodb_mapping import DynamoDBMapping
-    mapping = DynamoDBMapping(table_name="my_table")
+    Example::
 
-    # Iterate over all items:
-    for key, value in mapping.items():
-        print(key, value)
+        from dynamodb_mapping import DynamoDBMapping
+        mapping = DynamoDBMapping(table_name="my_table")
 
-    # Get a single item:
-    print(mapping["my_key"])
+        # Iterate over all items:
+        for key, value in mapping.items():
+            print(key, value)
 
-    # Create or modify an item:
-    mapping["my_key"] = {"description": "foo", "price": 123}
+        # Get a single item:
+        print(mapping["my_key"])
+
+        # Create or modify an item:
+        mapping["my_key"] = {"description": "foo", "price": 123}
+
+        # Delete an item:
+        del mapping["my_key"]
 
-    # Delete an item:
-    del mapping["my_key"]
-    ```
 
     All methods that iterate over the elements of the table do so in a lazy manner, in that the
     successive pages of the scan operation are queried only on demand. Examples of such operations
@@ -238,17 +238,17 @@ class DynamoDBMapping(MutableMapping):
     your table, which can be costly, and attempt to load all items into memory, which can be
     resource-demanding if your table is particularly large.
 
-    The `__len__` implementation of this class returns a best-effort estimate of the number of
+    The ``__len__`` implementation of this class returns a best-effort estimate of the number of
     items in the table using the TableDescription DynamoDB API. The number of items are updated
     at DynamoDB service side approximately once in every 6 hours. If you need the exact number of
-    items currently in the table, you can use `len(list(mapping.keys()))`. Note however that this
+    items currently in the table, you can use ``len(list(mapping.keys()))``. Note however that this
     will cause to run an exhaustive scan operation on your table.
 
     Args:
         table_name (str): The name of the DynamoDB table.
         boto3_session (Optional[boto3.Session]): An optional preconfigured boto3 Session object.
         **kwargs: Additional keyword parameters for manual configuration of the boto3 client:
-            `aws_access_key_id`, `aws_secret_access_key`, `aws_region`, `aws_profile`.
+            ``aws_access_key_id``, ``aws_secret_access_key``, ``aws_region``, ``aws_profile``.
     """
 
     def __init__(
@@ -275,8 +275,13 @@ def scan(self, **kwargs) -> Iterator[DynamoDBItemType]:
         """Performs a scan operation on the DynamoDB table. The scan is executed in a lazy manner,
         in that the successive pages are queried only on demand.
 
+        Example::
+
+            for item in mapping.scan():
+                print(item)
+
         Args:
-            **kwargs: keyword arguments to be passed to the underlying DynamoDB scan operation.
+            **kwargs: keyword arguments to be passed to the underlying DynamoDB ``scan`` operation.
 
         Returns:
             Iterator[DynamoDBItemType]: An iterator over all items in the table.
@@ -295,11 +300,16 @@ def get_item(self, keys: DynamoDBKeySimplified, **kwargs) -> DynamoDBItemType:
 
         The value(s) of the item's key(s) should be specified.
 
+        Example::
+
+            print(mapping.get_item("my_key"))
+
         Args:
             keys (DynamoDBKeySimplified): The key value. This can either be a simple Python type,
                 if only the partition key is specified in the table's key schema, or a tuple of the
                 partition key and the range key values, if both are specified in the key schema.
-            **kwargs: keyword arguments to be passed to the underlying DynamoDB get_item operation.
+            **kwargs: keyword arguments to be passed to the underlying DynamoDB ``get_item``
+                operation.
 
         Raises:
             ValueError: If the required key values are not specified.
@@ -317,14 +327,19 @@ def get_item(self, keys: DynamoDBKeySimplified, **kwargs) -> DynamoDBItemType:
         return DynamoDBItemAccessor(parent=self, item_keys=keys, initial_data=data)
 
     def set_item(self, keys: DynamoDBKeySimplified, item: DynamoDBItemType, **kwargs) -> None:
-        """Creates or overwrites a single item in the table.
+        """Create or overwrite a single item in the table.
+
+        Example::
+
+            mapping.set_item("my_key", {"name": "my first object", "data": {"foo": "bar"}})
 
         Args:
             keys (DynamoDBKeySimplified): The key value. This can either be a simple Python type,
                 if only the partition key is specified in the table's key schema, or a tuple of the
                 partition key and the range key values, if both are specified in the key schema.
             item (DynamoDBItemType): The new item.
-            **kwargs: keyword arguments to be passed to the underlying DynamoDB set_item operation.
+            **kwargs: keyword arguments to be passed to the underlying DynamoDB ``set_item``
+                operation.
 
         """
         key_params = self._create_key_param(keys)
@@ -333,11 +348,15 @@ def set_item(self, keys: DynamoDBKeySimplified, item: DynamoDBItemType, **kwargs
         self.table.put_item(Item=_item, **kwargs)
 
     def put_item(self, keys: DynamoDBKeySimplified, item: DynamoDBItemType, **kwargs) -> None:
-        """An alias for the `set_item` method."""
+        """An alias for the ``set_item`` method."""
         self.set_item(keys, item, **kwargs)
 
     def del_item(self, keys: DynamoDBKeySimplified, check_existing=True, **kwargs) -> None:
-        """Deletes a single item from the table.
+        """Delete a single item from the table.
+
+        Example::
+
+            mapping.del_item("my_key")
 
         Args:
             keys (DynamoDBKeySimplified): The key value. This can either be a simple Python type,
@@ -346,7 +365,7 @@ def del_item(self, keys: DynamoDBKeySimplified, check_existing=True, **kwargs) -
             check_existing (bool): Raise ValueError if the specified key does not exists in the
                 table. Defaults to True to be consistent with python dict implementation, however
                 this causes an additional get_item operation to be executed.
-            **kwargs: keyword arguments to be passed to the underlying DynamoDB delete_item
+            **kwargs: keyword arguments to be passed to the underlying DynamoDB ``delete_item``
                 operation.
         """
         key_params = self._create_key_param(keys)
@@ -360,7 +379,11 @@ def modify_item(self,
         modifications: DynamoDBItemType,
         **kwargs
     ) -> None:
-        """Modifies the properties of an existing item.
+        """Modify the properties of an existing item.
+
+        Example::
+
+            mapping.modify_item("my_key", {"title": "new_title"})
 
         Args:
             keys (DynamoDBKeySimplified): The key value of the item. This can either be a simple
@@ -371,7 +394,7 @@ def modify_item(self,
                 the fields of the item. This mapping follows the same format as the entire item,
                 but it isn't required to contain all fields: fields that are omitted will be
                 unaffected. To delete a field, set the field value to None.
-            **kwargs: keyword arguments to be passed to the underlying DynamoDB update_item
+            **kwargs: keyword arguments to be passed to the underlying DynamoDB ``update_item``
                 operation.
         """
         key_params = self._create_key_param(keys)
@@ -421,7 +444,13 @@ def _key_values_from_item(self, item: DynamoDBItemType) -> DynamoDBKeyAny:
     def __iter__(self) -> Iterator:
         """Returns an iterator over the table.
 
-        This method performs a lazy DynamoDB `scan` operation.
+        This method performs a lazy DynamoDB ``scan`` operation.
+
+        Example::
+
+            for item in mapping:
+                print(item)
+
         """
         for item in self.scan(ProjectionExpression=", ".join(self.key_names)):
             yield simplify_tuple_keys(self._key_values_from_item(item))
@@ -430,28 +459,49 @@ def __len__(self) -> int:
         """Returns a best effort estimation of the number of items in the table.
 
         If you need the precise number of items in the table, you can use
-        `len(list(mapping.keys()))`. However this later can be a costly operation.
+        ``len(list(mapping.keys()))``. However this later can be a costly operation.
+
+        Example::
+
+            print(len(mapping))
+
         """
         return self.table.item_count
 
     def __getitem__(self, __key: Any) -> Any:
         """Retrieves a single item from the table.
 
-        Delegates the call to `get_item` method without additional keyword arguments.
+        Delegates the call to ``get_item`` method without additional keyword arguments.
+
+        Example::
+
+            print(mapping["my_key"])
+            mapping["my_key"]["info"] = "You can directly add or modify item attributes!"
+
         """
         return self.get_item(__key)
 
     def __setitem__(self, __key: Any, __value: Any) -> None:
         """Creates or overwrites a single item in the table.
 
-        Delegates the call to `set_item` method without additional keyword arguments.
+        Delegates the call to ``set_item`` method without additional keyword arguments.
+
+        Example::
+
+            mapping["my_key"] = {"name": "my first object", "data": {"foo": "bar"}}
+
         """
         self.set_item(__key, __value)
 
     def __delitem__(self, __key: Any) -> None:
         """Deletes a single item from the table.
 
-        Delegates the call to `del_item` method without additional keyword arguments.
+        Delegates the call to ``del_item`` method without additional keyword arguments.
+
+        Example::
+
+            del mapping["my_key"]
+
         """
         self.del_item(__key)
 
@@ -460,6 +510,11 @@ def items(self) -> ItemsView:
 
         The returned view can be used to iterate over (key, value) tuples in the table.
 
+        Example::
+
+            for key, item in mapping.items():
+                print(key, item)
+
         Returns:
             ItemsView: The items view.
         """
@@ -470,6 +525,11 @@ def values(self) -> ValuesView:
 
         The returned view can be used to iterate over the values in the table.
 
+        Example::
+
+            for item in mapping.values():
+                print(item)
+
         Returns:
             ValuesView: The values view.
         """
@@ -480,6 +540,11 @@ def keys(self) -> KeysView:
 
         The returned view can be used to iterate over the keys in the table.
 
+        Example::
+
+            for key in mapping.keys():
+                print(key)
+
         Returns:
             KeysView: The keys view.
         """
diff --git a/requirements_dev.txt b/requirements_dev.txt
