pyproject2conda

https://pages.nist.gov/pyproject2conda/
Admin
A tool to convert pyproject.toml dependencies to environment.yaml and requirements.txt files for...
Tokens:21,487
Snippets:298
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Just Task Runner

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Install the 'just' task runner using 'uv tool install'. Run 'just' with no options to see available commands.

```bash
uv tool install rust-just

```

--------------------------------

### Install pyproject2conda with all extras using pip/pipx/uvx

Source: https://pages.nist.gov/pyproject2conda/installation.html

Install pyproject2conda with rich and shellingham support by using the '[all]' extra. Alternatively, install these dependencies separately.

```bash
$ pip/pipx/uvx install pyproject2conda[all]

```

--------------------------------

### Passing requirements with editable installs

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Demonstrates how to pass requirements for a package using the editable install syntax, such as `"-e ."`, with the `--req` or `-r` flag.

```bash
--req "-e ."

```

--------------------------------

### Install optional dependencies (extras)

Source: https://pages.nist.gov/pyproject2conda/index.html

Generates an environment.yaml file including specified optional dependencies (extras) from the pyproject.toml.

```bash
$ pyproject2conda yaml --pyproject tests/data/test-pyproject.toml -e test
```

--------------------------------

### Install Pre-commit Hooks

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Install pre-commit hooks to ensure code quality and consistency before committing changes. Alternatively, prek can be used.

```bash
just pre-commit install

```

--------------------------------

### Install pyproject2conda using pip/pipx/uvx

Source: https://pages.nist.gov/pyproject2conda/installation.html

Use this command to install the stable release of pyproject2conda with pip, pipx, or uvx.

```bash
$ pip/pipx/uvx install pyproject2conda

```

--------------------------------

### Install Stable Release of pyproject2conda

Source: https://pages.nist.gov/pyproject2conda/_sources/installation.md

Use this command to install the latest stable version from PyPI. This is the recommended installation method.

```bash
pip install pyproject2conda
```

--------------------------------

### Install pyproject2conda using pip or conda

Source: https://pages.nist.gov/pyproject2conda/index.html

Install pyproject2conda using either pip, pipx, or uvx. For enhanced functionality including rich and shellingham support, install with the '[all]' extra.

```bash
$ pip/pipx/uvx install pyproject2conda

```

```bash
$ conda/condax install -c conda-forge pyproject2conda

```

```bash
$ pip/pipx/uvx install pyproject2conda[all]

```

--------------------------------

### Install self-referenced optional dependencies

Source: https://pages.nist.gov/pyproject2conda/index.html

Handles and installs self-referenced optional dependencies when generating the environment.yaml.

```bash
$ pyproject2conda yaml --pyproject tests/data/test-pyproject.toml -e dev
```

--------------------------------

### pyproject2conda CLI Usage Examples

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Demonstrates various ways to invoke the pyproject2conda command-line tool, including direct calls, using the 'p2c' alias, and executing via 'python -m pyproject2conda'.

```bash
pyproject2conda
p2c
python -m pyproject2conda
```

--------------------------------

### Example pyproject.toml structure

Source: https://pages.nist.gov/pyproject2conda/index.html

This TOML file defines project metadata, dependencies, and optional dependencies. It also includes a custom section `[tool.pyproject2conda.dependencies]` for specific package configurations.

```toml
[project]
name = "hello"
requires-python = ">=3.8,<3.11"
dependencies = [
"athing",                          #
"bthing",
"cthing; python_version < '3.10'",
]

[project.optional-dependencies]
test = [
"pandas", #
"pytest",
]
dev-extras = [ "matplotlib" ]
dev = [ "hello[test]", "hello[dev-extras]" ]
dist-pypi = [
# this is intended to be parsed with --skip-package option
"setuptools",
"build",
]

[tool.pyproject2conda.dependencies]
athing = { pip = true }
bthing = { skip = true, packages = "bthing-conda" }
cthing = { channel = "conda-forge" }
pytest = { channel = "conda-forge" }
matplotlib = { skip = true, packages = [
"additional-thing; python_version < '3.9'",
"conda-matplotlib",
] }
build = { channel = "pip" }

```

--------------------------------

### Install pyproject2conda using conda/condax

Source: https://pages.nist.gov/pyproject2conda/installation.html

Install the stable release of pyproject2conda from the conda-forge channel using conda or condax. This is the preferred method for the most recent stable release.

