More fixes from Chris's comments

Author: peterrrock2

gerrychain/constraints/validity.py

@@ -157,7 +157,8 @@ def districts_within_tolerance(
 
 
 def refuse_new_splits(partition_county_field: str) -> Callable[[Partition], bool]:
-    """Refuse all proposals that split a county that was previous unsplit.
+    """
+    Refuse all proposals that split a county that was previous unsplit.
 
     :param partition_county_field: Name of field for county information generated by
         :func:`.county_splits`.

gerrychain/graph/graph.py

@@ -131,10 +131,10 @@ def from_file(
 
         :param filename: Path to the shapefile / GeoPackage / GeoJSON / etc.
         :type filename: str
-        :param adjacency: The adjacency type to use ("rook" or "queen"). Defaults is "rook"
+        :param adjacency: The adjacency type to use ("rook" or "queen"). Default is "rook"
         :type adjacency: str, optional
         :param cols_to_add: The names of the columns that you want to
-            add to the graph as node attributes. Default is None
+            add to the graph as node attributes. Default is None.
         :type cols_to_add: Optional[List[str]], optional
         :param reproject: Whether to reproject to a UTM projection before
             creating the graph. Default is False.
@@ -187,13 +187,13 @@ def from_geodataframe(
         :param dataframe: The GeoDateFrame to convert
         :type dataframe: :class:`geopandas.GeoDataFrame`
         :param adjacency: The adjacency type to use ("rook" or "queen").
-            Default is "rook"
+            Default is "rook".
         :type adjacency: str, optional
         :param cols_to_add: The names of the columns that you want to
             add to the graph as node attributes. Default is None.
         :type cols_to_add: Optional[List[str]], optional
         :param reproject: Whether to reproject to a UTM projection before
-            creating the graph. Default is ``True``.
+            creating the graph. Default is ``False``.
         :type reproject: bool, optional
         :param ignore_errors: Whether to ignore all invalid geometries and
             attept to create the graph anyway. Default is ``False``.
@@ -275,7 +275,7 @@ def edge_indices(self):
     def add_data(self, df: pd.DataFrame,
                  columns: Optional[Iterable[str]] = None) -> None:
         """
-        Add columns of a DataFrame to a graph as node attributes using
+        Add columns of a DataFrame to a graph as node attributes
         by matching the DataFrame's index to node ids.
 
         :param df: Dataframe containing given columns.

gerrychain/partition/assignment.py

@@ -1,6 +1,6 @@
 from collections import defaultdict
 from collections.abc import Mapping
-from typing import Dict, Union, Optional, DefaultDict, Set
+from typing import Dict, Union, Optional, DefaultDict, Set, Type
 from ..graph import Graph
 
 import pandas
@@ -22,14 +22,14 @@ class Assignment(Mapping):
         'mapping'
     ]
 
-    def __init__(self, parts: Dict, mapping: Dict = None, validate: bool = True) -> None:
+    def __init__(self, parts: Dict, mapping: Optional[Dict] = None, validate: bool = True) -> None:
         """
-        :param parts: dictionary mapping partition assignments to sets or
-            frozensets of nodes
+        :param parts: Dictionary mapping partition assignments frozensets of nodes.
         :type parts: Dict
-        :param mapping: dictionary mapping nodes to partition assignments
-        :type mapping: Dict, optional
-        :param validate: whether to validate the assignment
+        :param mapping: Dictionary mapping nodes to partition assignments.
+            Default is None.
+        :type mapping: Optional[Dict], optional
+        :param validate: Whether to validate the assignment. Default is True.
         :type validate: bool, optional
 
         :returns: None
@@ -163,6 +163,7 @@ def get_assignment(part_assignment: Union[str, Dict, Assignment],
         :class:`Assignment` object corresponding to the desired assignment.
     :type part_assignment: str
     :param graph: The graph from which to extract the assignment.
+        Default is None.
     :type graph: Optional[Graph], optional
 
     :returns: An :class:`Assignment` object containing the assignment
@@ -190,16 +191,16 @@ def get_assignment(part_assignment: Union[str, Dict, Assignment],
         raise TypeError("Assignment must be a dict or a node attribute key")
 
 
-def level_sets(mapping: Dict, container: Set = set) -> DefaultDict:
+def level_sets(mapping: Dict, container: Type[Set] = set) -> DefaultDict:
     """
     Inverts a dictionary. ``{key: value}`` becomes
     ``{value: <container of keys that map to value>}``.
 
     :param mapping: A dictionary to invert. Keys and values can be of any type.
     :type mapping: Dict
     :param container: A container type used to collect keys that map to the same value.
-        By default, it is a set.
-    :type container: Set
+        By default, the container type is ``set``.
+    :type container: Type[Set], optional
 
     :return: A dictionary where each key is a value from the original dictionary,
         and the corresponding value is a container (by default, a set) of keys from

gerrychain/partition/partition.py

@@ -14,10 +14,14 @@ class Partition:
     the first layer of computations at each step in the Markov chain - basic
     aggregations and calculations that we want to optimize.
 
-    :ivar gerrychain.Graph graph: The underlying graph.
-    :ivar gerrychain.Assignment assignment: Maps node IDs to district IDs.
-    :ivar dict parts: Maps district IDs to the set of nodes in that district.
-    :ivar dict subgraphs: Maps district IDs to the induced subgraph of that district.
+    :ivar graph: The underlying graph.
+    :type graph: :class:`~gerrychain.Graph`
+    :ivar assignment: Maps node IDs to district IDs.
+    :type assignment: :class:`~gerrychain.assignment.Assignment`
+    :ivar parts: Maps district IDs to the set of nodes in that district.
+    :type parts: Dict
+    :ivar subgraphs: Maps district IDs to the induced subgraph of that district.
+    :type subgraphs: Dict
     """
     __slots__ = (
         'graph',

gerrychain/partition/subgraphs.py

@@ -12,7 +12,8 @@ class SubgraphView:
 
     :ivar graph: The parent graph from which subgraphs are derived.
     :type graph: Graph
-    :ivar parts: A dictionary mapping keys to subsets of nodes in the graph.
+    :ivar parts: A list-of-lists dictionary (so a dict with key values indicated by
+        the list index) mapping keys to subsets of nodes in the graph.
     :type parts: List[List[Any]]
     :ivar subgraphs_cache: Cache to store subgraph views for quick access.
     :type subgraphs_cache: Dict
@@ -28,7 +29,7 @@ def __init__(self, graph: Graph, parts: List[List[Any]]) -> None:
         :param graph: The parent graph from which subgraphs are derived.
         :type graph: Graph
         :param parts: A list of lists of nodes corresponding the different
-            parts of the partition of the graph
+            parts of the partition of the graph.
         :type parts: List[List[Any]]
 
         :returns: None

gerrychain/proposals/proposals.py

@@ -95,7 +95,7 @@ def propose_random_flip(partition: Partition) -> Partition:
 
 def slow_reversible_propose_bi(partition: Partition) -> Partition:
     """
-    Proposes a random boundary flip from the partition in a reversible fasion
+    Proposes a random boundary flip from the partition in a reversible fashion
     for bipartitions by selecting a boundary node at random and uniformly picking
     one of its neighboring parts. For k-partitions this is not uniform since there
     might be multiple parts next to a single node.

gerrychain/proposals/tree_proposals.py

@@ -8,13 +8,13 @@
     _bipartition_tree_random_all, uniform_spanning_tree,
     find_balanced_edge_cuts_memoization,
 )
-from typing import Callable, Optional, Dict
+from typing import Callable, Optional, Dict, Union
 
 
 def recom(
     partition: Partition,
     pop_col: str,
-    pop_target: float,
+    pop_target: Union[int, float],
     epsilon: float,
     node_repeats: int = 1,
     weight_dict: Optional[Dict] = None,
@@ -53,8 +53,9 @@ def recom(
     :param pop_col: The name of the population column.
     :type pop_col: str
     :param pop_target: The target population for each district.
-    :type pop_target: float
-    :param epsilon: The epsilon value for population deviation.
+    :type pop_target: Union[int,float]
+    :param epsilon: The epsilon value for population deviation as a percentage of the
+        target population.
     :type epsilon: float
     :param node_repeats: The number of times to repeat the bipartitioning step. Default is 1.
     :type node_repeats: int, optional
@@ -96,7 +97,7 @@ def recom(
 def reversible_recom(
     partition: Partition,
     pop_col: str,
-    pop_target: float,
+    pop_target: Union[int, float],
     epsilon: float,
     balance_edge_fn: Callable = find_balanced_edge_cuts_memoization,
     M: int = 1,
@@ -116,8 +117,9 @@ def reversible_recom(
     :param pop_col: The name of the population column.
     :type pop_col: str
     :param pop_target: The target population for each district.
-    :type pop_target: float
-    :param epsilon: The epsilon value for population deviation.
+    :type pop_target: Union[int,float]
+    :param epsilon: The epsilon value for population deviation as a percentage of the
+        target population.
     :type epsilon: float
     :param balance_edge_fn: The balance edge function. Default is
         find_balanced_edge_cuts_memoization.
@@ -211,15 +213,16 @@ class ReCom:
 
     def __init__(self,
                  pop_col: str,
-                 ideal_pop: int,
+                 ideal_pop: Union[int, float],
                  epsilon: float,
                  method: Callable = bipartition_tree_random):
         """
         :param pop_col: The name of the column in the partition that contains the population data.
         :type pop_col: str
         :param ideal_pop: The ideal population for each district.
-        :type ideal_pop: float
-        :param epsilon: The maximum allowable deviation from the ideal population.
+        :type ideal_pop: Union[int,float]
+        :param epsilon: The epsilon value for population deviation as a percentage of the
+            target population.
         :type epsilon: float
         :param method: The method used for bipartitioning the tree.
             Defaults to `bipartition_tree_random`.

gerrychain/updaters/compactness.py

@@ -10,8 +10,8 @@ def boundary_nodes(partition, alias: str = "boundary_nodes") -> Set:
     :param partition: A partition of a Graph
     :type partition: :class:`~gerrychain.partition.Partition`
     :param alias: The name of the attribute that the boundary nodes are
-        stored under.
-    :type alias: str
+        stored under. Default is 'boundary_nodes'.
+    :type alias: str, optional
 
     :returns: The set of nodes in the partition that are on the boundary.
     :rtype: Set
@@ -166,6 +166,9 @@ def interior_boundaries(partition, previous: Set, new_edges: Set, old_edges: Set
 
 def flips(partition) -> Dict:
     """
+    :param partition: A partition of a Graph
+    :type partition: :class:`~gerrychain.partition.Partition`
+
     :returns: The flips that were made to get from the parent partition to the
         given partition.
     :rtype: Dict