Setting up the Python SDK

The Python SDK is a python library which can be used to interact with SpecForge tools programmatically from within Python programs, including notebooks.

The Python SDK is packaged as a wheel file with the name specforge_sdk-x.x.x-py3-none-any.whl.

Refer to the SpecForge Python SDK guide for an overview of the SDK features and capabilities.

A Sample Walkthrough

The Python SDK can be installed directly using pip, or defined as a dependency via a build envionment such as poetry or uv.

We discuss below how such an environment can be setup using uv. If you prefer to use a different build system, the workflow should be similar.

1. Install uv on your operating system. See the uv installation guide for more details.

2. Create a new project directory and navigate into it. Populate it with a pyproject.toml file.

3. Declare the dependencies in the pyproject.toml file.

   • The wheel file for the Python SDK can be declared as a local dependency. Ensure that a correct path to the wheel file is provided.
   • Features of SpecForge, such as the interactive monitor, can be used as a part of Python Notebooks. To do so, you may want to include jupyterlab as a dependency as well.
   • Libraries such as numpy, pandas and matplotlib are frequently included for data processing and visualization.
   • Here is an example pyproject.toml file:

   [project]
   name = "sample-project"
   version = "0.1.0"
   description = "Sample Project for Testing SpecForge SDK"
   authors = [{ name = "Imiron Developers", email = "info@imiron.io" }]
   readme = "README.md"
   requires-python = ">=3.12"
   dependencies = [
       "jupyterlab>=4.4.5",
       "pandas>=2.3.1",
       "matplotlib>=3.10.3",
       "numpy>=2.3.2",
       "specforge-sdk",
   ]
   
   [tool.uv.sources]
   specforge_sdk = { path = "lib/specforge_sdk-0.5.5-py3-none-any.whl" }
   

4. Run uv sync. This should create a .venv directory which would have the appropriate dependencies (including the correct version of python) installed.

5. Run source .venv/bin/activate to use the Shell Hook with access to python. You can confirm that this has been configured correctly as follows.

   $ source .venv/bin/activate
   (falsification-examples) $ which python
   /path/to/project/falsification/.venv/bin/python
   

6. Now, you can browse the example notebooks. Make sure that your notebook is connected to the kernel in the .venv. This is usually configured automatically, but can also be done manually. To do so, run jupyter server and copy and paste the server URL in the kernel settings in the VSCode notebook viewer.