Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS-1111: Add virtualenv instructions for Python SDK #1830

76 changes: 76 additions & 0 deletions docs/program/python-venv.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
title: "Prepare your Python Virtual Environment"
linkTitle: "Viam with your Python Virtualenv"
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
weight: 50
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
weight: 50
weight: 10

type: "docs"
description: "Prepare your Python Virtual Environment to program robots with the Python SDK."
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
images: ["/services/icons/sdk.svg"]
tags: ["client", "sdk", "application", "sdk", "fleet", "program", "python", "venv"]
---

To manage Python packages for your Viam application, you should use a virtual environment, or `venv`.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
By using a `venv`, you can install Python packages like Viam's client SDK just within the virtual environment, and not globally, which could mess with other projects or cause issues within your system.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

Follow this guide to set up a fresh virtual environment and install the Python SDK as a requirement for your application.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

## Setup your project

First, create a directory to house your project.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
For example, name your directory `viam-python`:

```bash
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
mkdir viam-python
cd viam-python
```

## Create a Virtual Environment

Now that you are in the project directory, create and activate a virtual environment for Python to run in.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

> **INFO**
> Creating a virtual environment (`venv`) is important as it isolates this python environment from any other you might already have.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We currently don't have this type of styling in our style guide, while we can add it we'd need to discuss that as a team first.

Let's stick with an alert until then

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However, this also duplicates the info above. in the first paragraph on the page. I think we should not duplicate that.

This allows you to ensure a clean project and easier dependency management, as well as not bloating your global python environment.

```bash
python3 -m venv viam-env
source viam-env/bin/activate
```

Now, you should see `(viam-env)` prepend the commands in your terminal window.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove conditional

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Now, you should see `(viam-env)` prepend the commands in your terminal window.
Now, watch `(viam-env)` prepend the commands in your terminal window.

This shows that the python packages being used are from this particular environment.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

try remove passive voice


You can exit this environment by running `deactivate`.

## Install Viam

Inside the activated `viam-env` python environment, you can now install the Viam SDK:

```bash
pip3 install viam-sdk
```

This will install Viam and all required dependencies.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

Should you need to install your own requirements, be sure to do so in this virtual environment.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
You can [make a](https://openclassrooms.com/en/courses/6900846-set-up-a-python-environment/6990546-manage-virtual-environments-using-requirements-files) <file>requirements.txt</file> and include all necessary packages within, then install the requirements for your client application using `pip install -r requirements.txt`.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

## Setup your IDE

You'll now want to point your IDE to use the python interpreter of your new environment, rather than the default interpreter, likely the global python interpreter.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

avoid future tense - instead explain why they want that "If you awnt to ... then"

sguequierre marked this conversation as resolved.
Show resolved Hide resolved

The following steps are for VS Code.
If you're not using VS Code, please read your IDE's documentation on selecting python interpreters.

1. Open the `viam-python` directory in VS Code
1. Open the Command Palette (using `⇧⌘P` or through the menus View -> Command Palette)
1. Select the command `Python: Select Interpreter`.
There, you should see all the interpreters available to you.
You're looking for one the on you just made: `viam-env`.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
It will look something like: `Python 3.11.5 ('viam-env': venv) ./viam-env/bin/python`.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
If you don't see it, click the `Refresh` icon on the top right of the Command Palette.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

Your IDE will now recognize all packages installed in this environment.
npentrel marked this conversation as resolved.
Show resolved Hide resolved

## Start building

You are now ready to start using Viam's Python SDK!
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should instead point the user to the next step. Probably back to the /program page where they can get the code sample

sguequierre marked this conversation as resolved.
Show resolved Hide resolved
Loading