docs: rewrite for latest version

Author: eddieantonio

README.rst

@@ -4,53 +4,122 @@ sentinel — create sentinel and singleton objects
 
 |Tests| |PyPI version|
 
-.. |Tests| image:: https://github.com/eddieantonio/sentinel/workflows/Python%20package/badge.svg
-   :target: https://github.com/eddieantonio/sentinel/actions?query=workflow%3A%22Python+package%22
+.. |Tests| image:: https://github.com/eddieantonio/sentinel/workflows/Test%20and%20Lint/badge.svg
+   :target: https://github.com/eddieantonio/sentinel/actions?query=workflow%3A%22Test+and+Lint%22
 .. |PyPI version| image:: https://img.shields.io/pypi/v/sentinel
    :target: https://pypi.org/project/sentinel/
 
-Creates simple sentinel objects which are the only instance of their own
-anonymous class. As a singleton, there is a guarantee that there will only
-ever be one instance: they can be safely used with ``pickle`` and ``cPickle``
-alike, as well as being able to be used properly with ``copy.deepcopy()``. In
-addition, a self-documenting ``__repr__`` is provided for free!
+Creates simple sentinel objects.
+
+
+Install
+=======
+
+Basic features::
+
+   pip install sentinel
+
+with extra magic features powered by python-varname_::
+
+   pip install 'sentinel[varname]'
+
+
+What is a sentinel?
+===================
+
+Sentinels_ are singleton_ objects that typically represent some
+terminating (end) condition or have a special, symbolic meaning. Python's built-in
+``None`` is a sentinel. Python also has other sentinels like ``NotImplemented`` and
+``Ellipsis``.
+
+If you want to create your own sentinels, use this library! Make your calls to
+``dict.get()`` more meaningful! You can replace the ``object()`` idiom with a sentinel:
+
+.. code-block:: python
+
+   d = {"a": 1, "b": None}
+
+   # Before sentinel:
+   missing = object()
+   if d.get("c", missing) is missing:
+      ... # do some stuff
+
+   # After sentinel:
+   Missing = sentinel.create()
+   if d.get("c", Missing) is Missing:
+      ... # do some stuff
+
+
+Features
+--------
+
+ - sentinels are unique
+ - sentinels are singletons — the **only** instance of their own anonymous class
+ - sentinels can be used with ``is`` comparisons
+ - sentinels can be used with ``pickle``
+ - sentinels can be used with ``copy.deepcopy``
+ - you can **add** arbitrary attributes and methods to sentinels
+ - sentinels have a nice, self-documenting ``__repr__``!
 
 Usage
 =====
 
-Sentinels_ are singleton_ objects that typically represent some end or
-terminating condition. Some singletons already exist in Python, like ``None``,
-``NotImplemented``, and ``Ellipsis``.
+Create a sentinel:
 
+>>> import sentinel
+>>> MySentinel = sentinel.create("MySentinel")
+>>> Sentinel
+Sentinel
 
-All that's needed to create a sentinel is its name:
+If you have python-varname_ installed, or installed this module using
+``pip install 'sentinel[varname]'``, ``sentinel.create()`` can infer the name
+from the assignment expression:
 
->>> import sentinel
->>> Nothing = sentinel.create('Nothing')
->>> Nothing
-Nothing
+.. code-block:: python
+
+   import sentinel
 
-This by itself is useful when other objects such as ``None``, ``False``,
-``0``, ``-1``, etc.  are entirely valid values. For example, setting default
-values when all other values are valid with: ``dict.setdefault()``:
+   MySentinel = sentinel.create()
 
->>> MissingEntry = sentinel.create('MissingEntry')
->>> d = {'stdout': None, 'stdin': 0, 'EOF': -1}
->>> [d.setdefault(key, MissingEntry) for key in ('stdin', 'stdout', 'stderr')]
-[0, None, MissingEntry]
+   print(MySentinel)  # prints `MySentinel`
+
+
+Example
+-------
+
+Sentinels are useful when other objects such as ``None``, ``False``,
+``0``, ``-1``, are valid values within some data structure. For example, setting
+default values when all other values are valid with:
+``dict.setdefault()``:
+
+.. code-block:: python
+
+   d = {"stdout": None, "stdin": 0, "EOF": -1}
+
+   MissingEntry = sentinel.create()
+
+   [d.setdefault(key, MissingEntry) for key in ("stdin", "stdout", "stderr")]
+   [0, None, MissingEntry]
 
 Alternatively, using ``dict.get()`` when fetching values:
 
->>> d = {'stdout': None, 'stdin': 0, 'EOF': -1}
->>> d.get('stdout', MissingEntry)
+>>> d = {"stdout": None, "stdin": 0, "EOF": -1}
+>>> d.get("stdout", MissingEntry)
 None
->>> d.get('stdin', MissingEntry)
+>>> d.get("stdin", MissingEntry)
 0
->>> d.get('stderr', MissingEntry)
+>>> d.get("stderr", MissingEntry)
 MissingEntry
 
-It's known immediately which value was missing from the dictionary in a
-self-documenting manner.
+Since a new sentinel can never occur in the original dictionary, you can tell which
+entries are missing or unset in a dictionary in a self-documenting way:
+
+.. code-block:: python
+
+   Unset = sentinel.create()
+   if d.get("stdin", Unset) is Unset:
+      stdin = 0  # some reasonable default
+
 
 Adding extra methods and class attributes
 -----------------------------------------
@@ -110,7 +179,7 @@ Contributing
 This project uses Poetry_. To contribute to the codebase, make sure to `install poetry`_,
 With Poetry installed, clone then repo, then within the repo directory, install the developer dependencies::
 
-    $ poetry install
+    $ poetry install --extras varname
 
 Next, I recommend you do all development tasks within the ``poetry shell``::
 
@@ -122,3 +191,4 @@ Next, I recommend you do all development tasks within the ``poetry shell``::
 .. _singleton: http://en.wikipedia.org/wiki/Singleton_pattern
 .. _Poetry: https://python-poetry.org/
 .. _install poetry: https://python-poetry.org/docs/#installation
+.. _python-varname: https://github.com/pwwang/python-varname