Annotation

class pyinaturalist.models.Annotation(**kwargs)

Bases: BaseModel

An annotation, meaning a controlled term value applied by a user to an observation. Based on the schema of annotations from GET /observations and GET /observations/{id}.

For convenience, an Annotation object may be initialized from labels:

>>> Annotation(term='Life Stage', value='Adult')

Or from IDs:

>>> Annotation(controlled_attribute_id=1, controlled_value_id=2)

Or from objects:

>>> Annotation(
...     controlled_attribute=ControlledTerm(id=1, label='Life Stage'),
...     controlled_value_id=ControlledTermValue(id=2, label='Adult'),

Note: Different annotation information is returned from different API endpoints:

• GET /observations (used by get_observations() and ObservationController.search()) returns annotations with term and value IDs only.

• GET /observations/{id} (used by get_observations_by_id() and ObservationController.from_ids()) returns full annotations details, including labels.

Attributes

Name	Type	Description
id	int	Unique record ID
user_id	int
uuid	str
vote_score	int
votes	List
term (property)	str	Convenience property for getting/setting the controlled term label
value (property)	str	Convenience property for getting/setting the controlled value label
user (LazyProperty)	User	User who added the annotation
controlled_attribute (LazyProperty)	User	Term definition details
controlled_value (LazyProperty)	User	Annotation value details

Methods

__init__(**kwargs)

Method generated by attrs for class BaseModel.

classmethod copy(obj)

Copy a model object. This is defined as a classmethod to easily initialize a subclass from a parent class instance. For copying an instance to the same type, copy.deepcopy() can be used.

Return type:

BaseModel

classmethod from_json(value, **kwargs)

Initialize a single model object from an API response or response result.

Omits any invalid fields and None values, so default factories are used instead (e.g. for empty dicts and lists).

Return type:

TypeVar(T, bound= BaseModel)

classmethod from_json_file(value)

Initialize a collection of model objects from a JSON string, file path, or file-like object

Return type:

List[TypeVar(T, bound= BaseModel)]

classmethod from_json_list(value, **kwargs)

Initialize a collection of model objects from an API response or response results

Return type:

List[TypeVar(T, bound= BaseModel)]

to_dict(keys=None, recurse=True)

Convert this object back to dict format

Parameters:

• keys (Optional[List[str]]) – Only keep the specified keys (attribute names)

• recurse (bool) – Recurse into nested model objects

Return type:

Dict[str, Any]