Package: espressomaker
espressomakerespressomakeris a Python 3 module that provides a context manager, among other functionalities, 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 — without your Mac going to sleep.More specifically,espressomakeris a wrapper ofcaffeinate, a shell command in MacOS X distributions that allows users to alter the system's sleep behavior. In this sense,espressomakerrunscaffeinatesubprocesses 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.Contents1. Quick Start2. Purpose3. Installation4. User guide4.1 Working principle4.2 Importing the module4.3 Default settings4.4 Using the context manager —Espresso.shot()4.5 Manually opening and closing tabs —Espresso.opentab()andEspresso.closetab()4.6 Checking the tabs —Espresso.check()4.7 Killing allcaffeinateprocesses —Espresso.killall()1. Quick StartTo installespressomaker, run the following on your Terminal:$pipinstallespressomakerTo useespressomakeras a context manager for a block of code, run on a Python 3 interpreter or an IPython kernel:fromespressomakerimportEspressowithEspresso.shot():function_1()function_2()...The indented code will be run using the context manager ofespressomaker,Espresso.shot(). While this code is running, your Mac won't go to sleep.2. Purposeespressomakerprovides a Python 3 module that prevents your Mac from sleep when you are running lengthy tasks — blocks of code that take a long time to finish.Many 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 — e.g. a Python script — or an iPython kernel — e.g. a Jupyter notebook — and the system goes to sleep, the running processes will be interrupted and all the progress related to that block of code will be lost.To avoid that,espressomakerprovides a handful of functionalities, including a useful context manager to run blocks of code. The context manager functionality, provided inEspresso— a module ofespressomaker—, will allow you 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.espressomakeris 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.3. InstallationTo installespressomaker, run on your terminal:$pipinstallespressomakerYou can find the package's PyPI linkhere.TroubleshootingThe installation process usingpipshould be uneventful. After the installation, the package should be located at:/Users/<your_username>/.local/lib/pythonX.Y/site-packages/, if you usepipas the default package manager; or,/Users/<your_username>/anaconda3/lib/pythonX.Y/site-packages/, if you usecondaas a package manager;where 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:importsyssys.pathHowever, if when importing aModuleNotFoundErroroccurs, it could be possible that your current interpreter/kernel isnotincluding the directory whereespressomakeris installed at. Although this is unlikely, you can find the current location of the package by running on your Terminal:$find/Users/-typed-name'espressomaker'2>/dev/null|grep".*python.*"The previous command will search for a folder calledespressomakerin theUsers/directory and only print the matches that belong to apythonsubdirectory. If the directory found is not onsys.path, you can manually add it to Python's path using:sys.path.append('<path>')4. User guide4.1 Working principleTheEspressomodule fromespressomakerallows you to runcaffeinatesubprocesses — child processes of your current Python interpreter or IPython kernel.caffeinateis a shell command available on MacOS distributions that allows to modify the power management settings of your system by creating assertions. In this context,caffeinateis used to prevent your MacOS system from sleeping while a task is being computed.TheEspressomodule offers two ways to runcaffeinatesubprocesses:As a context manager for a task — a block of code —, using theshot()method, or;As a manual method call, using theopentab()andclosetab()methods (i.e. the user defines when to start running the subprocess and when to finish it).In either way, your Mac will not sleep until the task is completed — when using the context manager mode — or until you manuallyclose the tab.4.2 Importing the moduleTo import the functionalities ofespressomakerto Python, run:fromespressomakerimportEspresso4.3 Default settingsTheEspressomodule has two class-level settings:verboseanddisplay_on. Theverboseparameter enables messages related to the status of the module when using theshot()context manager. Thedisplay_onparameter determines whether the display of your Mac will remain on (ifdisplay_on = True) or if it will turn off (display_on = False) as per the current settings of your Mac.The default class-level settings can be retrieved usingconfig():>>>Espresso.config()Espresso(verbose=True,display_on=False)To change these class-level settings — to set new default settings —, just pass in the parameters you want to change intoEspresso.config():>>>Espresso.config(display_on=True)Espresso(verbose=True,display_on=True)Safety noteFor safety reasons,espressomakeronly works when your Mac is connected to AC power — it will not work if you are using battery power.4.4 Using the context manager —Espresso.shot()One of the main advantages of theEspressomodule is that it allows to run a task — a block of code — using a context manager. The context manager enables thecaffeinatefunctionality — instantiates the subprocess — for the code inside it and then closes the process — kills the subprocess.To use it, run:>>>withEspresso.shot(display_on=True):...function_1()...function_2()...As shown above, you can always override thedisplay_ondefault settings by passing in a new value for that argument, which will only work for that instance call.4.5 Manually opening and closing tabs —Espresso.opentab()andEspresso.closetab()Espressoalso provides a manual way to instantiate a "caffeinate" subprocess in the current interpreter or kernel. Theopentab()andclosetab()methods allow you to instantiate and kill thecaffeinatesubprocess, respectively.>>>Espresso.opentab()[espressomaker]EspressotabopenedonMon,23/Sep/201910:38:46(display_on=False).# Your work>>>Espresso.closetab()[espressomaker]Espressotabclosed.TheEspressomodule will prevent you from opening more than onecaffeinatesubprocess for the same parent process — e.g. the Python interpreter, the IPython kernel from which you are runningespressomaker. Moreover, you can always runespressomakerin multiple interpreters and kernels and check whichcaffeinatesubprocess belongs to your current interpreter or kernel by runningEspresso.check().WarningWhile opening more than onecaffeinatesubprocess from a single parent process usingespressomakerisnotpossible, if it occurs you mightnotbe able to useclosetab()to close all the running subprocesses. When you kill the parent process — e.g. close the Jupyter notebook, restart the kernel — all the child processes are killed along with it. If for some reason you suspect acaffeinateprocess is still running, you can try to pinpoint it usingEspresso.check(), or you can kill all thecaffeinateprocesses in your Mac runningEspresso.killall().4.6 Checking the tabs —Espresso.check()Espresso.check()allows you to retrieve a list of all the runningcaffeinateprocesses in your Mac. If you have one running in your current interpreter or kernel, it will be explicitly indicated:>>>Espresso.check()[espressomaker]Thefollowing"caffeinate"processeswerefound:USERPIDCOMMAND<your_username>62900caffeinate-is-w5531(Thiskernel)4.7 Killing allcaffeinateprocesses —Espresso.killall()Thekillall()method will killallcaffeinateprocesses running in the system. Before running it, be sure that you don't have othercaffeinateactive processes that you might need.Formatting (GitHub flavor) passed and completed.Release Historyv0.1a1Basic skeleton of the package ready for shipping to TestPyPI.v0.1a2Automated file exporting from .ipynb to .py and standardized the formatting.Automated file exporting from .ipynb to .md and standardized the formatting.Improved variable handling on instance methods.Added a message for the user to recognize the current kernel when using opentabs().Added debugging tracers for all private methods.Finished class- and static- methods docstrings.Updated setup.py.v0.1b1Improved HISTORY.md title formatting.Updated "classifiers" of setup.py.Changed opentabs() classmethod to check() in espresso.py.Successfully ran manual tests in all APIs.v0.1b2Added PyPI version and GitHub issues badges to README.md.Ran installation test using$ pip install espressomaker.Added config() classmethod to allow user modify Espresso class-level settings. Returns current settings.Added parameters to shot() and opentab() to allow user override "display_on" class-level setting.Repositioned status retrieval in closetab() classmethod.Added return message for killall() staticmethod.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).Finished User Guide in README.md.v0.1rc1Corrected numbering and hrefs on README.md to work correctly on GitHub.TODOFinish unittest.