| Name | milieux JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | None |
| Summary | Tool to assist in developing, building, and installing Python packages. |
| upload_time | 2024-11-01 18:30:04 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| 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.
- 💰 [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/en/3.1.x/) 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
```
#### 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/en/3.1.x/) and/or [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/).
### `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 |
## 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.9",
"maintainer_email": null,
"keywords": "virtualenv",
"author": null,
"author_email": "Jeremy Silver <jeremys@nessiness.com>",
"download_url": "https://files.pythonhosted.org/packages/29/99/68ca29d362ca0613d6e4d6033d3aab533fe0983ad4bf1816f00c3dfcfa67/milieux-0.2.3.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\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/en/3.1.x/) 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\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/en/3.1.x/) and/or [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/).\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## 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.3",
"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": "4a5bbfb6894644b95fa374d221dcfdbdd3a6eba12cf7f38dfa9f1d2dc50b4edc",
"md5": "c196ff5d8e1ac8dbae3327676b07a58e",
"sha256": "5b4a61d3d6519803e85a30ebf184b77ebcb0c6897231bb98832a917a595683e9"
},
"downloads": -1,
"filename": "milieux-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c196ff5d8e1ac8dbae3327676b07a58e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24160,
"upload_time": "2024-11-01T18:30:05",
"upload_time_iso_8601": "2024-11-01T18:30:05.742181Z",
"url": "https://files.pythonhosted.org/packages/4a/5b/bfb6894644b95fa374d221dcfdbdd3a6eba12cf7f38dfa9f1d2dc50b4edc/milieux-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "299968ca29d362ca0613d6e4d6033d3aab533fe0983ad4bf1816f00c3dfcfa67",
"md5": "71d7779f0b84b721a0cf1f0f70b92adb",
"sha256": "74f0d91933c8e11260cb250b545f5047ce3b19b307986846c7680496d05b46bf"
},
"downloads": -1,
"filename": "milieux-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "71d7779f0b84b721a0cf1f0f70b92adb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 400790,
"upload_time": "2024-11-01T18:30:04",
"upload_time_iso_8601": "2024-11-01T18:30:04.677043Z",
"url": "https://files.pythonhosted.org/packages/29/99/68ca29d362ca0613d6e4d6033d3aab533fe0983ad4bf1816f00c3dfcfa67/milieux-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-01 18:30:04",
"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"
}
