decribe minimal package

README.md

@@ -1,2 +1,103 @@
-# packagehowto
+# Package HowTo
+
+This is a brief introduction to python packages. How to make them, how
+to install them, how to upload them, how to maintain them, how to work
+with them. For details consult https://packaging.python.org and other
+sites.
+
+
+## Why packages?
+
+When working on your project, you typically end up with some scripts,
+functions and classes that are of more general interest. As a first
+step, you make some modules, i.e. separate python files, where you
+collect this code. These modules can be easily imported from other
+scripts in the very same directory.
+
+For example, consider a module `addition.py` and a script `anayze.py`
+both in the same directory:
+```txt
+├── addition.py
+└── analyze.py
+```
+
+In `addition.py` we define a function `add_two()`:
+```
+def add_two(x):
+    return x + 2
+```
+
+We can use this function in `analyze.py` by importing it from
+`addition.py`:
+```
+from addition import add_two
+
+x = 5
+y = add_two(x)
+```
+
+This works, however, only if scripts and modules are in the same
+directory (or if modules are in sub-directories). To make modules
+available in other places of your file system or for even for other
+people, you need to turn the modules into packages.
+
+
+## Minimal package
+
+First we make a project directory for our new package. Usually the
+name of the project directory is the same as the one of the
+package. Here, however, we called `packagehowto` and the name of the
+package is `numerix`.
+
+A package is a directory, and the name of the package is the name of
+this directory, here `numerix`. Inside the package directory we put
+all the modules, here `addition.py`.
+
+What makes this directory a package is the presence of a file named
+`__init__.py`. This file is executed when the package is imported. For
+now we leave it empty.
+
+The package directory resides in the `src/` directory of the project:
+```txt
+packagehowto/
+├── pyproject.toml
+└── src/
+    └── numerix
+        ├── __init__.py
+        └── addition.py
+```
+
+A package also needs a `pyproject.toml` file. This file contains some
+metadata about hte package and informations about how to build a
+package. As the bare minimum the content of the `pyproject.toml` file
+specifies `setuptools` to be used for building the project:
+
+```txt
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+```
+
+With this `pyproject.toml` file, and `addition.py` and `__init__.py`
+in the `src/numerix` directory, you can install the `numerix` package
+on your machine and import it from whereever you want.
+
+For installation go to the project root, here `packagehowto/` and run
+from your shell
+```sh
+pip3 install .
+```
+This installs the package of the current project folder `.` somewhere
+in your home directory. From anywhere in your home directory you now
+can import this package. The import line of our `analyze.py` file
+needs to look like this:
+```
+from numerix.addition import add_two
+```
+From the addition module of the numerix package the function add_two
+is imported.
+
+
+
+
 

analyze.py

@@ -0,0 +1,3 @@
+from numerix.addition import add_two
+
+print(add_two(5))