{ "info": { "author": "Raul Morales Delgado", "author_email": "rmoralesdelgado@gmail.com", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "Intended Audience :: Science/Research", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Operating System :: MacOS :: MacOS X", "Programming Language :: Python :: 3" ], "description": "\n

\n \n \n \n \n \n \n

\n\n# espressomaker\n\n`espressomaker` is a Python 3 module that provides a context manager \u2014 and other functionalities \u2014 to modify the power management settings on a MacOS X system so that lengthy tasks (e.g. a machine learning training algorithm) can run uninterruptedly \u2014 without your Mac going to sleep.\n\nMore specifically, `espressomaker` is a wrapper of `caffeinate`, a shell command in MacOS X distributions that allows users to alter the system's sleep behavior. In this sense, `espressomaker` runs `caffeinate` subprocesses from the Python 3 interpreter or the IPython kernel from where it was imported and allows to control your Mac's sleep settings through a simple and intuitive set of Python commands.\n\n

Table of Contents

\n
\n\n## 1. Quick Start\n\nTo install `espressomaker`, run the following on your Terminal:\n```bash\n$ pip install espressomaker\n```\n\nTo use `espressomaker` as a context manager for a block of code, run on a Python 3 interpreter or an IPython kernel:\n```python\nfrom espressomaker import Espresso\n\nwith Espresso.shot():\n function_1()\n function_2()\n ...\n```\n\nThe indented code will be run using the context manager of `espressomaker`, `Espresso.shot()`. While this code is running, your Mac won't go to sleep.\n\n## 2. Purpose\n\n`espressomaker` provides a Python 3 module that prevents your Mac from sleep when you are running lengthy tasks \u2014 blocks of code that take a long time to finish.\n\nMany applications that run on Python may take hours to finish, like machine learning training algorithms. If a task is actively running on a Python 3 interpreter \u2014 e.g. a Python script \u2014 or an iPython kernel \u2014 e.g. a Jupyter notebook \u2014\u00a0and the system goes to sleep, the running processes will be interrupted and all the progress related to that block of code will be lost. \n\nTo avoid that, `espressomaker` provides a handful of functionalities, including a useful context manager to run blocks of code. The context manager will allow you to use `Espresso`, a module of `espressomaker`, to temporarily change the power management settings of your Mac while the indented block of code is running. Once the task is done, the settings will return to its default state.\n\n`espressomaker` is a package that intends to facilitate dealing with lengthy Python tasks such that the user can, in a single line of code, forget about dealing with interrupted processes.\n\n## 3. Installation\n\nTo install `espressomaker`, run on your terminal:\n```bash\n$ pip install espressomaker\n```\n\nYou can find the package's PyPI link [here](https://pypi.org/project/espressomaker/).\n\n**Troubleshooting**\n\nThe installation process using `pip` should be uneventful. After the installation, the package should be located at:\n* `/Users//.local/lib/pythonX.Y/site-packages/`, if you use `pip` as the default package manager; or,\n* `/Users//anaconda3/lib/pythonX.Y/site-packages/`, if you use `conda` as a package manager;\n\nwhere X.Y is your current Python version (root environment). You can check if these directories are considered by Python's system's path by running:\n```python\nimport sys\nsys.path\n```\n\nHowever, if when importing a `ModuleNotFoundError` occurs, it could be possible that your current kernel is **not** including the directory where `espressomaker` is installed at. Although this is unlikely, you can find the current location of the package by running on your Terminal:\n```bash\n$ find /Users/ -type d -name 'espressomaker' 2>/dev/null | grep \".*python.*\"\n```\n\nThe previous command will search for a folder called `espressomaker` in the `Users/` directory and only print the matches that belong to a `python` subdirectory. If the directory found is not on `sys.path`, you can manually add it in Python using:\n```python\nsys.path.append('')\n```\n\n## 4. User guide\n\n### 4.1 Working principle\n\nThe `Espresso` module from `espressomaker` allows you to run `caffeinate` subprocesses \u2014 child processes of your current Python interpreter or IPython kernel. `caffeinate` is a shell command available on MacOS distributions that allows to prevent a computer from sleeping by creating assertions.\n\nThe `Espresso` module offers two ways to run `caffeinate` subprocesses:\n1. As a context manager for a task \u2014 a block of code \u2014, using the `shot()` method, or;\n1. As a manual method call, using the `opentab()` and `closetab()` methods (i.e. the user defines when to start running the subprocess and when to finish it).\n\nIn either way, your Mac will not sleep until the task is completed \u2014 when using the context manager mode \u2014 or until you manually *close the tab*.\n\n### 4.2 Importing the module\n\nTo import the functionalities of `espressomaker` to Python, run:\n```python\nfrom espressomaker import Espresso\n```\n\n### 4.3 Default settings\n\nThe `Espresso` module has two class-level settings: `verbose` and `display_on`. The `verbose` parameter enables messages related to the status of the module when using the `shot()` context manager. The `display_on` parameter determines whether the display of your Mac will remain on (if `display_on = True`) or if it will turn off (`display_on = False`) as per the current settings of your Mac.\n\nThe default class-level settings are the following and can be retrieved using `config()`:\n```python\n>>> Espresso.config()\nEspresso(verbose = True, display_on = False)\n```\n\nTo change these class-level settings \u2014 to set new default settings \u2014, just pass in the parameters you want to change into `Espresso.config()`:\n```python\n>>> Espresso.config(display_on = True)\nEspresso(verbose = True, display_on = True)\n```\n\n**Safety note**\n\nFor safety reasons, `espressomaker` only works when your Mac is connected to AC \u2014 it will not work if you are using battery power. \n\n### 4.3 Using the context manager \u2014 `Espresso.shot()`\n\nOne of the main advantages of the `Espresso` module is that it allows to run a task \u2014 a block of code \u2014 using a context manager. The context manager enables the `caffeinate` functionality \u2014 instantiates the subprocess \u2014\u00a0for the code inside it and then closes the process \u2014\u00a0kills the subprocess.\n\nTo use it, run:\n```python\n>>> with Espresso.shot(display_on = True):\n... function_1()\n... function_2()\n ...\n```\n\nAs shown above, you can always override the `display_on` default settings by passing in a new value for that argument, which will only work for that instance.\n\n### 4.4 Manually opening and closing tabs \u2014 `Espresso.opentab()` and `Espresso.closetab()`\n\nAlso, `Espresso` provides a manual way to instantiate a \"caffeinate\" subprocess in the current interpreter or kernel. The `opentab()` and `closetab()` methods allow you to instantiate and kill the `caffeinate` subprocess, respectively. \n```python\n>>> Espresso.opentab()\n[espressomaker] Espresso tab opened on Mon, 23/Sep/2019 10:38:46 (display_on = False).\n\n# Your work\n\n>>> Espresso.closetab()\n[espressomaker] Espresso tab closed.\n```\n\nThe `Espresso` module will prevent you from opening more than one `caffeinate` subprocess for the same parent process \u2014 e.g. the Python interpreter, the IPython kernel. Moreover, you can always run `Espresso` in multiple interpreters or kernels and check which `caffeinate` subprocess belongs to your current interpreter or kernel by running `Espresso.check()`.\n\n**Warning**\n\nOpening more than one `caffeinate` subprocess from a single parent process might not let `closetab()` to close all the running subprocesses. When you kill the parent process \u2014 e.g. close the Jupyter notebook \u2014 all the child process are killed along. If for some reason you suspect a `caffeinate` process is still running, you can try to pinpoint it using `Espresso.check()` or kill all the `caffeinate` processes running `Espresso.killall()`.\n\n### 4.5 Checking the tabs \u2014 `Espresso.check()`\n\n`Espresso.check()` allows you to retrieve a list of all running `caffeinate` processes in your Mac. If you have one running in your current interpreter or kernel, it will be explicitly indicated:\n```python\n>>> Espresso.check()\n[espressomaker] The following \"caffeinate\" processes were found:\nUSER PID COMMAND\n 62900 caffeinate -is -w 5531 (This kernel)\n```\n\n### 4.6 Killing all `caffeinate` processes \u2014 `Espresso.killall()`\n\nThe `killall()` method will kill **all** `caffeinate` processes running in the system. Before running it, be sure that you don't have other `caffeinate` active processes that you might need.\n\nFormatting passed and completed.\n\n

Release History

\n\n### v0.1a1\n\nBasic skeleton of the package ready for shipping to TestPyPI.\n\n### v0.1a2\n\n* Automated file exporting from .ipynb to .py and standardized the formatting.\n* Automated file exporting from .ipynb to .md and standardized the formatting.\n* Improved variable handling on instance methods.\n* Added a message for the user to recognize the current kernel when using opentabs().\n* Added debugging tracers for all private methods.\n* Finished class- and static- methods docstrings.\n* Updated setup.py.\n\n### v0.1b1\n\n* Improved HISTORY.md title formatting.\n* Updated \"classifiers\" of setup.py.\n* Changed opentabs() classmethod to check() in espresso.py.\n* Successfully ran manual tests in all APIs.\n\n### v0.1b2\n\n* Added PyPI version and GitHub issues badges to README.md.\n* Ran installation test using `$ pip install espressomaker`.\n* Added config() classmethod to allow user modify Espresso class-level settings. Returns current settings.\n* Added parameters to shot() and opentab() to allow user override \"display_on\" class-level setting.\n* Repositioned status retrieval in closetab() classmethod.\n* Added return message for killall() staticmethod.\n* Added atexit.register call to closetab() (to be used when using opentab() in a .py script and not using closetab() at the end; however, killing the parent process should kill the \"caffeinate\" subprocess anyway).\n* Finished User Guide in README.md.\n\n### TODO\n\n* Finish unittest.\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/rmoralesdelgado/espressomaker", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "espressomaker", "package_url": "https://pypi.org/project/espressomaker/", "platform": "", "project_url": "https://pypi.org/project/espressomaker/", "project_urls": { "Homepage": "https://github.com/rmoralesdelgado/espressomaker" }, "release_url": "https://pypi.org/project/espressomaker/0.1b2/", "requires_dist": null, "requires_python": ">=3.5", "summary": "Allows to temporarily modify the power management settings on a MacOS to run processes uninterruptedly.", "version": "0.1b2" }, "last_serial": 5889730, "releases": { "0.1b1": [ { "comment_text": "", "digests": { "md5": "0d1dcd45ef22468d359ca5273da07ff6", "sha256": "f0819d5c90dff0e0124f21edd3f9f8f29d084d877ccd8fd97fcfa84fc713f63a" }, "downloads": -1, "filename": "espressomaker-0.1b1-py3-none-any.whl", "has_sig": false, "md5_digest": "0d1dcd45ef22468d359ca5273da07ff6", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.5", "size": 8074, "upload_time": "2019-09-23T09:41:38", "url": "https://files.pythonhosted.org/packages/6f/82/e8e62ec368cbf7b8c43bb4906bbe762143a4d8470e0cdd7bd675d07b136c/espressomaker-0.1b1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "361e88b2ab9fcfed440cae004143e035", "sha256": "37a163f511602afc7c022a245753e94b75a2413ed89cb36f606423cb6b39f10a" }, "downloads": -1, "filename": "espressomaker-0.1b1.tar.gz", "has_sig": false, "md5_digest": "361e88b2ab9fcfed440cae004143e035", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.5", "size": 6902, "upload_time": "2019-09-23T09:41:47", "url": "https://files.pythonhosted.org/packages/65/85/4629f3ee6c0e0f10d962e97f5639e5115de874b63edfb74c15cd809a0869/espressomaker-0.1b1.tar.gz" } ], "0.1b2": [ { "comment_text": "", "digests": { "md5": "9c156b48359b1ffc602b91f9c209dafb", "sha256": "f5780e88e545e60ec0b9aa01fbe70f2717265adbad740d1f2302630d6956102e" }, "downloads": -1, "filename": "espressomaker-0.1b2-py3-none-any.whl", "has_sig": false, "md5_digest": "9c156b48359b1ffc602b91f9c209dafb", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.5", "size": 10078, "upload_time": "2019-09-26T09:38:16", "url": "https://files.pythonhosted.org/packages/c4/35/0ae951ca7ae9e6445e274961ed8a394230d5147b5d7c92090cba0f577201/espressomaker-0.1b2-py3-none-any.whl" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "9c156b48359b1ffc602b91f9c209dafb", "sha256": "f5780e88e545e60ec0b9aa01fbe70f2717265adbad740d1f2302630d6956102e" }, "downloads": -1, "filename": "espressomaker-0.1b2-py3-none-any.whl", "has_sig": false, "md5_digest": "9c156b48359b1ffc602b91f9c209dafb", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.5", "size": 10078, "upload_time": "2019-09-26T09:38:16", "url": "https://files.pythonhosted.org/packages/c4/35/0ae951ca7ae9e6445e274961ed8a394230d5147b5d7c92090cba0f577201/espressomaker-0.1b2-py3-none-any.whl" } ] }