Document methods that return (supposedly) read-only references. (#20)

It's impossible to actually enforce this, but at least it's documented
somewhere. We only do this for our custom methods that expose class members;
any behavior that mimics Python's inbuilt methods (e.g., returning a mutable
reference from `NamedList.__getitem__`) is assumed knowledge for the user.

src/biocutils/Factor.py

@@ -159,6 +159,9 @@ def get_codes(self) -> numpy.ndarray:
         Returns:
             Array of integer codes, used as indices into the levels from
             :py:meth:`~get_levels`. Missing values are marked with -1.
+
+            This should be treated as a read-only reference. To modify
+            the codes, use :py:meth:`~set_codes` instead.
         """
         return self._codes
 
@@ -193,6 +196,9 @@ def get_levels(self) -> StringList:
         """
         Returns:
             List of strings containing the factor levels.
+
+            This should be treated as a read-only reference. To modify the
+            levels, use :py:meth:`~set_levels` instead.
         """
         return self._levels
 
@@ -234,6 +240,9 @@ def get_names(self) -> Names:
         """
         Returns:
             Names for the factor elements.
+
+            This should be treated as a read-only reference. To modify the
+            names, use :py:meth:`~set_names` instead.
         """
         return self._names
 

src/biocutils/NamedList.py

@@ -118,6 +118,9 @@ def get_names(self) -> Names:
         """
         Returns:
             Names for the list elements.
+
+            The returned object should be treated as a read-only reference. To
+            modify the names, use :py:meth:`~set_names` instead.
         """
         return self._names
 
@@ -470,6 +473,8 @@ def as_list(self) -> list:
         """
         Returns:
             The underlying list of elements.
+
+            The returned object should be treated as a read-only reference.
         """
         return self._data
 
@@ -478,6 +483,8 @@ def as_dict(self) -> Dict[str, Any]:
         Returns:
             A dictionary where the keys are the names and the values are the
             list elements. Only the first occurrence of each name is returned.
+
+            Values of the dictionary should be treated as read-only references.
         """
         output = {}
         for i, n in enumerate(self._names):

src/biocutils/Names.py

@@ -98,6 +98,9 @@ def as_list(self) -> List[str]:
         """
         Returns:
             List of strings containing the names.
+
+            This should be treated as a read-only reference. Modifications
+            should be performed by creating a new ``Names`` object instead.
         """
         return self._names