Skip to content

Commit

Permalink
differences for PR #25
Browse files Browse the repository at this point in the history
  • Loading branch information
@actions-user
actions-user committed Aug 14, 2024
1 parent 69e1f3b commit e39e104
Show file tree
Hide file tree
Showing 4 changed files with 70 additions and 91 deletions.
33 changes: 25 additions & 8 deletions accessing-packages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ exercises: 2

:::::::::::::::::::::::::::::::::::::: questions

- What are the different ways of downloading python packages?
- What are the different ways of downloading Python packages?
- What are package managers?
- How can I access my own package?

Expand Down Expand Up @@ -39,7 +39,7 @@ Some of the most popular packages you may have heard of are:

:::

To use a package that is installed you use the key word `import` in python.
To use a package that is installed you use the key word `import` in Python.

```python
# This imports the pandas package and gives it a new name 'pd'.
Expand All @@ -51,7 +51,7 @@ pd.read_csv("/my_data.csv")

## Python Package Index (PyPI)

The Python Package Index or PyPI is an online repository of Python packages hosting over 500,000 packages! While there are alternatives such as [conda-forge](https://conda-forge.org), PyPI is by far the most commonly used and likely to have all you need.
The Python Package Index or PyPI is an online repository of Python packages hosting over 500,000 packages! While there are alternatives such as [conda-forge](https://conda-forge.org), PyPI is by far the most commonly used and likely to have all you need.

::: challenge

Expand All @@ -72,7 +72,7 @@ You can think of PyPI being the supermarket full of packages and pip being the d

### Using pip

pip itself is a python package that can be found on [PyPI](https://pypi.org/project/pip/). It however comes preinstalled with most python installations, for example [python.org](https://python.org) and inside virtual environments.
pip itself is a Python package that can be found on [PyPI](https://pypi.org/project/pip/). It however comes preinstalled with most Python installations, for example [python.org](https://python.org) and inside virtual environments.

The most common way to use pip is from the command line. At the top of a package page on PyPI will be the example line you need to install the package

Expand All @@ -82,6 +82,10 @@ py -m pip install numpy

The above will install [numpy](https://pypi.org/project/numpy/) from PyPI, a popular scientific computing package enabling a wide range of mathematical and scientific functions.

::: callout
You may notice a wheel file download during the pip install, for example `Downloading numpy-2.0.0-cp312-cp312-win_amd64.whl`. A wheel in Python is a prebuilt package format that allows for quicker and more efficient installation, so when it is downloaded your local computer doesn't need to do any building. The alternative is source files which often take the form `.zip` or `.tar.gz`, which when downloaded will then need to be built then installed, which is often far slower.

:::

::: challenge
### Exercise 2: Create venv and install Numpy
Expand All @@ -103,6 +107,8 @@ Step 1: Create a venv in the .venv directory using the command `py -m venv .venv

:::

When activated you should see the name of your environment in brackets at the start of your terminal line

Step 2: Install Numpy into your new environment

