cjm-nbdev-utils

Miscellaneous utilities for nbdev projects.

Install

pip install cjm_nbdev_utils

Project Structure

nbs/
└── env_gen.ipynb # Generate an environment.yml from an nbdev-style settings.ini

Total: 1 notebook

Module Dependencies

graph LR
    env_gen[env_gen<br/>env_gen]

No cross-module dependencies detected.

CLI Reference

gen_env_from_settings Command

usage: gen_env_from_settings [-h] [--settings SETTINGS] [--name NAME]
                             [--extras EXTRAS] [--no-editable]
                             [--include-pip-reqs] [--no-include-pip-reqs]
                             [--out OUT] [--stdout]

Generate environment.yml from nbdev settings.ini

options:
  -h, --help            show this help message and exit
  --settings SETTINGS   Path to settings.ini
  --name NAME           Environment name override
  --extras EXTRAS       Editable pip extras to install, e.g. 'dev' or
                        'dev,docs'. Use '' to install no extras.
  --no-editable         Do not include editable install (-e .).
  --include-pip-reqs    Also include 'requirements' and 'dev_requirements'
                        from settings.ini in pip section.
  --no-include-pip-reqs
                        Do not include pip requirements from settings.ini
                        (default).
  --out OUT             Output file path.
  --stdout              Write YAML to stdout instead of a file.

For detailed help on any command, use gen_env_from_settings <command> --help.

Module Overview

Detailed documentation for each module in the project:

env_gen (env_gen.ipynb)

Generate an environment.yml from an nbdev-style settings.ini

Import

from cjm_nbdev_utils.env_gen import (
    DEFAULT_ENV_NAME,
    DEFAULT_CHANNELS,
    read_settings,
    get_section,
    split_list,
    normalize_python_spec,
    collect_values,
    emit_yaml,
    main
)

Functions

def read_settings(
    path: str  # Path to settings.ini file
) -> configparser.ConfigParser:  # Configured ConfigParser object
    "Read settings.ini file with percent-style interpolation."

def get_section(
    cp: configparser.ConfigParser  # ConfigParser object
)
    "Get configuration section from ConfigParser. nbdev puts keys at top-level (DEFAULT). Falls back to first section if present."

def split_list(
    val: str | None  # String value to split (can be None)
) -> List[str]:  # List of unique, non-empty strings preserving order
    "Split space- and/or comma-separated lists while respecting quotes."

def normalize_python_spec(
    min_py: str=None  # Minimum Python version string
) -> str:  # Normalized Python specification string or None
    "Normalize Python version specification for conda. Accepts ">=3.10", "3.10", "3.9.*", etc. If bare like "3.10", makes it ">=3.10"."

def collect_values(
    cfg    # Configuration section dictionary - TODO: Add type hint
) -> Tuple[str, List[str], List[str], List[str], List[str]]:  # Tuple of (env_name, channels, conda_reqs, pip_reqs, dev_pip_reqs)
    "Collect configuration values from settings."

def emit_yaml(
    name: str,    # Environment name
    channels: List[str],    # List of conda channels
    conda_deps: List[str],    # List of conda dependencies
    pip_lines: List[str],    # List of pip packages
) -> str:  # YAML formatted string
    "Generate environment.yml content. Manual YAML emitter to avoid extra dependencies."

def main()
    """
    Generate environment.yml from nbdev settings.ini.
    
    Reads: lib_name, min_python, conda_channels, conda_requirements,
           requirements, dev_requirements (all optional).
    Writes: environment.yml (or stdout).
    Adds an editable pip install (-e ".[EXTRAS]") by default.
    
    Examples:
        python gen_env_from_settings.py
        python gen_env_from_settings.py --name myproj-dev --extras dev,docs --out env.yml
        python gen_env_from_settings.py --no-editable --stdout
        python gen_env_from_settings.py --no-include-pip-reqs
    """

Variables

DEFAULT_ENV_NAME = 'nbdev-env'
DEFAULT_CHANNELS = [1 items]