Shamrock - A Trefle API Library for Plant Data
Update: as of 03.05.2021. Trefle shut down. Therefore Shamrock library is currently not working. However, I will switch the domain from where the data is coming with a drop-in replacement. Soon things will work again. Thanks for your patience.
Shamrock is a Trefle API library written in Python. Trefle is a botany API with a number of plants in their database. It can be used for research, gardening software, automation, etc.
I made the Shamrock library using the existing requests library to interact with the Trefle API because I needed some structure in my upcoming project. I wanted to do things properly; testing, documentation, CI/CD pipeline, ensuring that the repository conforms to certain standards and publishing everything mentioned. It took me around a month and a half of casual work in free time to complete the first release. I also learned some new things along the way.
Without getting further into how the library is used, you can check it at these three links:
Now onto the technical side of things. The library acts as a shallow API layer between Python and the Trefle service. You need to get the token from them and use it when instantiating the Shamrock class.
The library relies on lists for navigation and endpoints. When you call a method on the Shamrock instance, it checks the __getattr__ magic method and filters according to the name called. That way I avoid code duplication and the code is routed to either the navigation or an API endpoint.
The navigation is largely solved by the dependent requests library.
While making requests, the library will raise any errors if the service is down in any way.
When a request is made, the response is stored in a variable on the instance itself so the subsequent request to the same endpoint is checked, and if it's the same, it's not repeated. Instead, the stored response is returned. I don't want the users to make an unnecessary hit on the API and to burn their traffic and need to wait on the response itself.
What I learned is using the PyPI publishing with Twine, using Sphinx to generate the documentation from docstrings and to use type hinting in Python 3. I also learned a bit about CircleCI because so far I was using other pipelines to run things. I also learned a bit about VCR.py library that I used with tests. The coverage is 100% because the surface of the library is not that big.
Now what can you use the library with? Well any kind of project that involves Python and botany. For instance, if you write a web application in Python and use the library on the back-end, you can make a comprehensive gardening software to keep track of your garden. Off the top of my head, you can have the number of plants planted on some surface, expected yield and such, and with the Shamrock have a rich display of what kind of plants you planted. I understand that their database is not complete, but they are working on it. The full example they have is the plant Allium acuminatum (tapertip onion) so you can query the plant with the ID 103505 and poke around with the data in the response. For any issues with their service, you can refer to the Trefle issue tracker on GitHub.
I hope you find the Shamrock library useful and that you might use it in one of your projects or even find some time to contribute to the library itself.