canvaslms 5.9__tar.gz → 6.0__tar.gz

{canvaslms-5.9 → canvaslms-6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: canvaslms
-Version: 5.9
+Version: 6.0
 Summary: Command-line interface to Canvas LMS
 License-Expression: MIT
 License-File: LICENSE

{canvaslms-5.9 → canvaslms-6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "canvaslms"
-version = "5.9"
+version = "6.0"
 description = "Command-line interface to Canvas LMS"
 authors = [
   {name = "Daniel Bosk", email = "daniel@bosk.se"}

{canvaslms-5.9 → canvaslms-6.0}/src/canvaslms/cli/assignments.nw

@@ -381,6 +381,8 @@ and pushed back without losing any formatting.
 view_parser = assignments_subp.add_parser("view",
     help="View assignment details",
     description="Views detailed information about assignments. "
+      "When piped (not a TTY), outputs YAML front matter with a 'regex' field "
+      "for stable identification, followed by the description as Markdown. "
       "Use --html to preserve HTML instead of converting to Markdown.")
 view_parser.set_defaults(func=assignments_view_command)
 add_assignment_option(view_parser)
@@ -418,16 +420,24 @@ edit_parser = assignments_subp.add_parser("edit",
     description="Edit assignment content. Without -f, opens each matching "
       "assignment in your editor for interactive editing with preview. "
       "With -f, reads from a Markdown file with YAML front matter and updates "
-      "directly (script-friendly). If the YAML contains an 'id' field, the "
-      "command uses it to identify the assignment; use --create to create a new "
-      "assignment if the ID is not found. Use --html to read/edit HTML directly "
-      "without Markdown conversion.")
+      "directly (script-friendly). "
+      "Assignment matching workflow: "
+      "(1) If the YAML contains a 'regex' field, it matches assignments by "
+      "name or Canvas numeric ID. The regex is tested against both. "
+      "This provides stable identification: export an assignment with "
+      "'assignments view -a \"Lab 1.*\" > lab.md', edit locally, and push "
+      "back with 'assignments edit -f lab.md'---the regex stays constant "
+      "even if the name changes slightly. "
+      "(2) If no 'regex' is present but 'name' is, exact name matching is "
+      "used. "
+      "(3) Otherwise, falls back to -a, -A, and -M filters. "
+      "Use --html to read/edit HTML directly without Markdown conversion.")
 edit_parser.set_defaults(func=assignments_edit_command)
 add_assignment_option(edit_parser, ungraded=False, required=True)
 canvaslms.cli.content.add_file_option(edit_parser)
 edit_parser.add_argument("--create",
     action="store_true",
-    help="Create a new assignment if the ID in the YAML is not found")
+    help="Create a new assignment if no match is found")
 edit_parser.add_argument("--html",
     action="store_true",
     help="Read file as HTML instead of converting from Markdown. "
@@ -633,11 +643,14 @@ contain this assignment. When editing:
 <<output assignment in editable format>>=
 <<get current modules for assignment>>
 <<get rubric for assignment>>
+<<determine regex for assignment>>
 output = canvaslms.cli.content.render_to_markdown(
     assignment,
     canvaslms.cli.content.ASSIGNMENT_SCHEMA,
     content_attr='description',
-    extra_attributes={'modules': assignment_modules, 'rubric': assignment_rubric})
+    extra_attributes={'modules': assignment_modules,
+                      'rubric': assignment_rubric,
+                      'regex': assignment_regex})
 print(output)
 @
 
@@ -657,6 +670,19 @@ assignment_modules = modules.get_item_modules(
     assignment.course, 'Assignment', assignment.id)
 @
 
+When determining the regex for export, we follow the same approach as for pages.
+If the user specified a non-default [[-a]] pattern, we use that regex verbatim
+(capturing their intent). Otherwise, we generate an exact-match regex from the
+assignment name by escaping special characters and adding anchors.
+<<determine regex for assignment>>=
+if hasattr(args, 'assignment') and args.assignment not in (None, '.*'):
+  # User specified a -a filter, use it verbatim
+  assignment_regex = args.assignment
+else:
+  # Generate exact-match regex from name
+  assignment_regex = '^' + re.escape(assignment.name) + '$'
+@
+
 \subsection{HTML output format}
 
 When [[--html]] is specified, we preserve the original HTML content instead of
@@ -691,11 +717,14 @@ and pushed back using [[assignments edit --html -f]].
 <<output assignment in html format>>=
 <<get current modules for assignment>>
 <<get rubric for assignment>>
+<<determine regex for assignment>>
 output = canvaslms.cli.content.render_to_html(
     assignment,
     canvaslms.cli.content.ASSIGNMENT_SCHEMA,
     content_attr='description',
-    extra_attributes={'modules': assignment_modules, 'rubric': assignment_rubric})
+    extra_attributes={'modules': assignment_modules,
+                      'rubric': assignment_rubric,
+                      'regex': assignment_regex})
 print(output)
 @
 
