Edit the README and the .gitignore

.gitignore

@@ -171,3 +171,4 @@ metastore_db/
 mlruns/
 spark-warehouse/
 .pdm-build
+/.venv/

README.md

@@ -7,26 +7,34 @@
 
 <img src="./logo.png" width="250"/>
 
-Plugin provides a `when` fixture, which enables the following way of mocking
-the python objects:
+Inspired
+by [mokito-scala](https://github.com/mockito/mockito-scala), `pytest-when`
+provides a fixture for `pytest` to simplify the mocking of python objects:
+
+## Purpose
+
+More readable than the full `Given...When...Then` pattern, `pytest-when` is
+meant for developers who want to test for behaviour, without any extra
+overhead.
+Enable the mock only for a specific argument's values to make code more
+readable.
+
+## Benefits
+
+In this example, when you specify the first two arguments and *any* third
+argument, the attribute will be mocked,
 
 ```python
 (
     when(some_object, "attribute")
     .called_with(1, 2, when.markers.any)
-    .then_return("mocked")
+    .then_return("attribute mocked")
 )
 ```
 
-It is readable and gives you a way to enable the mock only for a specific
-argument's values. In this the attribute will be mocked, for specific
-first two arguments and any third argument.
-
-Inspired by <https://github.com/mockito/mockito-scala>
-
-`.called_with` method arguments are compared with the
-real callable signature and gives additional protection against
-changing the real callable interface.
+Note that the `.called_with` method arguments are compared with the real
+callable signature.
+This gives additional protection against changing the real callable interface.
 
 With `when` fixture, the following expression:
 
@@ -76,14 +84,18 @@ where logic of `matches` and `create_call` is not trivial
 
 ## Installation
 
+Install the package into your development environment, from
+[pypi](https://pypi.org/project/pytest-when/), using `pip`, for example:
+
 ```bash
 pip install pytest-when
 ```
 
-## Usage
+## Implementation
 
-After installing the package a new fixture `when` will be available.
-See the following example how to use it:
+Onced installed, the `when` fixture will be available just like the rest of
+the `pytest` plugins.
+See the following example of how to use it:
 
 ```python
 # class which we're going to mock in the test
@@ -96,7 +108,7 @@ class Klass1:
             kwarg1: str,
             kwarg2: str,
     ) -> str:
-        return "Not mocked"
+        return "some_method not mocked"
 
 
 def test_should_properly_patch_calls(when):
@@ -105,7 +117,7 @@ def test_should_properly_patch_calls(when):
         when.markers.any,
         kwarg1="b",
         kwarg2=when.markers.any,
-    ).then_return("Mocked")
+    ).then_return("some method mocked")
 
     assert (
             Klass1().some_method(
@@ -114,7 +126,7 @@ def test_should_properly_patch_calls(when):
                 kwarg1="b",
                 kwarg2="c",
             )
-            == "Mocked"
+            == "some method mocked"
     )
     assert (
             Klass1().some_method(
@@ -123,7 +135,7 @@ def test_should_properly_patch_calls(when):
                 kwarg1="b",
                 kwarg2="c",
             )
-            == "Not mocked"
+            == "some method not mocked"
     )
 
 
@@ -134,7 +146,7 @@ def test_patch_a_function(when):
         when.markers.any,
         kwarg1="b",
         kwarg2=when.markers.any,
-    ).then_return("Mocked")
+    ).then_return("some_normal_function mocked")
 
     assert (
             example_module.some_normal_function(
@@ -143,7 +155,7 @@ def test_patch_a_function(when):
                 kwarg1="b",
                 kwarg2="c",
             )
-            == "Mocked"
+            == "some_normal_function mocked"
     )
     assert (
             example_module.some_normal_function(
@@ -152,14 +164,14 @@ def test_patch_a_function(when):
                 kwarg1="b",
                 kwarg2="c",
             )
-            == "Not mocked"
+            == "some_normal_function not mocked"
     )
 ```
 
-It is possible to use 'when' with class methods and standalone functions
+It is possible to use `when` with class methods and standalone functions
 (in this case cls parameter will become a python module).
 
-You can patch multiple times the same object with different "called_with"
+You can patch the same object multiple times using different `called_with`
 parameters in a single test.
 
 You can also patch multiple targets (cls, method)
@@ -169,10 +181,12 @@ See more examples at:
 
 ## Setup for local developement
 
-Requirements:
+The project can be extended by cloning the repo and
+installing [the `PDM` build tool](https://pdm-project.org/latest/#recommended-installation-method)
+So, the development environment requires:
 
 1. pdm <https://pdm.fming.dev/latest/#installation>
-2. python3.8 (minimum supported by a tool)
+2. python3.8 or greater
 
 ```bash
 pdm install