Merge pull request #15 from JamesPImes/trs_list

Implemented `TRSList` class

guides/guides/tractlist.md

@@ -3,7 +3,7 @@
 
 `TractList` objects are a subclass of the built-in `list`, with added functionality to:
 
-* type-check any objects that are added to it (if an object other than a `Tract` is appended, it will raise a `TractListTypeError`, although it can also unpack `Tract` objects out of `PLSSDesc`, `TractList` or other iterables that hold any of those object types -- see the `.from_multiple()` method).
+* type-check any objects that are added to it (if an object other than a `Tract` is appended, it will raise a `TypeError`, although it can also unpack `Tract` objects out of `PLSSDesc`, `TractList` or other iterables that hold any of those object types -- see the `.from_multiple()` method).
 
 * compile `Tract` data to lists or dicts, or write it to .csv files (see [the guide on extracting `Tract` data in bulk](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/extracting_data.md#guide-to-extracting-data-in-bulk-from-parsed-objects)).
 
@@ -33,14 +33,14 @@ normal_list = [tract1, tract2, plssdesc1, another_tractlist]
 some_tractlist = pytrs.TractList(normal_list)
 ```
 
-If the iterable includes an object of any other kind, it will raise a `TractListTypeError`.
+If the iterable includes an object of any other kind, it will raise a `TypeError`.
 ```
 bad_list = ['foo', tract1, tract2, plssdesc1, another_tractlist]
 some_tractlist = pytrs.TractList(bad_list)
 ```
 Raises... 
 ```
-pytrs.parser.parser.TractListTypeError: Only Tract objects (or unpacked PLSSDesc / TractList objects) may be added to TractList. Iterable contained <class 'str'>.
+TypeError: TractList will accept only type `pytrs.Tract`. Iterable contained <class 'str'>.
 ```
 
 ### Robustly construct a `TractList` from multiple sources with `.from_multiple()`
@@ -52,7 +52,7 @@ normal_list1 = [tract1, tract2]
 
 nested_list = [normal_list1, another_tractlist]
 
-# This would raise a TractListTypeError:
+# This would raise a TypeError:
 # some_tractlist = pytrs.TractList(nested_list)
 
 # This is fine.

guides/guides/trs.md

@@ -105,3 +105,61 @@ Footnotes:
 * `twp_num` is not `None` -> This township is fine.
 * (and similar for range and section)
 
+
+## `TRSList` objects
+
+The class `TRSList` is very similar to [`TractList`](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/tractlist.md) (in fact they are both subclassed from the same superclass and contain many of the same methods), but it holds `TRS` objects instead of `Tract` objects.
+
+If you add to a `TRSList` a string, the string will first be converted to a `TRS` object.
+
+```
+trs1 = pytrs.TRS('154n97w14')
+trs2 = pytrs.TRS('154n97w15')
+trs_list = pytrs.TRSList([trs1, trs2])
+
+# Or add strings directly (they will be converted to TRS objects):
+trs_list = TRSList(['154n97w14', '154n97w15'])
+```
+
+We can also pass to it `Tract` objects, in which case the `.trs` attribute will be extracted and converted to a `TRS` object before being added.
+```
+tract = pytrs.Tract('NE/4', trs='154n97w14')
+trs_list = pytrs.TRSList([tract])
+```
+
+Similarly, we can extract/convert the `.trs` attributes in `Tract` objects from a `PLSSDesc` or `TractList` object if we pass them to `.extend()`:
+```
+plssdesc = pytrs.PLSSDesc('T154N-R97W Sec 14: NE/4, Sec 15: W/2')
+trs_list = pytrs.TRSList()
+trs_list.extend(plssdesc)
+
+# or even...
+trs_list = pytrs.TRSList(plssdesc)
+```
+(In either case, `trs_list` contains `TRS` objects for `154n97w14` and `154n97w15`.)
+
+
+### Sorting / Filtering / Grouping
+
+We can sort, filter, or group `TRSList` objects, essentially the same [as with `TractList` objects](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/sort_filter_group.md#guide-to-sorting--filtering--grouping-tract-objects-in-a-tractlist-or-plssdesc):
+```
+trs_list = pytrs.TRSList(['154n97w14', '154n97w14', '154n97w15', '155n97w22'])
+trs_list.custom_sort(sort_key='s,r,t')
+group_dict = trs_list.group(by_attribute='twprge', sort_key='s,r')
+selected = trs_list.filter(key=lambda x: x.twprge = '154n97w')
+discarded = trs_list.filter_duplicates(drop=True)
+``` 
+
+## Get a regular list of strings with `TRSList.to_strings()`
+
+Use this method to get a regular list of strings in the pyTRS standard format.
+
+```
+trs1 = pytrs.TRS('154n97w14')
+trs2 = pytrs.TRS('154n97w01')
+trs_list = pytrs.TRSList([trs1, trs2])
+
+plain_list = trs_list.to_strings()
+```
+
+In this example, `plain_list` is simply `['154n97w14', '154n97w01']` (holding strings).

guides/readme.md

@@ -14,7 +14,7 @@ __Note also:__ These guides are not intended to cover all of the functionality o
 | [plssdesc.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/plssdesc.md)       | Parsing PLSS land descriptions into tracts. | `PLSSDesc`       |
 | [tract_attributes.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/tract_attributes.md) | The names of data fields of parsed descriptions (i.e. `Tract` <br> attributes). | `Tract` |
 | [tract.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/tract.md)          | Parsing tracts into lots/aliquots.          | `Tract`          |
-| [trs.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/trs.md)     | The pyTRS standard format for Twp/Rge/Sec     | `TRS` |
+| [trs.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/trs.md)     | The pyTRS standard format for Twp/Rge/Sec     | `TRS`, `TRSList` |
 | [config.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/config.md)    | Configuring how the descriptions and lots/aliquots are parsed | `PLSSDesc`, `Tract` |
 | [extracting_data.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/extracting_data.md) | Extracting data fields (e.g., township, range, section, description, <br>lots, aliquots, etc.) from tracts and land descriptions in bulk. | `Tract`, `TractList`, (`PLSSDesc`\*\*) |
 | [tractlist.md](https://github.com/JamesPImes/pyTRS/blob/master/guides/guides/tractlist.md) | Working with tracts that were parsed from multiple land <br> descriptions, and/or multiple individually-created tracts. | `TractList` (`PLSSDesc`\*\*) |

pytrs/__init__.py

@@ -34,6 +34,7 @@
     Tract,
     TractList,
     TRS,
+    TRSList,
     Config,
 
     # Misc. functions for examining / handling descriptions

pytrs/_constants.py

@@ -1,6 +1,6 @@
 
-__version__ = '1.0.1'
-__version_date__ = '4/7/2021'
+__version__ = '1.1.0'
+__version_date__ = '4/21/2021'
 __author__ = 'James P. Imes'
 __email__ = 'jamesimes@gmail.com'
 __website__ = 'https://github.com/JamesPImes/pyTRS'

pytrs/parser/__init__.py

@@ -7,10 +7,13 @@
 > Tract objects parse tract text into lots and aliquots.
 > Tract objects represent the land in a single, unique Twp/Rge/Sec, and
     also parse text into lots and aliquots.
+> TRS objects break a Twp/Rge/Sec into its components.
 > TractList objects contain a list of Tracts, and can compile that Tract
     data into broadly useful formats (i.e. into list, dict, string), as
     well as custom methods for sorting, grouping, and filtering the
     Tract objects themselves.
+> TRSList objects are similar to TractList, but instead hold TRS
+    objects.
 > Config objects configure parsing parameters for Tract and PLSSDesc.
 """
 
@@ -20,6 +23,7 @@
     Tract,
     TractList,
     TRS,
+    TRSList,
     Config,
 
     # Misc. functions for examining / handling descriptions