zmasek/shamrock

A Trefle API Library.

Shamrock - A Trefle API Library

☘ Shamrock is a Python shallow API library for Trefle integration. It enables interacting with the Trefle plants API in Python to get the information needed for various things you might want to use the API with such as research, gardening software, automation, etc. It is made for use with Python 3.6 and above.

For the full documentation refer to Shamrock documentation.

For more information what the Trefle service provides, refer to the Trefle API documentation. It is also useful for checking out how to use the API with Shamrock library.

Installation

pipenv install shamrock

or :

pip install shamrock

Simple Usage Example

from shamrock import Shamrock
api = Shamrock('mytoken')
species = api.species()

Advanced Usage

You can configure the API initially like this:

api = Shamrock(TOKEN)

Methods that can be run with the API are:

api.kingdoms()
api.subkingdoms()
api.divisions()
api.division_classes()
api.division_orders()
api.families()
api.genus()
api.plants()
api.species()

They correspond to the Trefle API endpoints.

You can also query a specific item from the database:

api.plants(103505)

Searching is covered with a separate method:

api.search("tomato")

Navigating the API is covered with these methods:

api.next()
api.prev()
api.first()
api.last()

It will work only if you previously made a request. For example:

api.species()
api.next()

You can also use the varoius query string options described on Trefle API documentation as keyword arguments in methods, however, be careful when unpacking filters, for example:

filters = {"filter[common_name]" : "blackwood"}
api.species(**filters)

shamrock's Issues

Trefle shut down, look for a replacement

https://twitter.com/trefle_api/status/1389232291302490117

Possible alternative is Flora Codex: https://twitter.com/FloraCodex/status/1389383248686587907

Add installer and publish to PyPI

Query string option

So far anything goes, but maybe blacklist all and whitelist only available ones would be a better solution.

Consider switching to httpx

Update to trefle 1.6 api?

Hey Zlatko! Thanks for shamrock. Are going to update endpoints/ syntax to the new version? Shamrock ist broken since couple of days.

https://docs.trefle.io/blog/1-6-0-released/

Expand documentation and publish to RTD

Develop pre-commit hooks strategy

Custom exception

Add custom exception to handle the breaking of the library instead of relying on other exceptions.

Better caching of calls

Currently, the library only caches one result. Explore if lru_cache would make sense to expand this.