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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

exception biolovision.api.HTTPError[source]

Bases: biolovision.api.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()

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

get()

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 key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault()

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: biolovision.api.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: biolovision.api.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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

exception biolovision.api.MaxChunksError[source]

Bases: biolovision.api.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: biolovision.api.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: biolovision.api.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[KT, VT]) → 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[KT, VT]] = 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[KT, VT]) → 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
controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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_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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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[source]

Return list of taxo groups, from cache or site.

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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[source]

Return list of taxo groups, from cache or site.

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

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: biolovision.api.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

controler

Return the controler name.

http_status

Return the latest HTTP status code.

transfer_errors

Return the number of HTTP errors during this session.

version

Return version.

wrong_api()

Query for a wrong api.

Calls /error API to raise an exception.

Module contents