Skip to content

claude code updates to lessons 1 and 2 #141

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

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

claude code updates to lessons 1 and 2 #141

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
66 changes: 42 additions & 24 deletions _episodes/01-package-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,9 @@ You should see the following directory structure.
├── README.md <- Description of the project which GitHub will render
├── molecool <- Basic Python Package import file
│ ├── __init__.py <- Basic Python Package import file
│ ├── _version.py <- Package version information
│ ├── functions.py <- Starting package module
│ ├── py.typed <- Marker file for type information
│ ├── data <- Sample additional data (non-code) which can be packaged. Just an example, delete in production
│ │ ├── README.md
│ │ └── look_and_say.dat
Expand All @@ -224,22 +226,24 @@ You should see the following directory structure.
│ │ └── README.md
│ ├── api.rst
│ ├── conf.py
│ ├── developer_guide.rst
│ ├── getting_started.rst
│ ├── index.rst
│ ├── make.bat
│ └── requirements.yaml <- Documentation building specific requirements. Usually a smaller set than the main program
│ ├── requirements.yaml <- Documentation building specific requirements. Usually a smaller set than the main program
│ └── user_guide.rst
├── pyproject.toml <- Generic Python build system configuration (PEP-517).
├── readthedocs.yml
├── .readthedocs.yaml <- ReadTheDocs configuration for documentation hosting
├── setup.cfg <- Near-master config file to make house INI-like settings for Coverage, Flake8, YAPF, etc.
├── setup.py <- Your package's setup file for installation with additional options that can be set
├── .codecov.yml <- Codecov config to help reduce its verbosity to more reasonable levels
├── .github <- GitHub hooks for user contribution, pull request guides, and GitHub Actions CI
│ ├── CONTRIBUTING.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ └── workflows
│ └── CI.yaml
├── .gitignore <- Stock helper file telling git what file name patterns to ignore when adding files
└── .lgtm.yml
│ ├── CI.yaml
│ └── codeql.yaml
├── .gitattributes <- Git configuration for file attributes
└── .gitignore <- Stock helper file telling git what file name patterns to ignore when adding files
```
```{admonition} Visualizing the Directory Structure
:class: note
Expand Down Expand Up @@ -277,7 +281,7 @@ We will first be working in the `molecool` folder to build our package, and addi
│ │ └── look_and_say.dat
│ ├── tests <- Unit test directory with sample tests
│ │ ├── __init__.py
│ │ └── test_functions.py
│ │ └── test_molecool.py
```

This the only folder we actually have to work with to build our package.
Expand Down Expand Up @@ -381,21 +385,23 @@ so that we can try out our functions and package as we develop it.
We access development mode using the `-e` option to `pip`.

#### Reviewing the generated config files

Return to the top directory (`molecool`).
Two of the files CookieCutter generated are `pyproject.toml` and `setup.cfg`.
These are the configuration files for our packaging and testing tools.
`pyproject.toml` tells [setuptools](https://packaging.python.org/key_projects/#setuptools) about your package (such as the name and version) as well as which code files to include.
We'll be using this file in the next section.

#### Installing your package

A development install, also known as an "editable" install, will allow you to import your package and use it from anywhere on your computer.
You will then be able to import your package into scripts in the same way you import `matplotlib` or `numpy`.
You will then be able to import your package into scripts in the same way you import `matplotlib` or `numpy`.
This setup is particularly useful during development, as it ensures that any changes you make to your package's code are immediately reflected in your Python environment, without the need for reinstallation.

To perform a development installation, you use pip with the `-e` option, which stands for "editable".
This tells pip to install the package in such a way that it links directly to your project's source code.
To perform a development installation, you use pip with the `-e` option, which stands for "editable".
This tells pip to install the package in such a way that it links directly to your project's source code.

````{tab-set-code}
````{tab-set-code}

```{code-block} shell
pip install -e .
Expand All @@ -409,35 +415,46 @@ while `.` indicates to install from the local directory (you could also specify

When you install a Python package using either `pip` or `conda`, that package is installed in your Python
environment's `site-packages` folder.
You can see where this is by checking your Python system path.
You can see where this is by checking your Python system path.
To do this, open Python (type `python` into your terminal window), and type

````{tab-set-code}
````{tab-set-code}

```{code-block} python
>>> import sys
>>> sys.path
```
````

This will output a list of locations that Python searches for packages.
This will output a list of locations that Python searches for packages.
One of these will typically end with `site-packages`, indicating the directory where Python looks for installed packages.

If you examine `site-packages`, you are likely to see a folder with your package's name followed by a `.dist-info`.
Inside, the `direct_url.json` file signifies an editable installation by pointing back to your project's directory.
You can also confirm that your package is installed in editable mode by using `pip show`:

````{tab-set-code}

```{code-block} shell
pip show molecool
```
````

Look for the `Editable project location:` line in the output, which indicates that your environment is using the live version from your source directory.

In the `site-packages` directory, you may see a folder with your package's name followed by `.dist-info`, which contains metadata about your installed package.
If the install is editable, Python also includes special `.pth` files or loader scripts (like `__editable__.pkg-version.pth`) to point back to your project directory.

:::{admonition} Python Packaging's Rapidly Evolving Landscape
:class: tip

In recent years, the Python packaging ecosystem has seen the development of numerous tools designed to streamline the process.
While the MolSSI CookieCutter primarily utilizes `setuptools` and `pyproject.toml` for packaging, alternatives like poetry and flit offer different features and workflows.
Depending on your tool of choice or even your Python version, you may encounter various files or configurations within `site-packages` following an editable installation.
:::
In recent years, the Python packaging ecosystem has seen the development of numerous tools designed to streamline the process.
While the MolSSI CookieCutter primarily utilizes `setuptools` and `pyproject.toml` for packaging, alternatives like poetry and flit offer different features and workflows.
Depending on your tool of choice or even your Python version, you may encounter various files or configurations within `site-packages` following an editable installation.
:::

After our install, we can use our package from any directory, similar to how we can use other installed packages like `numpy`.
Open Python, and type

````{tab-set-code}
````{tab-set-code}

```{code-block} python
>>> import molecool
Expand All @@ -447,14 +464,14 @@ Open Python, and type

This should print a quote.

````{tab-set-code}
````{tab-set-code}

```{code-block} output
'The code is but a canvas to our imagination.\n\t- Adapted from Henry David Thoreau'
```
````

A development installation inserts a link to your project into your Python
A development installation inserts a reference to your project into your Python
`site-packages` folder so that updates are immediately available the next time
you launch Python, without having to reinstall your package.

Expand All @@ -468,7 +485,8 @@ What if we switch directories?
```{admonition} Solution
:class: dropdown solution

If you are in the project directory, the code will still work. However, it will not work in any other location.
If you deactivate your environment, the code will not work unless your environment is reactivated.
If the package is installed in editable mode and your environment is active, the code will work from *any* directory.
```

````
Expand Down
10 changes: 6 additions & 4 deletions _episodes/02-git.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1110,7 +1110,7 @@ git merge add-functions
## Adding data
We now have a package with some functions.
Let's add the data from our starting material to our package as well.
We will add this to the `molecool/testing/data` directory.
We will add this to the `molecool/tests/data` directory.
Although it would be a best practice to add these files through a branch,
we will add them directly to the `main` branch for simplicity.

Expand Down Expand Up @@ -1284,7 +1284,7 @@ For example:
````{tab-set-code}

```{code-block} shell
git add data/calculation.in
git add molecool/data/calculation.out
```
````

Expand All @@ -1293,8 +1293,10 @@ git add data/calculation.in

```{code-block} output
The following paths are ignored by one of your .gitignore files:
data/calculation.in
Use -f if you really want to add them.
molecool/data/calculation.out
hint: Use -f if you really want to add them.
hint: Turn this message off by running
hint: "git config advice.addIgnoredFile false"
```
````

Expand Down