Design questions for gatenlp (and gateplugin Python)
===

### !!NOTE: the most important questions are marked with "**!?!**" below!!

## API

In general:
* what should be an attribute/propery what should be an accessor method/function?
* `obj.something` vs. `obj.something(..)`
* should we call accessor methods `get_xxx()` or just `xxx()`?
* JP: `xxx()`, CHANGED
* should we call methods that return a flag `is_xxx()` or just `xxx()`?
* JP: in most cases isxxx() (not underscore needed)
* CHANGED

### API for Document

* CHANGED: `get_annotation_set_names()` to `annset_names()`
* CHANGED: `get_annotations(..)` to `annset(..)`
* CHANGED: `remove_annotation_set(name)` to `remove_annset(..)`
* CHANGED `set_changelog` to `doc.changelog=cl`
* REMOVED `size()` as we have `len(doc)`
* `to_offset_type`: change offset type in place
* but we should add a method to get a different document with the same content and a different offset type!
* `copy`: so far just shallow copy but add options to create a tailor-made copy:
* `include_annsets`, `exclude_annsets`, `include_docfeatures`, `exclude_docfeatures`, `offset_type`, `deep=False`

### API for AnnotationSet

* `add(start,end,anntype,features=None,annid=None)`: ok
* IMPORTANT: `add(..)` returns the annotation, not the ID!
* `add_ann(ann, annid=None)`: OK
* `by_offset`: ordered list of lists, for each offset where an annotation starts one list
* should be `by_offsets`
* `by_span`: ordered list of lists, each list contains unique spans
* should be `by_spans`
* `type_names()`: list of all types in the set
* maybe should be `types()` or `types`
* JP: `type_names()` is consistent with `annset_names()`, keep
* `start_eq(start, ..)`: annotations starting at start, ok
* `start_min_ge(pffset, ...)`: all annotations which start at the first offset after the given offset where some annotation starts. ok
* `start_ge(offset, ...)`: all annotations which start at or after the given offset. ok
* `start_lt(offset, ...)`: all annotations which start before the given offset. ok
* `overlapping(span)`: ok
* `covering(span)`: ??
* could also be: `containing(span)`
* JP: prefer `covering` as contained/containing is sometimes hard to remember what contains what, bad for dyslexic like me
* `within(span)`: ??
* could also be: `contained(span)`
* JP: prefer `within` (see above)
* `coextensive(span)`: OK
* `clear()`: remove all anns
* `clone_anns()`: make all anns in the set a deep copy of themselves
* `document`: (no parentheses)
* `get(annid)`: return the annotation with the given annotation id, same as `annset[annid]`
* BUT: since we have `annset[annid]` could just as well remove
* CHANGED: `detached()` to `detach()`
* CHANGED: `detached_from(..)` to `detach_from(..)`
* CHANGED: `is_detached()` to `detached`
* CHANGED `is_immutable()` to `immutable` and setter `immutable=False`
* `name`: (no parens) get the name of an annotation set
(cannot be changed!)
* `remove(annorid)`: OK
* remove(el) is used for lists so this is kind of OK, the API for dicts is weird: del statement and pop.
* `x in annset`: if there is an annotation in the set which eq-compares to x: OK
* `iter(...)`: configurable iterater in offset order, needs index (but see below)
* `fast_iter(...)`: iterator, unpredictable order, no index needed
* **?!?** `start()`, `end()`: (parentheses): start, end of the set as a whole
* this should have parentheses as it can change over the lifetime of the set
* but it is equivalent to Annotation.start/end where we do not have parentheses because there the values cannot change
* which to choose: parentheses or no parentheses????
* `first()`: first annotation in offset order (random one if several at same offset)
* CHANGED `with_type(typenames...)` to `type(..)`
* CHANGED BACK TO "with_type" since it sounds too much like we want to know the type of the annset otherwise.
* **?!?** `size()` vs `len()`: number of anns in the set
* we could drop `size()`
* changed to `size` property
* ADDED `length()`: length of the annotation set span
* changed to length property
### API for Annotation

Main Q here is if some of the fields should look like attributes or like functions, `ann.start` or `ann.start()`.
What annoys me here (also in other packages) is that it is often not easy to remember what is a function and what is an attribute. Would be good to have a simple rule for
all cases.

