General Cache Flow¶
flowchart TD
request <--> load
request <-->|if delete request|delete <--> find
request <--> |if get or put request|add <--> find
request <---> |if patch or post request|update <--> find
request <---> |if cache is valid and get request| find
request[request method] --> valid[\valid?/] --> save
valid ----> returnn
save -----> returnl[return list of objects]
save -----> returnn[return none]
save -----> returno[return single object]
toggl_api.MissingParentError
¶
Bases: AttributeError
, ValueError
Raised when a cache object doesn't have a parent and is being called.
toggl_api.meta.cache.TogglCache
¶
Bases: ABC
, Generic[TC]
Abstract class for caching Toggl API data to disk.
Integrates as the backend for the TogglCachedEndpoint in order to store requested models locally.
Parameters:
-
path
(Path
) –Location where the cache will be saved.
-
expire_after
(Optional[timedelta | int]
, default:None
) –After how much time should the cache expire. Set to None if no expire_date or to 0 seconds for no caching at all. If using an integer it will be assumed as seconds. If set to None its ignored.
-
parent
(Optional[TogglCachedEndpoint]
, default:None
) –Endpoint which the cache belongs to. Doesn't need to be set through parameters as it will be auto assigned.
Attributes:
-
cache_path
(Path
) –Path to the cache file. Will generate the folder if it does not exist.
-
expire_after
(timedelta | None
) –Time after which the cache should be refreshed.
-
parent
(TogglCachedEndpoint[TC]
) –Parent TogglCachedEndpoint
Methods:
-
commit
–Commits the cache to disk, database or other form. Method for finalising the cache. Abstract.
-
load_cache
–Loads the cache from disk, database or other form. Abstract.
-
save_cache
–Saves and preforms action depending on request type. Abstract.
-
find_entry
–Looks for a TogglClass in the cache. Abstract.
-
add_entry
–Adds a TogglClass to the cache. Abstract.
-
update_entry
–Updates a TogglClass in the cache. Abstract.
-
delete_entry
–Deletes a TogglClass from the cache. Abstract.
-
find_method
–Matches a RequestMethod to cache functionality.
-
parent_exist
–Validates if the parent has been set. The parent will be generally set by the endpoint when assigned. Abstract.
-
query
–Queries the cache for various varibles. Abstract.
Raises:
-
MissingParentError
–If the parent is None and any cache method is being accessed.
Querying¶
toggl_api.Comparison
¶
Bases: Enum
Source code in toggl_api/meta/cache/base_cache.py
32 33 34 35 36 37 |
|
toggl_api.TogglQuery
dataclass
¶
Bases: Generic[T]
Dataclass for querying cached Toggl models.
Source code in toggl_api/meta/cache/base_cache.py
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 |
|
key: str = field()
class-attribute
instance-attribute
¶
Name of the target column to compare against.
value: T | Sequence[T] = field()
class-attribute
instance-attribute
¶
Value to compare against.
comparison: Comparison = field(default=Comparison.EQUAL)
class-attribute
instance-attribute
¶
The way the value should be compared. None 'EQUALS' comparisons for None numeric or time based values.
SQLite¶
Info
Make sure to install sqlalchemy if using SqliteCache with pip install toggl-api-wrapper[sqlite]
toggl_api.meta.cache.sqlite_cache.SqliteCache
¶
Bases: TogglCache[T]
Class for caching data to a SQLite database.
Disconnects database on deletion or exit.
Parameters:
-
expire_after
(Optional[timedelta | int]
, default:None
) –Time after which the cache should be refreshed. If using an integer it will be assumed as seconds. If set to None the cache will never expire.
-
parent
(Optional[TogglCachedEndpoint[T]]
, default:None
) –Parent endpoint that will use the cache. Assigned automatically when supplied to a cached endpoint.
Attributes:
-
expire_after
–Time after which the cache should be refreshed.
-
database
–Sqlalchemy database engine.
-
metadata
–Sqlalchemy metadata.
-
session
–Sqlalchemy session.
Methods:
-
load_cache
–Loads the data from disk and stores it in the data attribute. Invalidates any entries older than expire argument.
-
query
–Querying method that uses SQL to query cached objects.
Source code in toggl_api/meta/cache/sqlite_cache.py
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 |
|
query(*query: TogglQuery, distinct: bool = False) -> Query[T]
¶
Query method for filtering models from cache.
Filters cached model by set of supplied queries.
Supports queries with various comparisons with the Comparison enumeration.
Parameters:
-
query
(TogglQuery
, default:()
) –Any positional argument that is used becomes query argument.
-
distinct
(bool
, default:False
) –Whether to keep equivalent values around.
Returns:
-
Query[T]
–A SQLAlchemy query object with parameters filtered.
Source code in toggl_api/meta/cache/sqlite_cache.py
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 |
|
JSON¶
toggl_api.meta.cache.json_cache.JSONSession
dataclass
¶
Bases: Generic[T]
Data structure for storing JSON in memory.
Similar to a SQL session as its meant to have the same/similar interface.
This dataclass doesn't require interaction from the library user and will be created in the json cache object.
Examples:
>>> cache = JSONSession(max_length=5000)
Parameters:
-
max_length
(int
, default:10000
) –Max length of the data to be stored.
Attributes:
-
max_length
(int
) –Max length of the data to be stored.
-
version
(str
) –Version of the data structure.
-
data
(list[T]
) –List of Toggl objects stored in memory.
-
modified
(int
) –Timestamp of when the cache was last modified in nanoseconds. Used for checking if another cache object has updated it recently.
Methods:
-
save
–Saves the data to a JSON file. Setting current timestamp and version.
-
load
–Loads the data from disk and stores it in the data attribute. Invalidates any entries older than expire argument.
-
refresh
–Utility method that checks if cache has been updated.
-
process_data
–Processes models according to set attributes.
Source code in toggl_api/meta/cache/json_cache.py
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 |
|
toggl_api.JSONCache
¶
Bases: TogglCache
, Generic[T]
Class for caching Toggl data to disk in JSON format.
Examples:
>>> JSONCache(Path("cache"))
>>> cache = JSONCache(Path("cache"), 3600)
>>> cache = JSONCache(Path("cache"), timedelta(weeks=2))
>>> tracker_endpoint = TrackerEndpoint(231231, BasicAuth(...), cache)
Parameters:
-
path
(Path
) –Path to the cache file
-
expire_after
(Optional[timedelta | int]
, default:None
) –Time after which the cache should be refreshed. If using an integer it will be assumed as seconds. If set to None the cache will never expire.
-
parent
(Optional[TogglCachedEndpoint[T]]
, default:None
) –Parent endpoint that will use the cache. Assigned automatically when supplied to a cached endpoint.
-
max_length
(int
, default:10000
) –Max length list of the data to be stored permanently.
Attributes:
-
expire_after
–Time after which the cache should be refreshed.
-
session(JSONSession)
–Store the current json data in memory while handling the cache.
Methods:
-
commit
–Wrapper for JSONSession.save() that saves the current json data to disk.
-
save_cache
–Saves the given data to the cache. Takes a list of Toggl objects or a single Toggl object as an argument and process the change before saving.
-
load_cache
–Loads the data from the cache and returns the data to the caller discarding expired entries.
Source code in toggl_api/meta/cache/json_cache.py
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 |
|
query(*query: TogglQuery, distinct: bool = False) -> list[T]
¶
Query method for filtering Toggl objects from cache.
Filters cached Toggl objects by set of supplied queries.
Supports queries with various comparisons with the Comparison enumeration.
Parameters:
-
query
(TogglQuery
, default:()
) –Any positional argument that is used becomes query argument.
-
distinct
(bool
, default:False
) –Whether to keep the same values around. This doesn't work with unhashable fields such as lists.
Returns:
-
list[T]
–A list of models with the query parameters that matched.
Source code in toggl_api/meta/cache/json_cache.py
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 |
|