@@ -1032,69 +1061,91 @@ try:
   # body_content is Markdown or HTML depending on args.html
   attributes, body_content = canvaslms.cli.content.read_content_from_file(args.file)
 except FileNotFoundError:
-  logger.error(f"File not found: {args.file}")
-  print(f"Error: File not found: {args.file}", file=sys.stderr)
-  return
+  canvaslms.cli.err(1, f"File not found: {args.file}")
 except Exception as e:
-  logger.error(f"Error reading file: {e}")
-  print(f"Error reading file: {e}", file=sys.stderr)
-  return
+  canvaslms.cli.err(1, f"Error reading file: {e}")
 
 errors = canvaslms.cli.content.validate_attributes(
     attributes, canvaslms.cli.content.ASSIGNMENT_SCHEMA)
 if errors:
   for error in errors:
-    print(f"Validation error: {error}", file=sys.stderr)
-  return
+    logger.error(f"Validation error: {error}")
+  canvaslms.cli.err(1, "File validation failed")
 @
 
 \subsection{Updating assignment with new content}
 
 We convert the content to HTML for Canvas (unless [[--html]] is specified, in
-which case the content is already HTML). If the YAML front matter contains an
-[[id]] field, we use it to identify the specific assignment to update. This
-enables a Git-based workflow where the assignment can be reliably identified
-even if the name changes. If the ID is not found and [[--create]] is specified,
-we create a new assignment instead.
-
-If no [[id]] is in the YAML, we fall back to the filter-based matching using
-[[-a]], [[-A]], and [[-M]] options (the existing behavior).
+which case the content is already HTML).
+
+The matching strategy prioritizes reliability and safety:
+\begin{enumerate}
+\item If the YAML contains a [[regex]] field, we compile it and match against
+  assignment names and Canvas numeric IDs. This provides stable identification
+  even when names change, as long as the new name still matches the pattern.
+\item If no [[regex]] is in the YAML but a [[name]] is present, we use exact
+  name matching. This is safe because it won't accidentally match multiple
+  assignments.
+\item As a last resort (for backward compatibility), we fall back to
+  filter-based matching using [[-a]], [[-A]], and [[-M]] options only if no
+  name is specified.
+\end{enumerate}
 <<update assignment with new content>>=
 if args.html:
   html_content = body_content  # Already HTML, no conversion needed
 else:
   html_content = pypandoc.convert_text(body_content, 'html', format='md')
 
-if 'id' in attributes and attributes['id']:
-  <<update or create assignment by id>>
+if 'regex' in attributes and attributes['regex']:
+  <<update or create assignment by regex>>
 else:
   <<update assignments by filter matching>>
 @
 
-\subsubsection{ID-based assignment identification}
+\subsubsection{Regex-based assignment identification}
 
-When the YAML contains an [[id]] field, we look up the assignment directly by
-its Canvas ID. This is more reliable than filter matching because it identifies
-exactly one assignment even if multiple assignments have similar names.
-<<update or create assignment by id>>=
-assignment_id = attributes['id']
+When the YAML contains a [[regex]] field, we use [[match_item_by_regex]] from
+the content module to find the matching assignment. The function handles the
+three-way dispatch (one match, zero matches, multiple matches) and raises
+[[EmptyListError]] or [[MultipleMatchesError]] as appropriate.
+
+We match the regex against both assignment names and Canvas numeric IDs,
+providing flexibility: an assignment can be identified by a pattern in its name
+(\enquote{Lab 1.*}) or by its numeric ID (\verb|^12345$|).
+
+If exactly one assignment matches, we update it. If no assignments match and
+[[--create]] is specified, we create a new one. If multiple assignments match,
+the exception message lists the matching names so the user can make the regex
+more specific.
+<<update or create assignment by regex>>=
+regex_pattern = attributes['regex']
 course_list = courses.process_course_option(canvas, args)
 if not course_list:
