Basic Packaging =============== Unlike Parts 1–3, nothing is generated for you here — you build the whole thing by hand, which is the point: by the end you'll have created every piece the earlier templates handed you for free. Set up the starting point -------------------------- #. Create a project on ``git.tu-berlin.de`` exactly as in :doc:`../../part1-git-basics/tasks` Task 1 (untick "Initialize repository with a README"). Call it something like ``number-magic``. #. On your own machine, create a folder to work in and move into it: .. code-block:: none cd %USERPROFILE%\projects # Windows mkdir number_magic_project cd number_magic_project .. code-block:: none cd ~/projects # macOS/Linux mkdir number_magic_project cd number_magic_project Throughout these tasks this folder is referred to as ``some_directory`` — it's your project root, the folder everything else goes inside. #. Open it in PyCharm, then create a file called ``number_magic.py`` (right-click the folder → **New → File**; see :doc:`../../prerequisites`) and paste in: .. code-block:: python :caption: number_magic.py def addition(arg1, arg2): """ This function adds the first and the second argument. :param arg1: the first summand :type arg1: float :param arg2: the second and last summand :type arg2: float :return: the sum of both summands :rtype: float """ return arg1 + arg2 #. Make it a git repository and connect it to GitLab: .. code-block:: none git init git add . git commit -m "Add the number_magic function" git remote add origin git@git.tu-berlin.de:kiwi-git-workshops/your-project.git git branch -M main git push -u origin main From here on, keep using the branch → commit → merge request workflow from Part 1 for each step below. Make it a package ----------------- Right now this is just a plain Python file. To turn it into a **package** (something that can be imported by name), you need to put it in a folder and add an ``__init__.py`` file to that folder, which may be empty. .. important:: The filename is ``__init__.py`` — that's **two** underscores before and after ``init``. It's easy to miscount; if the import below fails, check this first. Create a folder called ``plain_magic``, move ``number_magic.py`` into it (drag it in PyCharm), and add an empty ``__init__.py`` next to it. You should have: .. code-block:: none some_directory/ plain_magic/ __init__.py number_magic.py Try it. In a terminal, in ``some_directory``, start Python's interactive interpreter — a prompt where you type Python code line by line and see the result immediately — by running ``python`` with no arguments: .. code-block:: none python # Windows ('python3' on macOS/Linux) The prompt changes to ``>>>``, meaning you're now typing Python rather than shell commands. Try importing your package: .. code-block:: python import plain_magic **How do you know it worked?** Nothing happens — you just get a fresh ``>>>`` prompt. That silence means success. A *failure* looks like this:: >>> import plain_magic Traceback (most recent call last): File "", line 1, in ModuleNotFoundError: No module named 'plain_magic' .. note:: To get back out of the Python interpreter to your normal terminal, type ``exit()`` and press Enter (Ctrl+Z then Enter also works on Windows, Ctrl+D on macOS/Linux). If your prompt still shows ``>>>``, shell commands like ``cd`` won't work. Enable Installations -------------------- Check Package Import ____________________ The package only imports while you're sitting in the folder above it, which isn't much use. See the problem for yourself — leave the interpreter, move somewhere else, and try again: .. code-block:: none cd %USERPROFILE% # Windows ('cd ~' on macOS/Linux) python .. code-block:: python import plain_magic This time it *should* fail with ``ModuleNotFoundError``. That's the problem installing solves. Type ``exit()`` and head back to your project: .. code-block:: none cd %USERPROFILE%\projects\number_magic_project Create a pyproject.toml _______________________ ``pyproject.toml`` is the file that tells Python's packaging tools how to build and install your code. Create it in ``some_directory`` (**not** inside ``plain_magic``) with this content: .. code-block:: toml :caption: pyproject.toml [build-system] requires = ["setuptools>=68"] build-backend = "setuptools.build_meta" [project] name = "plain_magic" version = "0.0.1" description = "A small package to practise packaging" requires-python = ">=3.10" dependencies = [] [tool.setuptools.packages.find] exclude = ["tests*"] A few things worth understanding rather than just copying: * ``[build-system]`` names the tool that does the building (``setuptools``). You rarely change this. * ``name`` is what the package is called when installed; keep it the same as your package folder to avoid confusion. * ``dependencies`` lists other packages yours needs — empty for now, but you'll add ``click`` shortly. * ``[tool.setuptools.packages.find]`` tells setuptools which folders are part of the package. The ``exclude`` line matters later: once you add a ``tests/`` folder in the next chapter, without it the build fails with ``Multiple top-level packages discovered in a flat-layout``. For a fuller reference on each field, see the `Kiwi template documentation `_. How can you check if you succeeded? ____________________________________ Install it and import it from somewhere else. First create and activate a virtual environment for the project (see :doc:`../../prerequisites`), then install: .. code-block:: none python -m venv .venv # Windows .venv\Scripts\Activate.ps1 pip install -e . .. code-block:: none python3 -m venv .venv # macOS/Linux source .venv/bin/activate pip install -e . **How do you know it worked?** The output ends with ``Successfully installed plain_magic-0.0.1``. Now repeat the `Check Package Import`_ experiment: ``cd`` somewhere else, run ``python``, and ``import plain_magic``. This time it succeeds from anywhere. .. important:: Keep the virtual environment active while you do this — the package was installed *into* that environment, so it's only importable while your prompt shows ``(.venv)``. Opening a fresh terminal means activating it again; a ``ModuleNotFoundError`` here usually means you forgot. Your project should now look like this: .. code-block:: none some_directory/ plain_magic/ __init__.py number_magic.py pyproject.toml Write a Command Line Interface ------------------------------ Now we want to use the package from the command line, like this: .. code-block:: none some-magic-cmd adding-two-numbers --first-summand 1 --second-summand 2 This takes two pieces. First, create ``cli.py`` inside ``plain_magic``: .. code-block:: python :caption: plain_magic/cli.py import click from plain_magic.number_magic import addition @click.group() def cli_group(): pass @cli_group.command() @click.option('--first-summand', type=float, required=True) @click.option('--second-summand', type=float, required=True) def adding_two_numbers(first_summand, second_summand): click.echo(f'The sum is {addition(first_summand, second_summand)}') The ``@click.command()`` and ``@click.option(...)`` lines above the function are *decorators* — they tell the `click `_ library to expose this plain Python function as a command with those options. Second, tell your package that this should become a real terminal command, by adding two sections to ``pyproject.toml``: .. code-block:: toml dependencies = ["click"] [project.scripts] some-magic-cmd = "plain_magic.cli:cli_group" The ``[project.scripts]`` entry is called an **entry point**: it maps the command name on the left to the function on the right (read ``plain_magic.cli:cli_group`` as "the ``cli_group`` function in the ``plain_magic.cli`` module"). .. important:: Entry points are wired up **at install time**, so you must re-run: .. code-block:: none pip install -e . This is the one thing an editable install doesn't pick up automatically. Editing the *body* of an existing command takes effect immediately; adding a *new* command, or changing its name, needs a reinstall. **How do you know it worked?** .. code-block:: none some-magic-cmd adding-two-numbers --first-summand 1 --second-summand 2 prints ``The sum is 3.0``. Also try ``some-magic-cmd --help``, which lists the available commands. If you get ``command not found``, check your virtual environment is active and that you re-ran ``pip install -e .``. For a reference implementation, see `the template package `_. Your project should now look like this: .. code-block:: none some_directory/ plain_magic/ __init__.py cli.py number_magic.py pyproject.toml