def get_protocol_api(
version: Union[str, APIVersion],
bundled_labware: Dict[str, Dict[str, Any]] = None,
bundled_data: Dict[str, bytes] = None,
extra_labware: Dict[str, Dict[str, Any]] = None)\
-> protocol_api.ProtocolContext:
"""
Build and return a :py:class:`ProtocolContext`connected to
Virtual Smoothie.
This can be used to run protocols from interactive Python sessions
such as Jupyter or an interpreter on the command line:
.. code-block:: python
>>> from opentrons.simulate import get_protocol_api
>>> protocol = get_protocol_api('2.0')
>>> instr = protocol.load_instrument('p300_single', 'right')
>>> instr.home()
If ``extra_labware`` is not specified, any labware definitions saved in
the ``labware`` directory of the Jupyter notebook directory will be
available.
:param version: The API version to use. This must be lower than
:py:attr:`opentrons.protocol_api.MAX_SUPPORTED_VERSION`.
It may be specified either as a string (``'2.0'``) or
as a :py:class:`.protocols.types.APIVersion`
(``APIVersion(2, 0)``).
:param bundled_labware: If specified, a mapping from labware names to
labware definitions for labware to consider in the
protocol. Note that if you specify this, _only_
labware in this argument will be allowed in the
protocol. This is preparation for a beta feature
and is best not used.
:param bundled_data: If specified, a mapping from filenames to contents
for data to be available in the protocol from
:py:attr:`.ProtocolContext.bundled_data`.
:param extra_labware: If specified, a mapping from labware names to
labware definitions for labware to consider in the
protocol in addition to those stored on the robot.
If this is an empty dict, and this function is called
on a robot, it will look in the 'labware'
subdirectory of the Jupyter data directory for
custom labware.
:returns opentrons.protocol_api.ProtocolContext: The protocol context.
"""
if isinstance(version, str):
checked_version = parse.version_from_string(version)
elif not isinstance(version, APIVersion):
raise TypeError('version must be either a string or an APIVersion')
else:
checked_version = version
if extra_labware is None\
and IS_ROBOT\
and JUPYTER_NOTEBOOK_LABWARE_DIR.is_dir(): # type: ignore
extra_labware = labware_from_paths(
[str(JUPYTER_NOTEBOOK_LABWARE_DIR)])
return _build_protocol_context(
checked_version, bundled_labware, bundled_data, extra_labware)
def get_protocol_api(
version: Union[str, APIVersion],
bundled_labware: Dict[str, 'LabwareDefinition'] = None,
bundled_data: Dict[str, bytes] = None,
extra_labware: Dict[str, 'LabwareDefinition'] = None,
) -> protocol_api.ProtocolContext:
"""
Build and return a :py:class:`ProtocolContext` connected to the robot.
This can be used to run protocols from interactive Python sessions
such as Jupyter or an interpreter on the command line:
.. code-block:: python
>>> from opentrons.execute import get_protocol_api
>>> protocol = get_protocol_api('2.0')
>>> instr = protocol.load_instrument('p300_single', 'right')
>>> instr.home()
If ``extra_labware`` is not specified, any labware definitions saved in
the ``labware`` directory of the Jupyter notebook directory will be
available.
When this function is called, modules and instruments will be recached.
:param version: The API version to use. This must be lower than
:py:attr:`opentrons.protocol_api.MAX_SUPPORTED_VERSION`.
It may be specified either as a string (``'2.0'``) or
as a :py:class:`.protocols.types.APIVersion`
(``APIVersion(2, 0)``).
:param bundled_labware: If specified, a mapping from labware names to
labware definitions for labware to consider in the
protocol. Note that if you specify this, _only_
labware in this argument will be allowed in the
protocol. This is preparation for a beta feature
and is best not used.
:param bundled_data: If specified, a mapping from filenames to contents
for data to be available in the protocol from
:py:attr:`.ProtocolContext.bundled_data`.
:param extra_labware: If specified, a mapping from labware names to
labware definitions for labware to consider in the
protocol in addition to those stored on the robot.
If this is an empty dict, and this function is called
on a robot, it will look in the 'labware'
subdirectory of the Jupyter data directory for
custom labware.
:returns opentrons.protocol_api.ProtocolContext: The protocol context.
"""
global _THREAD_MANAGED_HW
if not _THREAD_MANAGED_HW:
# Build a hardware controller in a worker thread, which is necessary
# because ipython runs its notebook in asyncio but the notebook
# is at script/repl scope not function scope and is synchronous so
# you can't control the loop from inside. If we update to
# IPython 7 we can avoid this, but for now we can't
_THREAD_MANAGED_HW = ThreadManager(API.build_hardware_controller)
if isinstance(version, str):
checked_version = version_from_string(version)
elif not isinstance(version, APIVersion):
raise TypeError('version must be either a string or an APIVersion')
else:
checked_version = version
if extra_labware is None\
and IS_ROBOT\
and JUPYTER_NOTEBOOK_LABWARE_DIR.is_dir(): # type: ignore
extra_labware = labware_from_paths([str(JUPYTER_NOTEBOOK_LABWARE_DIR)])
context = protocol_api.ProtocolContext(hardware=_THREAD_MANAGED_HW,
bundled_labware=bundled_labware,
bundled_data=bundled_data,
extra_labware=extra_labware,
api_version=checked_version)
context._hw_manager.hardware.cache_instruments()
return context