```bash
$ conda/condax install -c conda-forge pyproject2conda

```

--------------------------------

### Basic Conda YAML Output

Source: https://pages.nist.gov/pyproject2conda/index.html

This example shows the basic output of converting a pyproject.toml to a conda YAML file, including dependencies and pip packages.

```yaml
dependencies:
  - setuptools
  - pip
  - pip:
      - build
```

--------------------------------

### Generate Conda and Pip Requirements

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Use this command to create `conda.txt` and `pip.txt` files from your `pyproject.toml`. These files can then be used to install dependencies using conda and pip, respectively.

```bash
pyproject2conda conda-requirements [OPTIONS] [PATH_CONDA] [PATH_PIP]
```

--------------------------------

### Specify optional dependencies in dependency groups

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Example of how to specify optional dependencies within dependency groups in pyproject.toml. This allows for more granular control over environment configurations.

```toml
[project]
name = "mypackage"
...

optional-dependencies.opt = [ "opt1" ]

[dependency-groups]
dev = [
  "pytest",
  "mypackage[opt]"
]


```

--------------------------------

### Add Additional Pip Requirements

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Specify additional pip requirements, such as editable installs, using the --pip-dep or --req option.

```bash
pyproject2conda json -r '-e .'
```

```bash
pyproject2conda json -r <pip_deps>
```

--------------------------------

### Equivalent Configuration for Default Environments

Source: https://pages.nist.gov/pyproject2conda/index.html

This TOML snippet demonstrates an alternative way to configure the 'test' environment, specifying its extras.

```toml
is equivalent to

[tool.pyproject2conda.envs.test]
extras = ["tests"]


```

--------------------------------

### project()

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Create multiple environment files from `pyproject.toml` specification.

```APIDOC
## project()

### Description
Create multiple environment files from `pyproject.toml` specification.

### Parameters
#### Path Parameters
- **pyproject_filename** (str) - Required - 

#### Query Parameters
- **envs** (list[str] | None) - Optional - 

### Example
```bash
pyproject2conda project my_pyproject.toml --envs "["dev", "test"]"
```
```

--------------------------------

### Python version expansion options

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Demonstrates the use of the `--python` flag with various options to specify Python versions. Useful for setting Python compatibility in environment configurations.

```bash
--python default
--python all
--python lowest
--python highest

```

--------------------------------

### create_list()

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

List available extras.

```APIDOC
## create_list()

### Description
List available extras.

### Parameters
#### Path Parameters
- **pyproject_filename** (str) - Required - 

#### Query Parameters
- **verbose** (bool) - Optional - 

### Example
```bash
pyproject2conda create-list my_pyproject.toml --verbose
```
```

--------------------------------

### Include Optional Dependencies (Extras)

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Include dependencies from specific 'extras' defined in your `pyproject.toml`'s `project.optional-dependencies` table. Specify multiple extras by repeating the option.

```bash
-e, --extra <extras>
```

--------------------------------

### requirements()

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Create requirements.txt for pip dependencies.

```APIDOC
## requirements()

### Description
Create requirements.txt for pip dependencies.

### Parameters
#### Path Parameters
- **pyproject_filename** (str) - Required - 

#### Query Parameters
- **extras** (list[str] | None) - Optional - 

### Example
```bash
pyproject2conda requirements my_pyproject.toml --extras "["dev", "test"]"
```
```

--------------------------------

### pyproject2conda.cli.conda_requirements

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Generates requirement files for conda and pip from a pyproject.toml file. These files can be used for installing dependencies with conda and pip.

```APIDOC
## pyproject2conda.cli.conda_requirements

### Description
Create requirement files for conda and pip.
These can be install with, for example,
conda install –file {path_conda} pip install -r {path_pip}

### Parameters
#### Path Parameters
- **_pyproject_filename** (pathlib.Path) - Required - The path to the pyproject.toml file.
- **path_conda** (pathlib.Path | None) - Optional - Path to the conda requirements file.
- **path_pip** (pathlib.Path | None) - Optional - Path to the pip requirements file.

#### Query Parameters
- **extras** (list[str] | None) - Optional - Specifies extras to include.
- **groups** (list[str] | None) - Optional - Specifies dependency groups to include.
- **extras_or_groups** (list[str] | None) - Optional - Specifies extras or groups to include.
- **python_include** (str | None) - Optional - Specifies Python versions to include.
- **python_version** (str | None) - Optional - Specifies the Python version.
- **python** (str | None) - Optional - Specifies the Python version.
- **channels** (list[str] | None) - Optional - Conda channels to use.
- **skip_package** (bool) - Optional - If true, skips package installation (default: False).
- **prefix** (pathlib.Path | None) - Optional - Specifies a prefix for the environment.
- **prepend_channel** (bool) - Optional - If true, prepends channels to the environment (default: False).
- **header** (bool | None) - Optional - Whether to include a header in the output files.
- **custom_command** (str | None) - Optional - A custom command to execute.
- **conda_deps** (list[str] | None) - Optional - Additional conda dependencies.
- **pip_deps** (list[str] | None) - Optional - Additional pip dependencies.
- **verbose** (int | None) - Optional - Verbosity level for output.
```

