docassemble.AssemblyLine 4.7.0__tar.gz → 4.9.0__tar.gz

{docassemble_assemblyline-4.7.0/docassemble.AssemblyLine.egg-info → docassemble_assemblyline-4.9.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: docassemble.AssemblyLine
-Version: 4.7.0
+Version: 4.9.0
 Summary: Quickly go from a paper court form to a runnable, guided, step-by-step web application powered by Docassemble. Swap out branding and pre-built questions to meet your needs.
 Author-email: Suffolk Legal Innovation and Technology Lab <litlab@suffolk.edu>
 License-Expression: MIT
 Project-URL: Homepage, https://courtformsonline.org
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: docassemble.ALToolbox>=0.18.0
+Requires-Dist: docassemble.ALToolbox>=0.19.0
 Requires-Dist: docassemble.GitHubFeedbackForm>=0.4.1.1
 Dynamic: license-file
 

docassemble_assemblyline-4.9.0/docassemble/AssemblyLine/__init__.py

@@ -0,0 +1 @@
+__version__ = '4.9.0'

{docassemble_assemblyline-4.7.0 → docassemble_assemblyline-4.9.0}/docassemble/AssemblyLine/al_courts.py

@@ -22,20 +22,51 @@ __all__ = [
 
 
 class ALCourt(Court):
-    """Object representing a court in Massachusetts. We use a function on the CourtList object that filters courts by
+    """
+    Object representing a court in Massachusetts. We use a function on the CourtList object that filters courts by
     address and can use any of those three features of the court to do the filtering.
 
     <!-- TODO: it could be interesting to store a jurisdiction on a court. But this is non-trivial. Should it be geo boundaries?
     A list of cities? A list of counties? Instead, we use a function on the CourtList object that filters courts by
     address and can use any of those three features of the court to do the filtering.-->
+
+    Example:
+        In an interview:
+
+    ```yaml
+    objects:
+      - trial_court: ALCourt
+    ---
+    code: |
+      trial_court.name = "Example District Court"
+      trial_court.address.address = "123 Main Street"
+      trial_court.address.city = "Boston"
+      trial_court.address.state = "MA"
+      trial_court.address.zip = "02108"
+    ---
+    question: |
+      Your court
+    subquestion: |
+      ${ trial_court.short_label_and_address() }
+    ```
     """
 
     def init(self, *pargs, **kwargs) -> None:
-        """Create a new court object.
+        """
+        Create a new court object.
 
         Args:
             *pargs: Standard DAObject positional arguments.
             **kwargs: Standard DAObject keyword arguments.
+
+        Example:
+            Docassemble calls `init()` automatically during object creation.
+            See the class example for the rest of the setup.
+
+        ```yaml
+        objects:
+          - trial_court: ALCourt
+        ```
         """
         super().init(*pargs, **kwargs)
         if "address" not in kwargs:
@@ -84,6 +115,29 @@ class ALCourt(Court):
 
         Returns:
             str: string representing the court's name, with city if needed to disambiguate.
+
+        Example:
+            With `trial_court.name = "District Court"` and
+            `trial_court.address.city = "Boston"`, the city is added because it is
+            not already part of the name:
+
+            **Input (Mako)**
+
+        ```mako
+        ${ trial_court.short_label() }
+        ```
+
+            **Input (Jinja2)**
+
+        ```jinja2
+        {{ trial_court.short_label() }}
+        ```
+
+            **Output**
+
+        ```text
+        District Court (Boston)
+        ```
         """
         # Avoid forcing the interview to define the court's address
         if hasattr(self, "address") and hasattr(self.address, "city"):
@@ -100,6 +154,19 @@ class ALCourt(Court):
 
         Returns:
             str: string representing the court's name and address.
+
+        Example:
+            In question or Markdown attachment text (Mako):
+
+        ```mako
+        ${ trial_court.short_label_and_address() }
+        ```
+
+            In a DOCX template (Jinja2):
+
+        ```jinja2
+        {{ trial_court.short_label_and_address() }}
+        ```
         """
         return f"**{ self.short_label() }**[BR]{ self.address.on_one_line() }"
 
@@ -111,6 +178,19 @@ class ALCourt(Court):
 
         Returns:
             str: string representing the court's name and description.
+
+        Example:
+            In question or Markdown attachment text (Mako):
+
+        ```mako
+        ${ trial_court.short_description() }
+        ```
+
+            In a DOCX template (Jinja2):
+
+        ```jinja2
+        {{ trial_court.short_description() }}
+        ```
         """
         all_info = f"**{ self.short_label() }**"
         if hasattr(self, "address"):
@@ -129,6 +209,14 @@ class ALCourt(Court):
         Args:
             df_row: Pandas Series object.
             ensure_lat_long: bool, whether to use Google Maps to geocode the address if we don't have coordinates.
+
+        Example:
+            Given a pandas DataFrame loaded from your court data:
+
+        ```yaml
+        code: |
+          trial_court.from_row(court_dataframe.iloc[0])
+        ```
         """
         # A few columns we expect to see:
         # name
@@ -193,12 +281,28 @@ class ALCourt(Court):
         Use Google Maps to geocode the court's address and store the result in the location attribute.
 
         Deprecated: use geocode() instead.
+
+        Example:
+            In an interview code block:
+
+        ```yaml
+        code: |
+          trial_court.geolocate()
+        ```
         """
         self.geocode()
 
     def geocode(self) -> None:
         """
         Use Google Maps to geocode the court's address and store the result in the location attribute.
+
+        Example:
+            In an interview code block:
+
+        ```yaml
+        code: |
+          trial_court.geocode()
+        ```
         """
         self.address.geocode()
         self.location = self.address.location
@@ -213,14 +317,41 @@ class ALCourtLoader(DAObject):
     Attributes:
         filename (str): Path to the file containing court information.
         converters (Dict[str, Callable]): A dictionary of functions to apply to columns in the dataframe.
+
+    Example:
+        Place your court spreadsheet in the package’s `data/sources` directory:
+
+    ```yaml
+    objects:
+      - all_courts: ALCourtLoader.using(filename="courts.xlsx")
+    ---
+    question: |
+      Which court is handling your case?
+    fields:
+      - Court: selected_court_index
+        code: all_courts.all_courts()
+    ---
+    code: |
+      trial_court = all_courts.as_court("trial_court", selected_court_index)
+    ```
     """
 
     def init(self, *pargs, **kwargs) -> None:
-        """Create a new courtloader object.
+        """
+        Create a new courtloader object.
 
         Args:
             *pargs: Standard DAObject positional arguments.
             **kwargs: Standard DAObject keyword arguments.
+
+        Example:
+            Docassemble calls `init()` automatically during object creation.
+            See the class example for the rest of the setup.
+
+        ```yaml
+        objects:
+          - all_courts: ALCourtLoader.using(filename="courts.xlsx")
+        ```
         """
         super().init(*pargs, **kwargs)
         self.package = docassemble.base.functions.this_thread.current_question.package
@@ -242,6 +373,17 @@ class ALCourtLoader(DAObject):
 
         Returns:
             List[Tuple[int, str]]: List of tuples where each tuple contains (dataframe_index, display_value). The dataframe_index (int) can be used with as_court() to retrieve the full court object. The display_value (str) is the court's name or other display column value.
+
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        question: |
+          Which court is handling your case?
+        fields:
+          - Court: selected_court_index
+            code: all_courts.all_courts()
+        ```
         """
         return self.filter_courts(None)
 
@@ -256,6 +398,14 @@ class ALCourtLoader(DAObject):
             Set[str]:.
                 - A set containing unique values from the specified column.
                 - Returns an empty set if the column does not exist or an error occurs.
+
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        code: |
+          court_departments = all_courts.unique_column_values("department")
+        ```
         """
         df = self._load_courts()
         try:
@@ -273,6 +423,14 @@ class ALCourtLoader(DAObject):
 
         Returns:
             Set[str]: A list of all unique values in the specified row in the given spreadsheet.
+
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        code: |
+          court_counties = all_courts.county_list()
+        ```
         """
         return self.unique_column_values(column_name)
 
@@ -290,6 +448,14 @@ class ALCourtLoader(DAObject):
 
         Returns:
             bool: True if there is only one court associated with the specified county in the spreadsheet.
+
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        code: |
+          has_one_court_in_county = all_courts.county_has_one_court(users[0].address.county)
+        ```
         """
         return (
             len(self.filter_courts(court_types=county_name, column=county_column)) == 1
@@ -314,6 +480,13 @@ class ALCourtLoader(DAObject):
         Returns:
             ALCourt: The first court matching the county name.
 
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        code: |
+          trial_court = all_courts.county_court("trial_court", users[0].address.county)
+        ```
         """
         matches = self.filter_courts(court_types=county_name, column=county_column)
         if len(matches) > 0:
@@ -346,6 +519,17 @@ class ALCourtLoader(DAObject):
 
         Returns:
             List[Tuple[int, str]]: List of tuples where each tuple contains (dataframe_index, display_value). The dataframe_index (int) can be used with as_court() to retrieve the full court object. The display_value (str) is the court's name or other display column value.
+
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        question: |
+          Which court is handling your case?
+        fields:
+          - Court: selected_court_index
+            code: all_courts.matching_courts_in_county(users[0].address.county)
+        ```
         """
         return self.filter_courts(
             court_types=county_name,
@@ -357,11 +541,12 @@ class ALCourtLoader(DAObject):
 
     def filter_courts(
         self,
-        court_types: Optional[Union[List[str], str]],
+        court_types: Optional[Union[List[str], str]] = None,
         column: str = "department",
         display_column: str = "name",
         search_string: Optional[str] = None,
         search_columns: Optional[Union[List[str], str]] = None,
+        filters: Optional[Dict[str, Union[List[str], str]]] = None,
     ) -> List[Tuple[int, str]]:
         """
         Return a filtered subset of courts represented as a list of tuples.
@@ -378,8 +563,28 @@ class ALCourtLoader(DAObject):
             search_columns (Optional[Union[List[str], str]], optional): Columns to aggregate and search across with.
                 the search_string in a case-insensitive manner. Defaults to None.
 
+            filters (Optional[Dict[str, Union[List[str], str]]]): Additional exact matches by
+                column. Values must be strings or lists of strings. All columns must
+                match; a list matches any value in that column. An empty list matches
+                no courts. An empty mapping adds no restrictions. Unlike court_types,
+                an empty string is an exact match, not an omitted filter.
+
         Returns:
             List[Tuple[int, str]]: List of tuples where each tuple contains (dataframe_index, display_value). The dataframe_index (int) can be used with as_court() to retrieve the full court object. The display_value (str) is the court's name or other display column value.
+
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        question: |
+          Which court is handling your case?
+        fields:
+          - Court: selected_court_index
+            code: |
+              all_courts.filter_courts(
+                filters={"division_abbr": division, "address_county": county}
+              )
+        ```
         """
         df = self._load_courts()
         if court_types:
@@ -389,15 +594,15 @@ class ALCourtLoader(DAObject):
             filtered = df[df[column].isin(court_types)]
         else:
             filtered = df
-        if search_string and search_columns:
+        for filter_column, matches in (filters or {}).items():
+            if isinstance(matches, str):
+                matches = [matches]
+            filtered = filtered[filtered[filter_column].isin(matches)]
+        if search_string and search_columns and not filtered.empty:
             if isinstance(search_columns, str):
                 search_columns = [search_columns]
-            filtered["__search_col"] = (
-                filtered[search_columns].fillna("").agg(" ".join, axis=1)
-            )
-            filtered = filtered[
-                filtered["__search_col"].str.contains(search_string, case=False)
-            ]
+            search_values = filtered[search_columns].fillna("").agg(" ".join, axis=1)
+            filtered = filtered[search_values.str.contains(search_string, case=False)]
         return list(filtered[display_column].items())  # type: ignore
 
     def as_court(
@@ -413,6 +618,14 @@ class ALCourtLoader(DAObject):
 
         Returns:
             ALCourt: An ALCourt object initialized with data from the specified index.
+
+        Example:
+            With `all_courts` configured as an ALCourtLoader for your spreadsheet:
+
+        ```yaml
+        code: |
+          trial_court = all_courts.as_court("trial_court", selected_court_index)
+        ```
         """
         court = ALCourt(intrinsicName)
         df = self._load_courts()