| Name | milieux JSON |
| Version |
0.2.4
JSON |
| download |
| home_page | None |
| Summary | Tool to assist in developing, building, and installing Python packages. |
| upload_time | 2025-07-12 18:47:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
virtualenv
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Milieux
[](https://pypi.org/project/milieux)
[](https://raw.githubusercontent.com/jeremander/milieux/main/LICENSE)
[](https://github.com/pre-commit/pre-commit)
A general-purpose tool to assist in developing, building, and installing Python packages.
⚠️ `milieux` is currently in its very early stages and should *not* be considered stable.
## Introduction
`milieux` is a tool used for managing multiple [virtual environments](https://realpython.com/python-virtual-environments-a-primer/#why-do-you-need-virtual-environments) and *distributions*.
We define a *distribution* (or "distro") to be a collection of Python packages you often want bundled together. For example, you might want to bundle `numpy`, `scipy`, and `pandas` together into a distribution named `scientific`, which you can then install into one more more virtual environments. To do this, you can run:
```shell
milieux distro new scientific -p numpy scipy pandas
```
Then to create a new environment `my_env` and install all dependencies from this distribution:
```shell
milieux env new my_env
milieux env install -d scientific
```
## Installation
```shell
pip install milieux
```
### Dependencies
- 🦀 [uv](https://github.com/astral-sh/uv), an ultra-fast package resolver and installer written in Rust.
- 🐍 [hatch](https://github.com/pypa/hatch), for building/publishing packages.
- 🤵🏻♂️ [fancy_dataclass](https://fancy-dataclass.readthedocs.io/en/latest/), for configurations and argument parsing.
- 📄 [mkdocs](https://www.mkdocs.org), for documentation generation.
- 💰 [rich](https://rich.readthedocs.io/en/stable/index.html), for text and table styling.
## Usage
View help menu:
```shell
milieux -h
```
View subcommand help menu:
```text
milieux <SUBCOMMAND> -h
```
For brevity, you may want to alias the command as follows:
```shell
alias mlx="milieux"
```
Then you can type `mlx` in place of the full (tricky-to-spell) name.
## Commands
Here is a quick tour of the commands available in `milieux`.
### `distro`: Manage distributions
`milieux distro` has a collection of subcommands for creating, viewing, and modifying distributions (distros), which are collections of Python packages.
A distro is nothing more than a *requirements file*, a plaintext file containing a list of Python packages. See the [specification](https://pip.pypa.io/en/stable/reference/requirements-file-format/) for more details about how to specify package URLs, versions, etc.
| Subcommand | Description |
| ----------- | ----------- |
| `list` | List all distros |
| `lock` | Lock dependencies |
| `new` | Create new distro |
| `remove` | Remove a distro |
| `show` | Show contents of a distro |
#### Locking dependencies
`milieux distro lock` can be used to "lock" or "pin" the packages listed in a distro (requirements) file. This calls the dependency resolver to figure out the latest versions of all the packages that are mutually compatible. It then saves them out to a new requirements file.
Locking dependencies can ensure reproducibility of environments (someone else can set up the exact same environment, regardless of what the latest package versions happen to be). The downside is that the locked dependencies may become out of date.
**Example**: from the earlier `scientific` distro example, lock dependencies to the current versions, and save them to a new distro marked with the current date.
```text
$ milieux distro lock scientific --new scientific.20240609
Locking dependencies for 'scientific' distro
...
Creating distro 'scientific.20240609'
$ milieux distro show scientific.20240609
...
numpy==1.26.4
pandas==2.2.2
python-dateutil==2.9.0.post0
pytz==2024.1
scipy==1.13.1
six==1.16.0
tzdata==2024.1
```
### `env`: Manage environments
`milieux env` has a collection of subcommands for creating, viewing, and modifying virtual environments.
| Subcommand | Description |
| ----------- | ----------- |
| `activate` | Activate an environment |
| `freeze` | List installed packages |
| `install` | Install packages |
| `list` | List all environments |
| `new` | Create new environment |
| `remove` | Remove an environment |
| `show` | Show environment info |
| `sync` | Sync dependencies |
| `template` | Render a [jinja](https://jinja.palletsprojects.com/) template, filling in variables from an environment |
| `uninstall` | Uninstall packages |
#### Activate an environment
`milieux env activate` provides an easy way to activate a virtual environment. Unfortunately it is awkward to source an activation script directly from Python, so this command actually just prints out instructions for how to activate the environment.
However, you can also activate the environment directly by calling the command within backticks (which executes its output). For example:
```shell
`milieux env activate my_env`
```
This will source the activation script associated with the `my_env` virtual environment. To deactivate the environment, run `deactivate`.
#### Install packages
`milieux env install` lets you install packages into an environment. You can list specific packages with `-p`, requirements files with `-r`, or distro names with `-d`.
**Example**: install packages from the `scientific` distro, plus `scikit-learn` and PyTorch.
```shell
milieux env install my_env -d scientific -p scikit-learn torch
```
If you are already in an activated environment, you may omit the name of the environment, and it will assume the active one:
```shell
milieux env install -p pandas
```
#### Sync packages
`milieux env sync` is similar to `install`, but instead of installing new packages, it will *sync* them to the environment, making sure these are the *only* packages in the environment. This is ideal for controlling exactly what version of each specific package you want (see: [locking dependencies](#locking-dependencies)).
<!--
#### Render template file for an environment
TODO: include a description of `milieux env template` (this may be TMI).
-->
### `scaffold`: Create project scaffold
`milieux scaffold` creates a new Python project from a default or custom scaffold.
```shell
milieux scaffold my_project
```
The command above will create a new project in a `my_project` subdirectory.
The `--utility` argument lets you specify the utility for creating the project scaffold.
🚧 At present, the only supported scaffold utility is [hatch](https://hatch.pypa.io/latest). In the future we plan to support arbitrary project templates via [jinja](https://jinja.palletsprojects.com/) and/or [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/).
### `doc`: Create API reference documentation
`milieux doc` builds API reference documentation for one or more packages.
**Example**: build docs for all packages in a distro, saving them to a `docs/` directory:
```shell
milieux doc build -d my_distro -o docs
```
**Example**: serve documentation on `localhost` for a single package:
```shell
milieux doc serve -p my_package
```
This uses [mkdocs](https://www.mkdocs.org), [mkdocs-material](https://squidfunk.github.io/mkdocs-material/), and [mkdocs-api-autonav](https://github.com/tlambert03/mkdocs-api-autonav/) to produce the documentation.
#### Customization
`milieux` does not (yet) expose much in the way of customization, but some things may be controlled using [jinja](https://jinja.palletsprojects.com/) templates.
To customize the `mkdocs` settings, you can provide a jinja YAML template file to `--config-template`. The default is [doc_template.yml.jinja](milieux/doc/doc_template.yml.jinja).
To customize the home page (`index.html`), you can provide a jinja Markdown template file to `--home-template`. The default is [home_template.md.jinja](milieux/doc/home_template.md.jinja).
Two template variables may be used within the templates. Their values will be passed in based on other command-line arguments:
- `SITE_NAME`: based on `--site-name` (if provided), or the distro/package name (if there is only one), or the default name "API Docs" otherwise.
- `PKG_PATHS`: list of paths to each of the packages to be included in the reference docs. This is derived from the list of distros, requirements, and packages provided by the user.
### `config`: Manage configurations
`milieux config` lets you manage global configurations.
Configs are stored by default in a TOML file, `$HOME/.milieux/config.toml`. If none exists, you will be prompted to create one when running most commands.
The config file stores things like paths to directories containing your environments and distros.
To override the default config path, you can provide `--config` to point to a specific file.
| Subcommand | Description |
| ---------- | ----------- |
| `new` | Create a new config file |
| `path` | Print out path to the configs |
| `show` | Show the configs |
#### PyPI Configurations
`milieux` uses `uv` as its package manager, which in turn defaults to the standard [Python Packaging Index](https://pypi.org/) (PyPI) to download packages. However, you may want to override this in order to use a custom PyPI mirror.
This can be done in one of two ways:
1. Set the `UV_DEFAULT_INDEX` or `UV_INDEX` environment variables.
2. Configure the `default_index` or `indexes` fields in the `[pip]` section of your config file.
Example `pip` section of file:
```toml
[pip]
# URL for default PyPI index
default_index_url = "https://pypi.org/simple"
# URLs for extra indexes, in descending priority order (but all taking priority over the default)
index_urls = [
"https://internal-pypi-mirror.example.com",
"https://backup-pypi-mirror.example.com"
]
```
See the `uv` page on [Package Indexes](https://docs.astral.sh/uv/concepts/indexes/) for more information on how package index overrides work.
## Support and feedback
🛠️ Feel free to submit pull requests, ask questions, or make bugfix/feature requests on [Github Issues](https://github.com/jeremander/milieux/issues).
Raw data
{
"_id": null,
"home_page": null,
"name": "milieux",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "virtualenv",
"author": null,
"author_email": "Jeremy Silver <jeremys@nessiness.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/38/f0bc8cab113f627b4c3e6be13401adf16e2200524e71258bb5c2fdc03b19/milieux-0.2.4.tar.gz",
"platform": null,
"description": "# Milieux\n\n[](https://pypi.org/project/milieux)\n\n\n[](https://raw.githubusercontent.com/jeremander/milieux/main/LICENSE)\n[](https://github.com/pre-commit/pre-commit)\n\nA general-purpose tool to assist in developing, building, and installing Python packages.\n\n\u26a0\ufe0f `milieux` is currently in its very early stages and should *not* be considered stable.\n\n## Introduction\n\n`milieux` is a tool used for managing multiple [virtual environments](https://realpython.com/python-virtual-environments-a-primer/#why-do-you-need-virtual-environments) and *distributions*.\n\nWe define a *distribution* (or \"distro\") to be a collection of Python packages you often want bundled together. For example, you might want to bundle `numpy`, `scipy`, and `pandas` together into a distribution named `scientific`, which you can then install into one more more virtual environments. To do this, you can run:\n\n```shell\nmilieux distro new scientific -p numpy scipy pandas\n```\n\nThen to create a new environment `my_env` and install all dependencies from this distribution:\n\n```shell\nmilieux env new my_env\n\nmilieux env install -d scientific\n```\n\n## Installation\n\n```shell\npip install milieux\n```\n\n### Dependencies\n\n- \ud83e\udd80 [uv](https://github.com/astral-sh/uv), an ultra-fast package resolver and installer written in Rust.\n\n- \ud83d\udc0d [hatch](https://github.com/pypa/hatch), for building/publishing packages.\n\n- \ud83e\udd35\ud83c\udffb\u200d\u2642\ufe0f [fancy_dataclass](https://fancy-dataclass.readthedocs.io/en/latest/), for configurations and argument parsing.\n\n- \ud83d\udcc4 [mkdocs](https://www.mkdocs.org), for documentation generation.\n\n- \ud83d\udcb0 [rich](https://rich.readthedocs.io/en/stable/index.html), for text and table styling.\n\n## Usage\n\nView help menu:\n\n```shell\nmilieux -h\n```\n\nView subcommand help menu:\n\n```text\nmilieux <SUBCOMMAND> -h\n```\n\nFor brevity, you may want to alias the command as follows:\n\n```shell\nalias mlx=\"milieux\"\n```\n\nThen you can type `mlx` in place of the full (tricky-to-spell) name.\n\n## Commands\n\nHere is a quick tour of the commands available in `milieux`.\n\n### `distro`: Manage distributions\n\n`milieux distro` has a collection of subcommands for creating, viewing, and modifying distributions (distros), which are collections of Python packages.\n\nA distro is nothing more than a *requirements file*, a plaintext file containing a list of Python packages. See the [specification](https://pip.pypa.io/en/stable/reference/requirements-file-format/) for more details about how to specify package URLs, versions, etc.\n\n| Subcommand | Description |\n| ----------- | ----------- |\n| `list` | List all distros |\n| `lock` | Lock dependencies |\n| `new` | Create new distro |\n| `remove` | Remove a distro |\n| `show` | Show contents of a distro |\n\n#### Locking dependencies\n\n`milieux distro lock` can be used to \"lock\" or \"pin\" the packages listed in a distro (requirements) file. This calls the dependency resolver to figure out the latest versions of all the packages that are mutually compatible. It then saves them out to a new requirements file.\n\nLocking dependencies can ensure reproducibility of environments (someone else can set up the exact same environment, regardless of what the latest package versions happen to be). The downside is that the locked dependencies may become out of date.\n\n**Example**: from the earlier `scientific` distro example, lock dependencies to the current versions, and save them to a new distro marked with the current date.\n\n```text\n$ milieux distro lock scientific --new scientific.20240609\n\nLocking dependencies for 'scientific' distro\n...\nCreating distro 'scientific.20240609'\n\n$ milieux distro show scientific.20240609\n\n...\nnumpy==1.26.4\npandas==2.2.2\npython-dateutil==2.9.0.post0\npytz==2024.1\nscipy==1.13.1\nsix==1.16.0\ntzdata==2024.1\n```\n\n### `env`: Manage environments\n\n`milieux env` has a collection of subcommands for creating, viewing, and modifying virtual environments.\n\n| Subcommand | Description |\n| ----------- | ----------- |\n| `activate` | Activate an environment |\n| `freeze` | List installed packages |\n| `install` | Install packages |\n| `list` | List all environments |\n| `new` | Create new environment |\n| `remove` | Remove an environment |\n| `show` | Show environment info |\n| `sync` | Sync dependencies |\n| `template` | Render a [jinja](https://jinja.palletsprojects.com/) template, filling in variables from an environment |\n| `uninstall` | Uninstall packages |\n\n#### Activate an environment\n\n`milieux env activate` provides an easy way to activate a virtual environment. Unfortunately it is awkward to source an activation script directly from Python, so this command actually just prints out instructions for how to activate the environment.\n\nHowever, you can also activate the environment directly by calling the command within backticks (which executes its output). For example:\n\n```shell\n`milieux env activate my_env`\n```\n\nThis will source the activation script associated with the `my_env` virtual environment. To deactivate the environment, run `deactivate`.\n\n#### Install packages\n\n`milieux env install` lets you install packages into an environment. You can list specific packages with `-p`, requirements files with `-r`, or distro names with `-d`.\n\n**Example**: install packages from the `scientific` distro, plus `scikit-learn` and PyTorch.\n\n```shell\nmilieux env install my_env -d scientific -p scikit-learn torch\n```\n\nIf you are already in an activated environment, you may omit the name of the environment, and it will assume the active one:\n\n```shell\nmilieux env install -p pandas\n```\n\n#### Sync packages\n\n`milieux env sync` is similar to `install`, but instead of installing new packages, it will *sync* them to the environment, making sure these are the *only* packages in the environment. This is ideal for controlling exactly what version of each specific package you want (see: [locking dependencies](#locking-dependencies)).\n\n<!--\n#### Render template file for an environment\n\nTODO: include a description of `milieux env template` (this may be TMI).\n-->\n\n### `scaffold`: Create project scaffold\n\n`milieux scaffold` creates a new Python project from a default or custom scaffold.\n\n```shell\nmilieux scaffold my_project\n```\n\nThe command above will create a new project in a `my_project` subdirectory.\n\nThe `--utility` argument lets you specify the utility for creating the project scaffold.\n\n\ud83d\udea7 At present, the only supported scaffold utility is [hatch](https://hatch.pypa.io/latest). In the future we plan to support arbitrary project templates via [jinja](https://jinja.palletsprojects.com/) and/or [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/).\n\n### `doc`: Create API reference documentation\n\n`milieux doc` builds API reference documentation for one or more packages.\n\n**Example**: build docs for all packages in a distro, saving them to a `docs/` directory:\n\n```shell\nmilieux doc build -d my_distro -o docs\n```\n\n**Example**: serve documentation on `localhost` for a single package:\n\n```shell\nmilieux doc serve -p my_package\n```\n\nThis uses [mkdocs](https://www.mkdocs.org), [mkdocs-material](https://squidfunk.github.io/mkdocs-material/), and [mkdocs-api-autonav](https://github.com/tlambert03/mkdocs-api-autonav/) to produce the documentation.\n\n#### Customization\n\n`milieux` does not (yet) expose much in the way of customization, but some things may be controlled using [jinja](https://jinja.palletsprojects.com/) templates.\n\nTo customize the `mkdocs` settings, you can provide a jinja YAML template file to `--config-template`. The default is [doc_template.yml.jinja](milieux/doc/doc_template.yml.jinja).\n\nTo customize the home page (`index.html`), you can provide a jinja Markdown template file to `--home-template`. The default is [home_template.md.jinja](milieux/doc/home_template.md.jinja).\n\nTwo template variables may be used within the templates. Their values will be passed in based on other command-line arguments:\n\n- `SITE_NAME`: based on `--site-name` (if provided), or the distro/package name (if there is only one), or the default name \"API Docs\" otherwise.\n- `PKG_PATHS`: list of paths to each of the packages to be included in the reference docs. This is derived from the list of distros, requirements, and packages provided by the user.\n\n### `config`: Manage configurations\n\n`milieux config` lets you manage global configurations.\n\nConfigs are stored by default in a TOML file, `$HOME/.milieux/config.toml`. If none exists, you will be prompted to create one when running most commands.\n\nThe config file stores things like paths to directories containing your environments and distros.\n\nTo override the default config path, you can provide `--config` to point to a specific file.\n\n| Subcommand | Description |\n| ---------- | ----------- |\n| `new` | Create a new config file |\n| `path` | Print out path to the configs |\n| `show` | Show the configs |\n\n#### PyPI Configurations\n\n`milieux` uses `uv` as its package manager, which in turn defaults to the standard [Python Packaging Index](https://pypi.org/) (PyPI) to download packages. However, you may want to override this in order to use a custom PyPI mirror.\n\nThis can be done in one of two ways:\n\n1. Set the `UV_DEFAULT_INDEX` or `UV_INDEX` environment variables.\n2. Configure the `default_index` or `indexes` fields in the `[pip]` section of your config file.\n\nExample `pip` section of file:\n\n```toml\n[pip]\n# URL for default PyPI index\ndefault_index_url = \"https://pypi.org/simple\"\n# URLs for extra indexes, in descending priority order (but all taking priority over the default)\nindex_urls = [\n \"https://internal-pypi-mirror.example.com\",\n \"https://backup-pypi-mirror.example.com\"\n]\n```\n\nSee the `uv` page on [Package Indexes](https://docs.astral.sh/uv/concepts/indexes/) for more information on how package index overrides work.\n\n## Support and feedback\n\n\ud83d\udee0\ufe0f Feel free to submit pull requests, ask questions, or make bugfix/feature requests on [Github Issues](https://github.com/jeremander/milieux/issues).\n",
"bugtrack_url": null,
"license": null,
"summary": "Tool to assist in developing, building, and installing Python packages.",
"version": "0.2.4",
"project_urls": {
"Documentation": "https://github.com/jeremander/milieux#readme",
"Issues": "https://github.com/jeremander/milieux/issues",
"Source": "https://github.com/jeremander/milieux"
},
"split_keywords": [
"virtualenv"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d9c9b9cb97fb1223101d28704dd6d93ec580cab218c1f75fec02840542703f80",
"md5": "c2596199c8decfd986f27d0eaca82946",
"sha256": "bdb1ba02bc2514279232de5cadb4081b329f66da809523c163da89537f74570a"
},
"downloads": -1,
"filename": "milieux-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2596199c8decfd986f27d0eaca82946",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 28945,
"upload_time": "2025-07-12T18:47:49",
"upload_time_iso_8601": "2025-07-12T18:47:49.105834Z",
"url": "https://files.pythonhosted.org/packages/d9/c9/b9cb97fb1223101d28704dd6d93ec580cab218c1f75fec02840542703f80/milieux-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0e38f0bc8cab113f627b4c3e6be13401adf16e2200524e71258bb5c2fdc03b19",
"md5": "ec95b0b509b0366383322a50bacbbcf2",
"sha256": "74f419f8d5b0601029f1fbd2ec1867b7932d927e251c07e0590c8a2582f583e1"
},
"downloads": -1,
"filename": "milieux-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "ec95b0b509b0366383322a50bacbbcf2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21756,
"upload_time": "2025-07-12T18:47:48",
"upload_time_iso_8601": "2025-07-12T18:47:48.101889Z",
"url": "https://files.pythonhosted.org/packages/0e/38/f0bc8cab113f627b4c3e6be13401adf16e2200524e71258bb5c2fdc03b19/milieux-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 18:47:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeremander",
"github_project": "milieux#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "milieux"
}
