Metadata-Version: 2.4
Name: cjm-nbdev-utils
Version: 0.0.3
Summary: Miscellaneous utilities for nbdev projects.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-nbdev-utils
Project-URL: Documentation, https://cj-mills.github.io/cjm-nbdev-utils
Keywords: nbdev,jupyter,notebook,python
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: cjm_nbdev_docments>=0.0.11
Requires-Dist: cjm_nbdev_overview>=0.0.18
Dynamic: license-file

# 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]
```
