# cjm-nbdev-utils


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
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

``` mermaid
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

``` python
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

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

``` python
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."
```

``` python
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."
```

``` python
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"."
```

``` python
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."
```

``` python
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."
```

``` python
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

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