biolovision package

Submodules

biolovision.api module

Provide python interface to Biolovision API.

Thin Python binding to Biolovision API, returning dict instead of JSON. Currently, only a subset of API controlers are implemented, and only a subset of functions and parameters for implemented controlers. See details in each class.

Each Biolovision controler is mapped to a python class. Class name is derived from controler name by removing ‘_’ and using CamelCase. Methods names are similar to the corresponding API call, prefixed by ‘api’. For example, method ‘api_list’ in class ‘LocalAdminUnits’ will call ‘local_admin_units’.

Most notable difference is that API chunks are grouped under ‘data’, i.e. calling species_list(‘1’) will return all birds in one array under ‘data’ key. This means that requests returning lots of chunks (all bird sightings !) must be avoided, as memory could be insufficient. max_chunks __init__ parameter controls the maximum number of chunks allowed and raises an exception if it exceeds.

Biolovision API to Classes mapping:

Controler

Class

Taxo groups

TaxoGroupsAPI

Families

FamiliesAPI

Species

SpeciesAPI

Territorial Units

TerritorialUnitsAPI

Local admin units

LocalAdminUnitsAPI

Places

PlacesAPI

Observers

ObserversAPI

Entities

EntitiesAPI

Protocols

NA

Export organizations

NA

Observations

ObservationsAPI

Fields

FieldsAPI

Media

NA

Import files

NA

Import files/Observations

NA

Validations

ValidationsAPI

Mortality informations

NA

Bearded Vulture Birds

NA

Bearded Vulture informations

NA

Grids

NA

Grid-Commune

NA

Atlas documents

NA

Methods, see each class

Properties:

  • transfer_errors - Return number of HTTP errors

Exceptions:

  • BiolovisionApiException - General exception

  • HTTPError - HTTP protocol error

  • MaxChunksError - Too many chunks returned from API calls

  • IncorrectParameter - Incorrect or missing parameter

class biolovision.api.BiolovisionAPI(config, controler, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: object

Top class, not for direct use. Provides internal and template methods.

api_get(id_entity, **kwargs)[source]

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)[source]

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()[source]

Query for a wrong api.

Calls /error API to raise an exception.

exception biolovision.api.BiolovisionApiException[source]

Bases: Exception

An exception occurred while handling your request.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class biolovision.api.EntitiesAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to entities controler.

Methods:

  • api_get - Return a single entity from the controler

  • api_list - Return a list of entity from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.FamiliesAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to families controler.

Methods:

  • api_get - Return a single entity from the controler

  • api_list - Return a list of entity from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.FieldsAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to fields controler.

Methods:

  • api_get - Return a single entity from the controler

  • api_list - Return a list of entity from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

exception biolovision.api.HTTPError[source]

Bases: BiolovisionApiException

An HTTP error occurred.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class biolovision.api.HashableDict[source]

Bases: dict

Provide hashable dict type, to enable @lru_cache.

clear() → None.  Remove all items from D.
copy() → a shallow copy of D
fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values
exception biolovision.api.IncorrectParameter[source]

Bases: BiolovisionApiException

Incorrect or missing parameter.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class biolovision.api.LocalAdminUnitsAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to local_admin_units controler.

Methods:

  • api_get - Return a single entity from the controler

  • api_list - Return a list of entity from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

exception biolovision.api.MaxChunksError[source]

Bases: BiolovisionApiException

Too many chunks returned from API calls.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception biolovision.api.NotImplementedException[source]

Bases: BiolovisionApiException

Feature not implemented.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class biolovision.api.ObservationsAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to observations controler.

Methods:

  • api_get - Return a single observations from the controler

  • api_list - Return a list of observations from the controler

  • api_diff - Deprecated: Return all changes in observations since a given date

  • api_search - Search for observations based on parameter value

  • api_create - Create a single observation

  • api_update - Update an existing observation

  • api_delete - Delete an observation

  • api_delete_list - Delete a list/form