--------------------------------

### Clean ipykernel Kernels

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Remove installed ipykernel kernels that point to removed environments using the provided Python script.

```bash
python tools/clean_kernelspec.py

```

--------------------------------

### yaml()

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Create yaml file from dependencies and optional-dependencies.

```APIDOC
## yaml()

### Description
Create yaml file from dependencies and optional-dependencies.

### Parameters
#### Path Parameters
- **pyproject_filename** (str) - Required - 

#### Query Parameters
- **extras** (list[str] | None) - Optional - 

### Example
```bash
pyproject2conda yaml my_pyproject.toml --extras "["dev", "test"]"
```
```

--------------------------------

### Clone Repository Locally

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Clone your forked repository locally to begin development. Use the --recursive-submodules flag if the repository includes submodules.

```bash
git clone git@github.com:your_name_here/pyproject2conda.git

```

```bash
git clone --recursive-submodules git@github.com:your_name_here/pyproject2conda.git

```

--------------------------------

### Run Pre-commit Checks

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Before committing, run pre-commit checks to verify your changes. Use --all-files to check all files in the repository.

```bash
just pre-commit run [--all-files]

```

--------------------------------

### Run Tests

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Execute the project's tests to ensure code integrity. Use 'just test-all' to test against multiple Python versions.

```bash
just test

```

```bash
just test-all

```

--------------------------------

### Filter Dependencies by Python Version

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Limit the included packages based on a specified Python version. For example, a dependency with `python_version < '3.9'` will be excluded if you set `--python-version 3.10` but included if you set `--python-version 3.8`.

```bash
--python-version <python_version>
```

--------------------------------

### Configuration overrides

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Details the ability to use `overrides` for all options and how they take precedence over environment options. This provides a flexible way to manage configuration settings.

```toml
tool.pyproject2conda.overrides.python = "3.10"

```

--------------------------------

### Configuring Default Environments in pyproject.toml

Source: https://pages.nist.gov/pyproject2conda/index.html

This TOML snippet shows how to set default environments, such as 'test', which can be equivalent to specifying extras or groups.

```toml
[tool.pyproject2conda]
# ...
default-envs = ["test"]


```

--------------------------------

### Equivalent pyproject2conda Commands

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Demonstrates equivalent ways to call pyproject2conda subcommands using different aliases or module execution.

```bash
$ pyproject2conda yaml ...
$ p2c y ...
$ python -m pyproject2conda yaml ...
```

--------------------------------

### Include Optional Dependencies (Extras or Groups)

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Include dependencies from either 'extras' or 'groups' defined in your `pyproject.toml`. The tool checks extras first, then groups. The first matching instance is used.

```bash
--extra-or-group <extras_or_groups>
```

--------------------------------

### List Available Extras

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Use this command to list available extras from your pyproject.toml file. You can specify a different pyproject.toml file using the --pyproject option.

```bash
pyproject2conda list [OPTIONS]
```

--------------------------------

### main()

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Extract conda `environment.yaml` and pip `requirement.txt` files from `pyproject.toml`. All subcommands can be called with the shortest possible match. You can also call with `pyproject2conda`, `p2c`, or `python -m pyproject2conda`.

```APIDOC
## main()

### Description
Extract conda `environment.yaml` and pip `requirement.txt` files from `pyproject.toml`.

### Parameters
#### Query Parameters
- **version** (bool) - Optional - 
- **columns** (int | None) - Optional - 

### Example
```bash
pyproject2conda main --version
pyproject2conda main --columns 100
```
```

--------------------------------

### List Nox Sessions

Source: https://pages.nist.gov/pyproject2conda/contributing.html

View all available nox sessions for automating tasks like testing and documentation generation.

