funktionsklempner 1.0.0__tar.gz

funktionsklempner-1.0.0/.gitlab-ci.yml

@@ -0,0 +1,22 @@
+# You can override the included template(s) by including variable overrides
+# SAST customization: https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings
+# Secret Detection customization: https://docs.gitlab.com/user/application_security/secret_detection/pipeline/configure
+# Dependency Scanning customization: https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#customizing-the-dependency-scanning-settings
+# Container Scanning customization: https://docs.gitlab.com/ee/user/application_security/container_scanning/#customizing-the-container-scanning-settings
+# Note that environment variables can be set in several places
+# See https://docs.gitlab.com/ee/ci/variables/#cicd-variable-precedence
+:stages:
+- test
+:sast:
+  :stage: test
+:include:
+- :template: Security/SAST.gitlab-ci.yml
+stages:
+- test
+- secret-detection
+variables:
+  SECRET_DETECTION_ENABLED: 'true'
+secret_detection:
+  stage: secret-detection
+include:
+- template: Security/Secret-Detection.gitlab-ci.yml

funktionsklempner-1.0.0/LICENSE

@@ -0,0 +1,287 @@
+                      EUROPEAN UNION PUBLIC LICENCE v. 1.2
+                      EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined
+below) which is provided under the terms of this Licence. Any use of the Work,
+other than as authorised under this Licence is prohibited (to the extent such
+use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work:
+
+        Licensed under the EUPL
+
+or has expressed by any other means his willingness to license under the EUPL.
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+- ‘The Licence’: this Licence.
+
+- ‘The Original Work’: the work or software distributed or communicated by the
+  Licensor under this Licence, available as Source Code and also as Executable
+  Code as the case may be.
+
+- ‘Derivative Works’: the works or software that could be created by the
+  Licensee, based upon the Original Work or modifications thereof. This Licence
+  does not define the extent of modification or dependence on the Original Work
+  required in order to classify a work as a Derivative Work; this extent is
+  determined by copyright law applicable in the country mentioned in Article 15.
+
+- ‘The Work’: the Original Work or its Derivative Works.
+
+- ‘The Source Code’: the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+- ‘The Executable Code’: any code which has generally been compiled and which is
+  meant to be interpreted by a computer as a program.
+
+- ‘The Licensor’: the natural or legal person that distributes or communicates
+  the Work under the Licence.
+
+- ‘Contributor(s)’: any natural or legal person who modifies the Work under the
+  Licence, or otherwise contributes to the creation of a Derivative Work.
+
+- ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+
+- ‘Distribution’ or ‘Communication’: any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright vested
+in the Original Work:
+
+- use the Work in any circumstance and for all usage,
+- reproduce the Work,
+- modify the Work, and make Derivative Works based upon the Work,
+- communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case may
+  be, the Work,
+- distribute the Work or copies thereof,
+- lend and rent the Work or copies thereof,
+- sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make effective
+the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to
+any patents held by the Licensor, to the extent necessary to make use of the
+rights granted on the Work under this Licence.
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates, in
+a notice following the copyright notice attached to the Work, a repository where
+the Source Code is easily and freely accessible for as long as the Licensor
+continues to distribute or communicate the Work.
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits from
+any exception or limitation to the exclusive rights of the rights owners in the
+Work, of the exhaustion of those rights or of other applicable limitations
+thereto.
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices and a
+copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will be
+done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of the
+Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions on
+the Work or Derivative Work that alter or restrict the terms of the Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed under
+a Compatible Licence, this Distribution or Communication can be done under the
+terms of this Compatible Licence. For the sake of this clause, ‘Compatible
+Licence’ refers to the licences listed in the appendix attached to this Licence.
+Should the Licensee's obligations under the Compatible Licence conflict with
+his/her obligations under this Licence, the obligations of the Compatible
+Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the Work,
+the Licensee will provide a machine-readable copy of the Source Code or indicate
+a repository where this Source will be easily and freely available for as long
+as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade names,
+trademarks, service marks, or names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright in the Original Work granted
+hereunder is owned by him/her or licensed to him/her and that he/she has the
+power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright in the modifications he/she brings
+to the Work are owned by him/her or licensed to him/her and that he/she has the
+power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under the
+terms of this Licence.
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+‘bugs’ inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an ‘as is’ basis
+and without warranties of any kind concerning the Work, including without
+limitation merchantability, fitness for a particular purpose, absence of defects
+or errors, accuracy, non-infringement of intellectual property rights other than
+copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a condition
+for the grant of any rights to the Work.
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural
+persons, the Licensor will in no event be liable for any direct or indirect,
+material or moral, damages of any kind, arising out of the Licence or of the use
+of the Work, including without limitation, damages for loss of goodwill, work
+stoppage, computer failure or malfunction, loss of data or any commercial
+damage, even if the Licensor has been advised of the possibility of such damage.
+However, the Licensor will be liable under statutory product liability laws as
+far such laws apply to the Work.
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional agreement,
+defining obligations or services consistent with this Licence. However, if
+accepting obligations, You may act only on your own behalf and on your sole
+responsibility, not on behalf of the original Licensor or any other Contributor,
+and only if You agree to indemnify, defend, and hold each Contributor harmless
+for any liability incurred by, or claims asserted against such Contributor by
+the fact You have accepted any warranty or additional liability.
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon ‘I agree’
+placed under the bottom of a window displaying the text of this Licence or by
+affirming consent in any other similar way, in accordance with the rules of
+applicable law. Clicking on that icon indicates your clear and irrevocable
+acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this Licence,
+such as the use of the Work, the creation by You of a Derivative Work or the
+Distribution or Communication by You of the Work or copies thereof.
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of electronic
+communication by You (for example, by offering to download the Work from a
+remote location) the distribution channel or media (for example, a website) must
+at least provide to the public the information requested by the applicable law
+regarding the Licensor, the Licence and the way it may be accessible, concluded,
+stored and reproduced by the Licensee.
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon
+any breach by the Licensee of the terms of the Licence.
+
+Such a termination will not terminate the licences of any person who has
+received the Work from the Licensee under the Licence, provided such persons
+remain in full compliance with the Licence.
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make it
+valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions of
+this Licence or updated versions of the Appendix, so far this is required and
+reasonable, without reducing the scope of the rights granted by the Licence. New
+versions of the Licence will be published with a unique version number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+- any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the Court
+  of Justice of the European Union, as laid down in article 272 of the Treaty on
+  the Functioning of the European Union,
+
+- any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive jurisdiction
+  of the competent court where the Licensor resides or conducts its primary
+  business.
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+- this Licence shall be governed by the law of the European Union Member State
+  where the Licensor has his seat, resides or has his registered office,
+
+- this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+
+- GNU General Public License (GPL) v. 2, v. 3
+- GNU Affero General Public License (AGPL) v. 3
+- Open Software License (OSL) v. 2.1, v. 3.0
+- Eclipse Public License (EPL) v. 1.0
+- CeCILL v. 2.0, v. 2.1
+- Mozilla Public Licence (MPL) v. 2
+- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+- European Union Public Licence (EUPL) v. 1.1, v. 1.2
+- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong
+  Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the above
+licences without producing a new version of the EUPL, as long as they provide
+the rights granted in Article 2 of this Licence and protect the covered Source
+Code from exclusive appropriation.
+
+All other changes or additions to this Appendix require the production of a new
+EUPL version.

funktionsklempner-1.0.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: funktionsklempner
+Version: 1.0.0
+Summary: Plumbing C++ with a Python frontend via ctypes.
+Author-Email: =?utf-8?q?Malte_J=C3=B6rn_Ziebarth?= <malte.ziebarth@tum.de>
+Maintainer-Email: =?utf-8?q?Malte_J=C3=B6rn_Ziebarth?= <malte.ziebarth@tum.de>
+License-Expression: EUPL-1.2
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11.4
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# Funktionsklempner
+A library and framework for plumbing C++ code to Python via ctypes.
+
+Why ctypes? It has the advantage of being widely available with Python itself, and interfaces C ABIs that can remain stable for long periods of time. This way, a compiled library can work across many different Python versions in which a dynamically linked extension would have to be recompiled due to binary incompatibility. The maintenance burden due to the recurring need to recompile packages is reduced. This comes at the cost of the additional overhead for having to pipe data through a C/ctypes API. Funktionsklempner generates this wrapping code automatically, which reduces the cost to the computational overhead. You may find Funktionsklempner useful for your open source project with low version iteration rate.
+
+Funktionsklempner's basic workflow is as follows:
+
+   1. Declare the interface in a C++ header (i.e. functions whose equivalents shall be
+      passed through to the Python world).
+   2. Declare all such headers in a project-wide `funktionsklempner.toml` file.
+   3. Generated wrapper source files via the `funktionsklempner` command.
+   4. Check the generated wrapper files and check them into your version control
+      system.
+   5. Keep the auto-generated files updated via a git pre-commit hook.
+
+
+## Usage
+Funktionsklempner assumes that you have created a C++ library with an interface that uses the Funktionsklempner (marker) types. For the sake of brevity, let's use the example in the [example](example) subdirectory; i.e. a project that has an [example.cpp](example/example.cpp) source file and whose interface with the Python world is designed in [example.hpp](example/examples.hpp). Specifically, the important part of the example's interface can be illustrated using the single function
+```cpp
+int test_function(
+    const char* name,
+    size_t i,
+    double* result
+);
+```
+that takes a string `name` and an integer `i`, does something with it, and returns a double as `result`. Note in this interface the pointer-to-double type of `result`: to transfer values to Python via ctypes, Funktionsklempner uses preallocated ctypes variables and passes pointers to them when calling the compiled library. The C++ side is then expected to write the return value into this provided pointer. The actual return value of the function is unused; Funktionsklempner convention is to use `void`.
+
+Note that the actual function in [example.hpp](example/examples.hpp) looks differently! What I have just described is the mechanism that Funktionsklempner makes use of, which is a bit cumbersome to do by hand. To write more explicit code and to make the parser of Funktionsklempner understand the intention of this function definition, it is annoted using macros and alias types defined in [funktionsklempner/funktionsklempner.hpp](subprojects/funktionsklempner/funktionsklempner/funktionsklempner.hpp) and [funktionsklempner/scalar.hpp](subprojects/funktionsklempner/funktionsklempner/scalar.hpp):
+```cpp
+FUNKTIONSKLEMPNER_EXPORT_FUNCTION
+int test_function(
+    funktionsklempner::input<const char*> name,
+    funktionsklempner::input<size_t> i,
+    funktionsklempner::output<double> result
+);
+```
+The first macro `FUNKTIONSKLEMPNER_EXPORT_FUNCTION` tells the parser that what follows is the declaration of a function that shall be callable from the Python world. The templated type alias `funktionsklempner::input<T>` tells the parser that the variables `name` and `i` are input variables passed by value `T`, and the alias `funktionsklempner::output<T>` tells the parser that `result` is a return value of the function (corresponding to a `T*` input parameter). Note that you shall name your variables when exporting via the `FUNKTIONSKLEMPNER_EXPORT_FUNCTION` macro.
+
+What does Funktionsklempner do with this C++ function declaration? On the Python side, it will generate a function that takes a string `name`, an int `i`, and returns a float, i.e.
+```python
+def test_function(
+      name: str,
+      i: int
+    ) -> float:
+    ...
+```
+On the C++ side, it will wrap `test_function` defined in the header by an exception handling function (any uncaught exceptions passing through to the Python world would crash the program!) that caches any occurring error messages. Between this C++ wrapper and the Python `test_function`, glue code will initialize ctypes variables and watch out for such error messages, raising errors on the Python side appropriately.
+
+All glue code is generated via the `funktionsklempner generate` command after the header [example.hpp](example/example.hpp) has been properly described in the project-wide [funktionsklempner.toml](example/funktionsklempner.toml). The following two sections describe both the `funktionsklempner` command line tool as well as the `funktionsklempner.toml` configuration file format.
+
+
+### `funktionsklempner.toml`
+The `funktionsklempner.toml` file collects all files in a source code repository that shall be wrapped via the `funktionsklempner` command. It has to be placed in the root of the packages source code directory and it is required for the `funktionsklempner` command line utility to work. As an example of its layout, consider the [funktionsklempner.toml](example/funktionsklempner.toml) file of the [example](example) subdirectory:
+```toml
+[package]
+name = "funkybadger"
+root = "funkybadger"
+
+[funkybadger]
+[funkybadger.example]
+header = "cpp/example.hpp"
+sources = [ "cpp/example.cpp" ]
+```
+First, note that the `[package]` entry---including the `name` and `root` fields---is mandatory. The `package.name` field describes the name of the Python packge, and the `package.root` field describes the location, relative to the source code directory's root, of the package's source code (see [src layout vs flat layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/), where `package.root` would correspond to the `awesome_package` folder).
+
+Second, there must be one entry per wrapped shared library. In the example, this is `[funkybadger.example]`. All of these entries must be under a root entry that corresponds to the package name (here `[funkybadger]`). The entry's key must correspond to the module name which shall be generated and from which the wrapped functions shall be imported (here the module `funkybadger.example`). Each shared library entry must contain two fields:
+
+   1. `header`, a string denoting the path to the Funktionsklempner-annotated, API-defining
+      header file (here [`example/example.hpp`](example/example.hpp)). The path shall be relative
+      to the source directory's root.
+   2. `sources`, a list of (strings denoting paths to) source files which encompass the shared
+      library.
+
+#### Optional fields
+There are further optional fields that can be used to tweak the code that Funktionsklempner injects into the Meson build file. This way, necessary information (such as a static library that must be linked to) can be passed to the autogenerated Meson build code. The following optional fields are available:
+
+   1. `link_with`, a list of strings denoting `static_library` targets of the injection-targeted
+      Meson build file which the Python shared library shall be linked with.
+   2. `dependencies`, a list of strings denoting `dependency` objects of the injection-targeted
+      Meson build files on which the Python shared library depends.
+   3. `wrapper_source`, a file name specifying the wrapper C++ source file
+      relative to the repository's root.
+   4. `include_root`, a directory name specifying the root include directory
+      for the library. If not given, will default to the directory in which
+      `header` resides.
+
+As an illustration, the code
+```toml
+[package.library]
+header = "..."
+sources = [ "..." ]
+link_with = [ "linklib" ]
+dependencies = [ "a_dependency" ]
+wrapper_source = "cpp/src/library_wrapped.cpp"
+```
+in the `funktionsklempner.toml` configuration file will generate a wrapper source file at `cpp/src/library_wrapped.cpp` (relative to the repository root), and inject the following code into the project's Meson build file:
+```meson
+package_library = shared_library(
+    'library',
+    # ...
+    'cpp/src/library_wrapped.cpp',
+    dependencies: [
+        a_dependency,
+    ],
+    link_with: [
+        linklib,
+    ],
+    # ...
+)
+```
+
+
+### Command line
+The Funktionsklempner package comes with the `funktionsklempner` command line utility. This program sets up the Meson subprojects and git pre-commit hook, injects the project's main Meson build file, and generates the wrapper code. It has three main commands, two of which are typically used by users themselves.
+
+#### `funktionsklempner init`
+This command needs to be called once after the `funktionsklempner.toml` configuration file has been written. The command performs the following tasks:
+
+   1. Setup the `funktionsklempner`, `objektbuch`, `gcem-1.18.0`, and (optional) `boost-1.90.0` Meson subprojects that are required for
+      the automatic error propagation to the Python side.
+   2. Setup the git pre-commit hook that internally uses `funktionsklempner verify` to check
+      that the generated code currently residing in the repository is up to date.
+   3. Start injecting the Funktionsklempner code into the project's Meson build file.
+
+Boost will be preferably used from the system side, but particulary during the pip package building, Boost might not be found. In this case, the reduced subset of Boost (shipping code relevant to Boost.Units) will act as a fallback subproject.
+
+#### `funktionsklempner generate`
+This command is the main workhorse. It generates or updates wrapper codes for all libraries described in `funktionsklempner.toml`, and updates the injection into the project's Meson build file. Call this command whenever a definition in one of the API-defining headers changes.
+
+
+#### `funktionsklempner verify`
+This command checks whether the potential result of `funktionsklempner generate` is identical to what is currently found in the source tree, raising an error if not. This command is used by the git pre-commit hook to ensure that the autogenerated code stays up to date with the API header definitions.
+
+
+### Header annotation syntax
+The introductory example lays out the basic syntax for annotating C++ headers using `FUNKTIONSKLEMPNER_*` macros. The following macros are available:
+
+| Macro                                       | Purpose                                                                                                | Scope           |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------- |
+| `FUNKTIONSKLEMPNER_EXPORT_FUNCTION`         | Export the following function to Python module                                                         | Top level       |
+| `FUNKTIONSKLEMPNER_EXPORT_STRUCT`           | Export the following structure to Python module                                                        | Top level       |
+| `FUNKTIONSKLEMPNER_SIZE_CONTROL("X", "Y")`  | Declare variable `X` as an (output) array whose size is controlled by the (input) array(s) or integer `Y` | Function export |
+
+####  `FUNKTIONSKLEMPNER_EXPORT_FUNCTION`
+This function will generate a wrapper for the following function and export it to the Python module.
+
+####  `FUNKTIONSKLEMPNER_EXPORT_STRUCT`
+This function will generate a `ctypes.Structure` wrapping the following `struct` and export it to the Python module. Functions accepting pointers to this struct (including as return values!) will then be able to pass this data type to and from the Python world. This can be helpful when complex data types shall be transferred with a limited amount of ctypes calls.
+
+#### `FUNKTIONSKLEMPNER_SIZE_CONTROL("X", "Y")`
+A way to return NumPy arrays with known size. Works with and is required for `funktionsklempner::OutputNDArray` and `funktionsklempner::OutputQuantityArray`-type variables. Declares that the variable `X` is an array of size given by the variable `Y`. On the Python side, the two C++ parameters `X` and `Y` will be translated into a single NumPy array `X` of shape `Y.shape` (if `Y` is an input array) or `(Y,)` (if `Y` is not an input parameter of the C++ function, in which case it will be generated as an integer input on the Python side). This allows handling the frequent task of performing computational tasks on vector data kept in Numpy arrays.
+
+The simplest way to automatically derive the size of an output array is by following the size of an input array:
+```cpp
+FUNKTIONSKLEMPNER_EXPORT_FUNCTION
+FUNKTIONSKLEMPNER_SIZE_CONTROL("out", "in_")
+void a_function(
+    funktionsklempner::InputNDArray<double> in_,
+    funktionsklempner::OutputNDArray<double> out
+);
+```
+Here, `in_` is an automatically converted input array, and the return value `out` of the Python wrapper to this function will be a newly generated Numpy array of size `out.size = in_.size`.
+
+##### Multidimensional size control
+Sometimes, following the size of a single array will not be enough. Think of a two-parameter function evaluated on a meshgrid, for instance. For this particular use case, one can use the size multiplication syntax:
+```cpp
+FUNKTIONSKLEMPNER_EXPORT_FUNCTION
+FUNKTIONSKLEMPNER_SIZE_CONTROL("X", "Y,Z")
+void a_function(
+    funktionsklempner::InputNDArray<double> Y,
+    funktionsklempner::InputQuantityArray<boost::units::si::length, double> Z,
+    funktionsklempner::OutputNDArray<double> out
+);
+```
+Here, `Y` is an automatically converted input array of shape `Y.shape`, `Z` is an automatically converted input array of shape `Z.shape` and length dimension, and the return value `X` of the Python wrapper to this function will be a newly generated Numpy array of shape `X.shape = (*Y.shape, *Z.shape)`.
+
+The size control works equivalently with QuantityArrays instead of NDArrays.
+
+### `funktionsklempner::NDArray<NumPyDType T>`
+This class is a thin random access range wrapper around a scalar pointer (e.g., a NumPy array buffer). It is accessible in the `funktionsklempner` namespace as `InputNDArray<T>` (=`NDArray<const T>`, read-only access to the underlying buffer) and `OutputNDArray<T>` (=`NDArray<T>`, can be written to).
+
+The API of the class is as follows:
+```cpp
+template<NumPyDType T>
+class NDArray
+{
+public:
+    /* Constructors: */
+    constexpr NDArray(T* data, size_t N, const char* dtype);
+    constexpr NDArray(NDArray&&) noexcept = default;
+    constexpr NDArray(const NDArray&) noexcept = default;
+
+    /* Sized range: */
+    constexpr size_t size() const noexcept;
+
+    /* Random access iterators, pointers to the underlying buffer: */
+    constexpr T* begin() const noexcept;
+    constexpr T* end() const noexcept;
+
+    /* Random index-based access: */
+    constexpr T& operator[](size_t i) const;
+};
+```
+Note that `NumPyDType` is a concept that captures the basic scalar types of NumPy array buffers (integer and floating point types).
+
+
+### `funktionsklempner::QuantityArray<Unit U, NumPyDType T>`
+A rather thin random access wrapper around a scalar pointer that represents values of a certain physical (SI) unit via Boost.Units. Iterating over the quantity array yields value views that act, basically, as physical quantities of the given unit `U` (`boost::unit::quantity<U, T>`). It is accessible in the `funktionsklempner` namespace as `InputQuantityArray<U, T>` (=`QuantityArray<U, const T>`, read-only access to the underlying buffer) and `OutputQuantityArray<U, T>` (=`QuantityArray<U, T>`, can be written to).
+
+The value type of the iterators of `QuantityArray` is the the `QuantityView<U,T>` class, which internally contains a pointer to the numerical buffer of the `QuantityArray` and a `boost::unit::quantity<U, T>` that represents the physical unit. The `QuantityView` can be casted to `boost::unit::quantity<U, T>`, and addition, subtraction, multiplication, and division operators of `QuantityView<U,T>` with `boost::unit::quantity<U, T>` are provided. In case of the `OutputQuantityArray`, assignment and inplace addition and subtraction operators with `boost::unit::quantity<U, T>` are provided as well. Essentially, `QuantityArray<U,T>` can be used to wrap a floating point buffer `T*` in a way that looks like a buffer of quantities, `boost::unit::quantity<U, T>*`.
+
+The API of the class is as follows:
+```cpp
+template<Unit U, NumPyDType T>
+class QuantityArray
+{
+public:
+    /* Constructor with given unit of same dimension as `U`. */
+    constexpr QuantityArray(
+        T* data,
+        size_t N,
+        const char* dtype,
+        const char* unit
+    );
+
+    /* Constructor with default unit `U` */
+    constexpr QuantityArray(
+        T* data,
+        size_t N,
+        const char* dtype
+    );
+
+    /* Sized range: */
+    constexpr size_t size() const noexcept;
+
+    /* Random access iterators, pointing to the underlying buffer: */
+    constexpr QuantityIterator<U, T> begin() const;
+    constexpr const std::decay_t<T>* end() const noexcept;
+
+    /* Random index-based access: */
+    constexpr QuantityView<U, T> operator[](size_t i) const;
+
+    /* Setting the unit to `u`, a quantity of unit `U`.
+     * Note: this method is enabled only if `T` is not a const value
+     *       (i.e. for OutputQuantityArray<U,T>).
+     */
+    constexpr void set_unit(const boost::units::quantity<U>& u);
+};
+```
+Note that `Unit` is a concept that captures `boost::units::unit<Dim, System>` of some dimension `Dim` and system `System` (which essentially has to be the SI system from `boost::units::si` to be able to interact with the remainder of Funktionsklempner). As before, `NumPyDType` is a concept that captures the basic scalar types of NumPy array buffers (integer and floating point types).
+
+## Caveats
+Some known caveats to keep in mind when using Funktionsklempner:
+
+   1. This uses a simplified grammar.
+   2. There is some effort in this code base to handle comments. However, this
+      effort is designed empirically rather than after a standard. You might
+      run into complications with more 'unusual' comment or preprocessor layouts.
+      If you hit such a bug, you may try to file a bug report--but there is no
+      guarantee that all such bugs will be fixed (in which case reduction to the
+      simplified grammar may be the only way to run Funktionsklempner).
+
+Note, furthermore, the terms listed in the [LICENSE](LICENSE).
+
+
+## License
+Funktionsklempner itself is licensed under the European Public License, v1.2 (`EUPL-1.2`, see [LICENSE](LICENSE) file in this directory). The template code for the code generation is licensed under the BSD 3-Clause license (`BSD-3-Clause`, noted in corresponding source files). The example under the [example/](example) subfolder is equally licensed under the `BSD-3-Clause` license.
+
+Funktionsklempner vendors a subset of the Boost C++ Libraries, version 1.90.0 in [subprojects/packagefiles/boost-1.90.0_units.tar.gz](subprojects/packagefiles/boost-1.90.0_units.tar.gz). This code is licensed under the Boost Software License as indicated in the archive. You can find the full Boost library at [boost.org](https://www.boost.org/).
+
+
+## Changelog
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+### [1.0.0] - 2026-03-09
+#### Added
+- Start of the changelog.