{"id":43281766,"url":"https://github.com/thruflo/alkey","last_synced_at":"2026-02-01T17:11:55.736Z","repository":{"id":57409789,"uuid":"9375853","full_name":"thruflo/alkey","owner":"thruflo","description":"Redis backed tool for generating cache keys that implicitly invalidate when SQLAlchemy model instances change.","archived":false,"fork":false,"pushed_at":"2015-09-25T14:53:20.000Z","size":276,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-27T04:06:17.443Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://pypi.python.org/pypi/alkey","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thruflo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-11T17:13:15.000Z","updated_at":"2016-08-03T04:19:37.000Z","dependencies_parsed_at":"2022-08-24T18:50:50.881Z","dependency_job_id":null,"html_url":"https://github.com/thruflo/alkey","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thruflo/alkey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thruflo%2Falkey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thruflo%2Falkey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thruflo%2Falkey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thruflo%2Falkey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thruflo","download_url":"https://codeload.github.com/thruflo/alkey/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thruflo%2Falkey/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28983676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T16:29:42.054Z","status":"ssl_error","status_checked_at":"2026-02-01T16:29:41.428Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-01T17:11:55.262Z","updated_at":"2026-02-01T17:11:55.731Z","avatar_url":"https://github.com/thruflo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alkey\n\n[Alkey][] is a [Redis][] backed tool for generating cache keys that implicitly\nupdate / invalidate when [SQLAlchemy][] model instances change, e.g.:\n\n    from alkey.cache import get_cache_key_generator\n    key_generator = get_cache_key_generator()\n    \n    # The `cache_key` will be invalidated when `instance1` or `instance2` change.\n    cache_key = key_generator(instance1, instance2)\n\nIt can be used by any [SQLAlchemy][] application that has access to [Redis][].\nPlus it has (optional) integration with the [Pyramid][] framework:\n`config.include` the package and generate keys using, e.g.:\n\n    cache_key = request.cache_key(request.context)\n\n## How it Works\n\n[Alkey][] works by binding to the SQLAlchemy session's [before_flush][] and\n[after_commit][] events to maintain a unique token, in Redis, against every\nmodel instance. As long as the model instance has a unique `id` property, this\ntoken will change whenever the instance is updated or deleted. In addition,\nAlkey maintains a global write token and a token against each database table.\nYou can use these to generate cache keys that invalidate:\n\n* when an *instance* changes\n* when a *table* changes; or\n* when *anything* changes\n\nThe main algorithm is to record instances as changed when they're flushed to\nthe db in the session's new, dirty or deleted lists (identifiers in the format\n`alkey:tablename#row_id`, e.g.: `alkey:users#1`, are stored in a Redis set).\nThen, when the session's transaction is committed, the tokens for each recorded\ninstance (plus their table and the global write token) are updated. This means\nthat a cache key that contains the tokens will miss, causing the cached value\nto be regenerated.\n\nNew tokens are generated when instances are looked up that are not already\nin the cache. So keys will always be invalidated if you lose / flush your\nRedis data.\n\n\u003e Note also that changes recorded during a transaction that's\nsubsequently rolled back will be discarded (i.e.: the tokens will not be updated)\n*unless* the rolled-back transaction is a sub-transaction. In that case \u0026mdash; if\nyour application code explicitly uses sub-transactions \u0026mdash; rollbacks may lead\nto unnecessary cache-misses.\n\n## Configuring a Redis Client\n\n[Alkey][] looks in the `os.environ` (i.e.: you need to provide\n[environment variables][]) for a values to configure a [redis client][]:\n\n* `REDIS_URL`: a connection string including any authenticaton information, e.g.:\n  `redis://username:password@hostname:port`\n* `REDIS_DB`: defaults to `0`\n* `REDIS_MAX_CONNECTIONS`: the maximum number of connections for the client's\n  connection pool (defaults to not set)\n\n## Binding to Session Events\n\nUse the `alkey.events.bind` function, e.g.:\n    \n    from alkey import events\n    from myapp import Session # the sqlalchemy session you're using\n    \n    events.bind(Session)\n\n## Generating Cache Keys\n\nYou can then instantiate an `alkey.cache.CacheKeyGenerator` and call it with\nany of the following types as positional arguments to generate a cache key:\n\n* SQLAlchemy model instances\n* model instance identifiers in the format `alkey:tablename#row_id`\n* SQLAlchemy model classes\n* model class identifiers in the format `alkey:tablename#*`\n* the `alkey.constants.GLOBAL_WRITE_TOKEN`, which has the value `alkey:*#*`\n* arbitrary values that can be coerced to a unicode string\n\nE.g. using the `alkey.cache.get_cache_key_generator` factory to instantiate:\n\n    from alkey.cache import get_cache_key_generator\n    \n    key_generator = get_cache_key_generator()\n    cache_key = key_generator(instance, 'alkey:users#1', 1, 'foo', {'bar': 'baz'})\n\nOr, for example, imagine you have a `users` table, of which `user` is an instance\nwith an `id` of `1`:\n\n    # Invalidate when this user changes.\n    cache_key = key_generator(user)\n    cache_key = key_generator('alkey:users#1')\n\n    # Invalidate when any user is inserted, updated or deleted.\n    cache_key = key_generator(user.__class__)\n    cache_key = key_generator('alkey:users#*')\n\n    # Invalidate when any instance of any type is inserted, updated or deleted.\n    cache_key = key_generator('alkey:*#*')\n\nOr you can directly get the instance token with `alkey.cache.get_token`, e.g.:\n\n    from alkey.cache import get_token\n    from alkey.client import get_redis_client\n    \n    redis_client = get_redis_client()\n    \n    token = get_token(redis_client, user)\n    token = get_token(redis_client, 'alkey:users#1')\n\n## Pyramid Integration\n\nIf you're writing a [Pyramid][] application, you can bind to the session events\nby just including the package:\n\n    config.include('alkey')\n\nThis will, by default, use the [pyramid_basemodel][] threadlocal scoped session.\nTo use a different session class, provide a dotted path to it as the\n`alkey.session_cls` in your .ini settings, e.g.:\n\n    alkey.session_cls=myapp.model.Session\n\nAn appropriately configured `alkey.cache.CacheKeyGenerator` instance will then\nbe available as ``request.cache_key``, e.g:\n\n    key = request.cache_key(instance1, instance2, 'arbitrary string')\n\nOr e.g.: in a [Mako template][]:\n\n    \u003c%page cached=True, cache_key=${request.cache_key(1, self.uri, instance)} /\u003e\n\n## Tests\n\n[Alkey][] has been developed and tested against Python2.7. To run the tests,\ninstall `mock`, `nose` and `coverage` and either hack the `setUp` method in\n`alkey.tests:IntegrationTest` or have a Redis db available at\n`redis://localhost:6379`. Then, e.g.:\n\n    $ nosetests alkey --with-doctest --with-coverage --cover-tests --cover-package alkey\n    ..........................\n    Name               Stmts   Miss  Cover   Missing\n    ------------------------------------------------\n    alkey                 11      0   100%   \n    alkey.cache           74      0   100%   \n    alkey.client          73      0   100%   \n    alkey.constants        6      0   100%   \n    alkey.events          12      0   100%   \n    alkey.handle          76      0   100%   \n    alkey.interfaces       6      0   100%   \n    alkey.tests          184      0   100%   \n    alkey.utils           30      0   100%   \n    ------------------------------------------------\n    TOTAL                472      0   100%   \n    ----------------------------------------------------------------------\n    Ran 26 tests in 0.566s\n    \n    OK\n\n[alkey]: http://github.com/thruflo/alkey\n[Redis]: http://redis.io\n[SQLAlchemy]: http://www.sqlalchemy.org/\n[redis client]: https://github.com/andymccurdy/redis-py\n[before_flush]: http://docs.sqlalchemy.org/ru/latest/orm/events.html#sqlalchemy.orm.events.SessionEvents.before_flush\n[after_commit]: http://docs.sqlalchemy.org/ru/latest/orm/events.html#sqlalchemy.orm.events.SessionEvents.after_commit\n[Pyramid]: http://docs.pylonsproject.org/projects/pyramid/en/latest\n[Mako template]: http://www.makotemplates.org/\n[pyramid_basemodel]: http://github.com/thruflo/pyramid_basemodel\n[environment variables]: http://blog.akash.im/per-project-environment-variables-with-forema\n[Heroku addons]: https://www.google.co.uk/search?q=Heroku+addons+redis\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthruflo%2Falkey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthruflo%2Falkey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthruflo%2Falkey/lists"}