Utils Modules

Shared utility modules used across commands.

dbx_python_cli.utils.output module

Output utilities for formatting and pagination.

dbx_python_cli.utils.output.paginate_output(output: str, use_pager: bool = False)

Display output using a pager if requested and available.

Parameters:

• output – The text to display

• use_pager – Whether to use a pager (from -p flag or command default)

The function will use ‘less -R’ if: - use_pager is True - stdout is a terminal (not piped) - ‘less’ is available on the system

Otherwise, it will print directly to stdout.

dbx_python_cli.utils.output.should_use_pager(ctx: Context, command_default: bool = False) → bool

Determine if pager should be used based on context and command default.

Parameters:

• ctx – Typer context containing the pager flag

• command_default – Whether this command uses pager by default

Returns:

True if pager should be used, False otherwise

dbx_python_cli.utils.project module

Project management utilities.

This module provides helper functions for Django project management, including project path resolution, venv detection with Django-specific fallback, and environment setup for Django commands.

These utilities are used by dbx project commands.

class dbx_python_cli.utils.project.ProjectContext(name: str, project_path: Path, base_dir: Path | None, projects_dir: Path | None)

Bases: object

Container for resolved project information.

dbx_python_cli.utils.project.apply_libmongocrypt_env(env: dict, config: dict, *, include_dyld_fallback: bool = True, base_dir: Path | None = None, verbose: bool = False) → dict

Merge libmongocrypt env vars from [project.default_env] into env.

Existing keys in env are never overwritten. File-style vars (PYMONGOCRYPT_LIB, CRYPT_SHARED_LIB_PATH) are only set if the file exists; directory-style vars are set as-is. If PYMONGOCRYPT_LIB is missing from config but a libmongocrypt clone is built at base_dir/libmongocrypt/cmake-build/libmongocrypt.{dylib,so}, it is auto-populated. CRYPT_SHARED_LIB_PATH is never auto-derived.

dbx_python_cli.utils.project.get_django_python_path(ctx: ProjectContext, directory: Path | None) → tuple[str, str]

Get the Python path for Django commands, with Django group venv fallback.

Checks in priority order (most specific to least specific): 1. project-level venv (project_path/.venv) 2. group-level venv (projects_dir/.venv OR directory/.venv) 3. django group venv (base_dir/django/.venv) 4. base-level venv (base_dir/.venv, only when using config path) 5. activated / PATH venv

Parameters:

• ctx – ProjectContext from resolve_project_path

• directory – The original directory argument from CLI

Returns:

(python_path, venv_type)

Return type:

tuple

Raises:

typer.Exit – If no suitable venv is found

dbx_python_cli.utils.project.get_newest_project(projects_dir: Path, exclude_names: set | None = None) → tuple[str, Path]

Get the newest project from the projects directory.

Returns:

(project_name, project_path)

Return type:

tuple

Raises:

typer.Exit – If no projects are found

dbx_python_cli.utils.project.resolve_project_path(name: str | None, directory: Path | None, require_exists: bool = True) → ProjectContext

Resolve project path from name and directory arguments.

This helper consolidates the common pattern of resolving a project’s location from CLI arguments, including the “newest project” fallback when no name is provided.

Parameters:

• name – Project name (optional, will use newest project if None and directory is None)

• directory – Custom directory where the project is located (optional)

• require_exists – If True, raises typer.Exit if project doesn’t exist

Returns:

ProjectContext with resolved name, project_path, base_dir, and projects_dir

Raises:

typer.Exit – If project name is required but not provided, or if project doesn’t exist

dbx_python_cli.utils.project.setup_django_command_env(ctx: ProjectContext, typer_ctx: Context, mongodb_uri: str | None = None, settings: str | None = None, include_dyld_fallback: bool = True) → dict

Set up the environment for running Django commands.

This helper consolidates the common pattern of: - Setting up MONGODB_URI (explicit or via ensure_mongodb) - Setting library paths for libmongocrypt (Queryable Encryption) - Setting DJANGO_SETTINGS_MODULE - Setting PYTHONPATH

Parameters:

• ctx – ProjectContext from resolve_project_path

• typer_ctx – The typer Context for accessing CLI overrides

• mongodb_uri – Optional explicit MongoDB URI (takes precedence)

• settings – Optional settings module name (defaults to project name)

• include_dyld_fallback – Whether to include DYLD_FALLBACK_LIBRARY_PATH

Returns:

Environment dictionary ready for subprocess calls

Return type:

dict

dbx_python_cli.utils.project.validate_qe_env(config: dict, *, base_dir: Path | None = None, fatal: bool = False) → list

Return list of problems with QE env vars; optionally raise typer.Exit(1).

dbx_python_cli.utils.repo module

Repository utilities and helper functions.

dbx_python_cli.utils.repo.extract_repo_name_from_url(url)

Extract repository name from a git URL.

Parameters:

url – Git URL (e.g., “git@github.com:mongodb/mongo-python-driver.git”)

Returns:

Repository name (e.g., “mongo-python-driver”)

Return type:

str

dbx_python_cli.utils.repo.find_all_repos(base_dir, config=None)

Find all cloned repositories in the base directory.