-  print("Error: No courses found matching criteria", file=sys.stderr)
-  return
+  canvaslms.cli.err(1, "No courses found matching criteria")
 
 course = course_list[0]
+
+all_assignments = list(course.get_assignments())
+for a in all_assignments:
+  a.course = course
+
 try:
-  assignment = course.get_assignment(assignment_id)
-  assignment.course = course
+  assignment = canvaslms.cli.content.match_item_by_regex(
+      all_assignments, regex_pattern,
+      [lambda a: a.name, lambda a: str(a.id)],
+      item_type="assignment",
+      name_func=lambda a: a.name)
   <<update existing assignment>>
-except Exception as e:
+except re.error as e:
+  canvaslms.cli.err(
+      1, f"Invalid regex pattern '{regex_pattern}': {e}")
+except canvaslms.cli.EmptyListError:
   if args.create:
     <<create new assignment>>
   else:
-    print(f"Error: Assignment with ID '{assignment_id}' not found. "
-          f"Use --create to create a new assignment.", file=sys.stderr)
-    return
+    canvaslms.cli.err(1,
+      f"No assignments match regex '{regex_pattern}'. "
+      f"Use --create to create a new assignment.")
 @
 
 When updating an existing assignment, we build the update dictionary and call
@@ -1115,8 +1166,8 @@ try:
   logger.info(f"Updated assignment: {assignment.name}")
   <<update assignment module membership>>
 except Exception as e:
-  logger.error(f"Error updating assignment '{assignment.name}': {e}")
-  print(f"Error updating assignment '{assignment.name}': {e}", file=sys.stderr)
+  canvaslms.cli.err(1,
+    f"Error updating assignment '{assignment.name}': {e}")
 @
 
 \subsubsection{Creating new assignments}
@@ -1142,11 +1193,11 @@ if 'published' in attributes:
 try:
   new_assignment = course.create_assignment(assignment=create_params)
   new_assignment.course = course
-  print(f"Created assignment: {new_assignment.name} (id: {new_assignment.id})", file=sys.stderr)
+  logger.info(f"Created assignment: {new_assignment.name} "
+    f"(id: {new_assignment.id})")
   <<update new assignment module membership>>
 except Exception as e:
-  logger.error(f"Error creating assignment: {e}")
-  print(f"Error creating assignment: {e}", file=sys.stderr)
+  canvaslms.cli.err(1, f"Error creating assignment: {e}")
 @
 
 For newly created assignments, we also process module membership if specified.
@@ -1161,14 +1212,65 @@ if 'modules' in attributes:
 
 \subsubsection{Filter-based assignment matching}
 
-When no ID is specified in the YAML, we use the filter options ([[-a]], [[-A]],
-[[-M]]) to find matching assignments. This maintains backwards compatibility
-with the original behavior.
+When no [[regex]] is specified in the YAML, we check whether a [[name]] is
+present. If so, we use exact name matching to find the assignment---this is
+critical for safety. Without it, the command would fall back to filter-based
+matching with the default [[-a '.*']] pattern, which matches \emph{all}
+assignments in the course. The result would be catastrophic: every assignment
+would be overwritten with the content from the file.
+
+If no [[name]] is present either, we fall back to filter-based matching using
+the [[-a]], [[-A]], and [[-M]] options (the original behavior). To prevent
+accidental mass-updates, we refuse to proceed if the filter matches more than
+one assignment.
 <<update assignments by filter matching>>=
-assignment_list = process_assignment_option(canvas, args)
+if 'name' in attributes and attributes['name']:
+  <<update or create assignment by name>>
+else:
+  assignment_list = process_assignment_option(canvas, args)
+  if len(assignment_list) > 1:
+    canvaslms.cli.err(1,
+      f"{len(assignment_list)} assignments match filter. "
+      f"Add 'name' or 'regex' to YAML, or use -a to narrow selection.")
+  for assignment in assignment_list:
+    <<update existing assignment>>
+@
 
