# Command cheat sheet
* [pyOpenSci packaging tutorials](https://www.pyopensci.org/python-package-guide/tutorials/create-python-package.html)

## Create an environment and install your package

**Using mamba**
*(Mamba and conda are installed in our codespace. You can use whatever environment manager that you prefer)*

`mamba create -n pyosdev python=3.12`

**TIP:** `Mamba create` is faster at creating a new environment so use that. `Mamba activate` won't work by default in Codespaces because mamba is not initialized. Use `conda` to activate your environment:

`conda activate myenv`

**Using venv** (windows & linux like)

# Create a venv
$ uv venv myvenv

Activate on mac/linux:

# Activate VENV (mac/linux/Codespace)
$ source myvenv/bin/activate

Activate on Windows

.\myvenv\Scripts\activate

## Run the copier template (requires internet access to run from GitHub)

This will create the new package from the copier template in your current working directory:

`copier copy gh:pyopensci/pyos-package-template .`

And this will install it in a subdirectory `path/here` (if that exists on your computer)

`copier copy gh:pyopensci/pyos-package-template path/here`

## Build and check your package distro (needed for pypi)

`hatch run build:check`

## Run test suite across multiple python versions

`hatch run test:run`

## Build your docs

`hatch run docs:build`

Serve the docs locally (works if you have microsoft live preview extension setup in vscode!)

`hatch run docs:serve`

Stop serving the docs

mac: <kbd>ctrl + c</kbd>
windows:

### Enter a hatch environment from your terminal

$ hatch shell envt-name
example to open the docs environment:

`$ hatch shell docs`

To exit the environment

`deactivate`

*(exit might work too?)*

## Install your package into the active Python environment:

# First cd into the directory where the package lives.
# then run:
`pip install -e .`

Output:

Obtaining file:///workspaces/pyopensci-scipy25-create-python-package
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Installing backend dependencies ... done
  Preparing editable metadata (pyproject.toml) ... done
Building wheels for collected packages: greatproject
  Building editable for greatproject (pyproject.toml) ... done
  Created wheel for greatproject: filename=greatproject-0.1.0-py3-none-any.whl size=2728 sha256=76c0795f9b9e7c284f4df1c79ff9cf26592b6769fc87f291002c2e3183919f6f
  Stored in directory: /tmp/pip-ephem-wheel-cache-r5_ysx3y/wheels/0a/d5/0a/bd3f38f03d791e55149a5bddb532e68f903ce6d1d6ae80d094
Successfully built greatproject
Installing collected packages: greatproject
Successfully installed greatproject-0.1.0

### Check that package is installed

`pip list`

(myenv) @lwasser ➜ /workspaces/pyopensci-scipy25-create-python-package (main) $ pip list
Package      Version Editable project location
------------ ------- ---------------------------------------------------
greatproject 0.1.0   /workspaces/pyopensci-scipy25-create-python-package
pip          25.1.1
setuptools   80.9.0
wheel        0.45.1

## Launch and exit a Python prompt

(myenv) @lwasser ➜ /workspaces/pyopensci-scipy25-create-python-package (main) $ python

Python 3.12.11 | packaged by conda-forge | (main, Jun  4 2025, 14:45:31) [GCC 13.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from greatproject.example import add_numbers
>>> add_numbers(1,2)
3
>>> exit() # this exits the python prompt and returns you to the terminal
# You can also use ctrl + d to exit

## Publish to test pypi

please do not publish to pypi during this workshop! Use the test PyPI to develop your skills first:

This step requires a test PyPI token (usename is `__token__`)

1. build your **sdist** and **wheel**

`$ hatch run build:check`

2. Publish to test PyPI using hatch (on your computer):

`hatch publish -r test`

2b. Publish to test PyPI using twine (in Codespaces)

`twine upload --repository testpypi dist/*`

If you need to troubleshoot, use the verbose flag:

`twine upload --repository testpypi dist/* --verbose`