Install and setup the DCNM Ansible Collection using uv

This repository exists because I prefer uv over pip for dependency management, and the DCNM Ansible Collection is setup with pip in mind.

This repository contains a script which installs the DCNM Ansible Collection and uses uv to install the DCNM Ansible Collection's dependencies. The script also copies files (described below) into the DCNM Ansible Collection repository that are useful for uv and for VS Code.

Hence, this repository is really only useful if you tend to do this a lot, or you've never done it and want to understand how to do it.

What gets installed

1. uv (via https://astral.sh/uv/install.sh)
2. Python 3.11 (via uv) the DCNM Collection's currently-recommended Python version
3. $HOME/repos/ansible/collections/ansible_collections/ansible/netcommon
4. $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm
5. uv installs files in $HOME/.local/bin/* (see bottom of this README for specifics)
6. The setup_dcnm_repo.bash script sources $HOME/.local/bin/env immediately after uv is installed
7. The following files are added to the DCNM Ansible Collection in $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm

• dcnm/pyproject.toml -> $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm/pyproject.toml
  • Used by uv to install dependencies needed for the DCNM Ansible Collection (ansible, requests, pydantic, among others)
  • Used by VS Code when editing files in the DCNM Ansible Collection
  • Used by the various linters for the DCNM Ansible Collection
• .venv (created by uv)
  • source this (per below) to enable the virtual environment
• dcnm/env -> $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm/env/env
  • source this to add environment vars pointing to all the right places

NOTE

The pyproject.toml file in this repository's root is for local use.

dcnm/pyproject.toml is what gets copied to the DCNM Ansible Collection.

Installation and Usage

Basic Installation

mkdir -p $HOME/repos
cd $HOME/repos
git clone https://github.com/allenrobel/ansible-dcnm-setup.git
cd ansible-dcnm-setup
./setup_dcnm_repo.bash
cd $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm
source .venv/bin/activate
source env/env

By default, setup_dcnm_repo.bash uses uv sync --no-group dev --no-group test to install base runtime dependencies only. There are two other sets of dependencies, described below, that are not installed by default.

Command-Line Options

The setup script now supports several options for flexibility:

./setup_dcnm_repo.bash --help              # Show all available options
./setup_dcnm_repo.bash --dry-run           # Preview what would be done without making changes
./setup_dcnm_repo.bash --verbose           # Show detailed debug output
./setup_dcnm_repo.bash --skip-clone        # Skip cloning repositories (useful for updates)
./setup_dcnm_repo.bash --skip-uv-install   # Skip installing uv (if already installed)
./setup_dcnm_repo.bash --skip-python-install  # Skip installing Python
./setup_dcnm_repo.bash --skip-venv         # Skip creating virtual environment
./setup_dcnm_repo.bash --skip-deps         # Skip installing dependencies

Environment Variable Configuration

You can customize installation paths and Python version using environment variables:

# Use Python 3.12 instead of 3.11
DCNM_PYTHON_VERSION=3.12 ./setup_dcnm_repo.bash

# Install to a custom location
DCNM_REPOS_HOME=/custom/path/repos ./setup_dcnm_repo.bash

# Customize Ansible home directory
DCNM_ANSIBLE_HOME=/custom/ansible ./setup_dcnm_repo.bash

Updating an Existing Installation

If you've already installed the DCNM Collection and just want to update configuration files or dependencies:

cd $HOME/repos/ansible-dcnm-setup
./setup_dcnm_repo.bash --skip-clone --skip-uv-install --skip-python-install --skip-venv

This will:

• Update pyproject.toml and env files from this repository
• Update dependencies to match the current configuration

Dry Run Mode

To see what the script would do without making any changes:

./setup_dcnm_repo.bash --dry-run

This is useful for:

• Understanding what the script does before running it
• Verifying the installation paths are correct
• Troubleshooting issues

Dependencies for testing

If you want to run pytest and/or pytest --cov, install the test group, per below.

cd $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm
source .venv/bin/activate
uv sync --group test

Dependencies used for development

If you want to run the various linters used by the DCNM Ansible Collection e.g. mypy, black, isort, pylint, etc, install the dev group, per below.

cd $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm
source .venv/bin/activate
uv sync --group dev

Installing everything

If you want to install everything at once, you can do so with either of the following:

cd $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm
source .venv/bin/activate
uv sync --all-groups

# OR

uv sync --group dev --group test

At this point, the DCNM Ansible Collection repository is ready to use. For example, to run unit tests related to the dcnm_fabric module (assuming you've added the testing dependencies as described above):

cd $HOME/repos/ansible/collections/ansible_collections/cisco/dcnm
source .venv/bin/activate
source env/env
cd tests/unit/modules/dcnm
pytest -k dcnm_fabric

Files installed by uv

On MacOS

arobel@Allen-M4 ~ % ls -l $HOME/.local/bin
total 82384
-rw-r--r--@ 1 arobel  staff       328 Nov  5 16:17 env
-rw-r--r--@ 1 arobel  staff       165 Nov  5 16:17 env.fish
lrwxr-xr-x@ 1 arobel  staff        86 Nov  5 16:27 python3.11 -> /Users/arobel/.local/share/uv/python/cpython-3.11.13-macos-aarch64-none/bin/python3.11
-rwxr-xr-x@ 1 arobel  staff  41831152 Oct 30 12:13 uv
-rwxr-xr-x@ 1 arobel  staff    336528 Oct 30 12:13 uvx
arobel@Allen-M4 ~ %

On Ubuntu

(dcnm) arobel@glide:~$ ls -l $HOME/.local/bin
total 52332
-rw-rw-r-- 1 arobel arobel      328 Aug 17 23:49 env
-rw-rw-r-- 1 arobel arobel      165 Aug 17 23:49 env.fish
lrwxrwxrwx 1 arobel arobel       83 Nov  6 01:42 python3.11 -> /home/arobel/.local/share/uv/python/cpython-3.11.14-linux-x86_64-gnu/bin/python3.11
-rwxr-xr-x 1 arobel arobel 53208480 Oct 30 21:58 uv
-rwxr-xr-x 1 arobel arobel   362448 Oct 30 21:58 uvx
(dcnm) arobel@glide:~$