* REMOVED: `contains_offset(off)`: NOW: `covering(off)`
* `end`: no parentheses
* `start`: no parentheses
* `type`: no parentheses
* `features`: get the Features
* `gap(other)`: gap between the two annotations
* `id`: no parentheses
* CHANGED `is_after(other)` to `after(other)`
* CHANGED `is_before(other)` to `before(other)`
* CHANGED `is_coextensive(other)` to `coextensive(other)`
* CHANGED `is_overlapping(other)` to `overlapping(other)`
* CHANGED`is_within(other)` to `within(other)`
* ADDED `covering(other)` : does it cover the span
* ADDED `length()`: length of the annotation span

### API for objects that can have features

ALREADY CHANGED:

* previously there were methods on the bearing object to set/get features and do other stuff:
* `obj.get_feature("xx")`
* `obj.set_feature("name", "value")`
* also `clear_features`, `del_feature`, `feature_names`, `feature_values`, `has_feature`, `num_features`, `update_features(other)`: this is awful
* `features_copy`: this should be `to_dict(deep=False)`
* the original idea was: we do not want to return a dict which can then be passed around and modified without us noticing, so hide the dict and make each FeatureBearer inherit the methods to modify it
* This was not very pythonic though and maybe hard to remember

Now implemented a different solution:
* `obj.features`: returns a Features object
* That object has methods that make it almost identical to a dict
* `obj.features["x"] = "y"`
* `obj.feature["value]"`
* `obj.features` - returns the Features instance that can be passed around
* selected other methods of `dict` provided they work with feature change logging
* An object that has features always has an initialized Features instance. The feature instance gets the logger method from its owner.
* if the owner gets its changelog removed the logger will automatically not make an attempt to log any more.
* a copy of a Features object (no matter if deep or shallow) does not copy the feature logger!
* Methods to convert to a dict that is a shallow/deep copy
* e.g. `obj.to_dict(deep=False)`

## Print Representation

* How to print/pprint the various objects: lots of detail but huge, tiny detail ... ? Especially with `Document` and `AnnotationSet`

Document: which information to include, how:
* full text? Mid-truncated text?
* name?
* all document features? truncated document features? number of document features?
* annotations: all, number of annotations per type, only total numner?

AnnotationSet:
* Will get massive for annotated documents if we show details

Annotation:
* I guess showing everything is fine
* But with massive annotations this could get big too

For some or all of the objects it would be cool that have support for pprint, so e.g.
each annotation is in a separate line, maybe even each feature per annotation is in a separate line ...

## Annotation Set Representation

This is not trivial:
* the result of `doc.get_anns(name)` is an instance of AnnotationSet which knows the document it belongs to. If changes are made through the API of that instance, they affect the set stored with the document AND get logged in the changelog if there is one.
* but what about the sets returned from methods like `within`?
* I *think* the best approach is:
* return a "detached" annotation set
* that set does NOT belong to the document
* by default the set is immutable (cannot add or remove annotations)
* the annotations in the set are shallow copies of the originals
* but it can be made mutable. Since it does not "belong" to the document, any removals or additions to the annotations are not visible in the document or logged in the changelog
* If annotations are removed or added in the original set in the document, they do not affect the detached set
* however, since we have shallow copies, changes to a mutable feature value will affect the document
* to avoid that too, there is a method on the annotation set to replace all annotations with a deep copy (should rarely be necessary)

Iterating over annotations:
* any annotation set can be itereated over
* with `fast_iter` we get annotations in arbitrary order
* with `iter` and `for ann in annset` we iterate in offset order
* HOWEVER: offset order is not a strict order since we can have several annotations on the same offset
* How should we provide a stable strict order of annotations? This could be based on the `<` comparison definition on annotations
* BUT what is the correct `<` and `==` definition for annotations

Maybe:
* annotations are only equal if
* start, end, type are equal
* annotation id is equal
* all features are equal
* for annotations from the same set, no two annotations can have the same id, so the id being unequal is already enough to be sure the annotations are not equal

So when iterating over annotations from a single set (and I think we always do this), a stable strict order could be based on
* start
* end
* annid

Maybe: add a method `strict_iter` to `iter` and `fast_iter` for this?

## GATE Slave interface

TBD!