13. Packaging

13.1. Third party module

Having your data_models/projects/targets/info in fuddly’s data folder is useful when developing them, but it can quickly become a disorganized mess. It is also not very practical if you want to distribute you project to a wider audience.

Therefore, it is possible to package your code and install it alongside the other python packages on your system.

For this, you will need to configure entry points that fuddly will be able to look-up to find your objects.

These entry points are identified by group names that are known to fuddly. They are the following:

  • fuddly.projects

  • fuddly.data_models

  • fuddly.targets

  • fuddly.info

Using the tutorial as an example, you would package it by creating the following pyproject.toml

See Defining the Imaginary MyDF Data Model for the implementation.

[project]
name = "modulename"
description = "The best data format"
version = "0.1"
authors = [
  { name="Steve Harwell", email="somebody@once.told.me" },
]
dependencies=["fuddly@git+https://github.com/k0retux/fuddly"]

[project.entry-points."fuddly.data_models"]
modulename__root__ = "modulename"
mydf = "modulename.mydf"

A special value in the entry_points needs to be added for fuddly to be able to find where the root of your module is. The name should end in __root__, the first part will be used during imports. With the example above, you would import the module with import fuddly.data_models.modulename.mydf. It’s value should point to the namespace in which the module can be found. This is usually the parent directory to your data_model, project, target or info. In case of a package containing only your module, the name of the module should be used.

Note

When building a package like this, your source files need to be either in a directory named like your module, or in a src directory with a subdirectory named like your module, this second format is preferred. Your package should not actually contain a module in the python sense, it should be a namespace. Therefore you should not include any __init__.py files outside of where you have your data_model, project, target or info. See https://packaging.python.org/en/latest/ for more general information about python packaging.

You can then produce a python .whl with python -m build --wheel and install it with pip install dist/*.whl (or better yet, package it properly for you distribution and install it using your distribution’s package manager)

13.1.1. Samples

When you packages your data model (or your project), you can add a samples folder to your data_model (or project) modules. In this namespace, you can add samples that your model (or the models used by the projects) can use to instantiate atoms. (This is simply a python namespace and not a module, trying to import from it will fail but it can be used to get the path of the resource so it can then be read from your code)

This folder will automatically be found by fuddly when it load the data model (or the data models used by the project) through the fuddly.framework.data_model.DataModel.import_file_content() method.

13.1.2. Load order

When fuddly loads data models and projects, it first looks at it’s data folder, then in fuddly’s internal modules, then finally looks for python modules. If a naming conflict appear during the python module loading, they will be ignored, and a warning will be printed.

Loading objects like this means that you can override python modules by redefining their data models, projects, targets, info, and so on, in fuddly’s data folder.

Note

A side effect of this is that fuddly cannot differentiate between 2 python modules defining objects with the same name and a module and an object in the data folder sharing the same name.

Similarly, samples have a priority/load order. They are loaded in this order:

  1. from a data model module first;

  2. then from the user’s data_models folder in fuddly’s data folder (if the data model is available there);

  3. then the user’s imported_data folder in fuddly’s data folder;

  4. then from the user’s projects folder in fuddly’s data folder or project module (depending on how the project module is deployed).

When files have the same name in different locations, the latest will override earlier files, i.e. the user’s projects folder override any other sample with the same name.

13.2. Fuddly

Fuddly itself is also itself packageable.

It’s done in the conventional python way of producing a wheel package with python -m build --wheel that can be installed with pip install dist/<file_name>.whl.

You can also see that fuddly’s pyproject.toml declare entry points for it’s internal data_models, projects, targets and info in the same way a third party package could.

If you are lucky, you might also find a build script to create a native package for your distribution. They are located in the contrib/build/<distribution_name> folder.