source commit: 9ce029c

Author: actions-user

1_intoduction_python_packaging.md

@@ -0,0 +1,101 @@
+---
+title: "Why Python Packages?"
+teaching: 15
+exercises: 5
+---
+
+:::::::::::::::::::::::::::::::::::::: questions
+
+- Why must we package our Python code?
+- What precisely may be packaged?
+- Why is __init_.py file important?
+- What is the Python Package Index (PyPI), and what purpose does it serve?
+- What is a build?
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- To understand the benefits of Python packaging.
+- To determine whether packaging is suitable for your use case.
+- To understand the importance of __init_.py file.
+- To acquire knowledge of components of Python packaging and understand Python Package Index (PyPI).
+- To become familiar with the build process.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+<img width="983" height="974" alt="image" src="https://github.com/user-attachments/assets/5df6c1a0-bee9-4b38-99e3-725ada1b5d3c" />
+ Ref : https://xkcd.com/1987/
+
+ 
+## Introduction
+Software development is a creative pursuit, and it is satisfying to write code that solves interesting problems. However, once our code is ready, how can we share it globally? This course provides instruction in how to distribute Python code using Pixi. You might liken a package to the old-style setup.exe: a standardised method of distributing software.
+
+By packaging code, you address several important challenges, including ensuring reproducibility, achieving cross-platform compatibility, and supporting multiple environments. Distributing code as a package offers many advantages over merely sharing source files, for example via GitHub:
+
+- Dependency management: A package can explicitly declare its dependencies. Tools such as pip (or uv) can then automatically install them for the user.
+- Versioning: You may version your package and distribute multiple versions, thereby supporting backwards compatibility.
+- Standardisation: Packaging is the established method of distributing code via recognised repositories such as PyPI and conda forge.
+- Metadata: Packages include project-specific metadata, which is essential for end users.
+
+## Python Package Structure Hierarchy
+
+- Function : A block of reusable code that performs a single specific task.
+- Module : A single Python file (.py) that groups related classes,  functions and variables.
+- Package : A folder/ collection containing multiple modules and an __init__.py file to organize them.
+- The __init__.py files are required to make Python treat folders containing the file as packages
+- Library : A collection of related packages or modules that provide broad functionality for reuse.
+- Library can have Package(s), which can have module(s) which can have function(s). It can also be considered a Project.
+- Python package : A Python package is a collection of related code modules (files) bundled with metadata describing how the package should be installed and used [*](https://pydevtools.com/handbook/explanation/what-is-a-python-package/)
+
+<img width="371" height="659" alt="image" src="https://github.com/user-attachments/assets/32c036e1-246a-4f4c-9072-97bfb39376a7" />
+
+
+[GIT](https://github.com/psf/requests)
+[PyPI](https://pypi.org/project/requests/ )
+
+## Steps to create a Python Package :
+
+<img width="1298" height="250" alt="image" src="https://github.com/user-attachments/assets/be6f94ec-599b-4a1e-bd5b-63c2dfad720c" />
+
+
+## What may be packaged ?
+
+Any .py files (modules) or directories with __init__.py (packages) can be packaged.
+
+
+## What is __init__.py file in Python?
+The __init__.py file (aka dunder init)  is a Python file that is executed when a package is imported.
+It serves two main purposes:
+
+- It marks the directory as a Python Package so that the interpreter can find the modules inside it.
+- It can contain initialization code for the Package, such as importing submodules, defining variables, or executing other code.
+
+  [source](https://www.geeksforgeeks.org/python/what-is-__init__-py-file-in-python/)
+
+## What is PyPI
+
+[PyPI](https://pypi.org/) is the repository where all released Python packages are made available for end users.
+There is also [TestPyPI](https://test.pypi.org/), a repository which allows us to experiment with distribution tools and procedures without affecting the live PyPI. In this course, we will publish our package to TestPyPI.
+You can search PyPI for existing packages to use in your project instead of creating a new one. To make your package easily discoverable, it’s important to provide correct metadata and appropriate [classifiers](https://pypi.org/classifiers/).
+
+## What is a Build ?
+
+A build is the process by which your project’s source code is transformed into a distributable format. These build artefacts can then be installed using tools such as `pip`.
+ A build may be created using the command in the terminal : 
+ ```bash
+python -m build
+```
+ The successful build process produces files such as a **wheel** (`.whl`) or a **source archive** (`.tar.gz`), which can be installed via `pip` or uploaded to PyPI. It is vital to version your build and supply the requisite metadata.
+
+**Please note**: There are several tools and backends available for building Python packages.
+
+::::::::::::::::::::::::::::::::::::: keypoints
+
+- To make Python code installable, reusable and distributable via PyPI or TestPyPI, one must package the code.
+- The Package should have modules (.py file(s)) and __init__.py file.
+- The code must be versioned.
+- Project dependencies must be managed.
+- The project’s metadata must be clearly defined.
+
+::::::::::::::::::::::::::::::::::::::::::::::::

2_why_pixi.md

@@ -0,0 +1,67 @@
+---
+title: "Why choose Pixi for Python Packaging ?"
+teaching: 5
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions
+
+- Why use Pixi?
+- What are the benefits of Pixi ?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- To understand the advantages offered by Pixi.
+-  To learn about `pixi.toml` and `pyproject.toml`
+-  To understand the role of `pixi.lock`.
+-  To explore the concept of multi-environment support.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Introduction
+
+Pixi is a fast, modern and reproducible package management tool. It has lots of [features](https://pixi.sh/latest/#what-is-the-difference-with-pixi) which are not all present in a single tool at this point in time. Read [here](https://pixi.sh/latest/concepts/conda_pypi/#tool-comparison). These capabilities make Pixi an attractive choice for managing Python and multi-language projects.
+
+Key features include:
+
+- **Support for both PyPI and Conda packages**: enabling flexibility in sourcing dependencies.
+- **Performance**: lightweight and modern, designed for speed.
+- **Multi-language dependency management**: e.g. Python with Rust, or Python with C/C++.
+- **Integration with `uv`**: leveraging a high-performance package installer.
+- **Reproducibility**: guaranteed through the use of `pixi.lock`.
+- **Configuration via TOML files**: supports both `pixi.toml` and `pyproject.toml`.
+   
+## Configuration files (`pixi.toml` and `pyproject.toml`)
+
+`pixi.toml`: The configuration file used by Pixi to define environments, dependencies, and tasks.
+`pyproject.toml`: A standard configuration file within the Python ecosystem (PEP 518/621). It is required by build tools such as Poetry, Hatch, Flit, and setuptools. This file specifies project metadata (e.g. name, version, author) as well as dependencies and build settings.
+
+## Multi-environment support
+
+Pixi allows you to define dependencies for specific operating systems (e.g. Windows, macOS, Linux) or for distinct environments such as development, testing, and production. This makes it easier to tailor the project configuration to match the context in which the software is being deployed or developed.
+
+## pyproject.toml
+For this demo, we will mainly focus on `pyproject.toml` file.
+We make this choice due to following specifications and recomendations : [PEP 621](https://peps.python.org/pep-0621/), [PEP 517](https://peps.python.org/pep-0517/), and [PEP 660](https://peps.python.org/pep-0660/).
+
+You can also read at these links: 
+
+- https://pixi.sh/v0.40.1/reference/pixi_manifest/#pypi-dependencies
+- https://pixi.sh/v0.40.1/advanced/pyproject_toml/
+  
+## envs 
+Pixi automatically manages project environments. When you initialize the project with `pixi init`, it creates the project configuration, and the environment is automatically set up when you install dependencies or run tasks.
+
+## dependency management
+When you add a package via Pixi (`pixi add <package>`), it updates the project configuration (`pyproject.toml` or `pixi.toml`) and generates or updates the `pixi.lock` file, recording the exact version and source to ensure reproducible environments.
+
+
+::::::::::::::::::::::::::::::::::::: keypoints
+
+- Choose a tool with good support and long term vision.
+- Choose a tool suitable for your project.
+- Focus on  PEP specifications and recomendations.
+  
+::::::::::::::::::::::::::::::::::::::::::::::::