Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove reference to mamba and use conda instead. #58

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Remove reference to mamba and use conda instead. #58

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -56,12 +56,12 @@ Please note this documentation assumes you already have `mamba` and `Git` instal
git clone [email protected]: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 .
```

Expand Down
22 changes: 12 additions & 10 deletions docs/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
Expand All @@ -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"
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
23 changes: 12 additions & 11 deletions {{cookiecutter.repository_name}}/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<!--- --8<-- [start:docs-install-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 [email protected]:{{ 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 %}
```
Expand All @@ -47,8 +48,8 @@ pip install --no-deps -e .
``` shell
git clone [email protected]:{{ 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 .
```
<!--- --8<-- [end:docs-install-dev] -->
Expand All @@ -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/).

Expand All @@ -82,4 +83,4 @@ Then you can view the documentation in a browser at <http://localhost:8000/>.

## 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.
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.
19 changes: 10 additions & 9 deletions {{cookiecutter.repository_name}}/docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]:{{ 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:

Expand Down Expand Up @@ -82,15 +83,15 @@ 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`.

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
```
Expand Down Expand Up @@ -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.

Expand Down
Loading
Loading