Step 3: Check your results with `py -m pip list`
Expand All @@ -122,13 +128,24 @@ Check out [this documentation](https://docs.python.org/3/l[PyPI](https://pypi.or

pip can also be used to install packages from source. This means that the package file structure (source) is on your local computer and pip installs it using the instructions from the `setup.py` or `pyproject.toml` file. This is especially handy for packages either not on PyPI, like ones downloaded from github, or for your own packages you're developing.

```
py -m pip install .
```
::: tab

### Windows

`py -m pip install .`



### macOS / Linux

`python3 -m pip install .`


:::

::: instructor

The above command should be universal on both windows and mac/unix setups. It may be worth checking with the class at this point that they are all familiar with the -m notation, and what the above command does exactly
It may be worth checking with the class at this point that they are all familiar with the -m notation, and what the above command does exactly

:::

Expand Down
26 changes: 13 additions & 13 deletions creating-packages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ exercises: 2

## Introduction

This episode will see us creating our own Python project from scratch and installing it into a python virtual environment ready for use. Feel free if you're feeling adventurous to create your own package content or follow along with this example of a Fibonacci counter.
This episode will see us creating our own Python project from scratch and installing it into a Python virtual environment ready for use. Feel free if you're feeling adventurous to create your own package content or follow along with this example of a Fibonacci counter.


## Fibonacci Counter
Expand All @@ -43,7 +43,7 @@ In this section we will go through creating everything required for the package.
Think back to the earlier episodes and try to recall all the things that can go into a package.

::: solution
1. Python Module - This is the directory with the python code that does the work.
1. Python Module - This is the directory with the Python code that does the work.
2. Configuration File - e.g. your pyproject.toml file
3. Other metadata files - e.g. LICENCE, README.md, citation.cff
4. Python Tests - A directory full of unit-tests and other tests
Expand All @@ -61,12 +61,12 @@ In this episode we will only be creating a minimal example so many of the files
└── 📄 test_fibonacci.py
```

The first thing we will do in this project is create the python module (the actual code!).
The first thing we will do in this project is create the Python module (the actual code!).

::: challenge
### Creating Python module

1. Create a python file called `fibonacci.py` as shown in the structure above.
1. Create a Python file called `fibonacci.py` as shown in the structure above.
2. Add the following code which contains a function that returns the Fibonacci sequence
```python
def fibonacci(n_terms):
Expand All @@ -86,11 +86,11 @@ def fibonacci(n_terms):
::: challenge
### Using your Python module

Create a script in your project directory that imports and uses your fibonacci script. This will serve as a good quick test that it works.
Create a script in your project directory that imports and uses your Fibonacci script. This will serve as a good quick test that it works.

::: solution
1. Create the file in `/my_project`, for example `fibonacci_test.py`.
2. Import and run the fibonacci function:
2. Import and run the Fibonacci function:
```python
from my_package.fibonacci import fibonacci

Expand All @@ -110,9 +110,9 @@ requires = ["setuptools"]


[project]
name = "my_cool_package"
version = "0.0.0"
description = "A package to do awesome things"
name = "fibonacci"
version = "0.1.0"
description = "A package to calculate the fibonacci sequence"
dependencies = ["pandas", "numpy"]
```

Expand Down Expand Up @@ -147,7 +147,7 @@ requires = ["setuptools"]

[project]
name = "fibonacci"
version = "0.0.0"
version = "0.1.0"
description = "A package which can produce the Fibonacci sequence"
authors = [{name = "your_name", email="[email protected]"}]
keywords = ["fibonacci", "maths"]
Expand All @@ -162,16 +162,16 @@ Running `py -m pip install .` will install your package. Just ensure your termin
When installing your own package locally, there is an option called editable or `-e` for short.
`py -m pip install -e .`

With a default installation (without -e), any changes to your source package will only appear in your python environment when your package is rebuilt and reinstalled. The editable option allows for quick development of a package by removing that need to be reinstalled, for this reason it is sometimes called development mode!
With a default installation (without -e), any changes to your source package will only appear in your Python environment when your package is rebuilt and reinstalled. The editable option allows for quick development of a package by removing that need to be reinstalled, for this reason it is sometimes called development mode!



:::
::::::::::::::::::::::::::::::::::::: keypoints

- A package can be built with as little as 2 files, a python script and a configuration file
- A package can be built with as little as 2 files, a Python script and a configuration file
- pyproject.toml files have 2 key tables, [build-system] and [project]
- Editable instals allow for quick and easy package development
- Editable installs allow for quick and easy package development

::::::::::::::::::::::::::::::::::::::::::::::::

32 changes: 16 additions & 16 deletions md5sum.txt
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
"file" "checksum" "built" "date"
"CODE_OF_CONDUCT.md" "c93c83c630db2fe2462240bf72552548" "site/built/CODE_OF_CONDUCT.md" "2024-08-13"
"LICENSE.md" "b24ebbb41b14ca25cf6b8216dda83e5f" "site/built/LICENSE.md" "2024-08-13"
"config.yaml" "99a5351bb0a8b0e05a779040982b5791" "site/built/config.yaml" "2024-08-13"
"index.md" "a02c9c785ed98ddd84fe3d34ddb12fcd" "site/built/index.md" "2024-08-13"
"links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-08-13"
"episodes/introduction.md" "977c92fa5c60f351e4ead45bfab1c28d" "site/built/introduction.md" "2024-08-13"
"episodes/package-file-history.Rmd" "7e70e2133c8c61dbfaca95ec89604ce6" "site/built/package-file-history.md" "2024-08-13"
"episodes/accessing-packages.md" "03c8f19155f411b7e2e3f367cfcfef85" "site/built/accessing-packages.md" "2024-08-13"
"episodes/creating-packages.md" "a9bc106eca83a7d5b82c62305bb3e24c" "site/built/creating-packages.md" "2024-08-13"
"episodes/versioning.md" "425e206c183ea417ab4bd87e3d9f06a1" "site/built/versioning.md" "2024-08-13"
"episodes/releasing.md" "749f7c717f5e11bad56a83ea8eb2cc14" "site/built/releasing.md" "2024-08-13"
"instructors/instructor-notes.md" "cae72b6712578d74a49fea7513099f8c" "site/built/instructor-notes.md" "2024-08-13"
"learners/reference.md" "1c7cc4e229304d9806a13f69ca1b8ba4" "site/built/reference.md" "2024-08-13"
"learners/setup.md" "5456593e4a75491955ac4a252c05fbc9" "site/built/setup.md" "2024-08-13"
"profiles/learner-profiles.md" "60b93493cf1da06dfd63255d73854461" "site/built/learner-profiles.md" "2024-08-13"
"renv/profiles/lesson-requirements/renv.lock" "9c9ea44ada337fd87a90aef2338ce9ba" "site/built/renv.lock" "2024-08-13"
"CODE_OF_CONDUCT.md" "c93c83c630db2fe2462240bf72552548" "site/built/CODE_OF_CONDUCT.md" "2024-08-14"
"LICENSE.md" "b24ebbb41b14ca25cf6b8216dda83e5f" "site/built/LICENSE.md" "2024-08-14"
"config.yaml" "99a5351bb0a8b0e05a779040982b5791" "site/built/config.yaml" "2024-08-14"
"index.md" "a02c9c785ed98ddd84fe3d34ddb12fcd" "site/built/index.md" "2024-08-14"
"links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-08-14"
"episodes/introduction.md" "977c92fa5c60f351e4ead45bfab1c28d" "site/built/introduction.md" "2024-08-14"
"episodes/package-file-history.Rmd" "1fc0a28476cda1a085e13640221be727" "site/built/package-file-history.md" "2024-08-14"
"episodes/accessing-packages.md" "90ad8759dd7403dde1d482e294c849ff" "site/built/accessing-packages.md" "2024-08-14"
"episodes/creating-packages.md" "05027e4644983d3fdb6bb8cb39a4d399" "site/built/creating-packages.md" "2024-08-14"
"episodes/versioning.md" "425e206c183ea417ab4bd87e3d9f06a1" "site/built/versioning.md" "2024-08-14"
"episodes/releasing.md" "749f7c717f5e11bad56a83ea8eb2cc14" "site/built/releasing.md" "2024-08-14"
"instructors/instructor-notes.md" "cae72b6712578d74a49fea7513099f8c" "site/built/instructor-notes.md" "2024-08-14"
"learners/reference.md" "1c7cc4e229304d9806a13f69ca1b8ba4" "site/built/reference.md" "2024-08-14"
"learners/setup.md" "5456593e4a75491955ac4a252c05fbc9" "site/built/setup.md" "2024-08-14"
"profiles/learner-profiles.md" "60b93493cf1da06dfd63255d73854461" "site/built/learner-profiles.md" "2024-08-14"
"renv/profiles/lesson-requirements/renv.lock" "9c9ea44ada337fd87a90aef2338ce9ba" "site/built/renv.lock" "2024-08-14"
70 changes: 16 additions & 54 deletions package-file-history.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: 'Package File History'
teaching: 10
exercises: 2
exercises: 1
editor_options:
markdown:
wrap: 100
Expand Down Expand Up @@ -31,8 +31,7 @@ This is to both build an understanding of why the current standard is what it is

1. requirements.txt
2. setup.py
3. setup.cfg
4. pyproject.toml
3. pyproject.toml

:::

Expand All @@ -58,11 +57,15 @@ Before the introduction of `pyproject.toml` the main tool supported for installi

Q: Discuss with each other what problems if any you think there may be with using a python file to create python packages

`Hint: Think about the differences between a code file and a text file`
::: hint
### Hint

Think about the differences between a code file and a text file
:::

::: solution

Some potential issues are:

1. As `setup.py` is a code file, there is a potential for malicious code to be hidden in them if the file comes from an untrusted source
2. There is quite a bit of 'boilerplate' in each file
3. The syntax has to be precise and may be confusing to those not familiar with Python
Expand All @@ -74,66 +77,20 @@ Some potential issues are:
from setuptools import setup

setup(
name='my_cool_package',
name='fibonacci',
version='1.0.0',
description='A package to do awesome things',
description='A package to calculate the fibonacci sequence',
long_description=open('README.md').read(),
author='John Doe',
author_email='[email protected]',
license='MIT',
)
```

## Setup.cfg

To tackle some of the problems with `setup.py`, another standard file was introduced called `setup.cfg` (cfg stands for config).

The task of a `setup.cfg` file is to declare metadata and settings required for a package in a simple manner. Unlike a setup.py which requires code imports and functions, the `setup.cfg` only has headers and key value pairs.

::: callout
### Key Value Pair

A key value pair is a fundamental way of storing data which is used across many languages and formats. Here's how it works:

- Key: Is the unique identifier, like the label on a file in a filing cabinet
- Value: Is the actual data that needs storing. It can be a number, text or many other things.

An example would be name = Jane

:::

```
[metadata]
name = my_cool_package
description = A package to do awesome things
long_description = file: README.md
author = John Doe
author_email = [email protected]
keywords = data, analysis, python
license = MIT
[options]
# Specify libraries your project needs (dependencies)
install_requires = pandas numpy
# Python version compatibility (optional)
python_requires = >=3.7
```

When using a `setup.cfg` however, a dummy `setup.py` was still required to build the package. This looked like:

```python
from setuptools import setup

if __name__ == "__main__":
setup()
```

## Pyproject.toml

Introduced in (PEP517)[https://peps.python.org/pep-0517/], the latest file for packaging a python project is the `pyproject.toml` file.
Like a `.cfg` file, a `toml` file is designed to be easy to read and declarative.
Like a `.cfg` file, a `toml` file is designed to be easy to read and declarative. It is the current recommended way to package your Python

::: callout
TOML stands for Tom's Obvious Minimal Language!
Expand Down Expand Up @@ -170,3 +127,8 @@ dependencies = ["pandas", "numpy"]
[tool.black]
line-length = 98
```

::: keypoints
- pyproject.toml files are the current recommended packaging file for Python
- other standards are still used and you may come across them
:::

0 comments on commit e39e104

Please sign in to comment.