More concepts documentation (#946)

More work on #666

Author: chrisrink10

docs/concepts.rst

@@ -927,8 +927,132 @@ Suppose you wanted to serialize :external:py:class:`datetime.datetime` instances
 Data Types and Records
 ----------------------
 
-TBD
+Basilisp allows 3 different methods for defining custom data types which implement Python interfaces and :ref:`protocols`, detailed in the sections below.
+
+Each of the methods Basilisp supports for creating custom data types may implement 0 or more Python interfaces and Basilisp protocols.
+Types are required to implement every function defined by any declared interfaces and protocols.
+
+Types may also optionally implement 0 or more Python `"dunder" methods <https://docs.python.org/3/reference/datamodel.html>`_ without implementing every such method.
+
+.. note::
+
+   It is not necessary to declare :external:py:class:`object` as a superclass, but doing so is not an error.
+
+.. warning::
+
+   Python, unlike Java, does not have a true "interface" type.
+   The best approximation is :external:py:class:`abc.ABC`, although this type is merely advisory and many libraries and applications eschew its use.
+
+   For the cases where a host type is not defined as an ``abc.ABC`` instance, users can override the compiler check by setting the ``^:abstract`` meta key on the interface type symbol passed to the ``deftype`` form.
+   For example, take :external:py:class:`argparse.Action` which is required to be implemented for customizing :external:py:mod:`argparse` actions, but which is not defined as an ``abc.ABC``:
+
+   .. code-block::
+
+      (import argparse)
+
+      (reify
+        ^:abstract argparse/Action
+        (__call__ [this]
+          ;; ...
+          ))
+
+.. _deftype:
+
+``deftype``
+^^^^^^^^^^^
+
+In many cases it is desirable or necessary to define a Python class (or object instance which is a subtype of some type) to interact with a Python library.
+To facilitate this, Basilisp includes the :lpy:fn:`deftype` macro for creating Python classes which optionally implement Python interfaces or Basilisp protocols.
+
+Types defined via ``deftype`` may include 0 or more fields which are required at object instantiation.
+Fields defined in ``deftype`` forms are immutable by default.
+Attempting to set a field using :lpy:form:`set!` will result in a compile-time error.
+However, it is possible to mark a field as mutable by using the ``^:mutable`` metadata on a ``deftype`` field at compile time.
+Mutable fields may be ``set!`` from within class methods.
+Fields may be referred to freely by name from within method definitions as in Java (and unlike in Python where they must be qualified with ``self``).
+Fields may also specify defaults by providing the default value as a ``^:default`` metadata value.
+
+.. warning::
+
+   Python is known for taking a rather lax stance on object mutability as compared to many other languages and runtimes.
+   As a consequence of the language and VM not enforcing true immutability, even immutable fields may still be modified by other means.
+   Users should not take the immutable default state of ``deftype`` fields as a guarantee, but rather as a principled approach to reducing the surface area of potential bugs due to mutability.
+
+Types created by ``deftype`` automatically have some basic sensible defaults added via `attrs <https://www.attrs.org/en/stable/>`_, such as a constructor (whose argument order matches that of the defined fields) and Python ``__str__`` and ``__repr__`` methods.
+User supplied versions of methods besides ``__init__`` may override the generated variants in all cases.
+
+Methods may be defined with multiple arities if required by any declared protocols.
+``deftype`` methods may be :ref:`defined with support for Python kwargs <basilisp_functions_with_kwargs>` exactly like plain functions.
+Methods may be declared as by :external:py:func:`classmethod` and :external:py:func:`staticmethod` using the ``^:classmethod`` and ``^:staticmethod`` metadata respectively on the method name.
+Static and classmethods may be defined with multiple arities.
+Methods may also be declared as properties as by :external:py:class:`property` using the ``^:property`` metadata on the method name.
+Property methods must be single arity.
+
+Given a new type ``deftype`` named ``Point``, a new constructor function ``->Point`` will be created alongside the record type which accepts the full set of declared fields in the order they are declared.
+
+.. note::
+
+   Method definitions must include a ``self`` or ``this`` parameter.
+
+.. note::
+
+   Methods support tail recursion via :lpy:form:`recur`.
+   When recurring, users should *not* pass the ``this`` or ``self`` parameter.
+
+.. _reify:
+
+``reify``
+^^^^^^^^^
+
+Whereas :ref:`deftype` defines a true Python class which may be instantiated directly, :lpy:fn:`reify` defines an anonymous type implementing the named interfaces and protocols and returns an instance of that type immediately.
+Types defined via ``reify`` may not include fields.
+Instead, reified types close over their environment, which can provide many of the same benefits as fields.
+
+Reify is likely to be most useful for creating one-off types implementing some Python type, rather than for creating types that are going to be created and used frequently by consumers of your code.
+
+Reified types always implement :py:class:`basilisp.lang.interfaces.IWithMeta` and any metadata applied to the ``reify`` form are transferred to the created object.
+
+.. note::
+
+   While ``reify`` and ``deftype`` are broadly similar, ``reify`` types may not define class or static methods.
+
+.. _defrecord:
+
+``defrecord``
+^^^^^^^^^^^^^
+
+Basilisp offers a record type, created via :lpy:fn:`defrecord`, which is broadly similar to the types created by :ref:`deftype`.
+Record types are designed to be object types which can interact more readily with the core Basilisp library as a result of implementing the map interface directly.
+Records may be created from maps and fields in may be accessed, updated, and removed using standard :ref:`map <maps>` library functions.
+
+There are some key differences from ``deftype`` types, however.
+
+- Record types automatically implement :py:class:`basilisp.lang.interfaces.IPersistentMap`, :py:class:`basilisp.lang.interfaces.IWithMeta`, :py:class:`basilisp.lang.interfaces.IRecord`, and support for equality and hashing implemented via Python ``object`` methods.
+- ``defrecord`` fields may not be marked ``^:mutable``, nor may they provide a default via ``^:default``.
+- Types created by ``defrecord`` may not include :external:py:func:`classmethod`, :external:py:class:`property`, or :external:py:func:`staticmethod` methods.
+- Given a defrecord type ``Point``, a constructor function ``map->Point`` will be created alongside the record type which can construct a new ``Point`` record from a map in addition to the positional constructor ``->Point``.
+- Record literals may be constructed using their fully-qualified name as a :ref:`data reader <data_readers>` using a vector literal for a positional constructor or a map for a map based constructor.
+
+.. code-block::
+
+   (defrecord Point [x y z])
+   (->Point 1 2 3)                         ;; => #basilisp.user.Point{:z 3 :x 1 :y 2}
+   (def p (map->Point {:x 1 :y 2 :z 3}))   ;; => #basilisp.user.Point{:z 3 :x 1 :y 2}
+   (:x p)                                  ;; => 1
+   (dissoc p :x)                           ;; => {:z 3 :y 2}
+
+   (def p1 (assoc p :name "Best point"))   ;; => #basilisp.user.Point{:z 3 :x 1 :name "Best point" :y 2}
+   (dissoc p1 :name)                       ;; => #basilisp.user.Point{:z 3 :x 1 :y 2}
+
+   #basilisp.user.Point[4 5 6]             ;; => #basilisp.user.Point{:z 6 :x 4 :y 5}
+   #basilisp.user.Point{:x 4 :y 5 :z 6}    ;; => #basilisp.user.Point{:z 6 :x 4 :y 5}
+
+.. note::
+
+   Users may add arbitrary extra fields onto a record (as by :lpy:fn:`assoc`) without changing its type.
+   If a field required by the record definition is removed as by :lpy:fn:`dissoc`, the record type will be downgraded to a standard map.
+   Extra fields which are not part of the record may be removed without changing the type.
 
 .. seealso::
 
-   :lpy:fn:`deftype`, :lpy:fn:`defrecord` , :lpy:fn:`record?`
+   :lpy:fn:`deftype`, :lpy:fn:`defrecord`, :lpy:fn:`reify`, :lpy:fn:`record?`

docs/pyinterop.rst

@@ -212,6 +212,8 @@ The ``:collect`` strategy is a better accompaniment to functions with positional
 With this strategy, Python keyword arguments are converted into a Basilisp map with de-munged keyword arguments and passed as the final positional argument of the function.
 You can use :ref:`associative_destructuring` on this final positional argument, just as you would with the map in the ``:apply`` case above.
 
+.. _type_hinting:
+
 Type Hinting
 ------------