Add deck and note options.

[holocronweaver]

Adds options to decks and notes. This fulfills #11 and then some.

• Most deck options are handled in a new OptionsGroup class which allows multiple decks to share options, reflecting Anki's very similar option groups. OptionsGroup is closely modeled after the deck options window in Anki.
• Decks now have a description and creation_time. The latter is important since card due dates are defined relative to deck creation time.
• Notes now have a few option attributes, all related to SRS in some way (due date, interval, etc.).
• Add some initial README documentation.
• Add more internal documentation about database fields.
• Add internal documentation about options.
• No tests yet.
• akpg_col.py now has field substitution by dict rather than list. This was necessary due to the large number of options being substituted. I didn't use format though!

I tried to stick to the coding style that already existed. Hopefully my blasphemies were kept at a minimum. X-D

Edit: Currently investigating test failures. I have succesfully created and imported decks into Anki 2.0.47 and 2.1 beta 12, so curious why it is failing in test...

Edit 2: Found the problem. OptionsGroup requires a unique ID, which means the OptionsGroup ID must be manually set same as for the deck ID. Could generate an ID from the name of the OptionsGroup, but if users create generic option group names this could lead to conflicts. I updated tests accordingly by adding options groups to test decks. Now all tests pass.

[kerrickstaley]

Thanks for the PR! I don't have time to look at it right now but will try to get to it in the next two days.

[kerrickstaley]

Looks pretty good overall, thanks for taking this on!

[kerrickstaley]

This should be called type. In general, we should always use the same variable naming that Anki does. If Anki's naming is confusing (which it often is), detailed comments will help make the field's purpose clear to the user.

Ditto for all the other properties here.

[holocronweaver]

Do you mean just within this function, or in the user-facing API as well?
If the latter, I think of this as 'spreading the disease', where one unintuitive interface gives rise to another, but I can understand wanting a close correspondence for debugging. I doubt many users will be familiar with the Anki DB column names, so I don't believe it will make the lib easier to learn. So...I'll make the change, but I'll feel dirty, lol.

[holocronweaver]

Actually, I remember now why I didn't use type for a variable name: it's a Python reserved keyword. Perhaps we should make an exception in this case?

[kerrickstaley]

It's better to closely match Anki's naming. I want genanki to be a lower-level library that more-or-less directly maps to the way Anki represents data. Plus, the user will probably have to end up learning the Anki names anyway, for example if they're digging into the collections.anki2 SQLite file to debug something. Abstractions are leaky more often than people expect.

I's OK to use type as the name. If you need to access the real type() function, you can import the builtins module and call builtins.type. (Previously I also had an instance of this, calling a param ord_ instead of ord. But I changed it because it's silly to convolute your external API for the convenience of internal code, and I wasn't using ord() anyway).

[kerrickstaley]

I think all these properties should be attributes of the Card object, not the Note object, since you can set them per-card.

So the user would do something like this:

my_note = Note(...)
...
my_note.cards[0].queue = -1

If you have a use case for setting attributes on all cards, you can add a helper function like this:

def set_attributes_on_call_cards(self, **kwargs):
    for card in self.cards:
        for k, v in kwargs.items():
             setattr(card, k, v)

Note: you can skip adding ease, ivl, etc as keyword arguments to Card.__init__. Unlike Note and Deck, the user generally doesn't directly initialize Card instances; instead, they're implicitly initialized when the user creates the Note. So it doesn't make sense to set Card attributes via keyword arguments.

[holocronweaver]

Okydoke! I actually planned for and forgot to do this, heh.

[kerrickstaley]

Ditto here. This should be called left. If you want to, you can add a @property that aliases reps_til_grad to left. But the main name of the property should be left.

[kerrickstaley]

Per above comment, please move this out of the Note class and into the Card class.

[kerrickstaley]

I'd like to follow the pattern of allowing all arguments to be set via keyword arguments to __init__.

So you should write something like

def __init__(
    self,
    options_id=None,
    options_group_name=None,
    max_time_per_answer=60,
    ...
    misc=0):
  self.options_id = options_id
  self.options_group_name = options_group_name
  ...

I realize this is extremely verbose, so you could also go this alternate route:

class OptionsGroup:
  ATTRIBUTES_WITH_DEFAULTS = {
    'options_id': None,
    'options_group_name': None,
    'max_time_per_answer': 60,
    ...
  }

  def __init__(self, **kwargs):
    for attr, default in self.ATTRIBUTES_WITH_DEFAULTS.items():
      setattr(self, attr, kwargs.get(attr, default))

Either style is fine. However, the first style is advantageous in that it's easier for tools like IDEs to introspect. And it's pretty easy to automatically generate the code so it ends up being about the same amount of work.

[holocronweaver]

Will do!

[holocronweaver]

I think I made all the requested changes.

I moved the card options to a new CardOptions class. This simplifies sharing the same options among multiple cards, similar to what OptionsGroup does for decks, so it's handy on several levels.

I also added @property for the aliases as you suggested, while leaving the 'real' internal names consistent with the Anki DB field names.

[kerrickstaley]

With this options object, you can't directly set properties on the Card. For example, you can't do my_card.type = 1, you have to do my_card.options.type = 1, which seems like an unnecessary level of indirection and doesn't mesh with how other objects (Notes and Decks) work. Can you make these direct properties of Card and get rid of the CardOptions class?

To achieve what you're trying to do with CardOptions, you can write a helper function (in your own code) like

def set_card_attributes(card, attrs):
    for a in attr:
        setattr(card, a, attrs[a])

and then write code like

my_attrs = {'type': 2, 'due': 1234}
for note in notes:
    for card in note.cards:
        set_card_attributes(card, my_attrs)

[holocronweaver]

Okydoke, removed CardOptions and now Card has all the attributes. I left a utility function in Note to make the common case of setting all card options at once more concise.

[jontelang]

Very old bump, but is this something that can be done nowadays even without these changes?