Add models for API response objects

I would like to add models for all of our API response objects, as an alternative to working with just JSON. This would be a big improvement toward making this a fully-featured python API client.

To do this I'd like to use the attrs library. It's lightweight, fast, used everywhere (with a subset of very similar features added to the stdlib in 3.7 as dataclasses), integrated with python type annotations and mypy, and makes for super clean code.

Update: see pyinaturalist/models for what I've added so far.

Example

Quick example model for observation comments:

from attr import define, field
from datetime import datetime
from typing import Dict, List

@define
class Comment:
    body: str = field(default=None)
    hidden: bool = field(default=None)
    id: int = field(default=None)
    uuid: str = field(default=None)
    flags: List = field(factory=list)
    moderator_actions: List = field(factory=list)
    created_at: datetime = field(converter=try_datetime, factory=datetime.utcnow)

Some more examples here: naturtag/models.

Benefits

That gives you a ton of features that make responses easier to work with interactively, for example a nice default __str__ method and tab-completion: tabs

More benefits:

The type hints make it easier to spot bugs in client code (compared to consuming JSON)
The type hints can also potentially be used to convert to other data formats (via cattrs); also see the recently started pyinaturalist-convert repo
Models could potentially be reused to create objects to submit to POST and PUT endpoints (which would mean a lot less referring to the docs to figure out what format it needs to be in).
attrs can generate slotted classes, which are faster and more memory-efficient than dicts (maybe only noticeable when working with larger datasets, though).
The features for defaults, validators, and converters would simplify and/or replace many of the functions currently in the request_params and response_format modules.

Integrating with API functions

This issue will just be for creating the models. Integrating them with the API can be a separate issue. I imagine that can work by either:

Adding an option to pass to existing API functions
Adding wrappers for the API functions to the models (e.g., Observation.search(...))

Tasks

Models:

[x] Base
[x] ControlledTerm
- [x] ControlledTermValue
- [x] Annotation
[x] Comment
[x] Identification
[x] LifeList
- [x] LifeListTaxon
[x] Observation
[x] ObservationField
- [x] ObservationFieldValue
[x] Photo
[x] Place
[x] Project
- [x] ProjectObservation
- [x] ProjectObservationField
- [x] ProjectUser
[x] SearchResult
[x] Taxon
- [x] ConservationStatus
- [x] EstablishmentMeans
- [x] TaxonCount
- [x] TaxonCounts
[x] User

Other tasks:

[x] Apply type conversions (using response_format methods as attrs converters)
[x] Customize generated str and repr methods to include nested model objects
[x] Lazy-load nested model objects (like Observation.taxon) for better performance
[x] Add formatter functions as model methods
[x] Unit tests
[x] Documentation
[x] ~~Figure out how to auto-document attrs.fields in Sphinx docs~~ (see https://github.com/python-attrs/attrs/issues/357)
- Moved to #188

pyinat / pyinaturalist