-for assignment in assignment_list:
+\subsubsection{Name-based assignment identification}
+
+When no [[regex]] is specified in the YAML but a [[name]] is present, we use
+[[match_item_by_name]] from the content module for exact name matching. This
+avoids the catastrophic scenario where the default [[-a '.*']] pattern matches
+all assignments and overwrites them all with the file content.
+
+If exactly one assignment matches, we update it. If none match and [[--create]]
+is specified, we create a new assignment. If multiple assignments share the same
+name, the exception tells the user to add a [[regex]] field to disambiguate.
+<<update or create assignment by name>>=
+name = attributes['name']
+course_list = courses.process_course_option(canvas, args)
+if not course_list:
+  canvaslms.cli.err(1, "No courses found matching criteria")
+
+course = course_list[0]
+
+all_assignments = list(course.get_assignments())
+for a in all_assignments:
+  a.course = course
+
+try:
+  assignment = canvaslms.cli.content.match_item_by_name(
+      all_assignments, name,
+      lambda a: a.name,
+      item_type="assignment")
   <<update existing assignment>>
+except canvaslms.cli.EmptyListError:
+  if args.create:
+    <<create new assignment>>
+  else:
+    canvaslms.cli.err(1,
+      f"No assignments match name '{name}'. "
+      f"Use --create to create a new assignment.")
 @
 
 We add optional attributes only if they are present in the YAML front matter.

{canvaslms-5.9 → canvaslms-6.0}/src/canvaslms/cli/cli.nw

@@ -76,9 +76,19 @@ import argparse
 \section{Printing errors and warnings}
 
 We want uniform error handling.
+Both [[EmptyListError]] and [[MultipleMatchesError]] represent query-result
+conditions: the caller asked for items and got the wrong number.
+Different callers handle these differently---interactive commands may catch
+them locally and continue, while batch commands let them propagate to the
+main handler for uniform treatment.
 <<classes and exceptions>>=
 class EmptyListError(Exception):
-  """Exception raised when a process function returns an empty list"""
+  """Exception raised when a query returns no matching items"""
+  pass
+
+class MultipleMatchesError(Exception):
+  """Exception raised when a query matches multiple items
+  but exactly one was expected"""
   pass
 @
 
@@ -356,6 +366,19 @@ argp.add_argument("-v", "--verbose",
 @
 
 
+\subsection{Cache control}
+
+Most commands speed up by caching the Canvas API object between runs.
+Occasionally you want to bypass the cache for a single command,
+for example right after creating or updating objects.
+
+<<add global options to argp>>=
+argp.add_argument("--no-cache",
+  action="store_true",
+  help="Do not read or write the persistent Canvas object cache")
+@
+
+
 \subsection{Logging in and setting up Canvas}
 
 Each subcommand will have its own module in the package.
@@ -398,6 +421,11 @@ if args.func:
       err(1, str(e))
     else:
       sys.exit(1)
+  except MultipleMatchesError as e:
+    if args.quiet == 0:
+      err(1, str(e))
+    else:
+      sys.exit(1)
 @
 
 We know that the [[login]] command doesn't need the Canvas object.
@@ -445,15 +473,25 @@ Before creating a new Canvas object from scratch, we try to load it from the
 persistent cache.
 This can significantly speed up commands by reusing previously fetched course
 data, assignments, users, and submissions.
+If the cached object becomes stale (for example, right after creating a quiz),
+you can bypass the cache with [[--no-cache]].
+
+For example:
+\begin{verbatim}
+canvaslms --no-cache quizzes export -c "My Course" -a "My Quiz"
+\end{verbatim}
 <<try to load canvas from cache>>=
-canvas = canvaslms.cli.cache.load_canvas_cache(token, hostname)
+if args.no_cache:
+  canvas = None
+else:
+  canvas = canvaslms.cli.cache.load_canvas_cache(token, hostname)
 @
 
 After successfully executing a command, we save the Canvas object to the cache
 for future use.
 We only save if the canvas object was actually used (not [[None]]).
 <<save canvas to cache after command>>=
-if canvas:
+if canvas and not args.no_cache:
   canvaslms.cli.cache.save_canvas_cache(canvas, token, hostname)
 @