```bash
nox --list

```

--------------------------------

### Generate basic environment.yaml

Source: https://pages.nist.gov/pyproject2conda/index.html

Generates a basic environment.yaml file from a pyproject.toml. Dependencies are inferred from project.dependencies and project.optional-dependencies.

```bash
$ pyproject2conda yaml --pyproject tests/data/test-pyproject.toml
```

--------------------------------

### Config file option names (dashes vs. underscores)

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Explains that command-line options now accept either dashes or underscores in the `pyproject.toml` configuration file. The parser prioritizes dashed options.

```toml
tool.pyproject2conda.template-python = "3.9"
# or
tool.pyproject2conda.template_python = "3.9"

```

--------------------------------

### Specifying Multiple Styles for an Environment

Source: https://pages.nist.gov/pyproject2conda/index.html

This TOML snippet shows how to configure an environment, 'test-extras', to generate both a conda YAML file and a requirements file.

```toml
# ...
[tool.pyproject2conda.envs."test-extras"]
extras = [ "test" ]
style = [ "yaml", "requirements" ]

# ...


```

--------------------------------

### Add extra options for requirements and YAML extensions

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Introduces new flags `--reqs-ext` and `--yaml-ext` for specifying file extensions for requirements and environment.yaml files.

```bash
--reqs-ext
--yaml-ext

```

--------------------------------

### Commit and Push Changes

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Stage, commit, and push your changes to your forked repository. Pre-commit hooks enforce conventional commit messages.

```bash
git add .
git commit -m "feat: detailed description of your new feature."
git push origin name-of-your-bugfix-or-feature

```

--------------------------------

### Initialize RequirementsConfig in Python

Source: https://pages.nist.gov/pyproject2conda/index.html

Use the `RequirementsConfig` class from `pyproject2conda.requirements` to load and process `pyproject.toml` within a Python script.

```python
from pyproject2conda.requirements import RequirementsConfig
p = RequirementsConfig.from_path("./tests/data/test-pyproject.toml")
```

--------------------------------

### Include Optional Dependencies (Groups)

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Include dependencies from specific 'groups' defined in your `pyproject.toml`'s `dependency-groups` table. Specify multiple groups by repeating the option.

```bash
-g, --group <groups>
```

--------------------------------

### Use command alias and shortened subcommands

Source: https://pages.nist.gov/pyproject2conda/index.html

Demonstrates using the 'p2c' alias and shortened subcommands for pyproject2conda.

```bash
$ p2c y --pyproject tests/data/test-pyproject.toml --python 3.10
```

--------------------------------

### Specify and include Python version

Source: https://pages.nist.gov/pyproject2conda/index.html

Combines specifying a Python version and including it in the environment.yaml for common use cases.

```bash
$ pyproject2conda yaml --pyproject tests/data/test-pyproject.toml \
    --python-version 3.10 --python-include python~=3.10
```

--------------------------------

### PEP 735 support with groups

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Illustrates the addition of PEP 735 support, including the `--group` CLI option and the `groups` key in `pyproject.toml`. The `--extra-or-group` option is also shown.

```toml
tool.pyproject2conda.envs.dev.groups = ["group1", "group2"]

```

--------------------------------

### pyproject.toml Configuration for Environments

Source: https://pages.nist.gov/pyproject2conda/index.html

This TOML snippet demonstrates how to configure multiple conda environments (test, dev, dist-pypi) and specify overrides for specific environments like 'test-extras'.

```toml
# ...
[tool.pyproject2conda]
channels = [ 'conda-forge' ]
# these are the same as the default values of `p2c project`
template-python = "py{py}-{env}"
template = "{env}"
style = "yaml"
# options
python = [ "3.10" ]
# These environments will be created with the package, package dependencies, and
# dependencies from groups or extras with environment name so the below is the
# same as
#
# [tool.pyproject2conda.envs.test]
# extras-or-groups = "test"
#
default-envs = [ "test", "dev", "dist-pypi" ]

[tool.pyproject2conda.envs.base]
style = [ "requirements" ]

# This will have no extras or groups
#
# A value of `extras = true` will would be equivalent to
# passing extras-or-groups = <env-name>
[tool.pyproject2conda.envs."test-extras"]
extras = [ "test" ]
style = [ "yaml", "requirements" ]

[[tool.pyproject2conda.overrides]]
envs = [ 'test-extras', "dist-pypi" ]
skip-package = true

[[tool.pyproject2conda.overrides]]
envs = [ "test", "test-extras" ]
python = [ "3.10", "3.11" ]
```

