Add INamed interface for Keywords and Symbols (#885)

This PR introduces the `INamed` interface (similar to Clojure's `Named`)
which is applied to the Keyword and Symbol classes. Having an interface
for this allows us to perform type checking for relevant features (in
particular, the existence of a name or namespace) without needing the
import either class directly (thus avoiding circular dependencies).

I also added type annotations for the Lisp representation keyword
arguments (which is a useful addition ahead of #882 merging).

Fixes #884

Co-authored-by: Christopher Rink <[email protected]>

Author: chrisrink10

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Added custom exception formatting for `basilisp.lang.compiler.exception.CompilerException` and `basilisp.lang.reader.SyntaxError` to show more useful details to users on errors (#870)
  * Added `merge-with` core function (#860)
  * Added `fnext` core function (#879)
+ * Added `INamed` interface for Keywords and Symbols (#884)
 
 ### Changed
  * Cause exceptions arising from compilation issues during macroexpansion will no longer be nested for each level of macroexpansion (#852)

src/basilisp/lang/interfaces.py

@@ -15,8 +15,10 @@
     Union,
 )
 
+from typing_extensions import Unpack
+
 from basilisp.lang.obj import LispObject as _LispObject
-from basilisp.lang.obj import seq_lrepr
+from basilisp.lang.obj import PrintSettings, seq_lrepr
 
 T = TypeVar("T")
 
@@ -107,6 +109,20 @@ def with_meta(self: T_with_meta, meta: "Optional[IPersistentMap]") -> T_with_met
         raise NotImplementedError()
 
 
+class INamed(ABC):
+    __slots__ = ()
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        raise NotImplementedError()
+
+    @property
+    @abstractmethod
+    def ns(self) -> Optional[str]:
+        raise NotImplementedError()
+
+
 ILispObject = _LispObject
 
 
@@ -407,11 +423,11 @@ def create(cls, m: IPersistentMap) -> "IRecord":
         """Class method constructor from an IPersistentMap instance."""
         raise NotImplementedError()
 
-    def _lrepr(self, **kwargs) -> str:
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         return self._record_lrepr(kwargs)
 
     @abstractmethod
-    def _record_lrepr(self, kwargs: Mapping) -> str:
+    def _record_lrepr(self, kwargs: PrintSettings) -> str:
         """Translation method converting Python keyword arguments into a
         Python dict.
 
@@ -487,7 +503,7 @@ def cons(self, elem: T) -> "ISeq[T]":
     def seq(self) -> "Optional[ISeq[T]]":
         return self
 
-    def _lrepr(self, **kwargs):
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]):
         return seq_lrepr(iter(self), "(", ")", **kwargs)
 
     def __eq__(self, other):

src/basilisp/lang/keyword.py

@@ -2,20 +2,24 @@
 from functools import total_ordering
 from typing import Iterable, Optional, Union
 
+from typing_extensions import Unpack
+
 from basilisp.lang import map as lmap
 from basilisp.lang.interfaces import (
     IAssociative,
     ILispObject,
+    INamed,
     IPersistentMap,
     IPersistentSet,
 )
+from basilisp.lang.obj import PrintSettings
 
 _LOCK = threading.Lock()
 _INTERN: IPersistentMap[int, "Keyword"] = lmap.PersistentMap.empty()
 
 
 @total_ordering
-class Keyword(ILispObject):
+class Keyword(ILispObject, INamed):
     __slots__ = ("_name", "_ns", "_hash")
 
     def __init__(self, name: str, ns: Optional[str] = None) -> None:
@@ -31,7 +35,7 @@ def name(self) -> str:
     def ns(self) -> Optional[str]:
         return self._ns
 
-    def _lrepr(self, **kwargs) -> str:
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         if self._ns is not None:
             return f":{self._ns}/{self._name}"
         return f":{self._name}"

src/basilisp/lang/list.py

@@ -2,8 +2,10 @@
 
 from pyrsistent import PList, plist  # noqa # pylint: disable=unused-import
 from pyrsistent._plist import _EMPTY_PLIST  # pylint: disable=import-private-name
+from typing_extensions import Unpack
 
 from basilisp.lang.interfaces import IPersistentList, IPersistentMap, ISeq, IWithMeta
+from basilisp.lang.obj import PrintSettings
 from basilisp.lang.obj import seq_lrepr as _seq_lrepr
 from basilisp.lang.seq import EMPTY as _EMPTY_SEQ
 
@@ -36,7 +38,7 @@ def __hash__(self):
     def __len__(self):
         return len(self._inner)
 
-    def _lrepr(self, **kwargs) -> str:
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         return _seq_lrepr(self._inner, "(", ")", meta=self._meta, **kwargs)
 
     @property

src/basilisp/lang/map.py

@@ -3,6 +3,7 @@
 
 from immutables import Map as _Map
 from immutables import MapMutation
+from typing_extensions import Unpack
 
 from basilisp.lang.interfaces import (
     IEvolveableCollection,
@@ -14,6 +15,7 @@
     ITransientMap,
     IWithMeta,
 )
+from basilisp.lang.obj import PrintSettings
 from basilisp.lang.obj import map_lrepr as _map_lrepr
 from basilisp.lang.seq import sequence
 from basilisp.lang.vector import MapEntry
@@ -160,7 +162,7 @@ def __iter__(self):
     def __len__(self):
         return len(self._inner)
 
-    def _lrepr(self, **kwargs):
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]):
         return _map_lrepr(
             self._inner.items, start="{", end="}", meta=self._meta, **kwargs
         )

src/basilisp/lang/obj.py

@@ -8,7 +8,9 @@
 from functools import singledispatch
 from itertools import islice
 from pathlib import Path
-from typing import Any, Callable, Iterable, Pattern, Tuple, Union
+from typing import Any, Callable, Iterable, Pattern, Tuple, Union, cast
+
+from typing_extensions import TypedDict, Unpack
 
 PrintCountSetting = Union[bool, int, None]
 
@@ -23,17 +25,28 @@
 PRINT_SEPARATOR = " "
 
 
-def _dec_print_level(lvl: PrintCountSetting):
+class PrintSettings(TypedDict, total=False):
+    human_readable: bool
+    print_dup: bool
+    print_length: PrintCountSetting
+    print_level: PrintCountSetting
+    print_meta: bool
+    print_readably: bool
+
+
+def _dec_print_level(lvl: PrintCountSetting) -> PrintCountSetting:
     """Decrement the print level if it is numeric."""
     if isinstance(lvl, int):
         return lvl - 1
     return lvl
 
 
-def _process_kwargs(**kwargs):
+def _process_kwargs(**kwargs: Unpack[PrintSettings]) -> PrintSettings:
     """Process keyword arguments, decreasing the print-level. Should be called
     after examining the print level for the current level."""
-    return dict(kwargs, print_level=_dec_print_level(kwargs["print_level"]))
+    return cast(
+        PrintSettings, dict(kwargs, print_level=_dec_print_level(kwargs["print_level"]))
+    )
 
 
 class LispObject(ABC):
@@ -53,13 +66,13 @@ def __str__(self):
         return self.lrepr(human_readable=True)
 
     @abstractmethod
-    def _lrepr(self, **kwargs) -> str:
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         """Private Lisp representation method. Callers (including object
         internal callers) should not call this method directly, but instead
         should use the module function .lrepr()."""
         raise NotImplementedError()
 
-    def lrepr(self, **kwargs) -> str:
+    def lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         """Return a string representation of this Lisp object which can be
         read by the reader."""
         return lrepr(self, **kwargs)
@@ -70,7 +83,7 @@ def map_lrepr(
     start: str,
     end: str,
     meta=None,
-    **kwargs,
+    **kwargs: Unpack[PrintSettings],
 ) -> str:
     """Produce a Lisp representation of an associative collection, bookended
     with the start and end string supplied. The entries argument must be a
@@ -109,7 +122,11 @@ def entry_reprs():
 
 
 def seq_lrepr(
-    iterable: Iterable[Any], start: str, end: str, meta=None, **kwargs
+    iterable: Iterable[Any],
+    start: str,
+    end: str,
+    meta=None,
+    **kwargs: Unpack[PrintSettings],
 ) -> str:
     """Produce a Lisp representation of a sequential collection, bookended
     with the start and end string supplied. The keyword arguments will be
@@ -224,22 +241,22 @@ def _lrepr_str(
 
 
 @lrepr.register(list)
-def _lrepr_py_list(o: list, **kwargs) -> str:
+def _lrepr_py_list(o: list, **kwargs: Unpack[PrintSettings]) -> str:
     return f"#py {seq_lrepr(o, '[', ']', **kwargs)}"
 
 
 @lrepr.register(dict)
-def _lrepr_py_dict(o: dict, **kwargs) -> str:
+def _lrepr_py_dict(o: dict, **kwargs: Unpack[PrintSettings]) -> str:
     return f"#py {map_lrepr(o.items, '{', '}', **kwargs)}"
 
 
 @lrepr.register(set)
-def _lrepr_py_set(o: set, **kwargs) -> str:
+def _lrepr_py_set(o: set, **kwargs: Unpack[PrintSettings]) -> str:
     return f"#py {seq_lrepr(o, '#{', '}', **kwargs)}"
 
 
 @lrepr.register(tuple)
-def _lrepr_py_tuple(o: tuple, **kwargs) -> str:
+def _lrepr_py_tuple(o: tuple, **kwargs: Unpack[PrintSettings]) -> str:
     return f"#py {seq_lrepr(o, '(', ')', **kwargs)}"
 
 

src/basilisp/lang/queue.py

@@ -1,6 +1,7 @@
 from typing import Optional, TypeVar
 
 from pyrsistent import PDeque, pdeque  # noqa # pylint: disable=unused-import
+from typing_extensions import Unpack
 
 from basilisp.lang.interfaces import (
     ILispObject,
@@ -10,6 +11,7 @@
     IWithMeta,
     seq_equals,
 )
+from basilisp.lang.obj import PrintSettings
 from basilisp.lang.obj import seq_lrepr as _seq_lrepr
 from basilisp.lang.seq import sequence
 
@@ -47,7 +49,7 @@ def __iter__(self):
     def __len__(self):
         return len(self._inner)
 
-    def _lrepr(self, **kwargs) -> str:
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         return _seq_lrepr(self._inner, "#queue (", ")", meta=self._meta, **kwargs)
 
     @property

src/basilisp/lang/reader.py

@@ -33,6 +33,7 @@
 )
 
 import attr
+from typing_extensions import Unpack
 
 from basilisp.lang import keyword as kw
 from basilisp.lang import list as llist
@@ -56,6 +57,7 @@
     IType,
     IWithMeta,
 )
+from basilisp.lang.obj import PrintSettings
 from basilisp.lang.obj import seq_lrepr as _seq_lrepr
 from basilisp.lang.runtime import (
     READER_COND_DEFAULT_FEATURE_SET,
@@ -520,7 +522,7 @@ def select_feature(
                 return form
         return self.FEATURE_NOT_PRESENT
 
-    def _lrepr(self, **kwargs) -> str:
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         return _seq_lrepr(
             chain.from_iterable(self._feature_vec),
             "#?@(" if self.is_splicing else "#?(",

src/basilisp/lang/set.py

@@ -3,6 +3,7 @@
 
 from immutables import Map as _Map
 from immutables import MapMutation
+from typing_extensions import Unpack
 
 from basilisp.lang.interfaces import (
     IEvolveableCollection,
@@ -13,6 +14,7 @@
     ITransientSet,
     IWithMeta,
 )
+from basilisp.lang.obj import PrintSettings
 from basilisp.lang.obj import seq_lrepr as _seq_lrepr
 from basilisp.lang.seq import sequence
 
@@ -111,7 +113,7 @@ def __iter__(self):
     def __len__(self):
         return len(self._inner)
 
-    def _lrepr(self, **kwargs):
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]):
         return _seq_lrepr(self._inner, "#{", "}", meta=self._meta, **kwargs)
 
     issubset = _PySet.__le__

src/basilisp/lang/symbol.py

@@ -1,19 +1,22 @@
 from functools import total_ordering
 from typing import Optional, Union
 
+from typing_extensions import Unpack
+
 from basilisp.lang.interfaces import (
     IAssociative,
     ILispObject,
+    INamed,
     IPersistentMap,
     IPersistentSet,
     IWithMeta,
 )
-from basilisp.lang.obj import lrepr
+from basilisp.lang.obj import PrintSettings, lrepr
 from basilisp.lang.util import munge
 
 
 @total_ordering
-class Symbol(ILispObject, IWithMeta):
+class Symbol(ILispObject, INamed, IWithMeta):
     __slots__ = ("_name", "_ns", "_meta", "_hash")
 
     def __init__(
@@ -24,7 +27,7 @@ def __init__(
         self._meta = meta
         self._hash = hash((ns, name))
 
-    def _lrepr(self, **kwargs) -> str:
+    def _lrepr(self, **kwargs: Unpack[PrintSettings]) -> str:
         print_meta = kwargs["print_meta"]
 
         if self._ns is not None: