{ "info": { "author": "", "author_email": "", "bugtrack_url": null, "classifiers": [], "description": "|Build Status| |codecov| |PyPI version|\n\nConsul Lock\n===========\n\n*CLI and Python interface for easily managing Consul locks*\n\nAbout\n-----\n\n- CLI & Python interface:\n\n - Acquire and release a lock.\n - Execute shell whilst holding a lock (releasing on exit).\n - Set TTL of the session that acquires a lock.\n - Blocking and non-blocking locking.\n - Lock acquire timeouts.\n - Add extra metadata to lock information (useful for monitoring who\n is holding locks).\n - Specify lock event listeners to be fired before lock acquire is\n attempted and if unable to acquire locked lock.\n\n- CLI:\n\n - Release multiple locks with keys that match regular expression.\n - Meaningful exit codes (see ``configuration.py`` for details).\n - JSON output on stdout.\n - Add extra verbosity on stderr with ``-vv``.\n\n- Python interface:\n\n - Release multiple locks.\n - Find and release multiple locks with keys that match regular\n expression.\n - Type hinting.\n\nInstallation\n------------\n\nPrerequisites: - python >= 3.6\n\nThe tool can be installed from PyPi:\n\n.. code:: bash\n\n pip install consullock\n\nBleeding edge versions can be installed directly from GitHub:\n\n.. code:: bash\n\n pip install git+https://github.com/wtsi-hgi/consul-lock.git@master#egg=consullock\n\nUsage\n-----\n\nCLI\n~~~\n\nSetup\n^^^^^\n\nSet environment variables:\n\n.. code:: bash\n\n export CONSUL_HTTP_ADDR=consul.example.com:8500\n export CONSUL_HTTP_TOKEN=token\n\nGeneral\n^^^^^^^\n\n::\n\n usage: consullock [-h] [-v] {unlock,lock,execute} ...\n\n Tool to use locks in Consul (v4.2.0)\n\n positional arguments:\n {unlock,lock,execute}\n action\n unlock release a lock\n lock acquire a lock\n execute call executable whilst holding lock\n\n optional arguments:\n -h, --help show this help message and exit\n -v increase the level of log verbosity (add multiple\n increase further)\n\nLocking\n^^^^^^^\n\n::\n\n usage: consullock lock [-h] [--session-ttl SESSION_TTL] [--non-blocking]\n [--timeout TIMEOUT] [--metadata METADATA]\n [--on-before-lock ON_BEFORE_LOCK [ON_BEFORE_LOCK ...]]\n [--on-already-locked ON_ALREADY_LOCKED [ON_ALREADY_LOCKED ...]]\n [-i I]\n key\n\n positional arguments:\n key the lock identifier\n\n optional arguments:\n -h, --help show this help message and exit\n --session-ttl SESSION_TTL\n time to live (ttl) in seconds of the session that will\n be created to hold the lock. Must be between 10s and\n 86400s (inclusive). If set to 0, the session will not\n expire\n --non-blocking do not block if cannot lock straight away\n --timeout TIMEOUT give up trying to acquire the key after this many\n seconds (where 0 is never)\n --metadata METADATA additional metadata to add to the lock information\n (will be converted to JSON)\n --on-before-lock ON_BEFORE_LOCK [ON_BEFORE_LOCK ...]\n path to executable that is to be called before an\n attempt is made to acquire a lock, where the lock key\n is passed as the first argument. Any failures of this\n executable are ignored\n --on-already-locked ON_ALREADY_LOCKED [ON_ALREADY_LOCKED ...]\n path to executable that is to be called after an\n attempt has been made to acquire a lock but failed due\n to the lock already been taken, where the lock key is\n passed as the first argument. Any failures of this\n executable are ignored\n -i I number of seconds between polls to acquire a locked\n lock\n\nUnlocking\n^^^^^^^^^\n\n::\n\n usage: consullock unlock [-h] [-r] key\n\n positional arguments:\n key the lock identifier\n\n optional arguments:\n -h, --help show this help message and exit\n -r whether the key should be treated as a regular expression and to\n release all matching locks\n\nExecuting with lock\n^^^^^^^^^^^^^^^^^^^\n\n::\n\n usage: consullock execute [-h] [--session-ttl SESSION_TTL] [--non-blocking]\n [--timeout TIMEOUT] [--metadata METADATA]\n [--on-before-lock ON_BEFORE_LOCK [ON_BEFORE_LOCK ...]]\n [--on-already-locked ON_ALREADY_LOCKED [ON_ALREADY_LOCKED ...]]\n [-i I]\n key executable\n\n positional arguments:\n key the lock identifier\n executable to execute in shell\n\n optional arguments:\n -h, --help show this help message and exit\n --session-ttl SESSION_TTL\n time to live (ttl) in seconds of the session that will\n be created to hold the lock. Must be between 10s and\n 86400s (inclusive). If set to 0, the session will not\n expire\n --non-blocking do not block if cannot lock straight away\n --timeout TIMEOUT give up trying to acquire the key after this many\n seconds (where 0 is never)\n --metadata METADATA additional metadata to add to the lock information\n (will be converted to JSON)\n --on-before-lock ON_BEFORE_LOCK [ON_BEFORE_LOCK ...]\n path to executable that is to be called before an\n attempt is made to acquire a lock, where the lock key\n is passed as the first argument. Any failures of this\n executable are ignored\n --on-already-locked ON_ALREADY_LOCKED [ON_ALREADY_LOCKED ...]\n path to executable that is to be called after an\n attempt has been made to acquire a lock but failed due\n to the lock already been taken, where the lock key is\n passed as the first argument. Any failures of this\n executable are ignored\n -i I number of seconds between polls to acquire a locked\n lock\n\nExamples\n^^^^^^^^\n\nAcquire lock\n''''''''''''\n\nBlock until acquires lock with key \"my/lock\", which will expire after 10\nminutes:\n\n::\n\n $ consul-lock lock --session-ttl=600 my/lock\n {\"created\": \"2017-11-30T14:55:49.322108\", \"key\": \"my/lock\", \"secondsToLock\": 2.6241003070026636e-05, \"session\": \"9b92744f-f1a9-db12-7873-ad44af5ae224\"}\n $ echo $?\n 0 \n\nTry to acquire already locked \"my/lock\" but do not block:\n\n::\n\n $ consul-lock lock --non-blocking my/lock\n null\n Unable to acquire lock: my/lock\n $ echo $?\n 100\n\n(where ``null`` is the JSON output, written to stdout)\n\nAdd metadata to lock\n''''''''''''''''''''\n\n::\n\n $ consul-lock lock --metadata={\"testing\": 123} my/lock\n {\"created\": \"2017-12-05T12:26:13.717995\", \"key\": \"my/lock\", \"metadata\": {\"testing\": 123}, \"secondsToLock\": 4.327880731027108, \"session\": \"6ad662de-6e0c-8e0f-d92c-5fface60c49b\"}\n\nAcquire lock with event listeners\n'''''''''''''''''''''''''''''''''\n\n::\n\n $ consul-lock lock --on-before-lock=./my-before-script.sh --on-already-locked=./my-locked-script.sh my/lock\n {\"created\": \"2017-12-07T13:02:06.773088\", \"key\": \"my/lock\", \"secondsToLock\": 1.349498052150011e-05, \"session\": \"459266be-2a85-464e-aa08-eda97613a29c\"}\n\n*Note: if specifying event listeners in the form ``--x y``, you will\nneed to explicitly declare the end of the command options with a double\ndash, e.g.\n``consul-lock lock --on-before-lock ./my-before-script.sh -- my/lock``.*\n\nUnlock lock\n'''''''''''\n\n.. code:: bash\n\n $ consul-lock unlock my/lock\n [\"my/lock\"]\n $ echo $?\n 0\n\nExecute shell with lock\n'''''''''''''''''''''''\n\n.. code:: bash\n\n $ consul-lock execute my/lock ./my-executable\n I am printed in \"my-executable\"\n\n*Note: the return code is the result of the executable*\n\nPython\n~~~~~~\n\n.. code:: python\n\n from typing import Dict\n from consullock.configuration import get_consul_configuration_from_environment\n from consullock.managers import ConsulLockManager\n from consullock.models import ConsulLockInformation\n\n # Instantiate lock manager\n lock_manager = ConsulLockManager(\n consul_configuration=get_consul_configuration_from_environment(),\n session_ttl_in_seconds=3600)\n # Note: if the Consul configuration is not specified explicitly, an attempt to gather it from environmental variables \n # will be made (see: https://www.consul.io/docs/commands/index.html#environment-variables).\n\n # Use lock in context\n with lock_manager.acquire(\"my/lock\"):\n do_things_holding_lock()\n\n # Get lock\n lock = lock_manager.acquire(\"my/lock\", timeout=60, blocking=True, metadata=\"testing\")\n\n # Find lock associated to a given key\n lock = lock_manager.find(\"my/lock\")\n\n # Find locks that match a regex\n locks = lock_manager.find_regex(\"my/.*\") # type: Dict[str, Optional[ConsulLockInformation]]\n\n # Release single lock\n lock_manager.release(\"my/lock\")\n\n # Release many locks\n lock_manager.release_all(\"my/lock-1\", \"my/lock-2\", \"my/lock-3\")\n\n # Release locks with key matching regex\n lock_manager.release_regex(\"my/.*\")\n\n # Execute shell whilst holding lock (note: use context manager if executing Python!)\n lock_manager.execute(\"my/lock\", \"echo Hello World\")\n\nDevelopment\n-----------\n\nTests\n~~~~~\n\nPrerequisites: - Docker (used to start Consul instances)\n\nInstall the test requirements:\n\n::\n\n pip install -r test_requirements.txt\n\nRun tests with:\n\n::\n\n PYTHONPATH=. python -m unittest discover -v -s consullock/tests\n\nAlternatives\n------------\n\n- `alaa/consul-lock `__ - Go tool\n with CLI where the user has to deal with sessions.\n- `fidian/consul-locker `__ -\n bash script that locks, executes and then releases.\n- `KurToMe/python-consul-lock `__\n - unmaintained Python lock interface with with questionable\n configuration.\n\n.. |Build Status| image:: https://travis-ci.org/wtsi-hgi/consul-lock.svg?branch=master\n :target: https://travis-ci.org/wtsi-hgi/consul-lock\n.. |codecov| image:: https://codecov.io/gh/wtsi-hgi/consul-lock/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/wtsi-hgi/consul-lock\n.. |PyPI version| image:: https://badge.fury.io/py/consullock.svg\n :target: https://badge.fury.io/py/consullock\n", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/wtsi-hgi/consul-lock", "keywords": "", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "consullock", "package_url": "https://pypi.org/project/consullock/", "platform": "", "project_url": "https://pypi.org/project/consullock/", "project_urls": { "Homepage": "https://github.com/wtsi-hgi/consul-lock" }, "release_url": "https://pypi.org/project/consullock/4.2.0/", "requires_dist": null, "requires_python": "", "summary": "Tool to use locks in Consul", "version": "4.2.0" }, "last_serial": 3531249, "releases": { "1.0.0": [ { "comment_text": "", "digests": { "md5": "4b5a753fedd135e849a2f19fc3918626", "sha256": "3c44f6a2f5a466c63a66dea9bf6eaa26cfd19ffa01524d16c114259c0942c6e3" }, "downloads": -1, "filename": "consullock-1.0.0.tar.gz", "has_sig": false, "md5_digest": "4b5a753fedd135e849a2f19fc3918626", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15793, "upload_time": "2017-12-01T11:07:56", "url": "https://files.pythonhosted.org/packages/14/ff/c32142572268220f5b5b9f785346028c82049f4091dedee89f64db6afd5d/consullock-1.0.0.tar.gz" } ], "1.0.0b0": [ { "comment_text": "", "digests": { "md5": "5acfd98e749e6073bba9ae1fa7cbcf41", "sha256": "e432052d1279218d9c9e44b6bdb9397d893374f4714227e2435a64cbfaca918d" }, "downloads": -1, "filename": "consullock-1.0.0b0.tar.gz", "has_sig": false, "md5_digest": "5acfd98e749e6073bba9ae1fa7cbcf41", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 7066, "upload_time": "2017-11-17T16:10:49", "url": "https://files.pythonhosted.org/packages/1a/61/388653526dd6f5c107785f592d58b2489f5a9d73b4c83d82c1b99b6eb4cd/consullock-1.0.0b0.tar.gz" } ], "1.0.1": [ { "comment_text": "", "digests": { "md5": "d8ce7b3f52d599650dc611cab2a1baa7", "sha256": "bc6698e9c9faeabf0523cec091b2d9f091422ba6bbcb923f564f325e795b4744" }, "downloads": -1, "filename": "consullock-1.0.1.tar.gz", "has_sig": false, "md5_digest": "d8ce7b3f52d599650dc611cab2a1baa7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15780, "upload_time": "2017-12-01T11:22:13", "url": "https://files.pythonhosted.org/packages/09/7d/ba256991fd43caae8a7f8e96d3f76f063fa724d44a71c30208be30598c65/consullock-1.0.1.tar.gz" } ], "1.0.2": [ { "comment_text": "", "digests": { "md5": "6fe7b7fa4829bae0acb90b081a7a7c73", "sha256": "0b273a56bfe57f21c42ef0906e0120469900192859df17cfabbd73cd91eb7a05" }, "downloads": -1, "filename": "consullock-1.0.2.tar.gz", "has_sig": false, "md5_digest": "6fe7b7fa4829bae0acb90b081a7a7c73", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15856, "upload_time": "2017-12-01T16:54:45", "url": "https://files.pythonhosted.org/packages/a3/d6/bafde55d1b7bd77833a8861c94eafb9ebfb3160da13f82781dfb1a443b47/consullock-1.0.2.tar.gz" } ], "1.1.0": [ { "comment_text": "", "digests": { "md5": "537d0795265fc10d41d8b0b2ace9a0b4", "sha256": "7b0409770af3e19e8c8455bc91113c4e63b6c9958147028ee61eca59c3f2508c" }, "downloads": -1, "filename": "consullock-1.1.0.tar.gz", "has_sig": false, "md5_digest": "537d0795265fc10d41d8b0b2ace9a0b4", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 16772, "upload_time": "2017-12-05T12:51:30", "url": "https://files.pythonhosted.org/packages/3b/4a/3a17c24ba7d5e474ade2057e7588c412a45d82959e208eb76b688282909b/consullock-1.1.0.tar.gz" } ], "2.0.0": [ { "comment_text": "", "digests": { "md5": "dd293c03d24592a12351bbed68461e93", "sha256": "17bf39138c3a2ece79e8ebde003fe8e5df125f45cc5b5bd4f4fb872e2aaeabbb" }, "downloads": -1, "filename": "consullock-2.0.0.tar.gz", "has_sig": false, "md5_digest": "dd293c03d24592a12351bbed68461e93", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18706, "upload_time": "2017-12-05T17:02:14", "url": "https://files.pythonhosted.org/packages/a7/6c/9ca979a0e9580fb3155592b6d879165b397c61c121326a26dc1675ac582a/consullock-2.0.0.tar.gz" } ], "2.0.1": [ { "comment_text": "", "digests": { "md5": "e17bb697e69245af4fa3b2902c73a595", "sha256": "a49acce8b975b1920f6b74672dffaaf7d2a4a5c90f67b794c5eddac7aff2102e" }, "downloads": -1, "filename": "consullock-2.0.1.tar.gz", "has_sig": false, "md5_digest": "e17bb697e69245af4fa3b2902c73a595", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18867, "upload_time": "2017-12-06T10:33:18", "url": "https://files.pythonhosted.org/packages/1c/8c/f8340cedb738e5dfb59e1f16ba0928e9cba83e11a962956d5e5727633a2a/consullock-2.0.1.tar.gz" } ], "3.0.0": [ { "comment_text": "", "digests": { "md5": "1ea5c3de9c82fbad07e02cf2b2d61d3f", "sha256": "dd6f7665d88633d7de5a170a7313aa4cd5acd6b984b1e1073018574546ade41f" }, "downloads": -1, "filename": "consullock-3.0.0.tar.gz", "has_sig": false, "md5_digest": "1ea5c3de9c82fbad07e02cf2b2d61d3f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19275, "upload_time": "2017-12-06T17:09:10", "url": "https://files.pythonhosted.org/packages/9b/a7/352db70351d624a8c72ac24d94f9442df7e38aee6b3de77db7bc753b9d7b/consullock-3.0.0.tar.gz" } ], "4.0.0": [ { "comment_text": "", "digests": { "md5": "b5c74e10c71e53c02ebc47feb8309ef0", "sha256": "d41b2db863fd7bd1af49c9edec28e43019aa299f0e46c45f5d581e751c068738" }, "downloads": -1, "filename": "consullock-4.0.0.tar.gz", "has_sig": false, "md5_digest": "b5c74e10c71e53c02ebc47feb8309ef0", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 20176, "upload_time": "2017-12-07T14:56:29", "url": "https://files.pythonhosted.org/packages/73/2d/09727584a7991032afb67483bbada49ef6d22b66f11486ff3b3d4546ea40/consullock-4.0.0.tar.gz" } ], "4.1.0": [ { "comment_text": "", "digests": { "md5": "e252055ed7296dcee95519c875565650", "sha256": "7d88403f304a5153f5927658a1c0981274f08eb9140a23daf863655b9ab4c0cc" }, "downloads": -1, "filename": "consullock-4.1.0.tar.gz", "has_sig": false, "md5_digest": "e252055ed7296dcee95519c875565650", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 20393, "upload_time": "2018-01-18T14:12:36", "url": "https://files.pythonhosted.org/packages/09/17/e58c91280dbd61fe231e38f4cc4557167a6ca00a0a2ede2a9e8c5f13f0ff/consullock-4.1.0.tar.gz" } ], "4.2.0": [ { "comment_text": "", "digests": { "md5": "3c134871031b55c5f9680b54fbbb4a7e", "sha256": "18a5953ec998325644d74977f40d25847c296aedc696b51204a068b3b457be3a" }, "downloads": -1, "filename": "consullock-4.2.0.tar.gz", "has_sig": false, "md5_digest": "3c134871031b55c5f9680b54fbbb4a7e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22361, "upload_time": "2018-01-29T11:56:27", "url": "https://files.pythonhosted.org/packages/6d/4c/4d129d76ca74e3d785990fd6f10a44e08b8279e654a609b9c2a8c83a055b/consullock-4.2.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "3c134871031b55c5f9680b54fbbb4a7e", "sha256": "18a5953ec998325644d74977f40d25847c296aedc696b51204a068b3b457be3a" }, "downloads": -1, "filename": "consullock-4.2.0.tar.gz", "has_sig": false, "md5_digest": "3c134871031b55c5f9680b54fbbb4a7e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22361, "upload_time": "2018-01-29T11:56:27", "url": "https://files.pythonhosted.org/packages/6d/4c/4d129d76ca74e3d785990fd6f10a44e08b8279e654a609b9c2a8c83a055b/consullock-4.2.0.tar.gz" } ] }