--------------------------------

### Overriding Options for Multiple Environments

Source: https://pages.nist.gov/pyproject2conda/index.html

This TOML snippet illustrates how to use the `[[tools.pyproject2conda.overrides]]` section to apply specific options, like Python versions, to multiple environments.

```toml
# ...
[[tool.pyproject2conda.overrides]]
envs = [ "test", "test-extras" ]
python = [ "3.10", "3.11" ]


```

--------------------------------

### Specify Input Pyproject File

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

When listing extras, you can specify a different input pyproject.toml file using the --pyproject option.

```bash
pyproject2conda list --pyproject my_pyproject.toml
```

--------------------------------

### pyproject2conda list subcommand

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Lists available extras. This subcommand can be used to see what optional dependencies are available for your project.

```APIDOC
### list#
List available extras.
Usage
```
pyproject2conda list [OPTIONS]
```

Options 

--pyproject <pyproject_filename>#
    
input pyproject.toml file 

Default:
    
`'pyproject.toml'` 

-v, --verbose#
    
Pass `-v/--verbose` for verbose output. Pass multiple times to set verbosity level.
```

--------------------------------

### Python version placeholders in environment name

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Shows how to use Python version placeholders like `{py_version}`, `{py}`, and `{env}` in the `--name` option for environment.yaml files. This allows dynamic naming based on Python version and environment.

```bash
--name "myenv-{py_version}"
--name "myenv-{py}"
--name "myenv-{env}"

```

--------------------------------

### pyproject2conda.cli.project

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Creates multiple environment files from a pyproject.toml specification. Configuration options in pyproject.toml generally mirror the command-line options, with pluralization for multi-value options and boolean toggles for flags.

```APIDOC
## pyproject2conda.cli.project

### Description
Create multiple environment files from `pyproject.toml` specification.

### Parameters
#### Path Parameters
- **_pyproject_filename** (pathlib.Path) - Required - The path to the pyproject.toml file.

#### Query Parameters
- **envs** (list[str] | None) - Optional - Specifies environments to include.
- **template** (str | None) - Optional - A template string for environment files.
- **template_python** (str | None) - Optional - A template string for Python-specific environment files.
- **pip_deps** (list[str] | None) - Optional - Additional pip dependencies.
- **conda_deps** (list[str] | None) - Optional - Additional conda dependencies.
- **reqs_ext** (str | None) - Optional - Extension for requirement files (default: '.txt').
- **yaml_ext** (str | None) - Optional - Extension for YAML files (default: '.yaml').
- **header** (bool | None) - Optional - Whether to include a header in the output files.
- **custom_command** (str | None) - Optional - A custom command to execute.
- **overwrite** (pyproject2conda._schema.Overwrite) - Optional - Specifies how to handle overwriting existing files (default: Overwrite.force).
- **verbose** (int | None) - Optional - Verbosity level for output.
- **dry** (bool) - Optional - If true, only show what would be done (default: False).
- **pip_only** (bool) - Optional - If true, only generate pip requirements (default: False).
- **allow_empty** (bool | None) - Optional - If true, allows empty environment files.
```

--------------------------------

### Specify Output File

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Direct the output to a specific file using the --output option.

```bash
pyproject2conda json -o <output>
```

--------------------------------

### Set Python Version and Include

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

A shorthand option to set both the Python version for filtering and the include string. This overrides --python-version and --python-include.

```bash
pyproject2conda json --python "default"
```

```bash
pyproject2conda json --python "lowest"
```

```bash
pyproject2conda json --python "highest"
```

```bash
pyproject2conda json --python "3.8"
```

```bash
pyproject2conda json --python "all"
```

--------------------------------

### List Available Extras

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Lists the available extras defined in the pyproject.toml file. This command can be invoked using `pyproject2conda yaml ...`, `p2c y ...`, or `python -m pyproject2conda yaml ...`.

```APIDOC
## list

### Description
List available extras.

### Method
`pyproject2conda.cli.create_list`

### Parameters
#### Path Parameters
- **_pyproject_filename** (pathlib.Path) - Required - The path to the pyproject.toml file.

#### Query Parameters
- **verbose** (int | None) - Optional - Enable verbose output.
```

--------------------------------

### Update/Sync Requirements

