shamrock package

Submodules

shamrock.shamrock module

Shamrock - A Trefle API Integration.

class shamrock.shamrock.Shamrock(token: str)

Bases: object

API integration for Trefle service.

ENDPOINT(endpoint: str, identifier: Union[int, str, None] = None, **kwargs) → Any

Query the endpoint of the Trefle API and return results.

This method is called on any endpoint defined for the API. It can return any result from it or None if it doesn’t succeed.

Parameters:
  • endpoint (str) – An endpoint where the library will make a request.
  • identifier (int, str) – (optional) A primary key or the slug of the element.
  • **kwargs

    Any query strings to add to the search object.

Returns:

Any JSON that gets decoded from a successful response or None if it fails.

Return type:

Any

NAVIGATE(navigation: str, **kwargs) → Any

Navigate the API if any navigation exists on the results once the first call is made and stored on the instance.

This method is called on any navigation defined for the API. It can return any result from it or None if it doesn’t succeed.

Parameters:
  • navigation (str) – A navigation option where the library will make a request.
  • **kwargs

    Any query strings to add to the search object.

Returns:

Any JSON that gets decoded from a successful response or None if it fails.

Return type:

Any

auth(origin: str, **kwargs) → Any

Returns a JWT that you can use in a browser. You need to specify where you’ll be using the token so it can be bound to a certain address.

Parameters:
  • origin (str) – A URL that is delivered to the endpoint so the responding JWT can use it.
  • **kwargs

    Any query string options to add to the call.

corrections(identifier: Union[int, str, None] = None, json: Optional[Any] = None, **kwargs) → Any

Returns one correction or a list of corrections, or submits one.

Parameters:
  • identifier (int) – An identifier, a primary key of the correction.
  • json ((optional) most often a dict that gets submitted as a JSON body.) – Any object that can get serialized as a JSON when submitted to an endpoint.
  • **kwargs

    Any query string options to add to the call.

Returns:

Any JSON that gets decoded from a successful response.

Return type:

Any

plants_by(modifier: str, identifier: Union[int, str], **kwargs) → Any

Returns all the plants in a given distribution or genus.

Parameters:
  • modifier (str) – A string that tells what to use as a lookup. Either “distributions” or “genus”.
  • identifier (int or str) – An identifier, either a slug or a primary key of the modifier.
  • **kwargs

    Any query string options to add to the call.

:raises ShamrockException if the value of modifier is wrong. :returns: Any JSON that gets decoded from a successful response. :rtype: Any

report_error(identifier: Union[int, str], notes: str, what: str = 'plants', **kwargs) → Any

Report an error in the API database by passing the notes. The error can be reported to either the plants or the species. By default, to plants, providing an identifier of an item.

Returns the response of a report.

Parameters:
  • identifier (int or str) – An identifier, either a slug or a primary key of the entry.
  • notes (str) – A string that is delivered to report an error on the entry.
  • what (str (if not specified, then "plants", but can be specified as "species")) – A string that is signifying what item to report an error on.
  • kwargs (dict) – Any query strings to add to the post object.

:raises ShamrockException if the type of report is illegal. :returns: Any JSON that gets decoded from a successful response. :rtype: Any

search(q: str, what: str = 'plants', **kwargs) → Any

Search the plant and return results of the API call.

Searches the Trefle database of any matching plant and return either a successful result or None.

Parameters:
  • q (str) – A string that is used to search the plant with.
  • what (str (if not specified, then "plants", but can be specified as "species")) – A string that is signifying what item to report an error on.
  • **kwargs

    Any query strings to add to the search object.

:raises ShamrockException if the type of query is illegal. :returns: Any JSON that gets decoded from a successful response. :rtype: Any

Module contents

Shamrock - A Trefle API Integration.

class shamrock.Shamrock(token: str)

Bases: object

API integration for Trefle service.

ENDPOINT(endpoint: str, identifier: Union[int, str, None] = None, **kwargs) → Any

Query the endpoint of the Trefle API and return results.

This method is called on any endpoint defined for the API. It can return any result from it or None if it doesn’t succeed.

Parameters:
  • endpoint (str) – An endpoint where the library will make a request.
  • identifier (int, str) – (optional) A primary key or the slug of the element.
  • **kwargs

    Any query strings to add to the search object.

Returns:

Any JSON that gets decoded from a successful response or None if it fails.

Return type:

Any

NAVIGATE(navigation: str, **kwargs) → Any

Navigate the API if any navigation exists on the results once the first call is made and stored on the instance.

This method is called on any navigation defined for the API. It can return any result from it or None if it doesn’t succeed.

Parameters:
  • navigation (str) – A navigation option where the library will make a request.
  • **kwargs

    Any query strings to add to the search object.

Returns:

Any JSON that gets decoded from a successful response or None if it fails.

Return type:

Any

auth(origin: str, **kwargs) → Any

Returns a JWT that you can use in a browser. You need to specify where you’ll be using the token so it can be bound to a certain address.

Parameters:
  • origin (str) – A URL that is delivered to the endpoint so the responding JWT can use it.
  • **kwargs

    Any query string options to add to the call.

corrections(identifier: Union[int, str, None] = None, json: Optional[Any] = None, **kwargs) → Any

Returns one correction or a list of corrections, or submits one.

Parameters:
  • identifier (int) – An identifier, a primary key of the correction.
  • json ((optional) most often a dict that gets submitted as a JSON body.) – Any object that can get serialized as a JSON when submitted to an endpoint.
  • **kwargs

    Any query string options to add to the call.

Returns:

Any JSON that gets decoded from a successful response.

Return type:

Any

plants_by(modifier: str, identifier: Union[int, str], **kwargs) → Any

Returns all the plants in a given distribution or genus.

Parameters:
  • modifier (str) – A string that tells what to use as a lookup. Either “distributions” or “genus”.
  • identifier (int or str) – An identifier, either a slug or a primary key of the modifier.
  • **kwargs

    Any query string options to add to the call.

:raises ShamrockException if the value of modifier is wrong. :returns: Any JSON that gets decoded from a successful response. :rtype: Any

report_error(identifier: Union[int, str], notes: str, what: str = 'plants', **kwargs) → Any

Report an error in the API database by passing the notes. The error can be reported to either the plants or the species. By default, to plants, providing an identifier of an item.

Returns the response of a report.

Parameters:
  • identifier (int or str) – An identifier, either a slug or a primary key of the entry.
  • notes (str) – A string that is delivered to report an error on the entry.
  • what (str (if not specified, then "plants", but can be specified as "species")) – A string that is signifying what item to report an error on.
  • kwargs (dict) – Any query strings to add to the post object.

:raises ShamrockException if the type of report is illegal. :returns: Any JSON that gets decoded from a successful response. :rtype: Any

search(q: str, what: str = 'plants', **kwargs) → Any

Search the plant and return results of the API call.

Searches the Trefle database of any matching plant and return either a successful result or None.

Parameters:
  • q (str) – A string that is used to search the plant with.
  • what (str (if not specified, then "plants", but can be specified as "species")) – A string that is signifying what item to report an error on.
  • **kwargs

    Any query strings to add to the search object.

:raises ShamrockException if the type of query is illegal. :returns: Any JSON that gets decoded from a successful response. :rtype: Any