Merge pull request #10 from paradoxysm/release

0.1.7 Release to Production

Author: paradoxysm

.coveragerc

@@ -0,0 +1,3 @@
+[report]
+exclude_lines =
+    raise NotImplementedError

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md

@@ -1,16 +1,8 @@
----
-name: Pull request
-about: Propose a pull request
-title: ''
-labels: ''
-assignees: ''
-
----
-
 Please assign an appropriate label to the PR:
-- bug : This PR fixes a bug
-- documentation : This PR improves on the documentation
-- enhancement : This PR implements a new feature or enhancement
+- bug : This PR fixes a bug.
+- documentation : This PR improves on the documentation.
+- enhancement : This PR implements a new feature or enhancement.
+- release : This PR is a release PR to the `release` branch.
 
 **Reference Issues/PRs where applicable**
 

CHANGES.md

@@ -9,6 +9,19 @@
 - ![Documentation](https://img.shields.io/badge/-Documentation-blue) : An update to the documentation.
 - ![Other](https://img.shields.io/badge/-Other-lightgrey) : Miscellaneous updates such as package structure or GitHub quality of life updates.
 
+
+### Version 0.1.7
+
+- ![Feature](https://img.shields.io/badge/-Feature-blueviolet) : [`_utils.format_array`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_utils.py) is now removed and all code is changed to reflect. **This is a major feature. `kdtrees 0.1.7` is not backwards-compatible.**
+- ![Enhancement](https://img.shields.io/badge/-Enhancement-purple) : `__len__` no longer a required function in [`KDTreeType`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_kdtree_type.py) as per [ISS #9](https://github.com/paradoxysm/kdtrees/issues/9).
+- ![Fix](https://img.shields.io/badge/-Fix-red) : [`_kdtrees.initialize`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_kdtrees.py) now correctly handles `accept` overrides to update presorted arrays.
+- ![Fix](https://img.shields.io/badge/-Fix-red) : [`_utils.check_dimensionality`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_utils.py) now properly checks `accept` overridden types without unexepected errors.
+- ![Fix](https://img.shields.io/badge/-Fix-red) : [`KDTreeType`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_kdtree_type.py) now implements `__lt__` for proper sorting.
+- ![Fix](https://img.shields.io/badge/-Fix-red) : [`KDTreeType`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_kdtree_type.py) no longer extends `list` so that it can be properly wrapped into a list.
+- ![Fix](https://img.shields.io/badge/-Fix-red) : [`_kdtrees.nearest_neighbor`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_kdtrees.py) and [`_kdtrees.proximal_neighbor`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_kdtrees.py) now properly call [`_utils.distance`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/kdtrees/_utils.py) with `accept` override applied as per [ISS #7](https://github.com/paradoxysm/kdtrees/issues/7).
+- ![Documentation](https://img.shields.io/badge/-Documentation-blue) : Updated documentation to reflect changes.
+- ![Documentation](https://img.shields.io/badge/-Documentation-blue) : Implemented a number of new tests in [`tests`](https://github.com/paradoxysm/kdtrees/tree/0.1.7/tests/)
+
 ### Version 0.1.6
 
 - ![Enhancement](https://img.shields.io/badge/-Enhancement-purple) : `__iter__` no longer required for [`KDTreeType`](https://github.com/paradoxysm/kdtrees/blob/0.1.6/kdtrees/_kdtree_type.py) as per [ISS #2](https://github.com/paradoxysm/kdtrees/issues/2).

README.md

@@ -16,7 +16,7 @@ A K-Dimensional Tree, or K-D Tree, is a space-partitioning data structure which
 
 kdtrees implementation of a K-D Tree allows for construction, modification, searching, and other helpful functions such as k-nearest neighbors. It also maintains the tree in a pseudo-balanced manner through a secondary invariant where every node is the median ± dimensionality of subsidiary nodes along a specific axis.
 
-More details regarding this implementation can be found in the documentation [here](https://github.com/paradoxysm/kdtrees/tree/master/doc).
+More details regarding this implementation can be found in the documentation [here](https://github.com/paradoxysm/kdtrees/tree/0.1.7/doc).
 
 ## Installation
 
@@ -37,19 +37,21 @@ pip install kdtrees
 
 ## Changelog
 
-See the [changelog](https://github.com/paradoxysm/kdtrees/tree/master/CHANGES.md) for a history of notable changes to kdtrees.
+See the [changelog](https://github.com/paradoxysm/kdtrees/blob/0.1.7/CHANGES.md) for a history of notable changes to kdtrees.
 
 ## Development
 
 kdtrees is fully implemented for basic functionality. However, it may not have every utility function or have the most optimized algorithms. We welcome contributors of all experience levels to help grow and improve kdtrees. Guides on development, testing, and contribution are in the works!
 
 Currently, particular contributions regarding pytests and documentation would be greatly appreciated. Guides and examples of usage are warmly welcomed.
 
+There are three main branches for development and release. `master` is the current development build; `release` is the staging branch for releases; `production` is the current public release build.
+
 ## Help and Support
 
 ### Documentation
 
-Documentation for kdtrees can be found [here](https://github.com/paradoxysm/kdtrees/tree/master/doc).
+Documentation for kdtrees can be found [here](https://github.com/paradoxysm/kdtrees/tree/0.1.7/doc).
 
 ### Issues and Questions
 

doc/README.md

@@ -2,7 +2,7 @@
 
 All documentation for kdtrees is located here!
 
-[**pydoc**](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc) : Documentation regarding python classes and functions.
+[**pydoc**](https://github.com/paradoxysm/kdtrees/tree/0.1.7/doc/pydoc) : Documentation regarding python classes and functions.
 
 # KDTrees Overview
 
@@ -14,7 +14,7 @@ kdtrees supports all builtin types and numpy types. However, additional support
 
 **Construction**
 
-kdtrees constructs a K-D Tree from a given list of points in a manner such that a pseudo-balanced tree is produced (i.e. A tree that satisfies the secondary invariant). It does this by presorting the list of points along each of the available axes. At each recursive entry, the median point along an alternating axis of discrimination is chosen as the root of the sub-tree. This produces a pseudo-balanced tree in *O(nlogn)*. For details see [`initialize`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#initialize).
+kdtrees constructs a K-D Tree from a given list of points in a manner such that a pseudo-balanced tree is produced (i.e. A tree that satisfies the secondary invariant). It does this by presorting the list of points along each of the available axes. At each recursive entry, the median point along an alternating axis of discrimination is chosen as the root of the sub-tree. This produces a pseudo-balanced tree in *O(nlogn)*. For details see [`initialize`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#initialize).
 
 **Visualization**
 
@@ -29,28 +29,28 @@ kdtrees can be visualized in a preorder traversal. This is one such example:
 		None
 		None
 ```
-For details see [`visualize`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#visualize).
+For details see [`visualize`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#visualize).
 
 **Insertion and Deletion**
 
-kdtrees supports insertion and deletion in preorder traversal. The tree automatically balances as needed. It runs in *O(logn)*. For details see [`insert`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#insert) and [`delete`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#delete).
+kdtrees supports insertion and deletion in preorder traversal. The tree automatically balances as needed. It runs in *O(n)*. For details see [`insert`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#insert) and [`delete`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#delete).
 
 **Searching**
 
-kdtrees supports searches in preorder traversal, running in *O(logn)*. kdtrees searches and produces the KDTree that holds the queried value. Finding none, it will return None. For details see [`search`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#search).
+kdtrees supports searches in preorder traversal, running in *O(logn)*. kdtrees searches and produces the KDTree that holds the queried value. Finding none, it will return None. For details see [`search`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#search).
 
 **Aggregating**
 
-kdtrees can aggregate all subsidiary nodes, produced as a list in preorder, running in *O(logn)*. For details see [`collect`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#collect).
+kdtrees can aggregate all subsidiary nodes, produced as a list in preorder, running in *O(logn)*. For details see [`collect`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#collect).
 
 **Balancing**
 
-kdtrees balances in a pseudo-balanced manner, satisfying the secondary invariant. If the KDTree does not satisfy this invariant, it is reconstructed anew and thus returned to pseudo-balance. For details see [`balance`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#balance).
+kdtrees balances in a pseudo-balanced manner, satisfying the secondary invariant. If the KDTree does not satisfy this invariant, it is reconstructed anew and thus returned to pseudo-balance. For details see [`balance`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#balance).
 
 **K-Nearest Neighbors**
 
-kdtrees supports finding k-nearest neighbors, finding a specified number of (1 if not specified) of nodes that are closest to the query point. Ties are broken based on the preorder traversal (i.e. left-most nodes are prioritized). It produces a list of tuples, containing the value of the node and its corresponding distance to the query point. For details see [`nearest_neighbor`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#nearest_neighbor).
+kdtrees supports finding k-nearest neighbors, finding a specified number of (1 if not specified) of nodes that are closest to the query point. Ties are broken based on the preorder traversal (i.e. left-most nodes are prioritized). It produces a list of tuples, containing the value of the node and its corresponding distance to the query point. For details see [`nearest_neighbor`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#nearest_neighbor).
 
 **Neighbors-within-Distance**
 
-kdtrees is also able to find all neighbors within a specified distance (0 if not specified). This produces a list of tuples, containing the value of the node and its corresponding distance to the query point. For details see [`proximal_neighbor`](https://github.com/paradoxysm/kdtrees/tree/master/doc/pydoc/doc_kdtree.md#proximal_neighbor).
+kdtrees is also able to find all neighbors within a specified distance (0 if not specified). This produces a list of tuples, containing the value of the node and its corresponding distance to the query point. For details see [`proximal_neighbor`](https://github.com/paradoxysm/kdtrees/blob/0.1.7/doc/pydoc/doc_kdtree.md#proximal_neighbor).

doc/pydoc/doc_kdtree.md

@@ -12,7 +12,7 @@ median ± dimensionality of all nodes contained in the KDTree.
 
 **Parameters**
 ```
-value : array-like
+value : array-like or object
  Value at the KDTree node.
 
 k : int, default=0
@@ -34,6 +34,9 @@ right : KDTree
 
 nodes : int
  Number of nodes in the KDTree, including itself.
+
+accept : KDTreeType or None
+  Override and allow a custom type to be accepted.
 ```
 
 ## initialize
@@ -49,22 +52,23 @@ as the root.
 **Parameters**
 ```
 points : array-like, shape (n_points, *)
- List of points to build a KDTree where the last axis denotes the features
+  List of points to build a KDTree where the last axis denotes the features.
+  If `accept` is a KDTreeType, list can contain this type.
 
 k : int or None, default=None
- Dimensionality of the points. If None, `initialize` will self-detect.
+  Dimensionality of the points. If None, `initialize` will self-detect.
 
 init_axis : int, default=0
- Initial axis to generate the KDTree.
+  Initial axis to generate the KDTree.
 
 accept : KDTreeType or None
- Override and allow custom types to be accepted.
+  Override and allow a custom type to be accepted.
 ```
 
 **Returns**
 ```
 tree : KDTree
- The root of the KDTree built from `points`
+ The root of the KDTree built from `points`.
 ```
 
 ## visualize
@@ -90,7 +94,8 @@ Insert a point into the KDTree.
 **Parameters**
 ```
 point : array-like or scalar
- The point to be inserted, where the last axis denotes the features.
+  The point (KDTreeType if `accept` is used) to be inserted,
+  where the last axis denotes the features.
 ```
 
 **Returns**
@@ -110,7 +115,8 @@ Returns the KDTree node if found, None otherwise.
 **Parameters**
 ```
 point : array-like or scalar
- The point being searched, where the last axis denotes the features.
+ The point (KDTreeType if `accept` is used) being searched,
+ where the last axis denotes the features.
 ```
 
 **Returns**
@@ -131,7 +137,8 @@ KDTree. Returns the same tree if the point was not found.
 **Parameters**
 ```
 point : array-like or scalar
- The point to be deleted, where the last axis denotes the features.
+ The point (KDTreeType if `accept` is used) to be deleted,
+ where the last axis denotes the features.
 ```
 
 **Returns**
@@ -190,20 +197,21 @@ Determine the `n` nearest KDTree nodes to `point` and their distances.
 **Parameters**
 ```
 point : array-like or scalar
- The query point, where the last axis denotes the features.
+ The query point (KDTreeType if `accept` is used),
+ where the last axis denotes the features.
 
 n : int, default=1
  The number of neighbors to search for.
 
-neighbors : list, default=[]
+neighbors : array-like, default=[]
  The list of `n` tuples, referring to `n` nearest neighbors,
  sorted based on proximity. The first value in the tuple is the
  point, while the second is the distance to `point`.
 ```
 
 **Returns**
 ```
-neighbors : list, shape (n_neighbors, 2)
+neighbors : ndarray, shape (n_neighbors, 2)
  The list of `n` tuples, referring to `n` nearest neighbors.
 ```
 
@@ -218,12 +226,13 @@ to `point` and their distances.
 **Parameters**
 ```
 point : array-like or scalar
- The query point, where the last axis denotes the features.
+ The query point (KDTreeType if `accept` is used),
+ where the last axis denotes the features.
 
 d : int, default=0
  The maximum acceptable distance for neighbors.
 
-neighbors : list, default=[]
+neighbors : array-like, default=[]
  The list of `n` tuples, referring to proximal neighbors within
  `d` distance from `point`, sorted based on proximity.
  The first value in the tuple is the point, while the
@@ -232,7 +241,7 @@ neighbors : list, default=[]
 
 **Returns**
 ```
-neighbors : list, shape (n_neighbors, 2)
+neighbors : ndarray, shape (n_neighbors, 2)
  The list of `n` tuples, referring to proximal neighbors within
  `d` distance from `point`.
 ```

doc/pydoc/doc_kdtree_type.md

@@ -56,18 +56,23 @@ ne : bool
 	True if `other` is not equivalent to this `KDTreeType`
 ```
 
-## __len__
+## __lt__
 ```python
-len(KDTreeType)
-KDTreeType.__len__()
+KDTreeType < KDTreeType
+KDTreeType.__lt__(other)
+```
+Return if this `KDTreeType` is 'less' than `other`.
+
+**Parameters**
+```
+other : object
+	The object in question.
 ```
-Return the 'length' of the KDTreeType. This needs to be
-defined based on the custom implementation.
 
 **Returns**
 ```
-length : int
-	The 'length' of this `KDTreeType`.
+lt : bool
+	True if this `KDTreeType` is 'less' than `other`.
 ```
 
 ## __getitem__

doc/pydoc/doc_utils.md

@@ -1,35 +1,9 @@
 # kdtrees._utils
 Utilities for Various Tasks
-## format_array
-```python
-format_array(arr, l=False, accept=None)
-```
-
-Format the given array or scalar into a numpy ndarray
-such that the last axis denotes the features.
-If the argument given is a scalar, wrap into a list first.
-
-**Parameters**
-```
-arr : array-like or scalar
- Array-like object or scalar to convert into ndarray.
-
-l : bool
- `l` should be set to True if `arr` is semantically a list of items.
-
-accept : None or object, default=None
-  Accept override type. Allow `arr` to be this type
-```
-
-**Returns**
-```
-ndarr : ndarray
- Formatted ndarray where the last axis denotes the features.
-```
 
 ## check_dimensionality
 ```python
-check_dimensionality(*args, l=False, accept=None)
+check_dimensionality(*args, accept=None)
 ```
 
 Check that all arguments have the same dimensionality.
@@ -41,14 +15,11 @@ attribute, use that instead.
 **Parameters**
 ```
 *args : tuple, default=()
- Tuple of array-like objects where the last axis denotes the features.
-
-l : bool
- `l` should be set to True if `args` is a tuple where every
- item is semantically a list of items.
+	Tuple of ndarray objects where the last axis denotes the features.
+	If `accept` is an object, it can be this type.
 
 accept : None or object, default=None
-  Accept override type. Check the `dim` attribute of this object
+	Accept override type. Check the `dim` attribute of this object.
 ```
 
 **Returns**
@@ -69,19 +40,20 @@ function, use that instead. Uses `obj1.distance(obj2)`.
 
 **Parameters**
 ```
-obj1 : array-like or object, default=()
-	Tuple of array-like objects where the last axis denotes the features.
+obj1 : array-like or scalar or object
+	array-like or scalar where the last axis denotes the features.
+	If `accept` is an object, it can be this type.
 
-l : bool
-	`l` should be set to True if `args` is a tuple where every
-	item is semantically a list of items.
+obj2 : array-like or scalar or object
+	array-like or scalar where the last axis denotes the features.
+	If `accept` is an object, it can be this type.
 
 accept : None or object, default=None
-	Accept override type. Check the dimensionality attribute of this object
+	Accept override type. Use the `distance` function of this type.
 ```
 
 **Returns**
 ```
-dim : int
-	The dimensionality of all given arguments.
+distance : int
+	The distance between `obj1` and `obj2`.
 ```