api_create(data: Dict) → None[source]

Create an observation.

Calls POST on /observations to create a new observation.

Parameters

data (json) – Body containing observation in JSON format

api_delete(id: str) → None[source]

Deleta an observation.

Calls DELETE on /observations/%id% to delete the observation.

Parameters

id (str) – Id of observation to delete

api_delete_list(data: Optional[Dict] = None) → None[source]

Deleta a list/form.

Calls POST on /observations/delete_list/%id% to delete the observation.

Parameters

data (Dict) – id_form or id_form_universal to delete

api_diff(id_taxo_group, delta_time, modification_type='all')[source]

Query for a list of updates or deletions since a given date.

Calls /observations/diff to get list of created/updated or deleted observations since a given date (max 10 weeks backward).

Parameters

  • id_taxo_group (str) – taxo group from which to query diff.

  • delta_time (str) – Start of time interval to query.

  • modification_type (str) – Type of diff queried : can be only_modified, only_deleted or all (default).

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(id_taxo_group, **kwargs)[source]

Query for list of observations by taxo_group from the controler.

Calls /observations API.

Parameters

  • id_taxo_group (integer) – taxo_group to query for observations

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

Search for observations, based on parameter conditions.

Calls /observations/search to get observations same parameters than in online version can be used

Parameters

  • q_params (dict) – Query parameters, same as online version.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_update(id: str, data: Dict) → None[source]

Update an observation.

Calls PUT on /observations/%id% to update the observation.

Parameters

  • id (str) – Id of observation to update

  • data (json) – Body containing observation in JSON format

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.ObserversAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to observers controler.

Methods:

  • api_get - Return a single entity from the controler

  • api_list - Return a list of entity from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.PlacesAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to places controler.

Methods:

  • api_get - Return a single place from the controler

  • api_list - Return a list of places from the controler

  • api_diff - Search for change in places

api_diff(delta_time, modification_type='all')[source]

Query for a list of updates or deletions since a given date.

Calls /places/diff to get list of created/updated or deleted places since a given date (max 10 weeks backward).

Parameters

  • delta_time (str) – Start of time interval to query.

  • modification_type (str) – Type of diff queried : can be only_modified, only_deleted or all (default).

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.SpeciesAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to species controler.

Methods:

  • api_get - Return a single specie from the controler

  • api_list - Return a list of species from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.TaxoGroupsAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to taxo_groups controler.

Methods:

  • api_get - Return a single taxo group from the controler

  • api_list - Return a list of taxo groups from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None)[source]

Return list of taxo groups, from cache or site.

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.TerritorialUnitsAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to territorial_units controler.

Methods:

  • api_get - Return a single territorial unit from the controler

  • api_list - Return a list of territorial units from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None)[source]

Return list of taxo groups, from cache or site.

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

class biolovision.api.ValidationsAPI(config, max_retry=None, max_requests=None, max_chunks=None)[source]

Bases: BiolovisionAPI

Implement api calls to validations controler.

Methods:

  • api_get - Return a single validation from the controler

  • api_list - Return the list of validations from the controler

api_get(id_entity, **kwargs)

Query for a single entity of the given controler.

Calls /ctrl/id API.

Parameters

  • id_entity (str) – entity to retrieve.

  • **kwargs – optional URL parameters, empty by default. See Biolovision API documentation.

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

api_list(opt_params=None, optional_headers=None)

Query for a list of entities of the given controler.

Calls /ctrl API.

Parameters

  • opt_params (dict) – optional URL parameters, empty by default. See Biolovision API documentation.

  • optional_headers (dict) – Optional body for GET request

Returns

json – dict decoded from json if status OK, else None

Return type

dict or None

property controler

Return the controler name.

property http_status

Return the latest HTTP status code.

property transfer_errors

Return the number of HTTP errors during this session.

property version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

Module contents