In flat mode (config["repo"]["flat"] = true) repos live directly under base_dir. Otherwise the classic two-level layout is used: base_dir/<group>/<repo>.

Parameters:

• base_dir – Path to the base directory

• config – Optional configuration dictionary; enables flat-mode detection and group assignment from config when flat is true.

Returns:

List of dictionaries with ‘name’, ‘path’, and ‘group’ keys

Return type:

list

dbx_python_cli.utils.repo.find_all_repos_by_name(repo_name, base_dir, config=None)

Find all repositories with a given name in the base directory.

Parameters:

• repo_name – Name of the repository to find

• base_dir – Path to the base directory containing group subdirectories

• config – Optional configuration dictionary

Returns:

List of dictionaries with ‘name’, ‘path’, and ‘group’ keys

Return type:

list

dbx_python_cli.utils.repo.find_repo_by_name(repo_name, base_dir, config=None)

Find a repository by name in the base directory. If multiple repos with the same name exist in different groups, returns the one in the highest priority group.

Parameters:

• repo_name – Name of the repository to find

• base_dir – Path to the base directory containing group subdirectories

• config – Optional configuration dictionary for group priority

Returns:

Dictionary with ‘name’, ‘path’, and ‘group’ keys, or None if not found

Return type:

dict

dbx_python_cli.utils.repo.find_repo_by_path(path, base_dir, config=None)

Find a repository by filesystem path.

Resolves path to an absolute path and checks all known repos for a match. An exact match on the repo root is tried first; if not found, the function checks whether path is located inside a known repo (useful when the caller is in a subdirectory of the repo).

Parameters:

• path – A pathlib.Path (or anything accepted by Path()) pointing at or inside the repository root.

• base_dir – Path to the base directory containing group subdirectories.

• config – Optional configuration dictionary.

Returns:

Dictionary with 'name', 'path', and 'group' keys,

or None if no matching repository is found.

Return type:

dict

dbx_python_cli.utils.repo.get_base_dir(config)

Get the base directory for cloning repos.

dbx_python_cli.utils.repo.get_build_commands(config, group_name, repo_name)

Get build commands for a repository.

For repos that need a build step before installation (e.g., cmake builds), returns a list of shell commands to run.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘django’)

• repo_name – Name of the repository (e.g., ‘libmongocrypt’)

Returns:

List of build commands, or None if no build needed

Return type:

list

dbx_python_cli.utils.repo.get_config()

Load configuration from user config or default config.

dbx_python_cli.utils.repo.get_config_path()

Get the path to the user config file.

dbx_python_cli.utils.repo.get_default_config_path()

Get the path to the default config file shipped with the package.

dbx_python_cli.utils.repo.get_editor(config, group_name=None, repo_name=None)

Get the editor to use for opening repositories.

Priority order: 1. Repo-specific editor setting (if repo_name provided) 2. Group-level editor setting (if group_name provided) 3. Global editor setting in config 4. EDITOR environment variable 5. Default to ‘vim’

Parameters:

• config – Configuration dictionary

• group_name – Optional name of the group (e.g., ‘django’)

• repo_name – Optional name of the repository (e.g., ‘django’)

Returns:

Editor command to use

Return type:

str

dbx_python_cli.utils.repo.get_evergreen_project_name(config, repo_name)

Get the Evergreen project name for a repository.

Parameters:

• config – Configuration dictionary

• repo_name – Name of the repository

Returns:

Evergreen project name, or None if not configured

Return type:

str

dbx_python_cli.utils.repo.get_global_groups(config)

Get the list of global group names from config.

Repos in global groups are installed into every other group’s venv automatically when running dbx install -g <group>.

Returns:

Group names listed under repo.global_groups, or an empty list.

Return type:

list

dbx_python_cli.utils.repo.get_group_dir(base_dir, group, flat=False)

Return the group directory path, or base_dir itself in flat mode.

dbx_python_cli.utils.repo.get_group_priority(config)

Get the group priority list from configuration.

Parameters:

config – Configuration dictionary

Returns:

List of group names in priority order (highest priority first)

Return type:

list

dbx_python_cli.utils.repo.get_install_dirs(config, group_name, repo_name)

Get install directories for a repository.

For repos with packages in subdirectories, returns a list of subdirectories to install. For regular repos, returns None (install from root).

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘langchain’)

• repo_name – Name of the repository (e.g., ‘langchain-mongodb’)

Returns:

List of install directories, or None if packages are at the root

Return type:

list

dbx_python_cli.utils.repo.get_install_extras(config, group_name, repo_name)

Get default extras to install for a repository.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘langchain’)

• repo_name – Name of the repository (e.g., ‘langchain-mongodb’)

Returns:

List of extras to install by default, or empty list

Return type:

list

dbx_python_cli.utils.repo.get_install_groups(config, group_name, repo_name)

Get default dependency groups to install for a repository.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘langchain’)

• repo_name – Name of the repository (e.g., ‘langchain-mongodb’)

Returns:

List of dependency groups to install by default, or empty list

Return type:

list

dbx_python_cli.utils.repo.get_preferred_branch(config, group_name, repo_name)

