Help & Troubleshooting

This document provides guidance on setting up and troubleshooting the NTSM package.

Installation

NTSM can be installed directly from PyPI or from the local repository.

# Standard installation
pip install ntsm

# Local development installation
pip install -e .

Using uv (Recommended)

uv is a high-performance Python package manager. It is significantly faster for installing large dependencies like arcgis.

# Local development installation
uv pip install -e .

# Add as a dependency to your project
uv add ntsm

# Run ntsmdocs without manual environment activation
uv run ntsmdocs

Package Dependencies

NTSM relies on the following core libraries:

cryptography: For high-security Vault operations.
requests: For API connections.
msal: For Azure/Microsoft authentication.
loguru: For standardized logging.

Note: The arcgis library is optional but required for agol and token connections. Use pip install arcgis separately if needed.

Secure Vault Setup

The recommended way to use the Vault is via an environment variable to avoid storing keys in files.

Windows (Cmd)

set GIS_KEY=your_master_key_here

Windows (PowerShell)

$env:GIS_KEY = "your_master_key_here"

Linux/macOS (Bash)

export GIS_KEY="your_master_key_here"

Common Issues

ImportError: No module named ‘arcgis’

The ArcGIS library is large and is not included in the default NTSM installation to keep the package lightweight. Solution: Run pip install arcgis.

Vault decryption fails

Cause 1: The GIS_KEY environment variable is missing or has an extra newline.
Cause 2: You are using the modern VaultCipher on a string encrypted with the legacy VaultUtils.encrypt_text.
Solution: Ensure your keys match the cipher type.

Documentation

To view the complete API reference, use the built-in documentation viewer:

ntsmdocs

Support

If you encounter bugs or have suggestions:

Check the existing documentation using ntsmdocs.
Follow the Contact & Support section in the README for direct contact details.