Merge pull request #21 from jplacht/feat-cache

Integrate caching as package extra with `requests-cache`

Author: jplacht

.coveragerc

@@ -8,4 +8,4 @@ omit =
     # omit abstract endpoints
     */abstracts/*
     # omit config due to base_config
-    */config.py
+    # */config.py

docs/caching.md

@@ -0,0 +1,44 @@
+# Caching
+
+By default, FIO Wrapper does not include any form of caching for FIO requests. Enabling caching can be extremely helpful to minimize load on FIO and reduce wait times. You can install the wrapper with the `cache` extra.
+
+## Installation of FIO Wrapper with Cache Extra
+```python
+pip install fio-wrapper[cache]
+```
+
+FIO Wrapper will now make use of [requests-cache](https://requests-cache.readthedocs.io/en/stable/index.html) as a persistent HTTP cache on top of Python's `requests` library. This package will only use `memory` caching.
+
+## Cache configuration
+Caching can only be enabled with a [user configuration file](config.md) provided when instantiating the `FIO` wrapper. 
+
+### Minimal
+There are two minimal configuration options to be set:
+
+```yaml
+cache:
+  enabled: true
+  default_expire: 3600 
+```
+
+This user configuration enables the caching of requests and sets the default expiration to 10 seconds.
+
+### Advanced
+
+You are able to provide URL patterns matching [integrated endpoints](routes.md) to cache and specify their individual expiration with the following options:
+
+- `int` = Number of Seconds (e.g., `120` = 2 minutes)
+- `NEVER_EXPIRE` = route will always use cache and never expire
+- `DO_NOT_CACHE` = route will never be cached
+
+A minimal example of caching individual urls:
+
+```yaml
+cache:
+  urls:
+    "*/material/*": 3600
+    "*/exchange/all": NEVER_EXPIRE
+    "*/exchange/full": DO_NOT_CACHE
+```
+
+**Note**: Make sure to adjust the configuration according to your specific caching needs.

docs/config.md

@@ -2,67 +2,53 @@
 
 FIO Wrapper internally uses a configuration file to provide its standard capabilities. The configuration can be [overwritten](usage.md) by the user.
 
+## `base.yml`
+
+```yaml
+fio:
+  application: FIO Wrapper
+  version: 1.0.0
+  base_url: https://rest.fnar.net
+  timeout: 10
+  ssl_verify: true
+  versions:
+    - 1.0.0
+cache:
+  enabled: false
+  default_expire: 3600
+fio_urls:
+  1.0.0:
+    material_base: /material
+    material_all: /allmaterials
+    exchange_base: /exchange
+    exchange_orders: /orders
+    exchange_all: /all
+    exchange_full: /full
+    building_base: /building
+    building_all: /allbuildings
+    recipe_base: /recipes
+    recipe_all: /allrecipes
+    planet_base: /planet
+    planet_all: /allplanets
+    planet_full: /allplanets/full
+    planet_sites: /sites
+    planet_search: /search
+    localmarket_base: /localmarket
+    localmarket_planet: /planet
+    localmarket_shipping_source: /shipping/source
+    localmarket_shipping_destination: /shipping/destination
+    localmarket_company: /company
+    sites_base: /sites
+    sites_planets: /planets
+    sites_warehouses: /warehouses
+    storage_base: /storage
+    storage_planets: /planets
+    groups: /auth/groups
+    groups_group: /auth/group
+    groups_groupmemberships: /auth/groupmemberships
+    groups_hub: /fioweb/grouphub
+    groups_burn: /fioweb/burn/group
 
-
-## `base.ini`
-
-```ini
-[FIO]
-application = FIO Wrapper
-version = 1.0.0
-base_url = https://rest.fnar.net
-timeout = 10
-ssl_verify = True
-versions = 1.0.0
-
-[URL]
-# material
-1.0.0_material_base = /material
-1.0.0_material_all = /allmaterials
-
-# exchange
-1.0.0_exchange_base = /exchange
-1.0.0_exchange_orders = /orders
-1.0.0_exchange_all = /all
-1.0.0_exchange_full = /full
-
-# building
-1.0.0_building_base = /building
-1.0.0_building_all = /allbuildings
-
-# recipe
-1.0.0_recipe_base = /recipes
-1.0.0_recipe_all = /allrecipes
-
-# planet
-1.0.0_planet_base = /planet
-1.0.0_planet_all = /allplanets
-1.0.0_planet_full = /allplanets/full
-1.0.0_planet_sites = /sites
-1.0.0_planet_search = /search
-
-# localmarket
-1.0.0_localmarket_base = /localmarket
-1.0.0_localmarket_planet = /planet
-1.0.0_localmarket_shipping_source = /shipping/source
-1.0.0_localmarket_shipping_destination = /shipping/destination
-1.0.0_localmarket_company = /company
-
-# sites
-1.0.0_sites_base = /sites
-1.0.0_sites_planets = /planets
-1.0.0_sites_warehouses = /warehouses
-
-# storage
-1.0.0_storage_base = /storage
-1.0.0_storage_planets = /planets
-
-# groups
-1.0.0_groups = /auth/groups
-1.0.0_groups_group = /auth/group
-1.0.0_groups_groupmemberships = /auth/groupmemberships
-1.0.0_groups_hub = /fioweb/grouphub
-1.0.0_groups_burn = /fioweb/burn/group
 ```
 
 ## Config() class

docs/timeouts.md

@@ -9,7 +9,7 @@ Timeouts can be defined by the user on two levels:
 
 FIO Wrapper includes a default fallback to `10.0` seconds, if no value is defined by the user. Overwriting to `None` to disable timeouts is possible.
 
-## [`FIO`](fio.md) instantiation
+## [`FIO`](fio.md) Instantiation
 
 Define a default timeout for all requests by overwriting the [`Adapter`](fio_adapter.md) default.
 
@@ -23,13 +23,13 @@ fio = FIO(timeout=5)
 
 FIO Wrapper will now apply the timeout of `5 seconds` to all calls it is making towards FIO.
 
-## Configuration file
+## Configuration File
 
-A standard timeout can also be defined in a users [configuration file](config.md).
+A standard timeout can also be defined in a user's [configuration file](config.md).
 
-## Indidivual endpoint calls
+## Individual Endpoint Calls
 
-All endpoints allow passing the optional `timeout` argument that is of type `Optional[float]` and defaults to `None`.
+All endpoints allow passing the optional `timeout` argument, which is of type `Optional[float]` and defaults to `None`.
 
 ```python
 from fio_wrapper import FIO
@@ -46,4 +46,4 @@ all_exchange = fio.Exchange.all(timeout=3.5)
 
 ```
 
-It is highly recommended to not set any timeout to `None` to avoid infinite loops especially on expensive FIO endpoints like [`Group`](endpoints/group.md).
+It is highly recommended not to set any timeout to `None` to avoid infinite loops especially on expensive FIO endpoints like [`Group`](endpoints/group.md).

docs/usage.md

@@ -48,19 +48,25 @@ The complete list of parameters can be found on [`FIO()`](fio.md).
 
 FIO Wrapper can use a configuration file provided upon instantiation to overwrite its [base configuration](config.md).
 
-Example configuration file `config.ini`:
-
-```ini
-[FIO]
-application = My Awesome FIO application
-timeout = 3
-api_key = MY_FIO_API_KEY
+Example configuration file `config.yml`:
+
+```yaml
+fio:
+  application: MyExampleApplication
+  version: 1.0.0
+cache:
+  enabled: true
+  default_expire: 10 # seconds
+  urls:
+    "*/material/*": 3600
+    "*/exchange/all": NEVER_EXPIRE
+    "*/exchange/full": DO_NOT_CACHE
 ```
 
 Use this configuration file on [`FIO()`](fio.md) by providing the `config` attribute:
 
 ```python
 from fio_wrapper import FIO
 
-fio = FIO(config="config.ini")
+fio = FIO(config="config.yml")
 ```

fio_wrapper/base.ini

@@ -0,0 +1,44 @@
+---
+fio:
+  application: FIO Wrapper
+  version: 1.0.0
+  base_url: https://rest.fnar.net
+  timeout: 10
+  ssl_verify: true
+  versions:
+    - 1.0.0
+cache:
+  enabled: false
+  default_expire: 3600
+fio_urls:
+  1.0.0:
+    material_base: /material
+    material_all: /allmaterials
+    exchange_base: /exchange
+    exchange_orders: /orders
+    exchange_all: /all
+    exchange_full: /full
+    building_base: /building
+    building_all: /allbuildings
+    recipe_base: /recipes
+    recipe_all: /allrecipes
+    planet_base: /planet
+    planet_all: /allplanets
+    planet_full: /allplanets/full
+    planet_sites: /sites
+    planet_search: /search
+    localmarket_base: /localmarket
+    localmarket_planet: /planet
+    localmarket_shipping_source: /shipping/source
+    localmarket_shipping_destination: /shipping/destination
+    localmarket_company: /company
+    sites_base: /sites
+    sites_planets: /planets
+    sites_warehouses: /warehouses
+    storage_base: /storage
+    storage_planets: /planets
+    groups: /auth/groups
+    groups_group: /auth/group
+    groups_groupmemberships: /auth/groupmemberships
+    groups_hub: /fioweb/grouphub
+    groups_burn: /fioweb/burn/group