Update Notes from Markdown Files

[oddish3]

This is the start of a PR that aims to add a new feature that allows users to update existing notes from Markdown files. The implementation includes:

1. New update_notes_from_file method in Anki class:

   • Updates existing notes when a note ID (nid) or card ID (cid) is provided
   • Creates new notes when no ID is provided
   • Properly handles a mix of new and existing notes in the same file

2. New CLI command update-from-file:

   • Provides a user-friendly interface to the update functionality
   • Includes detailed documentation and examples in the help text

3. New tag handling:

   • merges global tags (defined at the file level) with note-specific tags
   • Ensures tags from both sources are preserved when updating notes

4. Note editing:

   • Includes note IDs in exported note content for easier reference
   • Improves feedback messages to differentiate between adding and updating notes

5. Added tests:

   • Added tests for updating notes by note ID
   • Added tests for updating notes by card ID
   • Added tests for mixed files with both new and existing notes
   • Tests for proper tag inheritance and merging

Example Usage

// example.md
model: Basic
tags: common-tags

# Existing Note
nid: 1619153168151
tags: note-specific-tag

## Front
Updated question?

## Back
Updated answer.

# New Note
## Front
This will be a new note

## Back
With common tags applied

Running apy update-from-file example.md will update the existing note with ID 1619153168151 and create a new note, both with the common tags applied.

Implementation Details

• Added proper error handling for invalid note/card IDs
• Ensured backward compatibility with existing functionality
• Feedback messages to clearly indicate when notes are updated vs. added
• Tag handling can merge global and note-specific tags

This feature makes batch editing of existing notes more convenient

However, I was very unsure on type-checking the code, this currently fails and I will need your help here please :)

[lervag]

I'll look at this when I get the time - probably later today or tomorrow.

[lervag]

This is the start of a PR that aims to add a new feature that allows users to update existing notes from Markdown files. The implementation includes: …

Wow, it seems you've done a lot of useful work here! A minor comment: if you were to submit some of those things as smaller PR's it would have been easier to review it and merge parts of it faster.

In the present case, I will need to do a proper review of all of it. That's perfectly fine for me and I look forward to doing it, but I can't make any promise on how fast I will get around to looking at all of it.

In the mean time, I noticed that the lint step failed, so feel free to fix that.

New CLI command update-from-file:

• Provides a user-friendly interface to the update functionality
• Includes detailed documentation and examples in the help text

I think this sounds very good! I also started to be curious if we should add some type of export functionality that made it possible to first export, then later sync between the markdown file and the anki deck from the exported file.

Although, I'm not sure how smart that would be. I have close to 10000 notes, and I'm not sure I would want to risk failing a sync with this.

New tag handling: …

Neat!

Added tests: …

Very good!

Running apy update-from-file example.md will update the existing note with ID 1619153168151 and create a new note, both with the common tags applied.

Just curious: This means that in your workflow, you would manually add the note IDs to your markdown files after adding them, right? I think this entire thing would be even more neat if we could somehow make that step redundant by having apy update the note file by adding the nid: ... directly (perhaps behind an option)?

However, I was very unsure on type-checking the code, this currently fails and I will need your help here please :)

I will be glad to help here.

[lervag]

By the way, I propose that you rebase your work on top of the latest master - either with git rebase or by simply making a new branch on master and copying the work you've made so far.

[oddish3]

• review feedback:
  • changed note ID comment in edit method
  • replaced elif k in ("nid") with elif k == "nid"
  • changed x.get("nid") to x["nid"]
• auto-update feature:
  • added update_file option to add_notes_from_file and update_notes_from_file
  • created _update_file_with_note_ids to modify markdown files with note IDs
  • introduced CLI flags -u/--update-file
  • added the textwrap.dedent() function
• fixed type errors:
  • resolved circular imports
  • improved type annotations for mypy
  • handled potential None values correctly
• tests:
  • added tests for the file update feature

[lervag]

Thanks, this is starting to look very good!

Some follow-up comments:

• In test_batch_edit.py at line 31 it seems you forgot to add textwrap.dedent.
• I asked a question that seems unanswered. I'll resolve the thread and repeat the question here: I'm curious, do we really want or need both add_notes_from_file and update_notes_from_file? Do we want both of the commands? (I guess yes, to avoid breaking backward compatibility. But they could be identical in implementation, right?)

[oddish3]

Yes, you are correct on both occasions - thanks and i have addressed them here.
Also, unrelatedly, do you mind if i send you an email re academic mentoring? completely understand if not :)

[lervag]

Yes, you are correct on both occasions - thanks and i have addressed them here.

Great!

Also, unrelatedly, do you mind if i send you an email re academic mentoring? completely understand if not :)

No, I don't mind - feel free to send an email. :)

[lervag]

The last thing now: I think we should consider if we really want both of the cli commands apy add-from-file and apy update-from-file. As far as I can see, update-from-file is really a superset of add-from-file. That is, whenever I use apy add-from-file, I could always use apy update-from-file instead. Right?

If I'm right, then I think we should also consider to simplify the cli.py file. As a first step, we could do something like what you just did in anki.py where add_notes_from_file just calls update_.... Perhaps click has a way to define an alias as well?

Finally, and less importantly, we should consider to update the zsh completion script in completion/_apy. If you don't use zsh, then it's not relevant to you and you can just ignore me - I'll update it later myself.

[lervag]

Very good work! This looks good to me and I'll be glad to merge now. But before I do, I just want to double check that you agree.

[oddish3]

Thanks!

I agree and hope others find this useful 😄

[lervag]

Great; and again, thanks for helping out and contributing! It's appreciated!