improve docs

Author: mr-mixas

HOWTO.md

@@ -12,7 +12,8 @@ differences already eliminated (strings converted to numbers, floats rounded
 with same precision and so on).
 
 But when initial objects must remain unchanged custom handlers may be used:
-```
+
+```py
 >>> from nested_diff import Differ, handlers
 >>>
 >>> class FloatHandler(handlers.FloatHandler):
@@ -45,11 +46,23 @@ Ensure `nested_diff` command available, otherwise install it with `pip`:
 
 Add to `.gitconfig` following section:
 
-```
+```ini
 [difftool "nested_diff"]
   cmd = nested_diff $LOCAL $REMOTE
 ```
 
 and `ndiff = difftool --no-prompt --tool nested_diff` to section `[aliases]`.
 
 Now `ndiff` subcommand available and may be used in the same manner as `diff`.
+
+### How to run tests locally
+
+```sh
+# prepare environment
+python3 -m venv venv && \
+    . venv/bin/activate && \
+    pip install -e '.[cli,test]'
+
+# run tests
+pytest
+```

README.md

@@ -26,25 +26,27 @@ For extra formats support (YAML, TOML) in cli tools, use
 
 ## Command line tools
 
-```
+```sh
 $ cat a.json b.json
 [0, [1],    3]
 [0, [1, 2], 3]
 ```
-```
+
+```sh
 $ nested_diff a.json b.json
   [1]
 +   [1]
 +     2
 ```
-```
+
+```sh
 $ nested_diff a.json b.json --ofmt json > patch.json
 $ nested_patch a.json patch.json
 ```
 
 ## Library usage
 
-```
+```py
 >>> from nested_diff import diff, patch
 >>>
 >>> a = {'one': 1, 'two': 2, 'three': 3}
@@ -67,7 +69,7 @@ $ nested_patch a.json patch.json
 
 ### Formatting diffs
 
-```
+```py
 >>> from nested_diff import diff, handlers
 >>> from nested_diff.formatters import TextFormatter
 >>>
@@ -117,9 +119,9 @@ key, except `D` may be omitted during diff computation. `E` key is used with
 `D` when entity unable to contain diff by itself (set, frozenset for example);
 `D` contain a list of subdiffs in this case.
 
-### Annotated example:
+### Annotated example
 
-```
+```text
 a:  {"one": [5,7]}
 b:  {"one": [5], "two": 2}
 opts: U=False  # omit unchanged items

nested_diff/__init__.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2018-2023 Michael Samoglyadov
+# Copyright 2018-2024 Michael Samoglyadov
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -199,7 +197,7 @@ def __init__(self, handlers=None):
     def patch(self, target, ndiff):
         """Patch object using nested diff.
 
-        This method calls apropriate handler for target value according to
+        This method calls appropriate handler for target value according to
         it's type.
 
         Args:
@@ -271,7 +269,7 @@ def __init__(self, handlers=None, sort_keys=False):
             self.set_handler(handler)
 
     def _get_iterator(self, ndiff):
-        """Return apropriate iterator for passed nested diff."""
+        """Return appropriate iterator for passed nested diff."""
         try:
             extension_id = ndiff['E']
             try:

nested_diff/cli.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2019-2023 Michael Samoglyadov
+# Copyright 2019-2024 Michael Samoglyadov
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -61,7 +59,8 @@ def cli(cls):
         return cls().run()
 
     @property
-    def dumper(self):  # noqa D102
+    def dumper(self):
+        """Return appropriate data dumper."""
         try:
             return self.__dumper
         except AttributeError:
@@ -195,7 +194,7 @@ def get_loader(fmt, **kwargs):
         raise RuntimeError(f'Unsupported input format: {fmt}')
 
     def load(self, file_):
-        """Load data from file using apropriate loader.
+        """Load data from file using appropriate loader.
 
         Args:
             file_: File object to load from.
@@ -214,8 +213,7 @@ def load(self, file_):
 
     @staticmethod
     def override_excepthook():
-        """
-        Change default exit code for unhandled exceptions from 1 to 127.
+        """Change default exit code for unhandled exceptions from 1 to 127.
 
         Mainly for diff tool (version control systems treat 1 as difference
         in files).

nested_diff/diff_tool.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2019-2022 Michael Samoglyadov
+# Copyright 2019-2024 Michael Samoglyadov
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

nested_diff/formatters.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2019-2022 Michael Samoglyadov
+# Copyright 2019-2024 Michael Samoglyadov
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -226,8 +224,7 @@ def format_value(val):
 
 
 class HtmlFormatter(TextFormatter):
-    """
-    Produce human friendly HTML diff with indenting formatting.
+    """Produce human friendly HTML diff with indenting formatting.
 
     Text copied from the browser should be exactly the same as TextFormatter
     produce.

nested_diff/handlers.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2022-2023 Michael Samoglyadov
+# Copyright 2022-2024 Michael Samoglyadov
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -73,7 +71,7 @@ def patch(self, patcher, target, diff):  # noqa U100
             Patched object.
 
         Raises:
-            ValueError: Inapropriate diff tag found.
+            ValueError: Inappropriate diff tag found.
 
         """
         try:

nested_diff/patch_tool.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright 2019-2023 Michael Samoglyadov
+# Copyright 2019-2024 Michael Samoglyadov
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.