Source: https://pages.nist.gov/pyproject2conda/contributing.html

Generate or update environment.yaml and requirement.txt files from pyproject.toml using 'just lock/sync'. Pass -upgrade/-U to upgrade requirements.

```bash
just lock/sync

```

--------------------------------

### Include Extra Dependencies

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Specify dependencies from 'project.optional-dependencies' in pyproject.toml using the --extra option. Multiple extras can be included by specifying the option multiple times.

```bash
pyproject2conda json --extra <extras>
```

--------------------------------

### Specify Input Pyproject File

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Use the `--pyproject` option to specify a different `pyproject.toml` file than the default.

```bash
--pyproject <pyproject_filename>
```

--------------------------------

### conda_requirements()

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Create requirement files for conda and pip.

```APIDOC
## conda_requirements()

### Description
Create requirement files for conda and pip.

### Parameters
#### Path Parameters
- **pyproject_filename** (str) - Required - 

### Example
```bash
pyproject2conda conda-requirements my_pyproject.toml
```
```

--------------------------------

### Generate environment.yaml with Python version inference

Source: https://pages.nist.gov/pyproject2conda/index.html

Includes the Python version specification in the environment.yaml by inferring it from the pyproject.toml.

```bash
$ pyproject2conda yaml --pyproject tests/data/test-pyproject.toml \
    --python-include infer
```

--------------------------------

### Handle Existing Output Files

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Control the behavior when the output file already exists using the --overwrite option. Options include 'check', 'skip', and 'force'.

```bash
pyproject2conda json -w check
```

```bash
pyproject2conda json -w skip
```

```bash
pyproject2conda json -w force
```

--------------------------------

### pyproject2conda CLI

Source: https://pages.nist.gov/pyproject2conda/_sources/reference/index.md

Documentation for the command-line interface of pyproject2conda.

```APIDOC
## pyproject2conda CLI

### Description

This section details the command-line interface for the pyproject2conda tool.

### Usage

```bash
pyproject2conda [OPTIONS] COMMAND [ARGS]...
```

### Commands

- `cli`: Main command group for pyproject2conda operations.
```

--------------------------------

### General pyproject2conda Usage

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Shows the basic structure for invoking the pyproject2conda command with options and arguments.

```bash
pyproject2conda [OPTIONS] COMMAND [ARGS]...
```

--------------------------------

### Configure pyproject2conda in pyproject.toml

Source: https://pages.nist.gov/pyproject2conda/index.html

Configure `pyproject2conda` settings, such as conda channels, environment templates, and default environments, within the `[tool.pyproject2conda]` section of `pyproject.toml`.

```toml
# ...
[tool.pyproject2conda]
channels = [ 'conda-forge' ]
# these are the same as the default values of `p2c project`
template-python = "py{py}-{env}"
template = "{env}"
style = "yaml"
# options
python = [ "3.10" ]
# These environments will be created with the package, package dependencies, and
# dependencies from groups or extras with environment name so the below is the
# same as
#
# [tool.pyproject2conda.envs.test]
# extras-or-groups = "test"
#
default-envs = [ "test", "dev", "dist-pypi" ]

[tool.pyproject2conda.envs.base]
style = [ "requirements" ]

# This will have no extras or groups
#
# A value of `extras = true` will would be equivalent to
# passing extras-or-groups = <env-name>
[tool.pyproject2conda.envs."test-extras"]
extras = [ "test" ]
style = [ "yaml", "requirements" ]

[[tool.pyproject2conda.overrides]]
envs = [ 'test-extras', "dist-pypi" ]
skip-package = true

[[tool.pyproject2conda.overrides]]
envs = [ "test", "test-extras" ]
python = [ "3.10", "3.11" ]


```

--------------------------------

### Build Conda YAML with Dependency Groups

Source: https://pages.nist.gov/pyproject2conda/index.html

Generate a conda environment YAML file by specifying dependency groups using the `-g/--group` flag with `pyproject2conda`.

```bash
$ pyproject2conda yaml --pyproject tests/data/test-pyproject-groups.toml \
    --group dev
channels:
  - conda-forge
dependencies:
  - additional-thing
  - bthing-conda
  - conda-forge::cthing
  - conda-forge::pytest
  - conda-matplotlib
  - pandas
  - pip
  - pip:
      - athing

```

--------------------------------

### Skip Package Dependencies

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Exclude the main package's dependencies from the output using --skip-package. This is useful for environments that should not include base dependencies.

