Restructure and update README-md

Author: marvinfriede

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
 
     runs-on: ${{ matrix.os }}
 

.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "[python]": {
+    "editor.detectIndentation": false,
+    "editor.formatOnSave": true,
+    "editor.formatOnPaste": false, // not supported by black
+    "editor.insertSpaces": true,
+    "editor.tabSize": 4
+  },
+  "python.analysis.diagnosticSeverityOverrides": {
+    "reportPrivateImportUsage": "information"
+  },
+  "python.defaultInterpreterPath": "${env:CONDA_PREFIX}/envs/base/bin/python",
+  "python.formatting.provider": "black",
+  "python.linting.enabled": true,
+  "python.linting.pylintEnabled": true,
+  "python.linting.pylintArgs": ["--indent-string='    '"],
+  "python.testing.pytestArgs": [],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true
+}

README.md

@@ -64,23 +64,43 @@ Finally, some handy features of pytest you should be aware of:
 
 - fixtures: common setup for multiple tests (e.g., reading file or database connection)
 - parametrize: multiple test cases for single function
-- expected fails: testing if the code handles wrong inputs (`pytest.raises(Exception)` or `@pytest.mark.xfail`)
+- expected fails: testing if the code handles wrong inputs (`with pytest.raises(Exception): ...` or `@pytest.mark.xfail`)
+- check for [test pollution](https://github.com/asottile/detect-test-pollution) by randomizing the order of tests ([pytest-plugin](https://pypi.org/project/pytest-random-order/))
 
 <br>
 
-Further links:
+## Setup files and Packaging
 
-- check for [test pollution](https://github.com/asottile/detect-test-pollution) by randomizing the order of tests ([pytest-plugin](https://pypi.org/project/pytest-random-order/))
+Packaging is done with [`setuptools`](https://setuptools.pypa.io/en/latest/index.html), which is configured through the `pyproject.toml` and/or `setup.cfg`/`setup.py` files.
 
-<br>
+<details><summary>`pyproject.toml` vs. `setup.cfg` vs `setup.py`</summary>
 
-## Setup files and Packaging
+The `setup.py` file is a Python script and configuration is passed through keyword arguments of `setuptools.setup()`. This is not recommended due to possible security and parsing issues. The same setup can be accomplished in a declarative style within `setup.cfg` and `setup.py` remains mostly empty only calling `setuptools.setup()`.
+The `pyproject.toml` file aims to unify configuration files including various tools like black or pytest. For packaging, it is very similar to `setup.cfg`. However, `pyproject.toml` has not been adopted as the default yet and many projects still use `setup.cfg` to declare the packaging setup. Note that `setup.py` is not necessary if a `pyproject.toml` is present.
 
-...
+</details>
 
-Additional points:
-- `setup.py` is not necessary if `pyproject.toml` is present
+#### `pyproject.toml`
+
+- minimal build specification to use with setuptools
+- configuration of other tools (black, pytest, mypy, ...)
+
+[](https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#using-a-src-layout)
+
+#### [`setup.cfg`](https://setuptools.pypa.io/en/latest/userguide/declarative_config.html)
+
+- declarative configuration for setuptools
+- [_metadata_](https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#metadata): must at least contain _name_ and _version_
+- [_options_](https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#options): package discovery, dependencies
+  - [additional setup](https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#using-a-src-layout) required for `src/` layout
+- [_options.extras_require_](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies): optional dependencies (dev tools, docs, ...)
+- [_options.package_data_](https://setuptools.pypa.io/en/latest/userguide/datafiles.html#package-data): inclusion of other, non-Python files (marker files, data, ...)
+  - alternative: `MANIFEST.in`
+- [_options.entry_points_](https://setuptools.pypa.io/en/latest/userguide/entry_point.html): entry point for command line interface
+
+<br>
 
+The package can be installed with `pip install .` or something like `pip install .[dev]` to also install additional dependencies specified in `setup.cfg`'s _options.extras_require_. Pass the `-e` flag for editable mode, which loads the package from the source directory, i.e., changing the source code does not require a new installation.
 
 <br>
 

environment.yaml

@@ -3,4 +3,10 @@ channels:
   - defaults
   - conda-forge
 dependencies:
+  - black
   - numpy
+  - pre-commit
+  - pylint
+  - pytest
+  - pytest-cov
+  - tox

setup.cfg

@@ -24,11 +24,14 @@ package_dir =
 
 [options.packages.find]
 where = src
-exclude = test
+exclude =
+    test*
+    docs*
+    examples*
 
 [options.entry_points]
 console_scripts =
-    squarer = squarer:main
+    squarer = squarer.cli:console_entry_point
 
 [options.extras_require]
 dev =
@@ -39,3 +42,7 @@ dev =
     pytest
     pytest-cov
     tox
+
+[options.package_data]
+squarer =
+    py.typed

src/squarer/__init__.py

@@ -1,30 +1,10 @@
 """
-Entry point for command line interface.
-"""
-
-from __future__ import annotations
+Squarer
+=======
 
-import argparse
-import sys
-from collections.abc import Sequence
+Dummy command line tool to square a number.
+"""
 
 from .__version__ import __version__
+from .cli import console_entry_point
 from .maths import square_a_number as square
-
-__all__ = ["__version__", "maths", "square"]
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    # get command line argument
-    parser = argparse.ArgumentParser()
-    parser.add_argument("number", type=float, help="Number to square.")
-    args = parser.parse_args(argv)
-
-    # print result
-    print(square(args.number))
-
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/squarer/__main__.py

@@ -2,9 +2,7 @@
 Entry point for command line interface via `python -m <prog>`.
 """
 
-import sys
-
-from . import main
+from .cli import console_entry_point
 
 if __name__ == "__main__":
-    sys.exit(main())
+    raise SystemExit(console_entry_point())

src/squarer/cli/__init__.py

@@ -0,0 +1,8 @@
+"""
+Command line interface
+======================
+
+This module contains functionality for the CLI.
+"""
+
+from .entrypoint import console_entry_point

src/squarer/cli/entrypoint.py

@@ -0,0 +1,22 @@
+"""
+Entrypoint for command line interface.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from ..maths import square_a_number as square
+
+
+def console_entry_point(argv: Sequence[str] | None = None) -> int:
+    # get command line argument
+    parser = argparse.ArgumentParser()
+    parser.add_argument("number", type=float, help="Number to square.")
+    args = parser.parse_args(argv)
+
+    # print result
+    print(square(args.number))
+
+    return 0

src/squarer/maths/__init__.py

@@ -1 +1,8 @@
+"""
+Math
+====
+
+This module contains all mathematical functions.
+"""
+
 from .calc import square_a_number