espressomaker
espressomaker
is 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, 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.
Contents
- 1. Quick Start
- 2. Purpose
- 3. Installation
-
4. User guide
- 4.1 Working principle
- 4.2 Importing the module
- 4.3 Default settings
- 4.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 all
caffeinate
processes βEspresso.killall()
1. Quick Start
To install espressomaker
, run the following on your Terminal:
$ pip install espressomaker
To use espressomaker
as a context manager for a block of code, run on a Python 3 interpreter or an IPython kernel:
from espressomaker import Espresso
with Espresso.shot():
function_1()
function_2()
...
The 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.
2. Purpose
espressomaker
provides 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, espressomaker
provides a handful of functionalities, including a useful context manager to run blocks of code. The context manager functionality, provided in Espresso
β a module of espressomaker
β, 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.
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.
3. Installation
To install espressomaker
, run on your terminal:
$ pip install espressomaker
You can find the package's PyPI link here.
Troubleshooting
The installation process using pip
should be uneventful. After the installation, the package should be located at:
-
/Users/<your_username>/.local/lib/pythonX.Y/site-packages/
, if you usepip
as the default package manager; or, -
/Users/<your_username>/anaconda3/lib/pythonX.Y/site-packages/
, if you useconda
as 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:
import sys
sys.path
However, if when importing a ModuleNotFoundError
occurs, it could be possible that your current interpreter/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:
$ find /Users/ -type d -name 'espressomaker' 2>/dev/null | grep ".*python.*"
The 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 to Python's path using:
sys.path.append('<path>')
4. User guide
4.1 Working principle
The Espresso
module from espressomaker
allows you to run caffeinate
subprocesses β child processes of your current Python interpreter or IPython kernel. caffeinate
is a shell command available on MacOS distributions that allows to modify the power management settings of your system by creating assertions. In this context, caffeinate
is used to prevent your MacOS system from sleeping while a task is being computed.
The Espresso
module offers two ways to run caffeinate
subprocesses:
- As a context manager for a task β a block of code β, using the
shot()
method, or; - As a manual method call, using the
opentab()
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 manually close the tab.
4.2 Importing the module
To import the functionalities of espressomaker
to Python, run:
from espressomaker import Espresso
4.3 Default settings
The 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.
The default class-level settings can be retrieved using config()
:
>>> 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 into Espresso.config()
:
>>> Espresso.config(display_on = True)
Espresso(verbose = True, display_on = True)
Safety note
For safety reasons, espressomaker
only works when your Mac is connected to AC power β it will not work if you are using battery power.
Espresso.shot()
4.4 Using the context manager β One of the main advantages of the Espresso
module is that it allows to run a task β a block of code β using a context manager. The context manager enables the caffeinate
functionality β instantiates the subprocess βΒ for the code inside it and then closes the process βΒ kills the subprocess.
To use it, run:
>>> with Espresso.shot(display_on = True):
... function_1()
... function_2()
...
As 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 call.
Espresso.opentab()
and Espresso.closetab()
4.5 Manually opening and closing tabs β Espresso
also 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.
>>> Espresso.opentab()
[espressomaker] Espresso tab opened on Mon, 23/Sep/2019 10:38:46 (display_on = False).
# Your work
>>> Espresso.closetab()
[espressomaker] Espresso tab closed.
The Espresso
module will prevent you from opening more than one caffeinate
subprocess for the same parent process β e.g. the Python interpreter, the IPython kernel from which you are running espressomaker
. Moreover, you can always run espressomaker
in multiple interpreters and kernels and check which caffeinate
subprocess belongs to your current interpreter or kernel by running Espresso.check()
.
Warning
While opening more than one caffeinate
subprocess from a single parent process using espressomaker
is not possible, if it occurs you might not be able to use closetab()
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 a caffeinate
process is still running, you can try to pinpoint it using Espresso.check()
, or you can kill all the caffeinate
processes in your Mac running Espresso.killall()
.
Espresso.check()
4.6 Checking the tabs β Espresso.check()
allows you to retrieve a list of all the running caffeinate
processes in your Mac. If you have one running in your current interpreter or kernel, it will be explicitly indicated:
>>> Espresso.check()
[espressomaker] The following "caffeinate" processes were found:
USER PID COMMAND
<your_username> 62900 caffeinate -is -w 5531 (This kernel)
caffeinate
processes β Espresso.killall()
4.7 Killing all The 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.
Formatting (GitHub flavor) passed and completed.