```bash
pyproject2conda json --skip-package
```

--------------------------------

### Set Output Prefix

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Specify a prefix for the output file names. `conda.txt` will be created as `prefix + conda.txt` and `pip.txt` as `prefix + pip.txt`.

```bash
--prefix <prefix>
```

--------------------------------

### Include Extras or Groups

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Include dependencies from either 'extras' or 'groups' defined in pyproject.toml using the --extra-or-group option. The tool checks for extras first, then groups.

```bash
pyproject2conda json --extra-or-group <extras_or_groups>
```

--------------------------------

### Reading default Python version

Source: https://pages.nist.gov/pyproject2conda/changelog.html

Explains the updated logic for reading the default Python version, which now prioritizes `.python-version-default` over `.python-version`. This allows for a distinct default version separate from pinned specifiers.

```bash
Read default version from first found file, in order, .python-version-default and .python-version.

```

--------------------------------

### Shorthand for specifying and including Python version

Source: https://pages.nist.gov/pyproject2conda/index.html

Uses the shorthand -p/--python option to specify and include the Python version in the environment.yaml.

```bash
$ pyproject2conda yaml --pyproject tests/data/test-pyproject.toml --python \
    3.10
```

--------------------------------

### Generate Basic Conda YAML from Python

Source: https://pages.nist.gov/pyproject2conda/index.html

Generate a basic conda environment YAML string from a `RequirementsConfig` object, inferring Python version requirements.

```python
print(p.to_conda_yaml(python_include="infer").strip())
dependencies:
  - python<3.11,>=3.8
  - bthing-conda
  - conda-forge::cthing
  - pip
  - pip:
      - athing

```

--------------------------------

### Specify Python Include Version

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Control the Python version string in the output using --python-include. Use 'infer' to automatically detect the version from pyproject.toml. PEP 440 should be followed.

```bash
pyproject2conda json --python-include "python~=3.8"
```

```bash
pyproject2conda json --python-include infer
```

--------------------------------

### Include Dependency Groups

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Include dependencies defined in the 'dependency-groups' table of pyproject.toml using the --group option. Multiple groups can be specified.

```bash
pyproject2conda json --group <groups>
```

--------------------------------

### Generate Conda YAML with Extras and Channels from Python

Source: https://pages.nist.gov/pyproject2conda/index.html

Generate a conda environment YAML string, specifying extras and conda channels to include in the environment.

```python
print(p.to_conda_yaml(extras="test", channels="conda-forge").strip())
channels:
  - conda-forge
dependencies:
  - bthing-conda
  - conda-forge::cthing
  - conda-forge::pytest
  - pandas
  - pip
  - pip:
      - athing

```

--------------------------------

### Generate Conda YAML File

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Creates a conda environment YAML file from the dependencies and optional-dependencies specified in the pyproject.toml file. This command can be invoked using `pyproject2conda yaml ...`, `p2c y ...`, or `python -m pyproject2conda yaml ...`.

```APIDOC
## yaml

### Description
Create yaml file from dependencies and optional-dependencies.

### Method
`pyproject2conda.cli.yaml`

### Parameters
#### Path Parameters
- **_pyproject_filename** (pathlib.Path) - Required - The path to the pyproject.toml file.

#### Query Parameters
- **extras** (list[str] | None) - Optional - Specify extras to include.
- **groups** (list[str] | None) - Optional - Specify dependency groups to include.
- **extras_or_groups** (list[str] | None) - Optional - Specify extras or groups to include.
- **channels** (list[str] | None) - Optional - Specify conda channels to use.
- **output** (pathlib.Path | None) - Optional - Path to the output YAML file.
- **name** (str | None) - Optional - Name of the conda environment.
- **python_include** (str | None) - Optional - Python version to include in the environment.
- **python_version** (str | None) - Optional - Python version to use for dependency resolution.
- **python** (str | None) - Optional - Alias for `python_version`.
- **skip_package** (bool) - Optional - Skip adding the main package to the environment. Defaults to False.
- **pip_only** (bool) - Optional - Only include pip dependencies. Defaults to False.
- **header** (bool | None) - Optional - Include a header in the output file.
- **custom_command** (str | None) - Optional - A custom command to run after generating the YAML file.
- **overwrite** (Overwrite) - Optional - Strategy for overwriting existing files. Defaults to Overwrite.force.
- **verbose** (int | None) - Optional - Enable verbose output.
- **conda_deps** (list[str] | None) - Optional - Explicitly list conda dependencies.
- **pip_deps** (list[str] | None) - Optional - Explicitly list pip dependencies.
- **allow_empty** (bool) - Optional - Allow generating an empty environment file. Defaults to False.
```

