Add Common Errors doc (#997)

* Add Common Errors

* Update changelog

.github/pull_request_template.md

@@ -33,6 +33,6 @@ Table.alter() # Comment regarding the change
 - [ ] If release, I have updated the `CITATION.cff`
 - [ ] This PR makes edits to table definitions: (yes/no)
 - [ ] If table edits, I have included an `alter` snippet for release notes.
-- [ ] If this PR makes changes to positon, I ran the relevant tests locally.
+- [ ] If this PR makes changes to position, I ran the relevant tests locally.
 - [ ] I have updated the `CHANGELOG.md` with PR number and description.
 - [ ] I have added/edited docs/notebooks to reflect the changes

CHANGELOG.md

@@ -16,6 +16,7 @@
 - Clean up old `TableChain.join` call in mixin delete. #982
 - Add pytests for position pipeline, various `test_mode` exceptions #966
 - Migrate `pip` dependencies from `environment.yml`s to `pyproject.toml` #966
+- Add documentation for common error messages #997
 
 ### Pipelines
 
@@ -29,7 +30,8 @@
 - Common
     - Don't insert lab member when creating lab team #983
 - Spikesorting
-    - Allow user to set smoothing timescale in `SortedSpikesGroup.get_firing_rate` #994
+    - Allow user to set smoothing timescale in `SortedSpikesGroup.get_firing_rate`
+        #994
     - Update docstrings #996
 
 ## [0.5.2] (April 22, 2024)

docs/mkdocs.yml

@@ -71,13 +71,14 @@ nav:
       - MUA Detection: notebooks/50_MUA_Detection.ipynb
   - Miscellaneous:
       - Overview: misc/index.md
+      - Common Errors: misc/common_errs.md
+      - Database Management: misc/database_management.md
+      - Export: misc/export.md
       - FigURL: misc/figurl_views.md
-      - Session Groups: misc/session_groups.md
       - Insert Data: misc/insert_data.md
-      - Mixin: misc/mixin.md
       - Merge Tables: misc/merge_tables.md
-      - Database Management: misc/database_management.md
-      - Export: misc/export.md
+      - Mixin: misc/mixin.md
+      - Session Groups: misc/session_groups.md
   - API Reference: api/ # defer to gen-files + literate-nav
   - How to Contribute: contribute.md
   - Change Log: CHANGELOG.md

docs/src/misc/common_errs.md

@@ -0,0 +1,111 @@
+# Common Errors
+
+## Debug Mode
+
+To enter into debug mode, you can add the following line to your code ...
+
+```python
+__import__("pdb").set_trace()
+```
+
+This will set a breakpoint in your code at that line. When you run your code, it
+will pause at that line and you can explore the variables in the current frame.
+Commands in this mode include ...
+
+- `u` and `d` to move up and down the stack
+- `l` to list the code around the current line
+- `q` to quit the debugger
+- `c` to continue running the code
+- `h` for help, which will list all the commands
+
+`ipython` and jupyter notebooks can launch a debugger automatically at the last
+error by running `%debug`.
+
+## Integrity
+
+```console
+IntegrityError: Cannot add or update a child row: a foreign key constraint fails (`schema`.`_table`, CONSTRAINT `_table_ibfk_1` FOREIGN KEY (`parent_field`) REFERENCES `other_schema`.`parent_name` (`parent_field`) ON DELETE RESTRICT ON UPDATE CASCADE)
+```
+
+`IntegrityError` during `insert` means that some part of the key you're
+inserting doesn't exist in the parent of the table you're inserting into. You
+can explore which that may be by doing the following...
+
+```python
+my_key = dict(value=key)  # whatever you're inserting
+MyTable.insert1(my_key)  # error here
+parents = MyTable.parents(as_objects=True)  # get the parents as FreeTables
+for parent in parents:  # iterate through the parents, with only relevant fields
+    parent_key = {k: v for k, v in my_key.items() if k in parent.heading.names}
+    print(parent & parent_key)  # restricted parent
+```
+
+If any of the printed tables are empty, you know you need to insert into that
+table (or another ancestor up the pipeline) first. This code will not work if
+there are aliases in the table (i.e., `proj` in the definition). In that case,
+you'll need to modify your `parent_key` to reflect the renaming.
+
+The error message itself will tell you which table is the limiting parent. After
+`REFERENCES` in the error message, you'll see the parent table and the column
+that is causing the error.
+
+## Permission
+
+```console
+('Insufficient privileges.', "INSERT command denied to user 'username'@'127.0.0.1' for table '_table_name'", 'INSERT INTO `schema_name`.`table_name`(`field1`,`field2`) VALUES (%s,%s)')
+```
+
+This is a MySQL error that means that either ...
+
+- You don't have access to the command you're trying to run (e.g., `INSERT`)
+- You don't have access to this command on the schema you're trying to run it on
+
+To see what permissions you have, you can run the following ...
+
+```python
+dj.conn().query("SHOW GRANTS FOR CURRENT_USER();").fetchall()
+```
+
+If you think you should have access to the command, you contact your database
+administrator (e.g., Chris in the Frank Lab). Please share the output of the
+above command with them.
+
+## Type
+
+```console
+TypeError: example_function() got an unexpected keyword argument 'this_arg'
+```
+
+This means that you're calling a function with an argument that it doesn't
+expect (e.g., `example_function(this_arg=5)`). You can check the function's
+accepted arguments by running `help(example_function)`.
+
+```console
+TypeError: 'NoneType' object is not iterable
+```
+
+This means that some function is trying to do something with an object of an
+unexpected type. For example, if might by running `for item in variable: ...`
+when `variable` is `None`. You can check the type of the variable by going into
+debug mode and running `type(variable)`.
+
+## KeyError
+
+```console
+KeyError: 'field_name'
+```
+
+This means that you're trying to access a key in a dictionary that doesn't
+exist. You can check the keys of the dictionary by running `variable.keys()`. If
+this is in your custom code, you can get a key and supply a default value if it
+doesn't exist by running `variable.get('field_name', default_value)`.
+
+## DataJoint
+
+```console
+DataJointError("Attempt to delete part table {part} before deleting from its master {master} first.")
+```
+
+This means that DataJoint's delete process found a part table with a foreign key
+reference to the data you're trying to delete. You need to find the master table
+listed and delete from that table first.

docs/src/misc/index.md

@@ -2,10 +2,11 @@
 
 This folder contains miscellaneous supporting files documentation.
 
+- [Common Errors](./common_errs.md)
 - [Database Management](./database_management.md)
 - [Export](./export.md)
-- [figurl Views](./figurl_views.md)
 - [Insert Data](./insert_data.md)
 - [Merge Tables](./merge_tables.md)
 - [Mixin Class](./mixin.md)
 - [Session Groups](./session_groups.md)
+- [figurl Views](./figurl_views.md)