Get the preferred branch to switch to after cloning a repository.

When configured, dbx clone will run git switch <branch> immediately after a successful clone, so the working tree starts on the right branch without any manual step.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘django’)

• repo_name – Name of the repository (e.g., ‘django’)

Returns:

Branch name to switch to, or None if no preferred branch is configured

Return type:

str

dbx_python_cli.utils.repo.get_projects_dir(base_dir, flat=False)

Return the directory where Django projects live.

In flat mode projects live directly in base_dir. In grouped mode they live in base_dir/projects/.

dbx_python_cli.utils.repo.get_python_version(config, group_name=None)

Get the Python version to use for a group’s virtual environment.

When configured, dbx clone and dbx env init will use this Python version when creating the group’s venv.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘django’), or None for the default

Returns:

Python version string (e.g., ‘3.13’), or None to use system default

Return type:

str

dbx_python_cli.utils.repo.get_repo_dir(base_dir, group, repo_name, flat=False)

Return the repo directory path regardless of layout mode.

dbx_python_cli.utils.repo.get_repo_groups(config)

Get repository groups from config.

dbx_python_cli.utils.repo.get_test_env_vars(config, group_name, repo_name, base_dir)

Get environment variables for test runs.

Returns a dictionary of environment variables to set when running tests. Supports both group-level and repo-specific environment variables.

When no repo-specific entry is found in the repo’s own group, falls back to checking global groups (listed under repo.global_groups), so that repos cloned from a global group into another group still pick up their test environment configuration.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘pymongo’)

• repo_name – Name of the repository (e.g., ‘mongo-python-driver’)

• base_dir – Base directory path for resolving relative paths

Returns:

Dictionary of environment variable names to values

Return type:

dict

dbx_python_cli.utils.repo.get_test_runner(config, group_name, repo_name)

Get test runner configuration for a repository.

Returns the test runner command/script if configured, otherwise None (use pytest).

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘django’)

• repo_name – Name of the repository (e.g., ‘django’)

Returns:

Test runner path/command, or None for default pytest

Return type:

str

dbx_python_cli.utils.repo.get_test_runner_args(config, group_name, repo_name)

Get default arguments for a custom test runner.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘django’)

• repo_name – Name of the repository (e.g., ‘django’)

Returns:

List of default args to pass to the test runner, or empty list

Return type:

list

dbx_python_cli.utils.repo.is_flat_mode(config)

Return True if repos live directly under base_dir (flat layout).

dbx_python_cli.utils.repo.list_repos(base_dir, format_style='default', config=None)

List all repositories in a formatted way.

Parameters:

• base_dir – Path to the base directory containing group subdirectories

• format_style – Output format style (‘default’, ‘tree’, ‘grouped’, or ‘simple’)

• config – Optional config dict to compare available vs cloned repos

Returns:

Formatted list of repositories

Return type:

str

dbx_python_cli.utils.repo.should_skip_install(config, group_name, repo_name)

Check if a repository should skip automatic installation.

Parameters:

• config – Configuration dictionary

• group_name – Name of the group (e.g., ‘django-3p’)

• repo_name – Name of the repository (e.g., ‘django’)

Returns:

True if installation should be skipped, False otherwise

Return type:

bool

dbx_python_cli.utils.repo.switch_to_branch(repo_path: Path, branch_name: str, verbose: bool = False) → bool

Switch to a branch in a cloned repository.

Runs git switch <branch_name> in repo_path. Failures are reported as warnings rather than hard errors so that the caller’s workflow is not interrupted.

Parameters:

• repo_path – Path to the repository

• branch_name – Branch to switch to

• verbose – Whether to show verbose output

Returns:

True if the switch succeeded, False otherwise

dbx_python_cli.utils.venv module

Utilities for virtual environment detection and management.

dbx_python_cli.utils.venv.get_venv_info(repo_path, group_path=None, base_path=None, fallback_paths=None)

Get information about which venv will be used.

Checks in priority order (most specific to least specific): 1. Repository-level venv 2. Group-level venv 3. Fallback group venvs (e.g. django group for projects), if provided 4. Base directory venv 5. Activated venv

Parameters:

• repo_path – Path to the repository

• group_path – Path to the primary group directory (optional)

• base_path – Path to the base directory (optional)

• fallback_paths – Additional group paths to check before base_path (optional)

Returns:

(python_path, venv_type) where venv_type is “base”, “repo”, “group”, or “venv”

Return type:

tuple

Raises:

typer.Exit – If no virtual environment is found (system Python detected)

dbx_python_cli.utils.venv.get_venv_python(repo_path, group_path=None, base_path=None)

Get the Python executable from a venv.

Checks in priority order (most specific to least specific): 1. Repository-level venv: <repo_path>/.venv/bin/python 2. Group-level venv: <group_path>/.venv/bin/python (if group_path provided) 3. Base directory venv: <base_path>/.venv/bin/python (if base_path provided) 4. System Python: “python” (fallback)

Parameters:

• repo_path – Path to the repository

• group_path – Path to the group directory (optional)

• base_path – Path to the base directory (optional)

Returns:

Path to Python executable or “python” as fallback

Return type:

str