--------------------------------

### pyproject2conda Global Options

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Global options that can be used with the pyproject2conda CLI.

```APIDOC
## Options 

-v, --version#
     
Default:
    
`False` 

--columns <columns>#
    
Column width in terminal. Set `COLUMNS` environment variable to this value 

--install-completion#
    
Install completion for the current shell. 

--show-completion#
    
Show completion for the current shell, to copy it or customize the installation.
Environment variables 

P2C_COLUMNS
    
> Provide a default for `--columns`
```

--------------------------------

### Update Submodules After Clone

Source: https://pages.nist.gov/pyproject2conda/contributing.html

If you did not clone with the --recursive-submodules flag, initialize and update submodules after cloning.

```bash
cd pyproject2conda
git submodule update --init --recursive

```

--------------------------------

### Generate Requirements File

Source: https://pages.nist.gov/pyproject2conda/reference/generated/pyproject2conda.cli.html

Creates a requirements.txt file for pip dependencies. All requirements are normalized using `packaging.requirements.Requirement`. This command can be invoked using `pyproject2conda requirements ...`, `p2c req ...`, or `python -m pyproject2conda requirements ...`.

```APIDOC
## requirements

### Description
Create requirements.txt for pip dependencies. Note that all requirements are normalized using `packaging.requirements.Requirement`

### Method
`pyproject2conda.cli.requirements`

### Parameters
#### Path Parameters
- **_pyproject_filename** (pathlib.Path) - Required - The path to the pyproject.toml file.

#### Query Parameters
- **extras** (list[str] | None) - Optional - Specify extras to include.
- **groups** (list[str] | None) - Optional - Specify dependency groups to include.
- **extras_or_groups** (list[str] | None) - Optional - Specify extras or groups to include.
- **output** (pathlib.Path | None) - Optional - Path to the output requirements file.
- **skip_package** (bool) - Optional - Skip adding the main package to the requirements file. Defaults to False.
- **header** (bool | None) - Optional - Include a header in the output file.
- **custom_command** (str | None) - Optional - A custom command to run after generating the requirements file.
- **overwrite** (Overwrite) - Optional - Strategy for overwriting existing files. Defaults to Overwrite.force.
- **verbose** (int | None) - Optional - Enable verbose output.
- **pip_deps** (list[str] | None) - Optional - Explicitly list pip dependencies.
- **allow_empty** (bool) - Optional - Allow generating an empty requirements file. Defaults to False.
```

--------------------------------

### Add Additional Conda Dependencies

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Specify extra conda dependencies to be included in the generated `conda.txt` file.

```bash
-d, --conda-dep, --dep <conda_deps>
```

--------------------------------

### Dry Run Output of `p2c project`

Source: https://pages.nist.gov/pyproject2conda/index.html

This output shows the files that would be generated by `p2c project --dry`, including requirements files and conda YAML files for different Python versions and environments.

```text
# --------------------
# Creating requirements base.txt
athing
bthing
cthing; python_version < "3.10"
# --------------------
# Creating yaml py310-test-extras.yaml
channels:
  - conda-forge
dependencies:
  - python=3.10
  - conda-forge::pytest
  - pandas
# --------------------
# Creating yaml py311-test-extras.yaml
channels:
  - conda-forge
dependencies:
  - python=3.11
  - conda-forge::pytest
  - pandas
# --------------------
# Creating requirements test-extras.txt
pandas
pytest
# --------------------
# Creating yaml py310-test.yaml
channels:
  - conda-forge
dependencies:
  - python=3.10
  - bthing-conda
  - conda-forge::pytest
  - pandas
  - pip
  - pip:
      - athing
# --------------------
# Creating yaml py311-test.yaml
channels:
  - conda-forge
dependencies:
  - python=3.11
  - bthing-conda
  - conda-forge::pytest

 ...
```

--------------------------------

### Add Additional Pip Requirements

Source: https://pages.nist.gov/pyproject2conda/reference/cli.html

Specify extra pip requirements to be included in the generated `pip.txt` file. Use `'-e .'` to include an editable version of the current package.

```bash
-r, --pip-dep, --req <pip_deps>
```
Tokens:
Raw