From 3487a3e551313817aeae4d32dcb75725b531006d Mon Sep 17 00:00:00 2001 From: Bryn Pickering <17178478+brynpickering@users.noreply.github.com> Date: Fri, 20 Dec 2024 17:17:43 +0000 Subject: [PATCH] Remove reference to `mamba` and use `conda` instead. --- CHANGELOG.md | 1 + CONTRIBUTING.md | 8 ++-- docs/tutorial.md | 22 ++++++----- {{cookiecutter.repository_name}}/README.md | 23 ++++++------ .../docs/contributing.md | 19 +++++----- .../docs/installation.md | 37 +++++++++++-------- 6 files changed, 61 insertions(+), 49 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9be3671..96c6836 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Recommend `conda` instead of `mamba` for project creation and package installation (#53). - Docs CI run on PR to main or on main, with different jobs run in each case (#33). - Docs/PR CI jobs do not trigger on github workflow changes except their own definition files (#32). - Package test parallelisation set to automatically select the number of threads based on those available (#36). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19903b6..de30b88 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ If you are proposing a new feature: ## Setting up and working in a development environment Ready to contribute? Here's how to set up `cookiecutter-pypackage` for local development. -Please note this documentation assumes you already have `mamba` and `Git` installed and ready to go. +Please note this documentation assumes you already have `conda` and `Git` installed and ready to go. 1. Fork the `cookiecutter-pypackage` repo on GitHub. @@ -56,12 +56,12 @@ Please note this documentation assumes you already have `mamba` and `Git` instal git clone git@github.com:YOUR_GITHUB_USERNAME/cookiecutter-pypackage.git ``` -1. Assuming you have mamba installed, you can create a new environment for your local +1. Assuming you have conda installed, you can create a new environment for your local development by typing: ``` shell - mamba create -c conda-forge -n cookiecutter-pypackage-dev --file requirements/dev.txt - mamba activate cookiecutter-pypackage-dev + conda create -c conda-forge -n cookiecutter-pypackage-dev --file requirements/dev.txt + conda activate cookiecutter-pypackage-dev pip install --no-deps -e . ``` diff --git a/docs/tutorial.md b/docs/tutorial.md index 22c5566..e0f67b2 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -27,7 +27,8 @@ If you are new to Git and GitHub, you should probably spend a few minutes on som Here are some of the assumptions we will make about your local system, which you will need to change as necessary: - - You have [mamba](https://mamba.readthedocs.io/en/latest/index.html) installed (conda/micromamba also work) + - You have [miniforge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#download) installed to give you access to `conda` in the terminal. + Arup users on Windows can install `miniforge` from the Arup software shop by downloading "VS Code for Python". - You store your projects on your device at `~/Repos` (Windows: `C:\\Users\yourusername\Repos`) 1. The package name needs to be *globally* unique, i.e., not available on [conda-forge](https://anaconda.org/conda-forge) or on [PyPI](https://pypi.org/). @@ -38,17 +39,18 @@ In the City Modelling Lab, we use the `cml-` prefix if we need to make our packa ### Step 1: Install Cruft -First, you need to create and activate a conda/[mamba](https://mamba.readthedocs.io/en/latest/index.html) environment for using Cruft (a Cookiecutter-compatible tool which allows for project updating). +First, you need to create and activate a [conda](https://docs.conda.io/en/latest/) environment for using Cruft (a Cookiecutter-compatible tool which allows for updating projects). + Use your favorite method, or create an environment like this: -=== "With mamba" +=== "With conda" ``` bash - mamba create -n cookiecutter cruft + conda create -n cookiecutter cruft ``` Activate your environment: ``` bash - mamba activate cookiecutter + conda activate cookiecutter ``` === "With pip" @@ -130,8 +132,8 @@ You should choose the `gh-pages` branch (this will only appear a few minutes aft ### Step 5: Define requirements As well as writing the package source code, documentation, and tests, you will need to define the packages on which your project depends. -You can find an _almost_ empty requirements file for you to complete in your new project folder: `requirements/base.txt`. -It cannot be empty, otherwise mamba might complain. +You can find an *almost* empty requirements file for you to complete in your new project folder: `requirements/base.txt`. +It cannot be empty, otherwise `conda` might complain. You can update this as you go along and need new packages in your project. ### Step 6: Create a development environment for your project @@ -140,14 +142,14 @@ To install the necessary packages to develop your Python package, follow the ins !!! note As you update the requirements that [you define as dependencies](#step-5-define-requirements), you should bulldoze your install and recreate it. - E.g., if you create your environment using mamba/conda: + E.g., if you create your environment using conda: ```bash - mamba create -n python-boilerplate -c conda-forge --file requirements/base.txt --file requirements/dev.txt + conda create -n python-boilerplate -c conda-forge --file requirements/base.txt --file requirements/dev.txt ``` You should run this exact same command after updating `requirements/base.txt` and say yes to overriding the existing `python-boilerplate` environment. - This is a much better way of managing your python environments than adding the dependencies ad-hoc using `mamba install ...`. + This is a much better way of managing your python environments than adding the dependencies ad-hoc using `conda install ...`. ### Step 7: Tweak the generated project files to meet your specific needs / preferences diff --git a/{{cookiecutter.repository_name}}/README.md b/{{cookiecutter.repository_name}}/README.md index 7a92b32..cdc76de 100644 --- a/{{cookiecutter.repository_name}}/README.md +++ b/{{cookiecutter.repository_name}}/README.md @@ -19,24 +19,25 @@ To install {{ cookiecutter.module_name }} {%- if cookiecutter.package_name != cookiecutter.module_name %} (indexed online as {{ cookiecutter.package_name }}) {%- endif -%} -, we recommend using the [mamba](https://mamba.readthedocs.io/en/latest/index.html) package manager: +, we recommend using the [conda](https://docs.conda.io/en/latest/) package manager, accessible from the terminal by installing [miniforge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#download). +Arup users on Windows can install `miniforge` from the Arup software shop by downloading "VS Code for Python" and then access `conda` from the VSCode integrated terminal. ### As a user ``` shell {% if cookiecutter.upload_conda_package == "y" %} -mamba create -n {{ cookiecutter.repository_name }} -c conda-forge -c {{ cookiecutter.conda_channel }} {{ cookiecutter.package_name }} -mamba activate {{ cookiecutter.repository_name }} +conda create -n {{ cookiecutter.repository_name }} -c conda-forge -c {{ cookiecutter.conda_channel }} {{ cookiecutter.package_name }} +conda activate {{ cookiecutter.repository_name }} {% elif cookiecutter.upload_pypi_package == "y" %} -mamba create -n {{ cookiecutter.repository_name }} -c conda-forge python -mamba activate {{ cookiecutter.repository_name }} +conda create -n {{ cookiecutter.repository_name }} -c conda-forge python +conda activate {{ cookiecutter.repository_name }} pip install {{ cookiecutter.package_name }} {% else %} git clone git@github.com:{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}.git cd {{ cookiecutter.repository_name }} -mamba create -n {{ cookiecutter.repository_name }} -c conda-forge --file requirements/base.txt -mamba activate {{ cookiecutter.repository_name }} +conda create -n {{ cookiecutter.repository_name }} -c conda-forge --file requirements/base.txt +conda activate {{ cookiecutter.repository_name }} pip install --no-deps -e . {%- endif %} ``` @@ -47,8 +48,8 @@ pip install --no-deps -e . ``` shell git clone git@github.com:{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}.git cd {{ cookiecutter.repository_name }} -mamba create -n {{ cookiecutter.repository_name }} -c conda-forge --file requirements/base.txt --file requirements/dev.txt -mamba activate {{ cookiecutter.repository_name }} +conda create -n {{ cookiecutter.repository_name }} -c conda-forge --file requirements/base.txt --file requirements/dev.txt +conda activate {{ cookiecutter.repository_name }} pip install --no-deps -e . ``` @@ -65,7 +66,7 @@ If you plan to make changes to the code then please make regular use of the foll The checks are: 1. check no large files have been staged, 2. lint python files for major errors, 3. format python files to conform with the [pep8 standard](https://peps.python.org/pep-0008/). You can also run these checks yourself at any time to ensure staged changes are clean by simple calling `pre-commit`. - `pytest` - run the unit test suite and check test coverage. -- `pytest -p memray -m "high_mem" --no-cov` (not available on Windows) - after installing memray (`mamba install memray pytest-memray`), test that memory and time performance does not exceed benchmarks. +- `pytest -p memray -m "high_mem" --no-cov` (not available on Windows) - after installing memray (`conda install memray pytest-memray`), test that memory and time performance does not exceed benchmarks. For more information, see our [documentation](https://{{ cookiecutter.repository_owner }}.github.io/{{ cookiecutter.repository_name }}/latest/contributing/). @@ -82,4 +83,4 @@ Then you can view the documentation in a browser at . ## Credits -This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [arup-group/cookiecutter-pypackage](https://github.com/arup-group/cookiecutter-pypackage) project template. \ No newline at end of file +This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [arup-group/cookiecutter-pypackage](https://github.com/arup-group/cookiecutter-pypackage) project template. diff --git a/{{cookiecutter.repository_name}}/docs/contributing.md b/{{cookiecutter.repository_name}}/docs/contributing.md index 7585d07..f9f180b 100644 --- a/{{cookiecutter.repository_name}}/docs/contributing.md +++ b/{{cookiecutter.repository_name}}/docs/contributing.md @@ -28,15 +28,16 @@ To find beginner-friendly existing bugs and feature requests you may like to sta ### Setting up a development environment -To create a development environment for {{ cookiecutter.module_name }}, with all libraries required for development and quality assurance installed, it is easiest to install {{ cookiecutter.package_name }} using the [mamba](https://mamba.readthedocs.io/en/latest/index.html) package manager, as follows: +To create a development environment for {{ cookiecutter.module_name }}, with all libraries required for development and quality assurance installed, it is easiest to install {{ cookiecutter.package_name }} using the [conda](https://docs.conda.io/en/latest/) package manager, as follows: -1. Install mamba with the [Mambaforge](https://github.com/conda-forge/miniforge#mambaforge) executable for your operating system. -1. Open the command line (or the "miniforge prompt" in Windows). +1. Install conda with the [miniforge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#download) executable for your operating system. +Arup users on Windows can install `miniforge` from the Arup software shop by downloading "VS Code for Python". +1. Open the command line (or the VSCode "integrated terminal" in Windows). 1. Download (a.k.a., clone) the {{ cookiecutter.repository_name }} repository: `git clone git@github.com:{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}.git` 1. Change into the `{{ cookiecutter.repository_name }}` directory: `cd {{ cookiecutter.repository_name }}` -1. Create the {{ cookiecutter.repository_name }} mamba environment: `mamba create -n {{ cookiecutter.repository_name }} -c conda-forge --file requirements/base.txt --file requirements/dev.txt` -1. Activate the {{ cookiecutter.repository_name }} mamba environment: `mamba activate {{ cookiecutter.repository_name }}` -1. Install the {{ cookiecutter.package_name }} package into the environment, in editable mode and ignoring dependencies (we have dealt with those when creating the mamba environment): `pip install --no-deps -e .` +1. Create the {{ cookiecutter.repository_name }} conda environment: `conda create -n {{ cookiecutter.repository_name }} -c conda-forge --file requirements/base.txt --file requirements/dev.txt` +1. Activate the {{ cookiecutter.repository_name }} conda environment: `conda activate {{ cookiecutter.repository_name }}` +1. Install the {{ cookiecutter.package_name }} package into the environment, in editable mode and ignoring dependencies (we have dealt with those when creating the conda environment): `pip install --no-deps -e .` All together: @@ -82,7 +83,7 @@ The integration tests can be slow, so if you want to avoid them during developme {{ cookiecutter.module_name }} can be memory intensive; we like to ensure that any development to the core code does not exacerbate this. If you are running on a UNIX device (i.e., **not*- on Windows), you can test whether any changes you have made adversely impact memory and time performance as follows: -1. Install [memray](https://bloomberg.github.io/memray/index.html) in your `{{ cookiecutter.repository_name }}` mamba environment: `mamba install memray pytest-memray`. +1. Install [memray](https://bloomberg.github.io/memray/index.html) in your `{{ cookiecutter.repository_name }}` conda environment: `conda install memray pytest-memray`. 2. Run the memory profiling integration test: `pytest -p memray -m "high_mem" --no-cov`. 3. Optionally, to visualise the memory allocation, run `pytest -p memray -m "high_mem" --no-cov --memray-bin-path=[my_path] --memray-bin-prefix=[my_prefix]` - where you must define `[my_path]` and `[my_prefix]` - followed by `memray flamegraph [my_path]/[my_prefix]-tests-test_100_memory_profiling.py-test_mem.bin`. You will then find the HTML report at `[my_path]/memray-flamegraph-[my_prefix]-tests-test_100_memory_profiling.py-test_mem.html`. @@ -90,7 +91,7 @@ You will then find the HTML report at `[my_path]/memray-flamegraph-[my_prefix]-t All together: ``` shell -mamba install memray pytest-memray +conda install memray pytest-memray pytest -p memray -m "high_mem" --no-cov --memray-bin-path=[my_path] --memray-bin-prefix=[my_prefix] memray flamegraph [my_path]/[my_prefix]-tests-test_100_memory_profiling.py-test_mem.bin ``` @@ -212,7 +213,7 @@ First, serve your documentation locally, then use e.g., the [Mozilla Firefox acc ## Updating the project when the template updates This project has been built with [cruft](https://cruft.github.io/cruft/) based on the [Arup Cookiecutter template](https://github.com/arup-group/cookiecutter-pypackage). -When changes are made to the base template, they can be merged into this project by running `cruft update` from the `{{ cookiecutter.repository_name }}` mamba environment. +When changes are made to the base template, they can be merged into this project by running `cruft update` from the `{{ cookiecutter.repository_name }}` conda environment. You may be prompted to do this when you open a Pull Request, if our automated checks identify that the template is newer than that used in the project. diff --git a/{{cookiecutter.repository_name}}/docs/installation.md b/{{cookiecutter.repository_name}}/docs/installation.md index 388bf80..ab8532d 100644 --- a/{{cookiecutter.repository_name}}/docs/installation.md +++ b/{{cookiecutter.repository_name}}/docs/installation.md @@ -3,29 +3,36 @@ ## Setting up a user environment -As a `{{ cookiecutter.module_name }}` user, it is easiest to install using the [mamba](https://mamba.readthedocs.io/en/latest/index.html) package manager, as follows: +As a `{{ cookiecutter.module_name }}` user, it is easiest to install using the [conda](https://docs.conda.io/en/latest/) package manager, as follows: -1. Install mamba with the [Mambaforge](https://github.com/conda-forge/miniforge#mambaforge) executable for your operating system. -1. Open the command line (or the "miniforge prompt" in Windows). +1. Install conda with the [miniforge](https://github.com/conda-forge/miniforge?tab=readme-ov-file#download) executable for your operating system. +Arup users on Windows can install `miniforge` from the Arup software shop by downloading "VS Code for Python". +1. Open the command line (or the VSCode "integrated terminal" in Windows). {%- if cookiecutter.upload_conda_package == "y" %} -1. Create the {{ cookiecutter.repository_name }} mamba environment: `mamba create -n {{ cookiecutter.repository_name }} -c conda-forge -c {{ cookiecutter.conda_channel }} {{ cookiecutter.package_name }}` -1. Activate the {{ cookiecutter.repository_name }} mamba environment: `mamba activate {{ cookiecutter.repository_name }}` +1. Create the {{ cookiecutter.repository_name }} conda environment: `conda create -n {{ cookiecutter.repository_name }} -c conda-forge -c {{ cookiecutter.conda_channel }} {{ cookiecutter.package_name }}` +1. Activate the {{ cookiecutter.repository_name }} conda environment: `conda activate {{ cookiecutter.repository_name }}` {%- elif cookiecutter.upload_pypi_package == "y" %} -1. Create a {{ cookiecutter.repository_name }} mamba environment: `mamba create -n {{ cookiecutter.repository_name }} -c conda-forge python` -1. Activate the {{ cookiecutter.repository_name }} mamba environment: `mamba activate {{ cookiecutter.repository_name }}` +1. Create a {{ cookiecutter.repository_name }} conda environment: `conda create -n {{ cookiecutter.repository_name }} -c conda-forge python` +1. Activate the {{ cookiecutter.repository_name }} conda environment: `conda activate {{ cookiecutter.repository_name }}` 1. Install the {{ cookiecutter.package_name }} package into the environment: `pip install {{ cookiecutter.package_name }}` {%- else %} 1. Download (a.k.a., clone) the {{ cookiecutter.repository_name }} repository: `git clone git@github.com:{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}.git` 1. Change into the `{{ cookiecutter.repository_name }}` directory: `cd {{ cookiecutter.repository_name }}` -1. Create the {{ cookiecutter.repository_name }} mamba environment: `mamba create -n {{ cookiecutter.repository_name }} -c conda-forge -c city-modelling-lab --file requirements/base.txt` -1. Activate the {{ cookiecutter.repository_name }} mamba environment: `mamba activate {{ cookiecutter.repository_name }}` -1. Install the {{ cookiecutter.package_name }} package into the environment, ignoring dependencies (we have dealt with those when creating the mamba environment): `pip install --no-deps .` +1. Create the {{ cookiecutter.repository_name }} conda environment: `conda create -n {{ cookiecutter.repository_name }} -c conda-forge -c city-modelling-lab --file requirements/base.txt` +1. Activate the {{ cookiecutter.repository_name }} conda environment: `conda activate {{ cookiecutter.repository_name }}` +1. Install the {{ cookiecutter.package_name }} package into the environment, ignoring dependencies (we have dealt with those when creating the conda environment): `pip install --no-deps .` {% endif %} All together: --8<-- "README.md:docs-install-user" +!!! tip + If you are an Arup user and are having difficulties with creating the `conda` environment, it may be due to *SSL certificates*. + You'll know that this is the case because there will be mention of "SSL" in the error trace. + Search `SSL Certificates` on the Arup internal Sharepoint to find instructions on adding the certificates for `conda`. + Windows users who have installed "VS Code for Python" from the software shop should have all the relevant certificates in place, but you will need to follow the instructions given on the SharePoint troubleshooting page if you want to run the command from in a Windows Subsystem for Linux (WSL) session. + {%- if cookiecutter.create_jupyter_notebook_directory|lower == "y" %} ### Running the example notebooks @@ -33,24 +40,24 @@ All together: If you have followed the non-developer installation instructions above, you will need to install `jupyter` into your `{{ cookiecutter.repository_name }}` environment to run the [example notebooks](https://github.com/{{ cookiecutter.repository_owner }}/{{ cookiecutter.repository_name }}/tree/main/examples): ``` shell -mamba install -n {{ cookiecutter.repository_name }} jupyter +conda install -n {{ cookiecutter.repository_name }} jupyter ``` With Jupyter installed, it's easiest to then add the environment as a jupyter kernel: ``` shell -mamba activate {{ cookiecutter.repository_name }} +conda activate {{ cookiecutter.repository_name }} ipython kernel install --user --name={{ cookiecutter.repository_name }} jupyter notebook ``` ### Choosing a different environment name -If you would like to use a different name to `{{ cookiecutter.repository_name }}` for your mamba environment, the installation becomes (where `[my-env-name]` is your preferred name for the environment): +If you would like to use a different name to `{{ cookiecutter.repository_name }}` for your conda environment, the installation becomes (where `[my-env-name]` is your preferred name for the environment): ``` shell -mamba create -n [my-env-name] -c conda-forge --file requirements/base.txt -mamba activate [my-env-name] +conda create -n [my-env-name] -c conda-forge --file requirements/base.txt +conda activate [my-env-name] ipython kernel install --user --name=[my-env-name] ``` {%- endif %}